ray-llm

Ray LLM

面向开源 Ray 上大模型工作负载的库参考技能——涵盖 5 个类别中的 13 条规则，涉及 ray.serve.llm（兼容 OpenAI、由 vLLM 提供支持的服务）和 ray.data.llm（批量推理）。Ray 的这一部分变化速度超过其他任何部分——独立仓库被合并并归档、入口点更名、配置结构重组——因此，模型学到的示例大多已无法运行。每条规则都指出它要纠正的错误默认做法；对于能力足够的模型本来就能正确处理的事项，则不设规则。

范围仅限大模型专属层。通用 Serve/Data/集群决策（部署生命周期、自动扩缩语义、KubeRay）属于同级 ray 技能——两者可组合使用。

固定使用 ray 2.57.0（ray[llm] extra 会固定匹配的 vLLM 版本）。API 相关说法均已根据解压后的 2.57.0 wheel 和已安装的包源码核实；规则中的每个配置示例都经过仅 CPU 环境下的 pydantic 验证（包括陷阱示例，其失败情况与描述完全一致）；引擎/GPU 运行时行为仅通过源码核实——实际并未提供任何模型服务。

适用场景

• 在 Ray 上搭建或审查兼容 OpenAI 的大模型服务部署
• 为数据集编写大模型批量推理——大规模摘要、嵌入、评分
• 为多 GPU 模型确定规格或放置位置——张量/流水线并行、加速器选择
• 扩缩大模型部署——副本自动扩缩、入口规格、请求路由
• 为共享基础模型提供一系列 LoRA 微调模型的服务
• 迁移使用已归档的 ray-llm 仓库、手写 vLLM 引擎或 2.5x 之前 ray.data.llm 名称的代码

规则类别

#	类别	前缀	涵盖内容
1	服务设置	serve-	使用 LLMConfig + build_openai_app，而非手写引擎和已归档仓库；model_id 与 model_source 的区别；ray[llm]↔vLLM 版本固定关系；已迁移的 LLMServer/OpenAiIngress 导入路径
2	批量推理	batch-	build_processor（旧名称已移除）；使用阶段配置而非布尔标志；accelerator_type 默认使用 CPU，自动扩缩时使用 concurrency；HTTP/Serve 处理器替代方案
3	放置与加速器	place-	引擎自身的 TP×PP 放置组（以及何时覆盖其策略）；经过验证的 accelerator_type 名称
4	自动扩缩与路由	scale-	使用 deployment_config.autoscaling_config 配合按引擎规格设定的副本；入口副本规格；基于前缀缓存亲和性的路由
5	LoRA 与 API 表面	api-	使用动态 LoRA 多路复用，而非为每个适配器单独部署；完整的 OpenAI 端点范围；无需 GPU 的配置验证

快速参考

1. 服务设置

• serve-builtin-not-handrolled — 使用 LLMConfig + build_openai_app；ray-llm 仓库已归档，手写引擎需要重新实现的内容更少
• serve-model-id-vs-source — model_id 是客户端可见的名称；model_source 是权重所在的位置
• serve-ray-llm-extra-pins-vllm — ray[llm] 会固定对应的 vLLM 版本；不要混用各自独立选择的版本
• serve-deprecated-server-router — LLMServer/LLMRouter 已迁移；入口类名为 OpenAiIngress（大小写须完全一致）

2. 批量推理

• batch-build-processor-renamed — build_llm_processor 已移除；改用 build_processor + vLLMEngineProcessorConfig
• batch-stage-configs-not-flags — 布尔值 apply_chat_template/tokenize/detokenize 已由阶段配置取代
• batch-concurrency-and-alternatives — accelerator_type=None 表示使用 CPU；concurrency 使用 (min, max)；HTTP/Serve 处理器

3. 放置与加速器

• place-engine-builds-pg — 引擎会构建其 TP×PP 放置组；应覆盖策略，而不是手动创建
• place-accelerator-type-validated — 规范的加速器常量；"A10" 会被规范化，大多数拼写错误都会引发异常

4. 自动扩缩与路由

• scale-autoscaling-deployment-config — 将标准 Serve 自动扩缩配置嵌套在 deployment_config 中；副本是完整的引擎
• scale-prefix-cache-routing — PrefixCacheAffinityRouter 会将相同前缀的请求路由到已预热 KV 缓存的实例

5. LoRA 与 API 接口

• api-lora-dynamic-multiplexing — 从云存储动态加载适配器，而不是为每个适配器部署一个实例
• api-endpoint-surface-cpu-validation — 也提供嵌入、转录、评分和分词服务；无需 GPU 即可验证配置

如何使用

遇到相关决策时，阅读对应的参考文件。每条规则都会说明它要纠正的错误默认做法，然后展示规范做法（仅在错误做法确实容易导致问题时，才会对比错误与正确的做法）。

• 章节定义 — 类别结构
• 规则模板 — 用于添加新规则
• AGENTS.md — 自动生成的所有规则目录

相关技能

• ray — 面向经典机器学习 Ray（Train、Tune、Data、Serve、Core、KubeRay 生产拓扑）的同级规则包；通用 Serve 和集群决策归属其中

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和来源引用