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

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 透传，必要时补充）