argus-cluster/specs/mvp/v1/v1_action.md

MVP V1 远程实验行动文档（待确认后执行）

1. 任务复述（我理解的需求）

你希望我在远程机器 argus@h1 上，进入目录 /home2/argus/infra/mvp，把 MVP V1 的“原本流程”手动完整跑一遍并验证。要求：

1. 在宿主机上编写脚本，脚本通过 docker exec 在容器内执行命令，负责协调启动顺序（先 head、后 worker）。
2. 集群拓扑改为：
   • 1 个 Ray Head：没有 GPU，并且 Head 的 Ray 资源 CPU=0（防止 Ray 把训练任务调度到 head）。
   • 2 个 Ray Worker：各自 4 GPU（总 8 GPU）。
3. PPO 训练需要“轻量化”，把 total_epochs 改为 1。
4. 先在本地仓库 src/mvp/v1/ 写好脚本与 compose 文件；再拷贝到远程目录执行与验证。
5. 在你确认这份行动文档没问题之前，我不执行远程操作。

2. 本地已准备的文件（在本仓库内）

• src/mvp/v1/docker-compose.yaml：3 容器（head + 2 worker），head 不使用 nvidia runtime；worker0/1 各限制 4 GPU。
• src/mvp/v1/scripts/：宿主机脚本（内部全部用 docker exec）
  • 01_up.sh：起容器
  • 20_start_head.sh：启动 Ray head（--num-cpus=0 --num-gpus=0）
  • 21_start_workers.sh：启动 Ray worker 加入集群
  • 30_prepare_data_and_model.sh：准备 GSM8K 数据与预下载模型
  • 40_submit_ppo_epoch1.sh：提交 PPO（trainer.total_epochs=1，并设置 nnodes=2, n_gpus_per_node=4）
  • run_all.sh：按顺序一键执行

3. 远程环境前置条件（需要你确认/保证）

在 argus@h1 上：

• Docker 可用，且有 docker compose 插件（Compose v2）。
• NVIDIA runtime 可用（worker 容器需要 runtime: nvidia），宿主机有至少 8 张 GPU。
• 不强制要求提前准备 ./verl：脚本会在宿主机侧检查 ${PWD}/verl，如果不存在会自动执行：
  • git clone https://github.com/volcengine/verl.git

此外本实验默认写入持久化目录：/home2/argus/infra/mvp/shared（会自动创建）。

4. 拷贝到远程（我执行前会再次征求你确认）

从本地（本机）同步到远程：

1. 同步脚本与 compose：
   • rsync -av ./src/mvp/v1/ argus@h1:/home2/argus/infra/mvp/src/mvp/v1/
   • rsync -av ./specs/mvp/v1_action.md argus@h1:/home2/argus/infra/mvp/specs/mvp/v1_action.md
2. verl/ 默认不需要同步（远程会 clone）。如果你更希望固定版本/避免网络波动，也可以手动同步：
   • rsync -av --delete ./verl/ argus@h1:/home2/argus/infra/mvp/verl/

5. 远程执行步骤（在宿主机上）

在远程机器执行：

1. 进入目录：
   • cd /home2/argus/infra/mvp
2. 确保脚本可执行（首次同步后需要做一次）：
   • chmod +x ./src/mvp/v1/scripts/*.sh
3. 启动容器：
   • ./src/mvp/v1/scripts/01_up.sh
4. 安装 editable 版 verl（保证 python -m verl... 可用）：
   • ./src/mvp/v1/scripts/10_install_verl_editable.sh
5. 启动 Ray Head（禁止调度到 head）：
   • ./src/mvp/v1/scripts/20_start_head.sh
6. 启动两个 Ray Worker 加入集群：
   • ./src/mvp/v1/scripts/21_start_workers.sh
7. 准备数据 + 预下载模型（落到 ./shared）：
   • ./src/mvp/v1/scripts/30_prepare_data_and_model.sh
8. 提交 PPO（total_epochs=1，必须用 ray job submit 在 head 提交；通过 --entrypoint-resources 强制 driver 调度到 worker）：
   • ./src/mvp/v1/scripts/40_submit_ppo_epoch1.sh
9. 观察状态：
   • ./src/mvp/v1/scripts/50_status.sh
   • 打开 Ray Dashboard：http://<h1宿主机IP>:8265

也可以一键跑：

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

6. 验收与验证点（执行时我会逐项检查）

1. Head 节点无 GPU：在 head 容器内 nvidia-smi 应不可用或无设备（worker 内可见 4 张）。
2. Head 的 Ray 逻辑资源为 CPU=0, GPU=0：head 不应承载训练任务调度资源（通过 ray start --num-cpus=0 --num-gpus=0）。
3. 集群节点数量正确：ray status 中应看到 1 head + 2 worker。
4. PPO driver 不在 head：ray job list 里该 submission_id 的 driver_info.node_ip_address 应该是 worker 的 IP（172.19.0.3/172.19.0.4），不能是 head（172.19.0.2）。
5. PPO 训练只跑 1 个 epoch：提交参数包含 trainer.total_epochs=1。
6. checkpoint 落盘：/mnt/shared/jobs/<job_id>/checkpoints/ 有产物（脚本通过 trainer.default_local_dir 强制指向该目录；不设置 trainer.default_hdfs_dir）。
7. 数据与缓存落盘：/home2/argus/infra/mvp/shared/ 下出现 datasets/hf/jobs 等目录。

补充（磁盘保护）：

• checkpoint 不要每步保存（会非常占空间）；当前脚本默认 trainer.save_freq=10（每 10 step 保存一次）。

10. 目录命名约定（submission id）

• 脚本默认会显式指定 ray job submit --submission-id=$SUBMISSION_ID，并使用同一个值作为输出目录名：
  • 输出目录：/mnt/shared/jobs/$SUBMISSION_ID/
• 你可以在提交时自定义 ID（推荐这样便于检索）：
  • SUBMISSION_ID=my_run_20251219_001 ./src/mvp/v1/scripts/40_submit_ppo_epoch1.sh

7. 风险点与兜底

• 如果 runtime: nvidia 在该环境不生效：需要改成 compose 的 gpus: 写法（我会按远程 docker 版本调整）。
• 如果 Ray Jobs 的 driver 必须在 head 启动（Ray 机制如此）：这不影响“训练任务不调度到 head”，但 head 仍会有一个 job driver 进程。
• 如果 verl 在镜像内已安装但版本不匹配：脚本会优先 pip install -e /workspace/verl 以保证行为一致。

8. 你需要确认的 3 个问题（你已确认，我按此执行）

1. verl/：脚本会在远程自动 git clone https://github.com/volcengine/verl.git（如你希望固定版本，可改成同步或 checkout tag/commit）。
2. GPU：0-7 可用（worker0 用 0-3，worker1 用 4-7）。
3. PPO：用满 8 GPU（nnodes=2, n_gpus_per_node=4）。

9. 你新增的关键要求（我已纳入脚本）

• 数据与模型必须落在 /mnt/shared（由宿主机 ./shared bind mount 提供），并且具备幂等：
  • 数据：如果 train.parquet/test.parquet 已存在则跳过下载。
  • 模型：优先检测本地 cache（HF_HOME=/mnt/shared/hf）；存在则跳过，否则才下载。
• 提交 job 时显式注入 HF_HOME/HUGGINGFACE_HUB_CACHE/TRANSFORMERS_CACHE，确保训练使用持久化缓存与数据路径。