# MVP v3.6 迭代研发总结（基于 v3.5）

> 时间基线：2026-01（H20 dev 环境：`argus@h1:/home2/argus/infra/mvp`）  
> v3.6 架构草图：`specs/mvp/v3.6/Snipaste_2026-01-05_10-56-34.png`

## 1. 迭代目标回顾

v3.6 在 v3.5（WebUI + API server + Ray stateless node pool + SFTPGo + Advanced TaskSpec）基础上，新增两块能力：

1) **Weights & Biases（W&B）local server 集成**
- 训练任务（PPO/GRPO/SFT）默认可写入 W&B。
- 采用“共享 W&B 账号 + 按用户拆分 project（`<user_id>_project`）”的隔离策略。

2) **New Task 增加 Evaluation 示例**
- New Task 页面新增一个最小可用的 evaluation 模板（以 Advanced command 方式运行 `verl.trainer.main_eval`）。

## 2. 交付内容（代码/配置/脚本）

### 2.1 部署形态（docker compose）

v3.6 在 `src/mvp/docker-compose.yaml` 新增 W&B 服务：

- 服务名：`wandb`（容器名：`argus-wandb`）
- 宿主机端口：`8090:8080`
- 持久化：`../../shared/common/wandb:/vol`
- 同 network：`argus-ray-net`（便于 Ray 容器内访问）

### 2.2 平台配置（YAML）

在 `src/mvp/configs/dev.yaml` 增加/启用 W&B 配置：

```yaml
tracking:
  wandb:
    enabled: true
    base_url: "http://172.22.0.1:8090"
    api_key_env: "WANDB_API_KEY"
    project_suffix: "_project"
```

说明：
- `base_url` 采用 docker bridge 网关 + 宿主机映射端口的方式，规避容器内 DNS 偶发解析失败问题。
- 不在 config 中写明文 key，统一通过启动 API server 时注入 `WANDB_API_KEY`。

### 2.3 Ray Job runtime_env 注入（核心）

v3.6 在**每个 Ray job attempt**提交时注入两类环境变量：

1) **始终注入（无论是否启用 W&B）**：便于 Advanced command 在不改模板的情况下能运行
- `MVP_TRAINER_LOGGER`：`console` 或 `[console,wandb]`
- `MVP_WANDB_PROJECT`：`<user_id>_project`（例如 `alice_project`）
- `MVP_WANDB_RUN`：`<ray_submission_id>`（每次 attempt 唯一）

2) **当 W&B 有效启用时注入**
- `WANDB_BASE_URL`
- `WANDB_API_KEY`
- `WANDB_MODE=online`
- `WANDB_DIR=<job_dir>/wandb`（例如 `/private/users/alice/jobs/<ray_sid>/wandb`）

降级策略：
- 当 `tracking.wandb.enabled=true` 但缺少 `WANDB_API_KEY` 时，平台会**降级为 console**（并在 attempt.message 中记录 warning），避免训练失败。

### 2.4 WebUI 变更

1) **Login 页面**
- 增加 “Open W&B” 跳转（指向 `tracking.wandb.base_url`）

2) **New Task 页面**
- 新增 **Evaluation example**
- Advanced example 更新为 v3.6：
  - `command: |` 内不再包含任何注释（避免 YAML/命令解析报错）
  - W&B 参数不再让用户手填，改为引用平台注入的 `${MVP_*}` env：
    - `trainer.logger=${MVP_TRAINER_LOGGER}`
    - `trainer.project_name=${MVP_WANDB_PROJECT}`
    - `trainer.experiment_name=${MVP_WANDB_RUN}`

> 备注：driver 日志里会打印 `MVP_DRIVER_EXEC: bash -lc '...'`，此处看到 `${MVP_*}` 仍是“未替换”的字符串是正常现象；变量替换发生在 `bash` 执行阶段，而不是打印 argv 阶段。

### 2.5 启动脚本

`src/mvp/scripts/60_start_api.sh` 支持将宿主机的 `WANDB_API_KEY` 透传进 head 容器内启动的 API server：

- 宿主机设置：`export WANDB_API_KEY=...`
- 启动 API：脚本会 `docker exec -e WANDB_API_KEY=...` 进入 head 容器启动 `python3 /workspace/mvp/py/server.py`

## 3. 用户侧操作流程（v3.6）

### 3.1 一次性初始化（只在首次启用/清空 /vol 时需要）

1) 打开 W&B UI：`http://<h1机器IP>:8090`
2) 在 System Admin 页面粘贴 license 完成初始化
3) 生成并记录 `WANDB_API_KEY`（local key）
4) 以后启动 API server 时注入该 key（`WANDB_API_KEY=...`）

只要保留 `shared/common/wandb`（即 `/vol` 持久化目录），重建容器无需再次进入 8090 配置。

### 3.2 日常使用

1) WebUI 登录：`http://<h1机器IP>:8080/ui/login`（输入 user token）
2) New Task 提交任务：`http://<h1机器IP>:8080/ui/tasks/new`
3) 到 Tasks 查看状态/日志：`/ui/tasks` 与 task detail
4) 打开 W&B：`http://<h1机器IP>:8090`，在 `<user_id>_project` 下查看 runs/metrics

## 4. 验收结果（本迭代应达成）

1) PPO/GRPO/SFT 任一任务运行后：
- W&B local server 可见对应 project（如 `alice_project`）
- run name 与 `ray_submission_id` 对齐（便于追踪每次 attempt）

2) Evaluation 示例：
- 可作为 Advanced 任务提交并在 Ray 上执行 `verl.trainer.main_eval`
- 支持用户在 command 内自行加入 reward overrides（平台不做封装）

## 5. 已知限制与后续建议

1) **W&B 初始化自动化**
- 当前：首次仍需在 8090 页面粘贴 license、生成 key（更稳、侵入最小）。
- 若需要“从零部署也完全免页面操作”，可进一步调研 W&B local 的可用管理 API/启动参数（自动注入 license + 自动创建 key）。

2) **Advanced command 的自由度**
- 平台只负责：
  - `$HOME` 宏替换
  - runtime_env env_vars 注入
  - 任务队列与 Ray job 提交
- command 的语义正确性仍由用户负责（例如 PPO 必需的 micro batch 等参数）。