ray-serve

Ray Serve 在线推理部署：副本、GPU、自动扩缩与滚动更新。

补充说明

Ray Serve 把普通 Python 类或 FastAPI 应用包装成可扩缩的 deployment，由 Ray 集群调度到多节点多 GPU。适合组合预处理、模型推理和后处理的多阶段服务。

基础集群操作见 ray；本页聚焦 Serve 的部署配置和生产行为。

安装与启动

pip install -U "ray[serve]"
ray start --head --num-gpus 8 --dashboard-host 0.0.0.0

客户端 Ray 版本必须与集群一致，混合版本会在连接或序列化阶段失败。

常用示例

定义带 GPU 副本和自动扩缩的服务：

cat > app.py <<'PY'
from fastapi import FastAPI
from ray import serve

app = FastAPI()

@serve.deployment(
    ray_actor_options={"num_gpus": 1},
    max_ongoing_requests=8,
    autoscaling_config={"min_replicas": 1, "max_replicas": 4,
                        "target_ongoing_requests": 4, "upscale_delay_s": 30},
)
@serve.ingress(app)
class Generator:
    def __init__(self) -> None:
        from transformers import pipeline
        self.pipe = pipeline("text-generation", model="Qwen/Qwen2.5-7B-Instruct",
                             device_map="cuda", torch_dtype="auto")

    @app.post("/generate")
    def generate(self, payload: dict) -> dict:
        out = self.pipe(payload["prompt"], max_new_tokens=payload.get("max_new_tokens", 128),
                        do_sample=False)
        return {"text": out[0]["generated_text"]}

generator = Generator.bind()
PY

生产部署时固定工作目录和依赖，并在部署后验证：

cat > serve.yaml <<'YAML'
applications:
  - name: llm
    import_path: app:generator
    runtime_env:
      working_dir: .
      pip: "-r requirements.txt"
YAML

serve deploy serve.yaml
curl -s localhost:8000/-/health
curl -X POST localhost:8000/generate -H 'Content-Type: application/json' \
  -d '{"prompt": "解释 CrashLoopBackOff", "max_new_tokens": 64}'

serve run 适合本地开发，退出终端服务就停；serve deploy 提交到持久化集群并支持滚动更新。

易错点与排错

• 忘记 ray_actor_options={"num_gpus": 1} 时副本都挤在 CPU 或同一张卡上，模型加载即 OOM。
• max_ongoing_requests 过高会把请求堆进显存，过低又浪费 GPU；按单副本并发显存实测设置。
• target_ongoing_requests 是每个副本的目标排队数，不是 QPS；按请求耗时和并发换算。
• GPU 副本冷启动要加载权重，可能几十秒到几分钟；延迟敏感服务保留 min_replicas >= 1。
• 每个副本加载完整模型，num_replicas 乘 GPU 数不能超过集群容量；大模型用单副本多卡做张量并行。
• 自动扩缩的字段名随 Ray 版本变化（旧版是 target_num_ongoing_requests_per_replica），升级前核对版本文档。
• runtime_env.working_dir 漏掉数据文件或配置，副本启动后找不到路径；依赖也要锁版本。
• 长请求在滚动更新时可能被中断；调大 graceful_shutdown_timeout_s 并让客户端支持重试。

读完自测

合上页面，先回答，再展开对照。

1. 为什么副本没有分到 GPU？
2. serve run 和 serve deploy 的区别是什么？
3. 自动扩缩为什么要看 target_ongoing_requests 而不是 QPS？

相关条目

• ray
• vllm
• triton
• gpu-operator
• kueue