RayService 快速入门#

先决条件#

本指南主要关注 KubeRay v1.5.1 和 Ray 2.46.0 的行为。

什么是 RayService？#

RayService 管理以下组件

  • RayCluster：管理 Kubernetes 集群中的资源。

  • Ray Serve Applications：管理用户的应用程序。

RayService 提供什么？#

  • 对 Ray 集群和 Ray Serve 应用程序的原生 Kubernetes 支持： 使用 Kubernetes 配置定义 Ray 集群及其 Ray Serve 应用程序后，您可以使用 kubectl 来创建集群及其应用程序。

  • Ray Serve 应用程序的就地更新： 有关更多详细信息，请参阅 RayService。

  • Ray 集群的零停机升级： 有关更多详细信息，请参阅 RayService。

  • 高可用服务： 有关更多详细信息，请参阅 RayService 高可用。

示例：使用 RayService 服务两个简单的 Ray Serve 应用程序#

步骤 1：使用 Kind 创建 Kubernetes 集群#

kind create cluster --image=kindest/node:v1.26.0

步骤 2：安装 KubeRay operator#

请按照 本文档 从 Helm 仓库安装最新的稳定版 KubeRay operator。请注意，此示例中的 YAML 文件使用 serveConfigV2 来指定多应用程序的 Serve 配置，该配置从 KubeRay v0.6.0 开始可用。

第 3 步：安装 RayService#

kubectl apply -f https://raw.githubusercontent.com/ray-project/kuberay/v1.5.1/ray-operator/config/samples/ray-service.sample.yaml

步骤 4：验证 Kubernetes 集群状态#

# Step 4.1: List all RayService custom resources in the `default` namespace.
kubectl get rayservice

# [Example output]
# NAME                SERVICE STATUS   NUM SERVE ENDPOINTS
# rayservice-sample   Running          2

# Step 4.2: List all RayCluster custom resources in the `default` namespace.
kubectl get raycluster

# [Example output]
# NAME                      DESIRED WORKERS   AVAILABLE WORKERS   CPUS    MEMORY   GPUS   STATUS   AGE
# rayservice-sample-cxm7t   1                 1                   2500m   4Gi      0      ready    79s

# Step 4.3: List all Ray Pods in the `default` namespace.
kubectl get pods -l=ray.io/is-ray-node=yes

# [Example output]
# NAME                                               READY   STATUS    RESTARTS   AGE
# rayservice-sample-cxm7t-head                       1/1     Running   0          3m5s
# rayservice-sample-cxm7t-small-group-worker-8hrgg   1/1     Running   0          3m5s

# Step 4.4: Check the `Ready` condition of the RayService.
# The RayService is ready to serve requests when the condition is `True`.
kubectl describe rayservices.ray.io rayservice-sample

# [Example output]
# Conditions:
#   Last Transition Time:  2025-06-26T13:23:06Z
#   Message:               Number of serve endpoints is greater than 0
#   Observed Generation:   1
#   Reason:                NonZeroServeEndpoints
#   Status:                True
#   Type:                  Ready

# Step 4.5: List services in the `default` namespace.
kubectl get services

# NAME                               TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)                                         AGE
# ...
# rayservice-sample-cxm7t-head-svc   ClusterIP   None            <none>        10001/TCP,8265/TCP,6379/TCP,8080/TCP,8000/TCP   71m
# rayservice-sample-head-svc         ClusterIP   None            <none>        10001/TCP,8265/TCP,6379/TCP,8080/TCP,8000/TCP   70m
# rayservice-sample-serve-svc        ClusterIP   10.96.125.107   <none>        8000/TCP                                        70m

当 Ray Serve 应用程序健康且准备就绪时，KubeRay 会为 RayService 自定义资源创建一个 head service 和一个 Ray Serve service。例如，在第 4.5 步中的 rayservice-sample-head-svc 和 rayservice-sample-serve-svc。

这些服务有什么作用？

  • rayservice-sample-head-svc
    此服务指向活动的 RayCluster 的head pod，通常用于查看Ray Dashboard（端口 8265）。

  • rayservice-sample-serve-svc
    此服务公开 Ray Serve 的HTTP 接口，通常在端口 8000 上。
    使用此服务向部署的 Serve 应用程序发送 HTTP 请求（例如，REST API、ML 推理等）。

第 5 步：验证 Serve 应用程序的状态#

# (1) Forward the dashboard port to localhost.
# (2) Check the Serve page in the Ray dashboard at https://:8265/#/serve.
kubectl port-forward svc/rayservice-sample-head-svc 8265:8265

  • 有关 RayService 可观察性的更多详细信息，请参阅 rayservice-troubleshooting.md。下面是 Ray dashboard 中 Serve 页面的截图示例。Ray Serve Dashboard

第 6 步：通过 Kubernetes serve service 向 Serve 应用程序发送请求#

# Step 6.1: Run a curl Pod.
# If you already have a curl Pod, you can use `kubectl exec -it <curl-pod> -- sh` to access the Pod.
kubectl run curl --image=radial/busyboxplus:curl -i --tty

# Step 6.2: Send a request to the fruit stand app.
curl -X POST -H 'Content-Type: application/json' rayservice-sample-serve-svc:8000/fruit/ -d '["MANGO", 2]'
# [Expected output]: 6

# Step 6.3: Send a request to the calculator app.
curl -X POST -H 'Content-Type: application/json' rayservice-sample-serve-svc:8000/calc/ -d '["MUL", 3]'
# [Expected output]: "15 pizzas please!"

第 7 步：清理 Kubernetes 集群#

# Delete the RayService.
kubectl delete -f https://raw.githubusercontent.com/ray-project/kuberay/v1.5.1/ray-operator/config/samples/ray-service.sample.yaml

# Uninstall the KubeRay operator.
helm uninstall kuberay-operator

# Delete the curl Pod.
kubectl delete pod curl

下一步#

  • 有关 RayService 的全部功能，包括就地更新、零停机升级和高可用，请参阅 RayService 文档。

  • 如果遇到任何问题，请参阅 RayService 故障排除指南。

  • 有关更多 RayService 示例，请参阅 示例。MobileNet 示例 是一个不错的入门示例，因为它不需要 GPU，并且易于在本地机器上运行。