NASP/argus-cluster
53
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
argus-cluster/specs/mvp/v1.1/v1.1_action.md
yuyr c405adc4fc mvp v1.1 save
2025-12-23 14:22:15 +08:00

16 KiB
Raw Blame History

MVP v1.1 行动文档（实施方案 / 部署测试 / 验收口径）

本文档面向“把 v1 跑通的实验脚本，升级为可长期回归的 v1.1 最小系统”，并给出开发改造 → 部署测试 → 验收的可复现流程。

v1.1 的核心约束（来自讨论结论）

  • 仍然必须通过 head 节点执行 ray job submit 提交任务。
  • 训练/driver 必须落在 worker（head 不跑训练）。
  • 多版本 verl 共存：同一镜像不变，必须通过 Ray Job runtime_env.env_vars 注入 PYTHONPATH 让 job 粒度选择代码版本。
  • 存储只考虑 NFS：dev 环境我们自己 mount；生产环境容器内统一看到 /private/。

1. 目标与非目标

1.1 目标（v1.1 必须做到）

  1. 可回归：同一环境连续跑多次 PPO 回归，不互相覆盖，输出按 submission id 归档。
  2. 可扩展：新增并验收通过 2 个 workload（GRPO + SFT）并跑通闭环。
  3. 可排障：每个 job 目录包含完整的提交快照、关键 env、Ray 状态快照与日志入口。
  4. 可多版本共存：同一 Ray 集群内，不同 job 通过 PYTHONPATH 选择不同 verl 代码快照。

1.2 非目标（v1.1 不做）

  • 不做平台 API/队列/多租户/RBAC（这是 v2/v3）。
  • 不做复杂调度（拓扑、IB 域、NUMA、Gang 等自动化策略）。

2. 运行环境约定（dev / prod 一致抽象）

2.1 拓扑（单机 3 容器）

  • mvp-ray-head：无 GPU，ray start --head --num-cpus=0 --num-gpus=0（控制面 only）
  • mvp-ray-worker-0：4 GPU
  • mvp-ray-worker-1：4 GPU

2.2 “head 不跑训练”的硬约束实现（必须）

  1. head CPU=0：从资源层面阻断默认 task/driver 落到 head。
  2. worker 自定义资源标签：worker 启动时带 --resources='{"worker_node": 100}'。
  3. ray job submit 强制 entrypoint 落 worker：提交时必须带：
    • --entrypoint-resources='{"worker_node": 1}'
    • --entrypoint-num-cpus=1（显式声明 driver 需要的 CPU）

验证口径：ray job list 的 driver_info.node_ip_address 必须是 worker 的 IP，而不是 head IP。

2.3 共享存储（NFS）与路径（关键）

  • 生产环境：容器内共享根路径固定为 /private/（算力平台统一挂载 NFS）。
  • 开发环境：docker compose 也应把宿主机共享目录挂载到容器内的 /private/，从而做到 dev/prod 一致。

统一约定（容器内视角）：

  • SHARED_ROOT=/private
  • Job 输出：${SHARED_ROOT}/jobs/<submission_id>/

建议的共享目录结构（v1.1 新增 common/ 与 user/）：

  • ${SHARED_ROOT}/datasets/：通用数据（例如 gsm8k parquet）
  • ${SHARED_ROOT}/hf/：HuggingFace cache（模型/分词器/权重）
  • ${SHARED_ROOT}/jobs/：按 submission id 归档的作业目录（强制）
  • ${SHARED_ROOT}/outputs/：临时/非强约束输出（不建议长期依赖）
  • ${SHARED_ROOT}/ray/：Ray 调试痕迹（可选，通常 Ray 默认写 /tmp/ray）
  • ${SHARED_ROOT}/common/：所有用户可读写共享区（模型/数据/代码快照）
    • ${SHARED_ROOT}/common/models/：可复用基础模型（可用软链指向 hf cache 或 snapshot）
    • ${SHARED_ROOT}/common/datasets/：共享数据（或与 datasets/ 统一规划）
    • ${SHARED_ROOT}/common/code/：代码快照（多版本 verl / 自定义 reward）
  • ${SHARED_ROOT}/user/：用户自定义内容（默认所有用户可写）
    • ${SHARED_ROOT}/user/code/：reward_fn 等自定义 Python 代码

3. 开发实施方案（代码改造清单）

v1.1 建议新增 src/mvp/v1.1/（保持 v1 可回归不被破坏）。

3.1 JobSpec（最小标准化）

v1.1 的工程化目标是把“提交机制”迁移到 Ray Python SDK，因此输入拆为两份 YAML：

  1. Ray 基础配置（YAML）：address / entrypoint resources / runtime_env 等
  2. 训练 JobSpec（YAML）：workload 语义与训练参数（仍由 Hydra overrides 组织）

训练 JobSpec（YAML）至少包含：

  • submission_id：可空；为空时由 submitter 生成（但最终必须显式传给 ray job submit --submission-id）
  • workload：ppo / grpo / sft（v1.1 必须 ppo + grpo + sft）
  • shared_root：默认 /private（容器内路径）
  • code_path：verl 代码快照目录（用于多版本共存）
  • reward_fn_path（可选）：指向 ${shared_root}/user/code/... 下的 Python 文件或模块入口
  • model / dataset：必须指向共享存储的持久化路径（避免每次下载/生成）
  • ray：address=http://127.0.0.1:8265（从 head 容器内部视角）
  • resources：
    • entrypoint_resources={"worker_node":1}
    • entrypoint_num_cpus=1
  • trainer_overrides：训练参数覆盖（v1.1 默认 total_epochs=1、save_freq=10）
  • env_vars：会被透传到 runtime_env.env_vars（必须包含 PYTHONPATH 注入）

交付物（v1.1 SDK 方式）：

  • src/mvp/v1.1/py/configs/dev.yaml（Ray 基础配置示例）
  • src/mvp/v1.1/py/jobspecs/{ppo,grpo,sft}.yaml（训练 JobSpec 示例）
  • src/mvp/v1.1/py/run.py（入口：使用 Ray Python SDK 提交/查询/停止/拉日志）
  • 设计文档：specs/mvp/v1.1/sdk_submit_refactor.md

3.2 多版本 verl 共存（必须）

原则：镜像固定不变；job 粒度通过 PYTHONPATH 选择 verl 代码快照。

提交时必须注入（runtime_env）：

  • PYTHONPATH="<CODE_PATH>:$PYTHONPATH"（CODE_PATH 放最前面）

并要求 job 在日志中打印一行确认 import 来源，例如：

  • python -c "import verl,inspect; print(verl.__file__)"（或训练入口启动时打印）

v1.1 具体实现（可复现）：

  • 先用 src/mvp/v1.1/scripts/31_snapshot_verl_code.sh 生成代码快照目录 ${SHARED_ROOT}/common/code/verl/<code_id>/
    • 该目录里会包含一个 mvp_marker.py（MARKER=<code_id>）
  • 提交 job 时让 code_path 指向该快照目录；submitter 会在 entrypoint 前打印：
    • MVP_PRECHECK_VERL_FILE（验证 import 来源）
    • MVP_PRECHECK_MARKER（验证选择的 code_path）

3.3 submit_job 工具（组装 ray job submit）

新增一个提交器（建议 Python，避免复杂 bash quoting）：

  • 输入：JobSpec JSON
  • 产物：
    • 生成/确定 submission_id
    • 创建 ${SHARED_ROOT}/jobs/<id>/config/、logs/、checkpoints/
    • 写入 config/job_spec.json（原样快照）
    • 写入 config/runtime_env.json（最终用于 submit 的 JSON）
    • 写入 config/submit_cmd.txt（最终命令行）
  • 执行：在 head 容器内运行 ray job submit ...

3.4 可排障：debug bundle（强制落盘）

在 job 生命周期的关键节点收集并落盘（至少 2 类）：

  • ray status
  • ray job list
  • ray list nodes
  • ray list actors

建议落盘到：

  • ${SHARED_ROOT}/jobs/<id>/debug/（每次收集带时间戳文件名）

3.5 Workload 扩展：GRPO（v1.1 新增闭环）

优先用与 PPO 相同入口 python -m verl.trainer.main_ppo，仅通过配置切换算法：

  • algorithm.adv_estimator=grpo
  • 其余保持最小可跑：total_epochs=1、save_freq=10

3.6 Workload 扩展：SFT on Ray（v1.1 必须新增闭环）

3.6.1 入口与参考实现

  • 入口：python -m verl.trainer.sft_trainer_ray
  • 参考代码：verl/verl/trainer/sft_trainer.py（非 Ray 版本）与 verl/verl/trainer/sft_trainer_ray.py（Ray 版本）

v1.1 要验收的是 “SFT on Ray”，因此默认使用 sft_trainer_ray.py。

3.6.2 连接已有 Ray 集群（必须）

sft_trainer_ray.py 内部直接调用 ray.init()，为了确保它连接到已有集群（head+workers），v1.1 约定：

  • 提交 job 时通过 runtime_env.env_vars 注入：RAY_ADDRESS=auto

如果发现 ray.init() 未按预期读取 RAY_ADDRESS（Ray 版本差异风险），v1.1 需要提供一个 launcher 兜底：

  • 由 launcher 先显式 ray.init(address="auto")，再调用 SFT trainer 逻辑

3.6.3 SFT 数据格式（parquet schema）

sft_trainer_ray 默认使用 MultiTurnSFTDataset，parquet 中至少需要：

  • messages 列：list[dict]，dict 至少含 role/content

v1.1 的 prepare 阶段需要生成并持久化 SFT 数据，例如：

  • ${SHARED_ROOT}/datasets/gsm8k_sft/train.parquet
  • ${SHARED_ROOT}/datasets/gsm8k_sft/val.parquet（可选）

单条样本的 messages 形态示例：

  • [{ "role": "user", "content": "<question>" }, { "role": "assistant", "content": "<answer>" }]

注意：SFT parquet 不能直接复用 PPO/RL 的 parquet（schema 不同）。

3.6.4 重要细节：SFT Ray Driver 不应依赖 GPU

在 ray job submit 模式下，我们的 entrypoint（driver）默认 不会分配 GPU（我们只指定了 --entrypoint-num-cpus=1，没有指定 --entrypoint-num-gpus）。

而 verl/verl/trainer/sft_trainer_ray.py 的 driver 逻辑里会用 trainer.device 来创建 torch.tensor(..., device=...) 做统计，如果设置为 cuda 且 driver 没有 GPU，会触发：

  • RuntimeError: No CUDA GPUs are available

因此 v1.1 的 SFT on Ray 验收默认要求：

  • trainer.device=cpu（driver 只做 orchestration；真正训练仍由 Ray 的 TrainingWorker/资源池占用 GPU）

3.7 v1.1 脚本化交付（必须独立完整）

src/mvp/v1.1/ 需要像 v1 一样提供一套完整脚本，确保 v1.1 可独立运行、可回归：

  • src/mvp/v1.1/docker-compose.yaml（容器名建议与 v1 区分，避免冲突）
  • src/mvp/v1.1/scripts/00_prereq_check.sh（含 GPU/目录/NFS/verl 代码检查）
  • src/mvp/v1.1/scripts/01_up.sh / 02_down.sh（起停）
  • src/mvp/v1.1/scripts/20_start_head.sh / 21_start_workers.sh
  • src/mvp/v1.1/scripts/30_prepare_data_and_model.sh（包含 PPO 数据 + SFT 数据）
  • src/mvp/v1.1/scripts/40_submit_ppo_epoch1.sh
  • src/mvp/v1.1/scripts/41_submit_grpo_epoch1.sh
  • src/mvp/v1.1/scripts/42_submit_sft_minimal.sh
  • src/mvp/v1.1/scripts/50_status.sh
  • src/mvp/v1.1/scripts/31_snapshot_verl_code.sh（多版本 code snapshot）
  • src/mvp/v1.1/scripts/43_submit_jobspec.sh（通过 JobSpec 提交）
  • src/mvp/v1.1/scripts/12_install_py_deps.sh（安装 PyYAML 等依赖）
  • src/mvp/v1.1/scripts/44_submit_sdk.sh（通过 Ray Python SDK + YAML 提交）

4. 部署与测试流程（dev 环境）

dev 环境以远程机目录为例：argus@h1:/home2/argus/infra/mvp。v1.1 的所有内容要求放在：

  • argus@h1:/home2/argus/infra/mvp/v1.1/

并在该目录中通过脚本使用 docker exec 协调容器。

4.0 清理 v1 环境（必须先做）

v1 已在 argus@h1 部署过容器与 Ray。为保证 v1.1 的可重复测试，开始 v1.1 前必须清理 v1：

  1. 停止并删除 v1 容器（推荐用 v1 的 down 脚本）
  2. 确认 docker ps 中不再有 v1 的 mvp-ray-head/mvp-ray-worker-*

v1.1 的脚本里也提供了一个 best-effort 清理脚本：src/mvp/v1.1/scripts/03_cleanup_v1_legacy.sh（远程目录中同名脚本）。

4.1 环境准备（一次性 / 幂等）

  1. 目录检查（远程机）：
    • ${WORKDIR}/shared/ 存在并具备上述子目录（含 common/、user/）
  2. verl 代码目录检查：
    • ${WORKDIR}/verl 不存在则执行 git clone https://github.com/volcengine/verl.git
  3. GPU 可用性检查：
    • 设备存在（例如 0-7 可见），并按 worker 容器分配（每个 worker 4 GPU）
  4. 模型与数据持久化路径：
    • 模型与数据必须落在 ${SHARED_ROOT} 下；若已存在则跳过下载/生成
    • SFT parquet 同样必须落在 ${SHARED_ROOT} 下；若已存在则跳过生成

4.2 启动 Ray 集群（每次测试）

  1. docker compose up -d
  2. head：ray start --head --num-cpus=0 --num-gpus=0 ...
  3. workers：ray start --address=<head>:6379 --resources='{"worker_node":100}' ...
  4. 验证：ray status 显示 1 head + 2 worker，且 head CPU:0 GPU:0

4.3 提交 PPO 回归（必须跑 2 次）

  1. 生成 JobSpec（可用模板 + 覆盖项）
  2. 在 head 容器内执行 submitter（或直接 ray job submit）
  3. 验证要点：
    • ray job list：driver node 是 worker
    • ${SHARED_ROOT}/jobs/<id>/ 下存在 config/、logs/、checkpoints/
    • checkpoint 每 10 step 产生（例如 global_step_10）

4.4 提交 GRPO（新增 workload 验收）

同 PPO，但覆盖 algorithm.adv_estimator=grpo，确保能进入 RUNNING 并完成最小步数。

4.5 提交 SFT on Ray（新增 workload 验收，必须）

  1. 确认 ${SHARED_ROOT}/datasets/gsm8k_sft/train.parquet 已存在（由 v1.1 prepare 生成）。
  2. 通过 head 容器执行 ray job submit 提交 python -m verl.trainer.sft_trainer_ray。
  3. 关键约束：
    • runtime_env.env_vars.RAY_ADDRESS=auto（连接已有集群）
    • --entrypoint-resources='{"worker_node": 1}'（driver 落 worker）
    • PYTHONPATH=<code_path>:$PYTHONPATH（多版本 verl）
  4. 最小化训练配置建议（避免 OOM/耗时过长）：
    • trainer.total_epochs=1
    • trainer.total_training_steps=10~30
    • trainer.save_freq=10
    • trainer.nnodes=2、trainer.n_gpus_per_node=4（用满 8 卡做一次最小分布式验证）
    • data.train_files=${SHARED_ROOT}/datasets/gsm8k_sft/train.parquet
    • trainer.default_local_dir=${SHARED_ROOT}/jobs/<id>/checkpoints

4.6 工程化验证：JobSpec + 多版本共存（v1.1 必须）

  1. 生成两个 code snapshot（不同 CODE_ID）：
    • CODE_ID=codeA ./scripts/31_snapshot_verl_code.sh
    • CODE_ID=codeB ./scripts/31_snapshot_verl_code.sh
  2. 分别修改/复制 JobSpec 模板，使 code_path 指向不同 snapshot：
    • ${SHARED_ROOT}/common/code/verl/codeA
    • ${SHARED_ROOT}/common/code/verl/codeB
  3. 用 JobSpec 提交（必须从 head）：
    • ./scripts/43_submit_jobspec.sh /workspace/mvp/v1.1/templates/ppo.json（示例）
  4. 在 Ray job logs 中验证：
    • MVP_PRECHECK_MARKER 打印为对应的 codeA/codeB
    • MVP_PRECHECK_VERL_FILE 指向 ${SHARED_ROOT}/common/code/verl/... 而不是镜像内 site-packages

5. 验收标准（Definition of Done）

5.1 Hardening DoD（全部必选）

  • 提交必须来自 head：能在 head 容器内看到 ray job submit ... 的提交记录
  • driver 不在 head：ray job list 的 driver_info.node_ip_address ∈ worker IP，且 ≠ head IP
  • 输出目录按 submission id 隔离：${SHARED_ROOT}/jobs/<submission_id>/ 不复用、不覆盖
  • 数据/模型持久化：再次提交时不重复下载/生成（有 “skip if exists” 的日志）
  • checkpoint 策略有效：默认 save_freq=10，不会每 step 保存爆盘
  • debug bundle 落盘：${SHARED_ROOT}/jobs/<id>/debug/ 至少包含 2 类 Ray 状态快照
  • 多版本共存验证通过：日志中能确认 verl import 来源来自 JobSpec 指定的 code_path

5.2 Workload DoD（GRPO + SFT 都必须）

  • GRPO job 能提交、RUNNING、完成最小训练步数
  • GRPO job 产物目录满足与 PPO 相同的目录规范与 debug 规范
  • SFT job 能提交、连接已有集群并跑到至少 1 个 step（建议最小步数/epoch）
  • SFT job 产物目录满足与 PPO 相同的目录规范与 debug 规范

6. 生产环境部署注意事项（v1.1 需要考虑但不强制在 dev 全量模拟）

  • 容器由算力平台创建：我们只负责 SSH 进去纳管（启动 ray / 提交 job / 收集产物）。
  • 容器内共享路径为 /private：所有脚本必须以 SHARED_ROOT=/private 工作，不得写死 /mnt/shared。
  • 认证仅内部 token：在 submitter 中把 token 作为 env var 透传（不写入日志明文）。