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 配置，建议结构：

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 作为一类“内置任务”，可新增：

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）：

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 时通过环境变量提供。

示例（在宿主机）：

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）。