argus-cluster/specs/mvp/v3.7/v3.7_summary.md

MVP v3.7 迭代总结：切换 vLLM rollout + verlai/verl:vllm011.latest

基线版本：v3.6（W&B + SFTPGo + WebUI/API + Ray stateless pool + Advanced TaskSpec）
验证环境：argus@h1:/home2/argus/infra/mvp

1. 目标与结果

1.1 本次目标

1. Ray 节点镜像切换到 vLLM 版本：

• base image：verlai/verl:vllm011.latest
• 构建镜像 tag：argus/argus-ray-node:vllm011.latest

2. 平台内置 PPO/GRPO 默认 rollout backend 全量切换：

• actor_rollout_ref.rollout.name=sglang → actor_rollout_ref.rollout.name=vllm

3. 端到端验证：

• 使用 src/mvp/scripts/run_all_v30_api.sh 在 h1 上跑通 E2E（通过 API 提交 PPO/GRPO/SFT）

1.2 实际结果（验收）

• h1 上已成功构建并使用新镜像拉起（head + 2 worker）：
  • docker ps 显示 argus-ray-head/worker-* 使用 argus/argus-ray-node:vllm011.latest
• run_all_v30_api.sh 端到端跑通：
  • PPO/GRPO/SFT 任务均 SUCCEEDED
• 在 job submit payload 中验证关键点：
  • actor_rollout_ref.rollout.name=vllm
  • HF_HUB_OFFLINE=1（见 §3.2）

---

2. 代码与配置改动点

2.1 训练默认参数（sglang → vllm）

• src/mvp/py/argus/ray/builders.py
  • 将 PPO/GRPO 默认参数中的 actor_rollout_ref.rollout.name 固定为 vllm
• src/mvp/py/argus/service/ui.py
  • New Task → Advanced example 同步改为 actor_rollout_ref.rollout.name=vllm（避免用户 copy/paste 走错）

并用单测锁定行为（TDD）：

• src/mvp/py/tests/test_builders.py
• src/mvp/py/tests/test_ui.py

2.2 镜像与 compose（强制用预构建镜像）

• src/mvp/images/argus-ray-node/Dockerfile
  • 默认 ARG BASE_IMAGE=verlai/verl:vllm011.latest
• src/mvp/docker-compose.yaml
  • 移除 ray_head.build（避免每次 docker compose up 触发 build）
  • head/worker 统一使用 image: argus/argus-ray-node:vllm011.latest

---

3. E2E 遇到的问题与修复

3.1 问题：vLLM 初始化触发 HF mirror 429

在切换到 vLLM rollout 后，PPO/GRPO 任务启动阶段出现：

• huggingface_hub.errors.HfHubHTTPError: 429 Too Many Requests
• 请求来源：https://hf-mirror.com/api/models/<repo>/tree/main?...

原因要点：

• 传入模型为 repo id（Qwen/Qwen2.5-0.5B-Instruct）时，vLLM 会调用 HF API 获取 repo tree/file list；
• 多进程/多 replica 并发会瞬间放大请求，导致 mirror 限流；
• 即便本地 cache 已存在，repo id 路径仍可能触发远端检查。

3.2 修复：禁用 HF Hub 联网 + 使用本地 snapshot path

1. 在 Ray job runtime_env 注入离线开关：

• src/mvp/configs/dev.yaml
• src/mvp/configs/dev_v30.yaml

新增：

HF_HUB_OFFLINE: "1"

2. E2E 脚本提交任务时，model_id 改为本地 snapshot 目录，避免 repo id：

• src/mvp/scripts/run_all_v30_api.sh
  • 在 head 容器内用 snapshot_download(..., local_files_only=True) 解析本地路径
  • 用该路径作为 model_id: 提交 PPO/GRPO/SFT

结果：E2E 任务不再触发 HF mirror 429，PPO/GRPO/SFT 全部跑通。

---

4. 远端部署/操作记录（h1）

4.1 构建镜像（h1 上执行）

在 argus@h1:/home2/argus/infra/mvp/src/mvp：

docker build -f images/argus-ray-node/Dockerfile \
  --build-arg BASE_IMAGE=verlai/verl:vllm011.latest \
  -t argus/argus-ray-node:vllm011.latest .

4.2 拉起环境（compose）

docker compose down
docker compose up -d

4.3 E2E

export MVP_INTERNAL_TOKEN=my-dev-token
export SFTPGO_ADMIN_PASSWORD=my-dev-sftpgo-admin
./scripts/run_all_v30_api.sh

---

5. 已知影响与注意事项

1. vLLM rollout 更敏感于模型加载路径与联网行为：建议默认离线（HF_HUB_OFFLINE=1）并优先使用本地 snapshot path。
2. 镜像切换可能带来依赖差异：后续若遇到 rollout 相关参数兼容问题，应以 vLLM 的配置要求为准逐项调整（保持小步快跑）。