ray

Ray

面向生产环境、开源 Ray 的库参考技能——包含 6 个类别中的 26 条规则，涵盖从训练到服务的整个流程。Ray 的 API 在 2.x 系列中经历了剧烈变化（Train V2 成为默认版本，Serve 彻底移除了参数和句柄类，Ray Data 则撤销了一项弃用），因此，熟悉旧版语料的模型生成的代码可能会产生警告、报错，或在不知不觉中改变含义。每条规则都指出并纠正一种错误的默认做法；对于能力较强的模型本就能正确处理的内容，不设规则。

适用范围为可自托管集群和 KubeRay 集群上的经典机器学习 Ray。LLM 服务和批量推理（ray.serve.llm、ray.data.llm）请参阅同级技能 ray-llm。

固定使用 ray 2.57.0（Python ≥ 3.10）。API 相关说明已根据解包后的 2.57.0 wheel 验证；经典机器学习示例已在本地运行的 Ray 2.57.0 环境中测试。

适用场景

• 编写或审查分布式训练代码——TorchTrainer、ScalingConfig、检查点、容错
• 使用 Ray Data 构建数据流水线——读取、map_batches、GPU 推理池、训练数据导入
• 使用 Ray Tune 运行超参数搜索，尤其是与 Ray Train 结合使用时
• 编写或审查 Ray Serve 部署——扩缩容、句柄、组合、生产配置
• 直接使用 Ray Core 原语——任务、Actor、对象存储、重试
• 搭建或审查生产 Ray 基础设施——KubeRay CRD、作业提交、容错、可观测性

规则类别

#	类别	前缀	涵盖内容
1	Ray Train	train-	默认使用 Train V2（已弃用的配置字段）、使用 ray.train.report 而非 ray.air session、配置导入和弹性扩缩容、prepare_model/prepare_data_loader 包装器
2	Ray Serve	serve-	max_ongoing_requests（旧名称已移除）、当前自动扩缩容字段、DeploymentResponse 句柄、serve.run/build/deploy 生命周期、副本放置选项
3	Ray Data	data-	compute= 策略（concurrency 的反转）、override_num_blocks、以流式执行替代流水线、Torch 数据导入、零拷贝只读批次
4	Ray Core	core-	经典反模式中不易察觉的遗留问题、重试/重启默认值、对象存储和 /dev/shm 容量配置、ray.util.state
5	Ray Tune	tune-	将 Tuner 作为规范用法（以及 tune.run 的实际状态）、ray.tune.RunConfig 导入、基于驱动函数的 Train 集成
6	生产环境与集群	prod-	KubeRay CRD 选择、Jobs API 提交、结合 Redis 的 GCS 容错、预构建镜像与 runtime_env、Prometheus/Grafana 配置

快速参考

1. Ray Train

• train-v2-default-changed-semantics — 从 2.51 起默认使用 V2；sync_config/verbose/fail_fast 已移除
• train-report-not-air-session — 使用 ray.train.report(metrics, checkpoint=)；ray.air 是旧版兼容层
• train-configs-from-ray-train-elastic — V2 配置导入、弹性 num_workers=(min, max)、区分大小写的资源键
• train-prepare-model-and-loader — 不使用 prepare_model/prepare_data_loader 时，N 个 Worker 会训练 N 个不同步的副本

2. Ray Serve

• serve-max-ongoing-requests — 已移除 max_concurrent_queries；使用 max_ongoing_requests（默认值为 5）+ max_queued_requests
• serve-autoscaling-current-fields — target_ongoing_requests、*_factor 字段、num_replicas="auto"、缩容至零
• serve-deployment-response-handles — 使用 DeploymentResponse.result()/await，切勿使用 ray.get；通过 .bind() 进行组合
• serve-run-build-deploy — 使用 serve.run + serve build/deploy；Deployment.deploy() 时代的用法已移除
• serve-placement-controls — max_replicas_per_node、每个副本的放置组、Gang 调度、请求路由器

3. Ray Data

• data-compute-not-concurrency — concurrency= 已弃用（再次弃用）；使用 compute=ActorPoolStrategy/TaskPoolStrategy
• data-override-num-blocks — 读取 API 中的 parallelism 已弃用
• data-streaming-replaced-pipelines — 已移除 DatasetPipeline/window/repeat；在消费时以流式方式执行
• data-iter-torch-batches-not-to-torch — to_torch 已不存在；使用 iter_torch_batches 和 Train 数据集分片
• data-zero-copy-read-only-batches — 默认情况下，批次是只读视图；显式设置 batch_size

4. Ray Core

• core-classic-traps-residue — 经典反模式中不易察觉的遗留问题：ray.wait 清空队列、闭包/全局变量复制、任务耗时至少数毫秒
• core-retries-system-failures-only — retry_exceptions 需显式启用；Actor 默认不会重启
• core-object-store-sizing — 默认值为 30%；容器中使用 /dev/shm；溢出时写入本地磁盘
• core-state-api-not-ray-state — ray.state 已不存在；ray.util.state 是用于内省的 API

5. Ray Tune

• tune-tuner-canonical — Tuner 是标准 API；tune.run 是旧版 API，但尚未移除
• tune-runconfig-from-ray-tune — Tuner 接受 ray.tune.RunConfig，而不是 ray.train 或 ray.air 中的 RunConfig
• tune-driver-function-not-trainer — Tuner 内使用 Trainer 的方式已弃用；请改用驱动函数 + with_resources

6. 生产环境与集群

• prod-kuberay-crd-choice — RayCluster 与 RayJob（shutdownAfterJobFinishes 默认值为 false）的选择，以及 RayService
• prod-jobs-api-not-head-driver — 对于长生命周期集群，使用 ray job submit；Ray Client 是开发工具
• prod-gcs-ft-redis — RayService 要在 head 节点崩溃后继续运行，需要使用外部 Redis GCS
• prod-baked-images-not-runtime-env — 镜像包含生产依赖；runtime_env（现已支持 uv、image_uri）用于迭代开发
• prod-metrics-wiring — 仪表板需要外部 Prometheus/Grafana 才能显示时间序列

使用方法

遇到相关决策时，请阅读对应的参考文件。每条规则都会指出需要纠正的错误默认做法，然后展示标准用法（仅当错误用法确实容易导致问题时，才会对比错误与正确的做法）。

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

相关技能

• ray-llm — 用于在 Ray 上提供 LLM 服务（ray.serve.llm）和批量推理（ray.data.llm）的配套规则包
• mlflow-3 — 实验跟踪和模型注册表；与 Ray Train 搭配，负责 MLOps 周期中的跟踪部分

参考文件

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