# MVP v3.7 设计方案：切换 `verlai/verl:vllm011.latest` + 默认 rollout=vllm

## 0. 背景与目标

当前 dev/h1 环境的 Ray 节点镜像基于 `verlai/verl:sgl055.latest`，并且平台内置 PPO/GRPO 的默认参数中写死了：

- `actor_rollout_ref.rollout.name=sglang`

v3.7 的目标是：

1. **Ray 节点镜像切换到 vLLM 版本**
   - 基础镜像改为 `verlai/verl:vllm011.latest`
   - 构建并打标：`argus/argus-ray-node:vllm011.latest`
   - 构建在远端 `argus@h1` 上完成（本地没有 verlai 基础镜像）
2. **端到端跑通 v3.0 API 流程**
   - 通过 `src/mvp/scripts/run_all_v30_api.sh` 完整 E2E
3. **内置训练任务默认使用 vLLM rollout**
   - 提交 VERL 训练任务时将 `actor_rollout_ref.rollout.name` 从 `sglang` 改为 `vllm`

> 备注：本迭代是“替换默认 backend”而非“新增能力”，尽量保持对 v3.6 功能兼容（W&B、SFTPGo、Advanced TaskSpec、stateless pool 等不改协议）。

---

## 1. 现状梳理（源码定位）

### 1.1 Ray 节点镜像与 compose

- Dockerfile：`src/mvp/images/argus-ray-node/Dockerfile`
  - 当前 `ARG BASE_IMAGE=verlai/verl:sgl055.latest`
- Compose：`src/mvp/docker-compose.yaml`
  - `ray_head.build.args.BASE_IMAGE: verlai/verl:sgl055.latest`
  - `ray_head.image / worker.image: argus/argus-ray-node:v2.5`

### 1.2 默认 rollout.name=sglang 的位置

平台内置 PPO/GRPO 参数由 Ray job 入口构建器生成：

- `src/mvp/py/argus/ray/builders.py`
  - `build_training_argv()` 中写死了：
    - `actor_rollout_ref.rollout.name=sglang`

WebUI 的 Advanced 示例也包含 rollout.name（用于指导用户）：

- `src/mvp/py/argus/service/ui.py`
  - Advanced example 中当前为 `actor_rollout_ref.rollout.name=sglang`（需要同步改成 vllm，避免用户 copy/paste 走错）

### 1.3 `run_all_v30_api.sh` 依赖默认参数

`src/mvp/scripts/run_all_v30_api.sh` 提交 PPO/GRPO/SFT 的 TaskSpec（YAML）时 **不会显式携带 rollout.name**，因此是否能切到 vllm，依赖平台默认值（builders）是否变更。

---

## 2. 方案设计

### 2.0 已确认决策（来自评审）

1) **compose 移除 build**：允许移除 `ray_head.build`，强制使用远端已构建镜像。  
2) **全量切换 vllm**：不保留 sglang 作为可选项（v3.7 默认全部切到 vllm）。  
3) **backend 名称**：确认 VERL backend 名为 `vllm`（即 `actor_rollout_ref.rollout.name=vllm`）。

### 2.1 镜像策略（vllm011）

#### 2.1.1 Dockerfile 修改

目标：
- 默认基础镜像改为 `verlai/verl:vllm011.latest`

改动点：
- `src/mvp/images/argus-ray-node/Dockerfile`
  - `ARG BASE_IMAGE=verlai/verl:vllm011.latest`

说明：
- 仍保留 `BASE_IMAGE` build arg，便于未来热切换不同基础镜像（而不是把镜像写死在 compose）。

#### 2.1.2 镜像 tag

构建产物镜像：
- `argus/argus-ray-node:vllm011.latest`

> 注意：该 tag 用于表达“运行时依赖的 vllm 版本线”，而不是 MVP 功能版本（v3.7）。

#### 2.1.3 compose 复用新镜像（避免每次重建）

目标：E2E 时尽量避免每次 `docker compose up` 都 build。

建议修改 `src/mvp/docker-compose.yaml`：
- `ray_head.image: argus/argus-ray-node:vllm011.latest`
- `ray_worker_0.image: argus/argus-ray-node:vllm011.latest`
- `ray_worker_1.image: argus/argus-ray-node:vllm011.latest`

并采用：**移除 `ray_head.build`**（强制使用已构建镜像），避免每次 `docker compose up` 触发 build。

---

### 2.2 训练默认参数切换到 vllm

目标：平台内置 PPO/GRPO 的默认 rollout backend 从 sglang 切到 vllm。

改动点：
- `src/mvp/py/argus/ray/builders.py`
  - 将 `actor_rollout_ref.rollout.name=sglang` 替换为 `actor_rollout_ref.rollout.name=vllm`

影响范围：
- PPO、GRPO（两者都走 `verl.trainer.main_ppo`）
- 对 SFT 不影响（SFT 走 `verl.trainer.sft_trainer_ray`）

兼容性评估：
- `run_all_v30_api.sh` 会受益：无需修改 TaskSpec，即可自动切换。
- 若未来仍需支持 sglang，可考虑在 v3.7 之后引入“配置驱动”的默认值（见 §2.4 可选增强）。

---

### 2.3 WebUI/模板同步（避免误导用户）

目标：New Task 页面的 Advanced example 也应默认 vllm，避免用户 copy 后手工改参数。

改动点：
- `src/mvp/py/argus/service/ui.py`
  - Advanced example 中 `actor_rollout_ref.rollout.name=vllm`

> 注意：该模板仅用于 UX 指导；实际生效仍由用户提交的 command 决定。

---

### 2.4 可选增强（不强制，供评审）

为避免后续再硬编码切换，可引入“平台训练默认值”配置（可选）：

- 在 `configs/dev.yaml` 增加：
  ```yaml
  verl_defaults:
    rollout_backend: "vllm"   # 或 "sglang"
  ```
- `builders.py` 从配置读取默认值，而非写死。

本次 v3.7 的最低交付可以先不做该增强，只做硬替换；若你希望后续支持 A/B 切换，再纳入。

---

## 3. 远端部署/迁移步骤（argus@h1）

> 本节是“计划步骤”，评审通过后再执行。

### 3.1 同步代码到远端目录

远端目录约定：
- `argus@h1:/home2/argus/infra/mvp/src/mvp`（compose 与 scripts）

将本地变更 rsync 到远端后再进行构建/拉起。

### 3.2 在远端构建镜像（只在 h1）

在 `argus@h1` 执行（示例命令）：

```bash
cd /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 \
  .
```

### 3.3 清理旧环境并用新镜像拉起

```bash
cd /home2/argus/infra/mvp/src/mvp
docker compose down
docker compose up -d
```

验证：
- `docker ps` 中 `argus-ray-head/worker` 的 image 为 `argus/argus-ray-node:vllm011.latest`
- Ray dashboard 可访问：`http://<h1IP>:8265`

### 3.4 E2E：跑 `run_all_v30_api.sh`

```bash
cd /home2/argus/infra/mvp/src/mvp
MVP_INTERNAL_TOKEN=my-dev-token \
WANDB_API_KEY=... \
./scripts/run_all_v30_api.sh
```

验收关键点：
- PPO/GRPO/SFT 全部成功（或至少 PPO/GRPO 不卡在 rollout backend 初始化阶段）
- 任一 PPO/GRPO 的 driver logs / hydra overrides 中能看到：
  - `actor_rollout_ref.rollout.name=vllm`

---

## 4. 风险与排查要点

### 4.1 vLLM backend 在 VERL 的参数兼容性

平台默认传入的这些参数当前是为 sglang 写的：
- `actor_rollout_ref.rollout.tensor_model_parallel_size=1`
- `actor_rollout_ref.rollout.gpu_memory_utilization=0.4`

vLLM rollout 是否接受/需要额外参数（例如 tokenizer、engine 配置），需要在 E2E 中观察：
- 如果 vLLM rollout 初始化报错，可能需要补充 vllm 特定 overrides（属于 v3.7 的后续修复项）。

### 4.2 镜像依赖差异

更换 base image 可能带来：
- Python/Ray/依赖版本差异
- CUDA/NCCL 依赖差异

建议：
- 在 v3.7 评审通过后，优先跑最小 PPO（epochs=1、steps=10）验证 vllm backend 能启动并完成。

---

## 5. 待确认问题（请你评审时确认）
已完成评审确认（见 §2.0），无额外待确认项。