Ray Serve：分布式推理

为什么需要 Ray Serve：单体脚本扛不住线上流量

传统做法是把训练好的模型包进一个 Flask/FastAPI 服务，再用容器和 K8s 部署。这种方式在单模型、低流量下没问题，但遇到多模型共存时，要么每个模型起一个独立服务导致 GPU 和内存严重浪费，要么把多个模型塞进一个进程里，一旦某个模型升级或崩溃，整个服务跟着遭殃。流量突增时，单体服务的水平扩容要手动改副本数，扩容后还要等模型重新加载，冷启动延迟动辄几十秒。模型本身还要管理健康检查、优雅停机、请求超时、批次调度这些本不该由业务代码处理的事。

Ray Serve 用「部署单元 + 路由层」的模型解决这些问题。每个模型声明为一个 Deployment（部署单元），框架负责实例化、健康检查和流量分发；多个 Deployment 可以共享同一批 GPU 资源，也可以各自独立扩缩容。流量上涨时，Serve 根据「正在处理的请求数」等指标自动增减副本，无需人工干预。Serve 还内置了优雅停机：缩容前先把该副本上的存量请求处理完，再回收资源，模型推理服务不会因为副本替换而中断。

与 KServe、Seldon Core 这类「在 Kubernetes 上定义服务」的框架不同，Ray Serve 的逻辑起点是 Python：你不用先学会写 K8s CRD 和 YAML，在本地 serve.run 一个函数就能得到可查询的 HTTP 接口，部署到集群时再套上 KubeRay Operator。这种「先本地后集群」的路径让它对算法工程师更友好，但代价是它不会替你管理容器和网络，K8s 层面的东西依然要自己负责。

安装与环境配置：3 步就绪

步骤一：准备 Python 3.9-3.12 环境，建议使用虚拟环境隔离依赖。

步骤二：安装 Ray Serve。直接 pip install ray 只装核心库，Serve 需要的 FastAPI/Starlette 等依赖要通过 [serve] 扩展安装。

步骤三：验证安装。import ray 并打印版本号确认核心库可用，再用 ray start --head 启动一个本地单机集群，验证集群能正常起来（Serve 在本地单机下也会自动初始化一个隐式集群，这个命令不是必须的，但能确认 Ray 运行时无异常）。

装完即可在 Python 里 import ray.serve。注意不要单独 pip install ray-serve，这个名字的包不是官方 Serve 组件。

# 创建并激活虚拟环境（Python 3.9-3.12）python -m venv serve-env && source serve-env/bin/activate # 安装 Ray 及 Serve 依赖pip install -U "ray[serve]" # 验证安装：打印版本号python -c "import ray; print(ray.__version__)" # 可选：显式启动本地 Ray 集群，确认运行时正常ray start --head --port=6379

快速上手：5 分钟跑通第一个 HTTP 推理服务

最小可用流程的思路是：定义一个 Python 类作为模型部署单元，用 @serve.deployment 装饰，再用 serve.run 把它绑定到本地 8000 端口。Serve 会自动创建 HTTP 入口，把请求转发给模型副本。整个过程不需要写 Flask 路由，也不需要配置容器。

步骤一：写一个部署类。在 __init__ 里加载模型（只加载一次，多个副本各自持有一份），在类方法里写推理逻辑。

步骤二：挂 FastAPI 路由。@serve.ingress(fastapi_app) 让 FastAPI 应用成为 HTTP 入口，路由方法用 @fastapi_app.post("/predict") 声明。

步骤三：调用 serve.run 启动。传入 SentimentModel.bind("模型ID")，Serve 自动初始化 Ray 运行时并阻塞监听请求。

运行 python demo.py 后，在另一个终端验证：

返回 {"label":"POSITIVE","score":0.9998} 即成功。进阶技巧：把部署参数加进装饰器，如 @serve.deployment(num_replicas=2)，Serve 会自动在本地启动两个副本并做负载均衡，无需改业务代码。

# demo.pyfrom ray import servefrom fastapi import FastAPI, Request fastapi_app = FastAPI() @serve.deployment@serve.ingress(fastapi_app)class SentimentModel:    def __init__(self, model_id: str):        from transformers import pipeline        self.classifier = pipeline("sentiment-analysis", model=model_id)     @fastapi_app.post("/predict")    async def predict(self, request: Request):        payload = await request.json()        pred = self.classifier(payload["text"])[0]        return {"label": pred["label"], "score": pred["score"]} serve.run(SentimentModel.bind("distilbert-base-uncased-finetuned-sst-2-english"))

curl -X POST http://localhost:8000/predict \  -H "Content-Type: application/json" \  -d '{"text": "Ray Serve is awesome!"}'

核心能力详解：3 大支柱

支柱一：弹性扩缩容与自动恢复。Serve 的 Deployment 支持声明式扩缩容：通过 autoscaling_config 设置 min_replicas、max_replicas 和 target_ongoing_requests（每个副本目标并发请求数），框架根据实时请求量自动增减副本。副本由 Ray Actor 承载，节点故障时会被自动调度到其他可用节点重建；ray_actor_options={"num_gpus": 1} 可绑定 GPU。这是 Serve 相对「容器按 CPU 扩缩容」方案的核心差异：它以请求级指标而非单纯的 CPU 利用率做决策，对推理这种短时高并发负载更精准。

支柱二：多模型路由与资源复用。一个 Serve 应用可以包含多个 Deployment，请求按 HTTP 路径分发到不同模型；多个模型也可放在同一批副本上共享 GPU 显存。典型用法是 A/B 测试：新旧两个模型各占一个 Deployment，用同一个入口按流量比例路由。Serve 还支持 Deployment 间的调用图（DAG 管道），例如「特征提取 → 模型推理 → 后处理」拆成三个 Deployment 串联，适合流水线式推理。

支柱三：与 Ray 生态及 AI 框架集成。Serve 与 Ray Data 集成可以做推理前的批量预处理，与 Ray Train 集成则能实现「同一套代码训练完直接部署」。模型侧无缝对接 PyTorch、HuggingFace Transformers、XGBoost 等；入口侧原生支持 FastAPI、纯 HTTP 路由和 gRPC。对于 LLM 场景，Serve 可作为 vLLM 等推理引擎的前置调度层，承担路由、扩缩容和容错职责。

生产部署与监控：从上线到运维

部署方式一：Kubernetes + KubeRay Operator。KubeRay 以 CRD 的方式在 K8s 上创建 RayCluster，把 Serve 应用发布为集群内服务。适用于已有 K8s 基础设施、需要与 Istio/Ingress 网关打通流量的团队。部署时用 serve deploy config.yaml 声明应用配置，KubeRay 负责把副本调度到节点上，配合 HPA 或 Serve 内置 autoscaling 使用。此路径要求团队具备 K8s 运维能力，网络策略、存储卷和 GPU 调度都需要自行配置。

部署方式二：Anyscale Managed 或裸 Ray 集群。Anyscale 提供托管的 Ray 集群，Serve 应用可通过 CLI 一键发布，免去运维 K8s 的成本。若不想引入商业依赖，也可以用 ray start --head --num-gpus=N 启动多节点集群，再用 serve.deploy 部署。

可观测性方面：Serve 默认暴露 /metrics 端点（Prometheus 格式），核心指标包括 serve_deployment_replica_healthy（副本健康状态）、serve_deployment_ongoing_requests（在处理请求数）、serve_deployment_queued_requests（排队请求数）。Ray Dashboard 提供 Web 界面查看副本分布、请求延迟和错误日志。生产环境建议：每个 Deployment 的副本数不小于 2，开启 health_check_period_s 与 health_check_timeout_s，并为每个模型配置独立的 max_ongoing_requests 防止单副本被慢请求拖垮。

<p class=“para-label“>避坑清单：</p><ul class=”dash-list”><li>坑 1：版本兼容。Ray 各模块（Core/ Serve/ Data）随主版本一起发布，升级时必须整体升级并用 pip install "ray[serve]" 重装，混用不同版本会出现反序列化失败或 GCS（集群控制平面）不兼容，且 Serve 应用的状态不保证跨版本无损迁移，升级前要在预发环境完整回放流量。</li><li>坑 2：有状态模型直接缩容导致丢请求。模型加载耗时长的 Deployment 若把 min_replicas 设为 0，冷启动时新副本要重新下载/加载模型，会拖垮首波请求；应设置合理的 min_replicas 并用 graceful_shutdown_timeout_s 保证缩容时存量请求处理完。</li><li>坑 3：本地 serve.run 与集群部署混用。本地直接 serve.run(app) 会占用当前 Python 进程并阻塞，生产环境应改用 serve.deploy 或 KubeRay 的声明式配置，否则进程退出后服务即消失。</li></ul>

版本迭代

Ray Serve 从 Ray 1.x 的实验模块逐步演进为 Ray 2.x 的一等公民，主线是「API 稳定化 → 部署体验简化 → 可观测性增强」。2.0 明确 Serve 为生产推荐的推理框架，2.4 引入声明式部署，2.9 之后聚焦性能和运维能力。Ray 版本每季度左右发布一次（截至训练数据，可能已有更新版本）。

AI 应用场景

常见误区

面试题