195 lines
8.6 KiB
Markdown
195 lines
8.6 KiB
Markdown
# MVP v3.6（基于 v3.5）开发计划（TDD）
|
||
|
||
> 设计依据：`specs/mvp/v3.6/v3.6_design.md`
|
||
> 本计划默认已确认：
|
||
> 1) W&B host 端口：`8090`；2) project：`<user_id>_project`；3) evaluation 先做 Advanced 模板；4) 不使用 `WANDB_ENTITY`。
|
||
|
||
## 总体原则
|
||
|
||
- **TDD**：每个里程碑先补齐单测（或契约测试）再实现功能；保证覆盖率门槛不回退。
|
||
- **最小闭环**：先做到“可用+可验证”，再做体验优化；不做超出 v3.6 scope 的扩展。
|
||
- **配置不落盘敏感信息**：`WANDB_API_KEY` 只能来自运行环境变量，不写入仓库配置文件。
|
||
|
||
---
|
||
|
||
## Milestones
|
||
|
||
### M1：配置层（tracking.wandb）与解析
|
||
|
||
**目标**
|
||
- 在服务配置中新增 `tracking.wandb`，支持开关、base_url、api_key_env。
|
||
- 不引入 `WANDB_ENTITY`（保持为空即可）。
|
||
|
||
**开发任务**
|
||
- 在 `src/mvp/py/argus/service/config.py`：
|
||
- 新增 `TrackingConfig/WandbConfig` dataclass（或等价结构）。
|
||
- `V2Config.from_root_dict()` 解析 `tracking.wandb.*`（缺省为 disabled）。
|
||
- 校验：`enabled=true` 时 `base_url` 不能为空；`api_key_env` 默认 `WANDB_API_KEY`。
|
||
|
||
**测试（先写）**
|
||
- `test_config_parses_wandb_defaults`：没有 tracking 字段时，默认 disabled。
|
||
- `test_config_parses_wandb_enabled`：enabled=true 能读到 base_url/api_key_env。
|
||
- `test_config_rejects_empty_base_url_when_enabled`：enabled=true 且 base_url 空时报错（或记录 warning，取决于实现选择）。
|
||
|
||
**验收**
|
||
- 仅通过 config 即能决定是否启用 W&B，且不会破坏 v3.5 现有配置解析。
|
||
|
||
---
|
||
|
||
### M2：Ray Job runtime_env 注入（WANDB_* env）
|
||
|
||
**目标**
|
||
- 当 `tracking.wandb.enabled=true` 时：平台在 job 粒度注入 `WANDB_BASE_URL/WANDB_API_KEY/WANDB_MODE/WANDB_DIR` 等 env。
|
||
- `WANDB_API_KEY` 从 API server 进程环境变量中读取：`os.environ[api_key_env]`。
|
||
|
||
**开发任务**
|
||
- 在 scheduler / ray job builder（`src/mvp/py/argus/service/scheduler.py` 或 `src/mvp/py/argus/ray/builders.py`）：
|
||
- 构造 job runtime_env.env_vars 的 merge 逻辑：
|
||
- 现有 `ray.runtime_env.env_vars` 为基础；
|
||
- 追加 W&B env（不覆盖用户显式指定的同名变量，或按“平台优先”策略二选一并写清楚）。
|
||
- 注入：
|
||
- `WANDB_BASE_URL=<cfg.tracking.wandb.base_url>`
|
||
- `WANDB_API_KEY=<os.environ[cfg.tracking.wandb.api_key_env]>`
|
||
- `WANDB_MODE=online`
|
||
- `WANDB_DIR=/private/users/<user_id>/jobs/<ray_submission_id>/wandb`（本地 run 文件随 job 一起由 janitor 清理）
|
||
|
||
**测试（先写）**
|
||
- `test_scheduler_injects_wandb_env_when_enabled`：
|
||
- mock env 中存在 `WANDB_API_KEY`；
|
||
- 提交一个内置任务（ppo/sft 任意），断言构造出来的 runtime_env 含以上 env_vars。
|
||
- `test_scheduler_sets_wandb_dir_under_job_dir`：
|
||
- 断言 `WANDB_DIR` 位于该 attempt 的 job 目录下（而不是 common 目录），避免无法跟随 job retention 清理。
|
||
- `test_scheduler_does_not_inject_wandb_env_when_disabled`。
|
||
- `test_scheduler_wandb_missing_api_key_behaviour`：
|
||
- enabled=true 但缺少 env 时的行为：
|
||
- 方案 A（推荐）：**自动降级**为 console（不注入 wandb），并在 task/attempt message 记录 warning；
|
||
- 或方案 B：fail-fast（返回 500/400）。
|
||
- 需在实现前确认采用哪种策略；建议 v3.6 选 A 提升可用性。
|
||
|
||
**验收**
|
||
- 任意内置任务提交后，在 Ray job runtime_env 中能看到 `WANDB_*`。
|
||
|
||
---
|
||
|
||
### M3：内置训练任务自动开启 wandb logger（PPO/GRPO/SFT）
|
||
|
||
**目标**
|
||
- 当 W&B enabled 时，平台默认把内置训练任务改成 `trainer.logger=["console","wandb"]`，并设置 project/run 命名。
|
||
|
||
**开发任务**
|
||
- 在 job 构建（PPO/GRPO/SFT 的 overrides 生成处）：
|
||
- 将 `trainer.logger` 从 `console` 改为 list：`[console,wandb]`（hydra 语法按现有实现方式拼接）。
|
||
- `trainer.project_name=<user_id>_project`
|
||
- `trainer.experiment_name=<ray_submission_id>`
|
||
- 保持 v3.5 的 job_dir/checkpoint/log dir 注入方式不变。
|
||
|
||
**测试（先写）**
|
||
- `test_job_overrides_include_wandb_logger_when_enabled`：
|
||
- 断言 entrypoint/overrides 包含 `trainer.logger=[console,wandb]`（或等价写法）。
|
||
- 断言包含 `trainer.project_name=<user>_project`、`trainer.experiment_name=<submission_id>`。
|
||
- `test_job_overrides_keep_console_only_when_wandb_disabled_or_missing_key`。
|
||
|
||
**验收**
|
||
- 训练任务 run 会自动出现在 W&B 对应 project 下（E2E 验证在 M6）。
|
||
|
||
---
|
||
|
||
### M4：API 输出与 WebUI 链接（最小闭环）
|
||
|
||
**目标**
|
||
- 用户可以在 UI 里“知道去哪看 W&B”，以及知道本 task 对应哪个 project/run。
|
||
|
||
**开发任务**
|
||
- API：
|
||
- `GET /api/v2/me` 增加 `wandb` 信息（仅当 enabled 时返回）：
|
||
- `base_url`
|
||
- `project_name`（`<user_id>_project`）
|
||
- `GET /api/v2/tasks/{task_id}`（或 attempt 结构）增加 `wandb_project` / `wandb_run_name`（run_name=ray_submission_id）。
|
||
- WebUI：
|
||
- Login/Data 页增加 “Open W&B” 链接（跳 `base_url`），展示 project_name + Copy。
|
||
- Task detail 增加 wandb 字段展示（project/run/可点击链接或可复制文本）。
|
||
|
||
**测试（先写）**
|
||
- `test_me_includes_wandb_when_enabled`（mock config + env）。
|
||
- `test_task_detail_contains_wandb_fields_when_enabled`（mock task/attempt）。
|
||
- `test_ui_contains_wandb_link`（渲染 HTML 断言包含 base_url/project_name 字样）。
|
||
|
||
**验收**
|
||
- WebUI 能一键跳转 W&B；Task detail 能定位到 run。
|
||
|
||
---
|
||
|
||
### M5：New Task 增加 Evaluation 模板（Advanced）
|
||
|
||
**目标**
|
||
- New Task 页面增加一个 Evaluation 模板按钮/示例（先按 Advanced TaskSpec 提供）。
|
||
|
||
**开发任务**
|
||
- 在 `src/mvp/py/argus/service/ui.py`：
|
||
- YAML 模式增加 “Evaluation example”。
|
||
- 表单模式本轮可选（不要求）：
|
||
- 如果要支持：把 evaluation 作为 advanced 模板的一种预填 command（仍 `kind: advanced`）。
|
||
- 模板建议使用 verL 自带入口：
|
||
- `python3 -m verl.trainer.main_eval ... +ray_kwargs.ray_init.address=auto`
|
||
- `data.path=$HOME/common/datasets/...`（按 v3.5 的宏规则）
|
||
|
||
**测试（先写）**
|
||
- `test_ui_new_task_contains_evaluation_example`：断言页面包含 `main_eval` 与关键字段。
|
||
|
||
**验收**
|
||
- 用户复制 evaluation 模板可提交成功并在 Ray 上运行（E2E 在 M6）。
|
||
|
||
---
|
||
|
||
### M6：端到端（dev/h1）部署与验收流程
|
||
|
||
> 里程碑 M6 以脚本/手工步骤为主；不强制写 e2e 自动化测试。
|
||
|
||
**部署任务**
|
||
- compose 增加 `wandb` 服务：
|
||
- `wandb/local:latest`
|
||
- host 端口 `8090:8080`
|
||
- 数据挂载到 `/private/common/wandb:/vol` 持久化（W&B 元数据/账号/API key/历史 runs）
|
||
- API 启动方式：
|
||
- 在宿主机 export：`WANDB_API_KEY=<从 W&B UI 生成的 key>`
|
||
- 启动 API（确保 env 透传到容器内）
|
||
- 首次初始化：
|
||
- 打开 `http://<h1_ip>:8090/system-admin` 粘贴 license（管理员操作）
|
||
|
||
**验收用例**
|
||
1) **训练类任务自动打点**
|
||
- 用 alice 提交一个 SFT（或 PPO）任务（内置 workload）
|
||
- 在 W&B UI 中看到 project：`alice_project`
|
||
- run name 为 `ray_submission_id`，metrics 可见
|
||
2) **Advanced task 可手动打点**
|
||
- 提交一个 Advanced（用户自己写 command）并在 command 中启用 `trainer.logger=["console","wandb"]`（如需）
|
||
- 确认 env 注入生效（W&B 记录出现）
|
||
3) **Evaluation 模板**
|
||
- 用 New Task 的 Evaluation example 提交
|
||
- 任务成功运行并输出 metrics（stdout/logs）
|
||
- （可选）如果 evaluation 也启用 wandb，则能出现在对应 project 下
|
||
|
||
**回归**
|
||
- v3.5 的三类任务（ppo/grpo/sft）在 W&B disabled 或缺少 key 时仍可跑通（至少 console 输出不受影响）。
|
||
|
||
**Retention 联动检查**
|
||
- 提交一个短任务生成 `WANDB_DIR`，结束后确认：
|
||
- `WANDB_DIR` 位于 `/private/users/<user>/jobs/<ray_submission_id>/wandb`
|
||
- janitor 运行后该目录会随 job 一起进入 trash / 被 purge（与 jobs retention 一致）
|
||
|
||
---
|
||
|
||
## 交付物清单（v3.6）
|
||
|
||
- 文档：
|
||
- `specs/mvp/v3.6/v3.6_design.md`（已存在，必要时补充操作流程）
|
||
- `specs/mvp/v3.6/v3.6_dev_plan.md`（本文）
|
||
- 代码（预期变更点）：
|
||
- `src/mvp/py/argus/service/config.py`
|
||
- `src/mvp/py/argus/service/scheduler.py` / `src/mvp/py/argus/ray/builders.py` / `src/mvp/py/argus/ray/ray_job_tool.py`
|
||
- `src/mvp/py/argus/service/app.py`（/me 与 task detail 输出）
|
||
- `src/mvp/py/argus/service/ui.py`（Open W&B + Evaluation template）
|
||
- `src/mvp/docker-compose.yaml`（wandb service）
|
||
- `src/mvp/configs/dev.yaml`（tracking.wandb 配置）
|
||
- `src/mvp/scripts/*`（API 启动时 env 透传，必要时补充）
|