# 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`

新增：
```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`：

```bash
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）

```bash
docker compose down
docker compose up -d
```

### 4.3 E2E

```bash
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 的配置要求为准逐项调整（保持小步快跑）。