argus-cluster/src/mvp/v1/README.md

MVP V1（Ray + VERL PPO）实验脚本

本目录用于在“宿主机 + Docker 容器”环境下，**用宿主机脚本（docker exec）**协调启动 Ray 集群，并通过 **ray job submit（在 head 提交）**跑通一次 verl 的 PPO 训练闭环（total_epochs=1），且数据/模型/日志/ckpt 都持久化到宿主机目录。

1. 运行环境与拓扑

1.1 依赖

• 宿主机：Linux
• 必需工具：docker、docker compose（Compose v2 插件）、git
• GPU：至少 8 张可用 GPU（索引 0-7），Docker 的 NVIDIA runtime 可用

1.2 集群拓扑（3 个容器）

• mvp-ray-head（Ray Head）
  • 不挂 GPU（容器内 nvidia-smi 不可用）
  • ray start --head --num-cpus=0 --num-gpus=0：head 只做控制面，不参与计算调度
  • 暴露 dashboard：宿主机端口 8265
• mvp-ray-worker-0（Ray Worker）
  • 4 GPU：0,1,2,3
  • ray start ... --resources='{"worker_node": 100}'
• mvp-ray-worker-1（Ray Worker）
  • 4 GPU：4,5,6,7
  • ray start ... --resources='{"worker_node": 100}'

关键点：driver 不在 head

• 作业通过 head 提交：ray job submit ...
• 通过 --entrypoint-resources='{"worker_node": 1}' 强制 entrypoint/driver 只能调度到 worker（head 没有该资源）

2. 持久化目录（宿主机 <-> 容器）

在宿主机项目根目录（运行脚本时的 ${PWD}）下使用 ./shared 做持久化根目录，并 bind mount 到容器内 /mnt/shared：

• 宿主机：./shared
• 容器：/mnt/shared

主要内容：

• 数据集：/mnt/shared/datasets/gsm8k/
• HF 缓存：/mnt/shared/hf/（脚本会设置 HF_HOME，并尽量幂等跳过重复下载）
• 每个 Ray Job 的输出（按 submission id 分目录）：
  • /mnt/shared/jobs/<submission_id>/logs/
  • /mnt/shared/jobs/<submission_id>/checkpoints/

3. 整体流程（代码逻辑）

脚本都在 src/mvp/v1/scripts/，整体顺序如下：

1. 00_prereq_check.sh
   • 检查 docker/docker compose/git
2. 05_ensure_verl_repo.sh
   • 若项目根目录下没有 ./verl，自动 git clone https://github.com/volcengine/verl.git
3. 01_up.sh
   • 创建持久化目录（./shared/...）
   • docker compose up -d 启动 3 个容器
4. 10_install_verl_editable.sh
   • 在 3 个容器内执行 pip install -e /workspace/verl（确保 python -m verl... 可用且代码与 ./verl 同步）
5. 20_start_head.sh
   • 在 mvp-ray-head 内启动 Ray head（CPU=0、GPU=0）
6. 21_start_workers.sh
   • 在两个 worker 内启动 Ray worker 加入集群
   • 同时给 worker 打 worker_node 自定义资源标签
7. 30_prepare_data_and_model.sh
   • 数据集：若 train.parquet/test.parquet 已存在则跳过，否则生成
   • 模型：使用 HF cache（HF_HOME=/mnt/shared/hf），存在则跳过，不存在才下载
8. 40_submit_ppo_epoch1.sh
   • 在 head 容器里执行 ray job submit
   • 显式指定 --submission-id=$SUBMISSION_ID
   • 通过 --entrypoint-resources='{"worker_node": 1}' 强制 driver 在 worker
   • 训练参数：
     • trainer.total_epochs=1
     • trainer.total_training_steps=29（GSM8K 该配置下对应 29 steps）
     • trainer.save_freq=10（每 10 step 保存一次 checkpoint，避免磁盘爆炸）
     • trainer.default_local_dir=/mnt/shared/jobs/$SUBMISSION_ID/checkpoints
     • hydra.run.dir=/mnt/shared/jobs/$SUBMISSION_ID/logs/hydra
9. 50_status.sh
   • 打印 ray status / ray job list / ray job status / ray job logs | tail

4. 运行方法

4.1 一键执行

在项目根目录执行：

• ./src/mvp/v1/scripts/run_all.sh

4.2 分步执行（推荐）

按顺序执行：

• ./src/mvp/v1/scripts/01_up.sh
• ./src/mvp/v1/scripts/10_install_verl_editable.sh
• ./src/mvp/v1/scripts/20_start_head.sh
• ./src/mvp/v1/scripts/21_start_workers.sh
• ./src/mvp/v1/scripts/30_prepare_data_and_model.sh
• SUBMISSION_ID=ppo_h20_8g_$(date +%Y%m%d_%H%M%S) ./src/mvp/v1/scripts/40_submit_ppo_epoch1.sh
• ./src/mvp/v1/scripts/50_status.sh

4.3 查看与停止

• Dashboard：http://<宿主机IP>:8265
• 列出作业（在 head 容器内）：
  • docker exec mvp-ray-head bash -lc "ray job list --address=http://127.0.0.1:8265"
• 停止某个 submission id：
  • docker exec mvp-ray-head bash -lc "ray job stop --address=http://127.0.0.1:8265 <submission_id>"

4.4 清理

• 停止并删除容器：./src/mvp/v1/scripts/02_down.sh
• 清理输出（谨慎，数据量可能很大）：删除 ./shared/jobs/<submission_id>/

5. 常见坑

• 不传 --submission-id 会导致“输出目录难以等于 submission id”：因为 hydra/ckpt 目录需要在提交前确定。当前脚本会显式传 --submission-id=$SUBMISSION_ID，并使用同名目录。
• checkpoint 太大：PPO 的 checkpoint 非常占空间。当前脚本默认 save_freq=10，如仍过大，可调大 save_freq 或减少保存内容/频率。

更多分步操作与验收标准见：specs/mvp/v1_action.md