Ray Starter Templates 模板体系全解析：从 5 大示例到新增模板的完整流程-酒店常州论坛

Ray Starter Templates 模板体系全解析：从 5 大示例到新增模板的完整流程

【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址: https://gitcode.com/gh_mirrors/ra/ray

Ray Starter Templates 是 Ray 仓库内置的一套"最小化示例"集合，以开箱即跑、便于定制为设计目标，覆盖批量推理、多模型训练、生成式 AI 服务化与大模型微调等热门 AI 应用场景。本文以 doc/source/templates/README.md 为核心骨架，逐一拆解 5 个官方模板的实现思路与运行配置，并给出向该集合贡献新模板的完整操作流程，帮助读者快速复用这些骨架代码，或把自有业务逻辑接入 Ray 分布式运行时。

模板定位：可替换业务逻辑的最小化骨架

按照 templates/README.md 的定位，这些模板不是完整应用，而是骨架（skeleton）：

每个模板都是最小化的示例，运行快捷、易于定制；
模板可能包含少量框架特有代码（例如 PyTorch、Hugging Face Diffusers），但各代码块均设计为可被你自己的应用逻辑整体替换；
模板只负责"展示 Ray 的热门应用方式"，例如分布式数据预处理、分布式训练、模型服务化与大规模参数微调。

因此，使用模板的正确姿势是：先跑通官方示例验证集群与环境，再逐步把示例中的业务代码块替换为真实业务实现。模板代码与配置均存放在 doc/source/templates 目录下，其发布版本同步镜像在 release/workspace_templates。

当前仓库中共有 5 个官方模板，覆盖 Ray 四大核心能力：

模板目录	主题	使用的 Ray 模块
01_batch_inference	GPU 批量图像推理	Ray Data
02_many_model_training	海量时序模型并行训练	Ray Tune
03_serving_stable_diffusion	Stable Diffusion 模型服务化	Ray Serve
04_finetuning_llms_with_deepspeed	Llama-2 系列大模型微调	Ray Train（TorchTrainer）
05_dreambooth_finetuning	DreamBooth 个性化微调	Ray Train + Ray Data

五个官方模板逐个拆解

1. 批量图像推理：Ray Data 驱动的 10k 图像分类

01_batch_inference/README.md 演示了用 Ray Data 在 GPU 上对约 1 万张图片执行 PyTorch 模型推理的全过程，核心规格如下：

项目	说明
总结	对图像数据集执行 GPU 批量推理
运行时长	对数据集完成推理预测少于 5 分钟
最低算力	无硬性要求；默认 4 个节点、每节点 1 块 NVIDIA T4 GPU
集群环境	基于 Anyscale 提供的 Python 3.9 Ray ML 镜像；若更换集群环境，需确保基于该镜像

启动工作区后，直接打开模板目录下的start.ipynb按步骤执行即可。该模板的核心价值在于演示如何把"单机单卡推理"改写为"分布式数据并行推理"——通过 Ray Data 将图片数据集分片分发到多个 GPU 节点，以数据并行方式提升吞吐。它的入口笔记本与 README 分别位于 doc/source/templates/01_batch_inference/start.ipynb 与 doc/source/templates/01_batch_inference/README.md。

2. 海量模型训练：Ray Tune 并行拟合数百个时序模型

02_many_model_training/README.md 演示如何用 Ray Tune 并行训练数百个时序预测模型：它使用statsforecast库，对 M4 预测竞赛数据集的不同分区分别拟合模型，最终在交叉验证指标上选出最优模型并生成预测。

项目	说明
总结	用 Ray Tune 并行化数百个时序预测模型的训练
运行时长	训练全部模型约 5 分钟
最低算力	无硬性要求；默认 8 个节点、每节点 8 个 CPU
集群环境	基于 Ray ML 镜像，并在其上额外安装`requirements.txt`中列出的依赖

该模板的附加依赖见 doc/source/templates/02_many_model_training/requirements.txt。与"一个任务用多卡"的常规分布式训练不同，这里展示的是"多任务并行"（many-model training）模式：每个模型训练是一个独立 Trial，由 Ray Tune 统一调度到集群各节点并行执行，是超参数搜索、多租户实验等场景的典型范式。

3. 生成式 AI 服务化：Ray Serve 部署 Stable Diffusion

03_serving_stable_diffusion/README.md 演示了如何将 Hugging Face 上的预训练 Stable Diffusion 模型包装为生产级服务，是模板中唯一覆盖"训练/推理之外的服务化上线"的示例。

项目	说明
总结	为预训练 Stable Diffusion 模型提供一键生产化部署方案，基于 Ray Serve 本地部署，并用 CLI 发布到生产环境
运行时长	首次搭建模型并生成首批图像约 2 分钟；此后每轮生成不足 10 秒（取决于图像尺寸）
最低算力	至少 1 个 GPU 节点，每节点 1 块 NVIDIA A10 GPU
集群环境	基于 Anyscale 提供的 Ray 2.9 Python 3.9 镜像（cu118）构建的 Docker 镜像

交互式生成：模板目录下运行start.ipynb，即可获得如下交互式命令行体验：

Enter a prompt (or 'q' to quit): twin peaks sf in basquiat painting style Generating image(s)... Generated 4 image(s) in 8.75 seconds to the directory: 58b298d9

FastAPI 服务化部署：模板自带生产级 FastAPI 服务（app.py），本地启动并查询：

serve run app:entrypoint python query.py

生产环境发布：

anyscale service rollout -f service.yaml --name {ENTER_NAME_FOR_SERVICE}

发布后可从日志中拿到服务控制台链接，并通过 OpenAPI 文档页面调用/imagine接口：在 "Deployments" 中找到 "APIIngress"，点击 "View" 下的 "API Docs" 打开渲染文档，再对/imagine端点点击 "Try it out" 交互式填写 prompt 并执行。

集群环境定制（附录）：模板提供两种方式——在 Anyscale 上直接修改 cluster_env.yaml 构建新集群环境；或基于现有镜像手工构建 Docker 镜像。从 cluster_env.yaml 可以看到典型的 Ray 集群环境定义：base_image指定基础镜像（anyscale/ray:2.9.0-py39-cu118），python.pip_packages声明diffusers、torch、transformers、accelerate、fastapi等关键依赖及其版本锁定。

4. 大模型微调：DeepSpeed ZeRO-3 + TorchTrainer 微调 Llama-2

04_finetuning_llms_with_deepspeed/README.md 是仓库中技术含量最高的模板，演示使用 Ray Train 的 TorchTrainer 配合 DeepSpeed ZeRO-3 策略，对 Llama-2 系列（7B/13B/70B）执行全参数微调与 LoRA 微调。该目录包含完整的训练工具链：finetune_hf_llm.py、run_llama_ft.sh、create_dataset.py、create_job_yaml.py、merge_lora_weights.py，以及位于 deepspeed_configs 的 ZeRO-3 配置（含 NVMe offload 变体）与 lora_configs/lora.json。

推荐的集群配置（A100 不可用时的替代选型）：

模型	Head 节点	Worker 节点	启动命令
7B	1 × m5.xlarge	16 × g5.4xlarge（1×A10G, 24GB）	`./run_llama_ft.sh --size=7b [--as-test]`
13B	1 × m5.xlarge	4 × g5.12xlarge（4×A10G, 24GB）	`./run_llama_ft.sh --size=13b [--as-test]`
70B	1 × m5.xlarge	4 × g5.48xlarge 或 2 × p4de.24xlarge	参考`compute_configs`下的 YAML

--as-test标志仅用于演示/测试，只跑一次前向与反向传播，但模型加载与远程 checkpoint 逻辑仍会完整执行。

官方实测的训练性能（Anyscale 平台，单 epoch，3.5M tokens）：

模型	Base HF Model ID	每设备 batch size	GPU	每 epoch 时长
7B	`meta-llama/Llama-2-7b-hf`	16	16×A10G (24G)	~14 分钟
13B	`meta-llama/Llama-2-13b-hf`	16	16×A10G (24G)	~26 分钟
70B	`meta-llama/Llama-2-70b-hf`	8	32×A10G (24G)	~190 分钟

全参数微调：

./run_llama_ft.sh --size=7b

LoRA 微调（更省资源、可解锁更小实例类型与更高效的模型服务）：

./run_llama_ft.sh --size=7b --lora

LoRA 微调产出的 checkpoint 只包含微调权重（默认配置下 7B/13B/70B 分别约 42/64/202MB）。如需得到完整模型，可用合并脚本把微调权重与原权重合并（该脚本 CPU 内存需求较高，7B/13B/70B 分别约需 13GB/24GB/152GB RAM）：

python merge_lora_weights.py --model-name=7b --checkpoint=<path to your checkpoint> --output-path=<desired output path>

集群选型的两条关键经验（README 明确给出的工程准则）：

优化器/参数 offload 的 CPU RAM 需求：模板默认启用 DeepSpeed Zero-offload，将优化器或参数状态卸载到 CPU 内存。经验规则是约需O(18M/N*K)CPU RAM（M 为模型大小、N 为分片数、K 为单机 GPU 数）。例如 70B 模型在 8×A100 单机 8 路分片下需要约 1.26TB，单机无法满足；改用两台 8×A100（16 路分片）则降至约 630GB。
checkpoint 聚合的 CPU RAM 需求：训练中 checkpoint 时需将各分片权重聚合回 rank 0，accelerate 实现经验上需要O(4M)CPU RAM（70B 约 280GB，仅 rank 0 所在机器需要）。因此需要把 rank 0 调度到大内存机型上——模板通过自定义标签实现：在集群配置中为满足要求的机型打上large_cpu_mem标签，再在ScalingConfig中声明该资源：

scaling_config=air.ScalingConfig( # "large_cpu_mem" 是集群配置中用于标识该机型的标签 trainer_resources={"large_cpu_mem": 0.01}, num_workers=args.num_devices, use_gpu=True, resources_per_worker={"GPU": 1}, )

数据集格式与预处理：训练脚本要求提供jsonl格式的 train/test 数据集与一个记录特殊 token 的json文件。例如每行数据形如：

{"input": "<ASSISTANT>How can I help you?</ASSISTANT><USER>how is the weather?</USER>}

特殊 token 文件形如：

{"tokens": ["<ASSISTANT>", "</ASSISTANT>", "<USER>", "</USER>"]}

模板默认配置为在 GSM8K（Grade School Math 8k）数据集上训练，运行python create_dataset.py会生成三个必需文件：data/train.jsonl（约 7.4k 条）、data/test.jsonl（约 1.3k 条）与tokens.json。训练上下文长度固定为 512，因此整个训练集约合 3.5M tokens。

checkpoint 与云端存储：训练期间通过 Ray Train Checkpointing 将各节点产生的 checkpoint 同步回集中式云存储（AWS S3），最终文件结构以 Hugging Face 格式组织（config.json、model.safetensors、tokenizer.json等），可直接把 checkpoint 路径交给部署侧进行模型服务。

提交生产作业：生成作业 YAML 并提交：

python create_job_yaml.py --size=7b --output-path=./job.yaml anyscale job submit job.yaml

查看全部训练参数：

python finetune_hf_llm.py --help

5. 个性化微调：Ray Train 数据并行训练 DreamBooth

05_dreambooth_finetuning/README.md 演示 DreamBooth 风格的 Stable Diffusion 个性化微调：使用 Ray Train 做多 worker 数据并行训练、Ray Data 做数据摄取，只需输入文本 prompt，即可在多种场景下生成指定主体的图像。

项目	说明
总结	用 Ray Train 对 Stable Diffusion 做 DreamBooth 微调，可使用内置数据集或自己的照片
运行时长	生成正则化数据集并完成微调约 10～15 分钟
最低算力	至少 1 块 ≥24GB 显存的 GPU；默认 1 节点 4 卡（AWS 用 A10G，GCE 用 L4）
集群环境	基于 Anyscale Ray Python 3.9 镜像（cu118）构建的 Docker 镜像

一键启动（默认在示例小狗数据集上微调）：

chmod +x ./dreambooth_run.sh ./dreambooth_run.sh

关键定制变量（README 逐一说明的dreambooth_run.sh修改点）：

主体数据集：通过$CLASS_NAME与$INSTANCE_DIR指定；可用自带 4～5 张照片作为主体图像并声明其所属大类（例如小狗数据集的主体类别是dog）；
$DATA_PREFIX：预训练模型下载目录，同时也是训练数据集与微调 checkpoint 的写出位置；增加 worker 节点后应指向共享 NFS（如/mnt/cluster_storage）；每次运行会覆盖上次 checkpoint，若需保留历史结果请每次更换该变量；
$NUM_WORKERS：数据并行 worker 数，默认 2（2 worker 各用 1 卡），增加 GPU worker 节点时应同步调大；
训练步数：--num_epochs与--max_train_steps共同决定微调步数，二者任一达到即终止；
图像生成：generate.py从 checkpoint 加载模型生成图像，可把 prompt 改成更有趣的文本；
再次微调：如只想重新微调，可只执行python train.py ...，避免重新生成正则化数据集。

LoRA 微调命令（注意此处学习率显著更高）：

python train.py \ --model_dir=$ORIG_MODEL_PATH \ --output_dir=$TUNED_MODEL_DIR \ --instance_images_dir=$IMAGES_OWN_DIR \ --instance_prompt="photo of $UNIQUE_TOKEN $CLASS_NAME" \ --class_images_dir=$IMAGES_REG_DIR \ --class_prompt="photo of a $CLASS_NAME" \ --train_batch_size=2 \ --lr=1e-4 \ --num_epochs=10 \ --max_train_steps=400 \ --num_workers $NUM_WORKERS \ --use_lora

与微调后模型交互：既可用脚本批量生成（python generate.py --model_dir=... --output_dir=... --prompts="photo of a $UNIQUE_TOKEN $CLASS_NAME" --num_samples_per_prompt=5，LoRA 模型需改用--lora_weights_dir=$TUNED_MODEL_DIR并指向原模型路径），也可在playground.ipynb中以交互式小部件生成（注意该笔记本的小部件在 VS Code 中不可用，请使用 Jupyter）。flags.py中的run_model_flags提供了完整的命令行参数清单。

集群环境与算力配置的共享约定

模板目录下的 configs/compute 提供了可复用的共享算力配置，按 CPU / GPU 与云厂商（AWS / GCE）拆分。以 configs/compute/gpu/aws.yaml 为例：

# 3 g5.4xlarge nodes --> 48 CPUs, 3 GPUs head_node_type: name: head_node_type instance_type: g5.4xlarge worker_node_types: - name: gpu_worker instance_type: g5.4xlarge min_workers: 0 max_workers: 3 use_spot: false

测试专用的集群环境定义位于 doc/source/templates/testing/cluster_envs，其中 default_cluster_env_nightly_ml_py39.yaml 展示了 release 测试环境的核心约定：基于anyscale/ray-ml:nightly-py39-gpu镜像，并在post_build_cmds中卸载并安装{{ env["RAY_WHEELS"] }}指定的 Ray wheel——这是 CI 注入每日构建版本的关键机制。而 doc/source/templates/testing/compute_configs/cpu/aws.yaml 则展示了 release 测试算力配置的占位符用法：cloud_id: {{ env["ANYSCALE_CLOUD_ID"] }}与 region 由 CI 基础设施运行时填充。

新增一个模板：五步贡献流程

templates/README.md 给出了向 Ray 官方模板集合贡献新模板的完整流程：

第 1 步：在doc/source/templates下创建模板目录

推荐目录结构如下：

ray/ doc/source/templates/ <name-of-your-template>/ README.md <name-of-your-template>.ipynb requirements.txt (可选) templates.yaml

模板不必须是 Jupyter notebook——也可以是带README运行说明的 Python 脚本。

第 2 步：在 release 测试配置中登记模板

在 release/release_tests.yaml 中为模板添加 release 测试（AWS 与 GCE 双云）；Data 相关测试则登记到 release/release_data_tests.yaml。需要注意 release 测试的集群环境与算力配置与普通工作区略有差异，应使用 doc/source/templates/testing 目录下的文件：release 测试的算力配置中包含 region 与 cloud id 占位符（由 CI 基础设施填充），集群环境会构建包含全部依赖的 nightly Docker 镜像。仓库 release/release_tests.yaml 中air_example_dreambooth_finetuning等条目即为此类模板测试的登记实例（含working_dir、cluster_compute、script等字段）。

第 3 步：在templates.yaml中登记入口

在doc/source/templates/templates.yaml中新增指向模板的条目（README 说明该文件顶部有可直接复制填写的模板）。配置模板的算力配置时，优先复用 doc/source/templates/configs 中的共享配置，也可按相同格式创建自定义配置。

依赖处理的两条约定：

若模板依赖基础镜像未包含的软件包，需在 notebook 内给出安装说明与命令（参考 02_many_model_training 的做法，其 requirements.txt 以显式依赖清单方式声明）；
若模板需要自定义 Docker 镜像，必须在README中说明并给出镜像 URL（参考 03_serving_stable_diffusion，其 cluster_env.yaml 与 testing/docker 下的 Dockerfile 构成镜像构建证据）。

第 4 步：运行校验脚本

对templates.yaml运行校验脚本，确认所有路径有效、所有 YAML 格式正确：

$ python doc/source/templates/testing/validate.py Success!

第 5 步：提交评审

校验通过后即可提交流程进入评审。README 末尾还以注释形式保留了一段早期（2.5 之前）的测试约定——为模板准备含测试代码的副本并用remove-cell标签标记、在doc/BUILD的 templates 段注册冒烟测试（设置SMOKE_TEST环境变量让模板适配单个 CI 实例，并按需添加gpu等 tag）。这些内容现已注释掉，说明模板测试机制已演进为以templates.yaml+ release 测试为主的现行方案。

小结：模板体系的设计意图

纵观 5 个模板与贡献流程，可以提炼出 Ray Starter Templates 的三层设计意图：

快速上手层：每个模板都是"能跑的最小示例"，让用户在 5 分钟内（批量推理、多模型训练）到 15 分钟内（DreamBooth）获得可验证的分布式运行结果；
场景覆盖层：模板刻意覆盖 Ray 的核心能力矩阵——Ray Data（数据并行批处理）、Ray Tune（多任务并行）、Ray Serve（模型服务化）、Ray Train（数据并行训练与大模型微调），每个模板对应一类典型的生产模式；
可持续扩展层：通过templates.yaml登记 + release 测试 + 校验脚本的机制，社区贡献者可以按统一规范持续扩充模板集合，并保证每个模板在 CI 中可验证、可发布。

对于希望在自有机房或云环境中落地分布式 AI 应用的开发者，最直接的路径是：先选择一个与你业务形态最接近的模板跑通（仓库内可直接查看 doc/source/templates 下的全部源码与配置），再按照模板骨架逐步替换业务逻辑，最后参考第 4 个模板的集群选型经验（CPU offload 与 checkpoint 的内存预算）规划生产集群。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析