argus-cluster/specs/mvp/v3.6/v3.6_design.md

# MVP v3.6 详细设计方案（基于 v3.5）

> 设计基线：当前线上已具备 v3.5 能力（PPO/GRPO/SFT + Advanced TaskSpec + SFTPGo 数据管理 + WebUI）。  
> v3.6 的架构草图见：`specs/mvp/v3.6/Snipaste_2026-01-05_10-56-34.png`

## 0. 目标与范围

### 0.1 v3.6 目标

1) **Weights & Biases（W&B）集成**
- 训练/任务运行时自动打点到 W&B local server。
- 采用“共享 W&B 账号（license 只支持 1 user） + 为每个 MVP 用户创建独立 project”的方式隔离可视化与检索体验。
- 平台提供 W&B 的跳转链接、以及每个 task 对应 run 的可定位信息（最小闭环）。

2) **New Task 增加 Evaluation 模板**
- 在 New Task 页面提供一个最小可用的 “Evaluation” 任务模板（用于离线评估/打分），并能把结果落到 job 输出与（可选）W&B。

### 0.2 非目标（v3.6 不做）

- 不引入新的 node management 机制；保持 v3.5 的 head discovery + worker watchdog stateless pool。
- 不做 Serving/IB/RDMA/断点续训/多版本 verl code_path 等（仍按 v3.5 的范围）。
- 不做多租户安全隔离（W&B API Key 注入属于内部可信环境）。

---

## 1. W&B local server（部署与连通）

> 资料参考：`specs/mvp/v3.6/wandb.md`。**文档中 license/token 属敏感信息，v3.6 设计不在代码/文档里写死。**

### 1.1 部署方式（dev/h1）

建议在 `src/mvp/docker-compose.yaml` 新增 `wandb` 服务（与现有 ray_head / sftpgo 同一 compose network）：

- 镜像：`wandb/local:latest`
- 容器端口：`8080`
- 宿主机端口：建议 `8090:8080`（避免和 MVP API `8080`、SFTPGo `8081` 冲突）
- 持久化：挂载到 NFS/共享目录（例如 `/private/common/wandb`）以持久化 runs/artifacts
- 首次启动后由管理员在 W&B System Admin 页面粘贴 license（见 `wandb.md`）

### 1.1.1 持久化策略（必须）

v3.6 约定 **W&B server 的元数据必须持久化**（否则会丢 license/账号/API key、历史 runs/project 索引等）：

- W&B server 数据目录（`/vol`）挂载到共享目录（NFS）：例如 `/private/common/wandb:/vol`
- 这部分数据由平台/管理员长期保留（不跟随单个 job 清理）

与之相对，**每个 Ray job 对应的本地 W&B run 文件**放在 job 目录下（见 §2.3 的 `WANDB_DIR`），并由现有 janitor 随 job 一起清理：

- `WANDB_DIR=/private/users/<user_id>/jobs/<ray_submission_id>/wandb`
- janitor 对 job 的策略是“结束后 3 天移入回收站、7 天后删除”，因此该目录会被一并处理

> 说明：W&B 的最终“事实数据”在 server 侧持久化（runs/metrics/可视化）；job 目录下的 `WANDB_DIR` 更像运行期缓存/临时文件与调试材料。

### 1.2 容器内访问 W&B 的 base_url

在 v3.5 经验中，Ray head 容器对 docker 内部 DNS 名称解析不稳定（`Temporary failure in name resolution`）。  
为避免再次踩坑，v3.6 统一采用 **“docker bridge 网关 + host 映射端口”** 的方式让容器访问 W&B：

- `WANDB_BASE_URL=http://172.22.0.1:8090`（其中 `172.22.0.1` 为 `mvp_argus-ray-net` 网关）

> 注意：如果未来 dev 环境 network 网段变化，需要把网关地址做成配置项（见 §2）。

---

## 2. 平台侧 W&B 集成（API/Scheduler/Ray Job runtime_env）

### 2.1 配置设计（YAML）

在 `configs/dev.yaml`（以及生产配置）中新增一段 W&B 配置，建议结构：

```yaml
tracking:
  wandb:
    enabled: true
    base_url: "http://172.22.0.1:8090"
    api_key_env: "WANDB_API_KEY"
    entity: ""              # 可选；verL 通过 env WANDB_ENTITY 读取
    project_suffix: "_project"  # 例如 alice_project
    # 可选：代理（verL 支持 trainer.wandb_proxy）
    proxy: null
```

平台读取 `api_key_env` 对应的环境变量，并在 job 维度注入 `WANDB_API_KEY`。  
**不在配置文件中存明文 API KEY**（避免泄露）。

### 2.2 项目/命名规范（共享账号 + user project）

由于 W&B local license 限制 “最多 1 user”，v3.6 采用：

- **同一个 W&B 账号**（同一个 `WANDB_API_KEY`）
- 每个 MVP user 使用不同 project：
  - `project_name = <user_id> + project_suffix`
  - 示例：`alice_project`
- 每个 Ray job attempt 对应一个 run：
  - `experiment_name = <ray_submission_id>`（保证 attempt 唯一；也便于从 dashboard 反查）

verL 内部 `wandb.init(project=project_name, name=experiment_name, entity=$WANDB_ENTITY)`（见 `verl/utils/tracking.py`）。

### 2.3 Ray Job 注入（runtime_env env_vars）

当 `tracking.wandb.enabled=true` 时，在 scheduler 提交 ray job 时，统一注入：

- `WANDB_BASE_URL`（来自配置）
- `WANDB_API_KEY`（来自 env `tracking.wandb.api_key_env`）
- `WANDB_ENTITY`（可选）
- `WANDB_MODE=online`（默认在线；可在 dev/离线时切换）
- `WANDB_DIR=/private/users/<user_id>/jobs/<ray_submission_id>/wandb`（保证每个 job 的本地 run 文件落到对应 job 目录；便于随 job 一起被 janitor 清理）

> 对 Advanced TaskSpec：平台无法替用户改 command，但仍可注入上述 env，让用户在 command 中自行启用 wandb。

### 2.4 verL 训练任务自动开启 wandb logger

对平台内置 workload（PPO/GRPO/SFT），平台将 hydra overrides 改为：

- `trainer.logger=[console,wandb]`（替代 v3.5 的 `trainer.logger=console`）
- `trainer.project_name=<user_id>_project`
- `trainer.experiment_name=<ray_submission_id>`
- 可选：如果配置了 `tracking.wandb.proxy`，注入 `trainer.wandb_proxy=...`

兼容性说明：
- `trainer.logger` 在 verL 的 ppo/sft config 中本身是 list（示例为 `["console","wandb"]`），因此不会破坏 verL 配置解析。
- 现有 v3.5 的 checkpoint/log dir 仍按 job_dir 注入，不依赖 `trainer.default_local_dir`。

### 2.5 数据库存储与 API 输出（最小闭环）

v3.6 需要让用户能在 WebUI/Task 详情中 “点一下跳转到 W&B”：

建议在 DB（sqlite）里新增 attempt 级字段（或 metadata JSON）：

- `wandb_project`：如 `alice_project`
- `wandb_run_name`：如 `<ray_submission_id>`
- `wandb_base_url`：如 `http://<host>:8090`
- `wandb_url`：拼出来的最终链接（若 W&B local 的 URL 结构不稳定，可只存前 3 项，由前端拼接）

API 侧在：
- `GET /api/v2/tasks/<task_id>` 的 `latest_attempt` 增加 `wandb` 字段（或顶层增加 `tracking` 字段）
- `GET /api/v2/me` 增加 `wandb` 信息（base_url、project_name），便于页面展示 “Open W&B”

> W&B local 的 URL 路径结构需要在接入时确认；若不确定，先只提供 base_url + project/run 名称，用户可在 W&B UI 搜索。

---

## 3. WebUI 变更（v3.6）

### 3.1 Data / Login 页

- 在 Data 或 Login 页新增：
  - “Open W&B” 链接（跳转到 `tracking.wandb.base_url` 的 Web UI）
  - 展示当前用户的 project 名称（例如 `alice_project`），并提供 Copy 按钮

### 3.2 Tasks / Task Detail

- Task list 无需大改；Task detail 页面增加：
  - W&B run 信息（project / run name / link）
  - 若任务失败，W&B 仍可用于查看已上报的中间日志（对训练类任务有价值）

### 3.3 New Task 增加 Evaluation 模板

New Task 页面新增一个 “Evaluation example”：

#### 方案 A（推荐，最小改动）：作为 Advanced TaskSpec 模板

- 直接提供 `kind: advanced` 的模板，command 运行 verL 自带评估入口：
  - `python3 -m verl.trainer.main_eval data.path=... custom_reward_function.path=... +ray_kwargs.ray_init.address=auto`
- 优点：不需要扩展 TaskSpec schema / scheduler 逻辑
- 缺点：Evaluation 在平台侧不可结构化（仍属于 advanced）

#### 方案 B（更产品化）：新增内置 workload: evaluation（后续可选）

若希望在任务分类/队列中把 evaluation 作为一类“内置任务”，可新增：

```yaml
workload: evaluation
code_path: /private/common/code/verl/verl_repo
nnodes: 1
n_gpus_per_node: 0
data_path: $HOME/common/datasets/<...>.parquet
response_key: responses
data_source_key: data_source
reward_model_key: reward_model
custom_reward_path: $HOME/code/reward.py   # 可选
custom_reward_name: compute_score          # 可选
```

平台把它编译成 `verl.trainer.main_eval` 的 hydra overrides + ray init address；并可选择把结果解析后上报 W&B。

v3.6 建议先落地 **方案 A**（模板即可），方案 B 作为 v3.7+ 的演进。

---

## 4. 验收标准（v3.6）

### 4.1 W&B（训练任务）

- 提交 PPO/GRPO/SFT 任一任务：
  - W&B local server 能看到对应 project（如 `alice_project`）
  - 能看到 run 名称为该任务 attempt 的 `ray_submission_id`
  - run 内能持续刷新 metrics（至少包含 loss/step 等 verL 默认上报）
- WebUI：
  - 能打开 W&B UI 链接
  - Task detail 能展示 project/run（或至少可检索信息）

### 4.2 Evaluation 模板

- New Task 中出现 “Evaluation example”
- 复制模板提交后：
  - 任务能在 Ray 上运行（CPU 即可，`+ray_kwargs.ray_init.address=auto` 连接集群）
  - 输出 metrics（`main_eval.py` 默认 print dict）
  - （可选）若用户在 command 里启用 wandb，则能在对应 project 下看到评估 run

---

## 5. 兼容性影响评估

- 对现有 v3.5 功能：
  - 默认行为改变：PPO/GRPO/SFT 会默认多一个 logger（wandb），并对外发起 HTTP 请求到 W&B server。
  - 若 W&B server 不可用/配置缺失：
    - 建议行为：平台自动降级为 `trainer.logger=[console]` 并在 task 状态中给出 warning（避免训练直接失败）。
    - 初版也可选择 fail-fast：缺少 `WANDB_API_KEY` 时拒绝开启 wandb（由配置开关控制）。
- 对资源/存储：
  - W&B server 自身会写入一定量数据（license 限制 10GB）；需配合 retention 策略做清理（v3.6 先手动，后续可自动）。
  - job 目录下的 `WANDB_DIR` 会随 jobs retention 被清理；不会无限增长。

---

## 6. 已确认的落地约定

- W&B server 对外端口：`8090`
- Project 命名：`<user_id>_project`（不使用 `WANDB_ENTITY`）
- Evaluation：先只提供 **Advanced 模板**（New Task 页面提供示例即可）

---

## 7. 运维与验收流程（dev/h1）

### 7.1 启动服务（docker compose）

1) 启动/重启 compose（Ray head/worker + SFTPGo + W&B）：

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

2) 访问 UI：
- MVP WebUI：`http://<HOST>:8080/ui`
- Ray Dashboard：`http://<HOST>:8265`
- SFTPGo Web：`http://<HOST>:8081/web/`
- W&B Web：`http://<HOST>:8090`

> W&B 容器数据目录已挂载到共享盘：`/private/common/wandb`（容器内 `/vol`）。

### 7.2 初始化 W&B（管理员一次性操作）

1) 打开 `http://<HOST>:8090/system-admin` 粘贴 license（详见 `specs/mvp/v3.6/wandb.md`）。
2) 进入 W&B UI 创建/登录到共享账号（license 只支持 1 user）。
3) 在 W&B UI 的用户设置页面生成 API Key（通常位于 “User Settings / API Keys”）。

### 7.3 启动 API server（需要注入 WANDB_API_KEY）

平台不会把 `WANDB_API_KEY` 写入配置文件；必须在启动 API server 时通过环境变量提供。

示例（在宿主机）：

```bash
export MVP_INTERNAL_TOKEN="my-dev-token"
export WANDB_API_KEY="...从 W&B UI 复制..."
cd /home2/argus/infra/mvp/src/mvp/scripts
./60_start_api.sh
```

> 说明：`./60_start_api.sh` 会把 `WANDB_API_KEY` 透传给 head 容器内运行的 API server。

### 7.4 验收（最小闭环）

1) 在 WebUI Login 页面能看到 W&B 区块（Open W&B + project copy）。
2) 提交一个 PPO/GRPO/SFT 任务（任意一个即可）：
   - W&B project 为 `<user_id>_project`（如 `alice_project`）
   - run name 为该 attempt 的 `ray_submission_id`
3) 提交 Evaluation 模板（Advanced）能在 Ray 上运行并输出评估结果（stdout / logs）。