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

MVP v3.8 开发计划（TDD，细化版）

目标：在 v3.7 基础上引入 Ray Serve（vLLM）模型动态部署与管理（多模型单 app），并提供 WebUI + API 管理闭环。
约束（已确认）：

• 推理端口固定 8000（Serve HTTP）。
• 推理侧不接入现有 token 鉴权（对外 OpenAI endpoint 无鉴权）。
• 对外 model_id 统一加前缀：<user_id>-<YYYYMMDDHHMM>-<suffix>（用户只填 suffix）。
• LLMConfig.accelerator_type 从 dev.yaml 读取（dev/h1: H20）。

本计划按“测试先行 → 实现 → 回归”的节奏拆分到可验证粒度；每个 milestone 都能单独验收。

---

M0 - 基线与依赖探测（不改行为）

目的：确认 v3.7 baseline 稳定，并明确 Ray Serve LLM 依赖是否已具备（否则后续会卡在镜像/依赖）。

M0.1 本地回归

• .venv/bin/python -m pytest 通过（coverage ≥ 90%）

M0.2 远端回归（h1）

• src/mvp/scripts/run_all_v30_api.sh 可跑通（确认训练闭环未回退）

M0.3 head 容器内依赖探测（记录结论）

• python3 -c "import ray; import ray.serve; print(ray.__version__)"
• python3 -c "from ray.serve.llm import LLMConfig, build_openai_app; print('serve_llm_ok')"
• 若失败（例如缺 gymnasium）：记录缺失项，并在 M6 通过补齐 ray[llm] 解决

M0.4 配置探测

• configs/dev.yaml 中存在：
  • serving.llm.accelerator_type: H20
  • serving.serve.http_port: 8000
  • serving.serve.proxy_location: HeadOnly

验收：

• baseline 无回退；依赖探测结论明确（可用/不可用）

---

M1 - ServingSpec（解析/校验/宏替换/路径校验）（单测驱动）

目的：先把“输入”这层彻底固化（API/UI 复用），避免后期反复改 schema。

M1.1 新增/扩展数据模型

• ServingSpec（输入）
  • model_id（suffix）
  • model_source（支持 $HOME 宏）
  • num_replicas（default=1）
  • gpus_per_replica（default=1）
  • engine_kwargs（可选 dict，先原样存 DB；实现阶段再做白名单/黑名单）
• ResolvedServingSpec（内部）
  • model_id_suffix
  • model_id_prefix（由平台生成：user_id-YYYYMMDDHHMM）
  • model_id（对外：<prefix>-<suffix>）
  • model_source（resolved path）

M1.2 规则（写成纯函数，便于测）

• validate_model_id_suffix(suffix)：长度/字符集限制（建议：[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}）
• $HOME 宏替换：$HOME、$HOME/common/hf、$HOME/common/datasets
• 路径校验（强制本地路径）：
  • 允许：/private/hf/...、/private/users/<user_id>/...
  • 拒绝：..、空、其它用户路径、非 /private 路径
• make_model_id_prefix(user_id, now_utc)：YYYYMMDDHHMM（UTC）+ user_id

M1.3 单测（先写失败用例，再补实现）

• test_serving_spec_validation.py
  • suffix 合法/非法
  • replicas/gpus 边界：0、负数、小数、超大值（按实现决定是否限制上限）
• test_serving_spec_paths.py
  • $HOME 替换正确
  • 越权路径返回 403/ValueError（按接口层映射）
  • /private/hf 与 /private/users/<user> 均可
• test_serving_model_id_prefix.py
  • 固定时间输入 → prefix 输出一致（避免时区/格式问题）

验收：

• 输入 spec 规则稳定；核心校验/替换均有单测覆盖

---

M2 - SQLite 表结构与 Db 接口（单测驱动）

目的：Serving 的声明式状态必须持久化，可审计、可恢复。

M2.1 DB schema

• serve_models
  • 主键：model_key（平台生成）
  • unique：(user_id, model_id_suffix)（实现 upsert）
  • 存储：resolved spec（包含 prefix/full model_id、resolved model_source）
  • 状态：QUEUED/DEPLOYING/RUNNING/FAILED/DELETING/DELETED
  • error_summary
• serve_events（append-only）

M2.2 Db 方法

• upsert_serve_model(user_id, spec_yaml, now) → (model_key, state)
• list_serve_models(user_id, include_deleted=False, limit/offset?)
• get_serve_model(model_key)
• set_serve_model_state(model_key, state, error_summary=None)
• append_serve_event(model_key, event_type, payload_json=None)
• pick_next_runnable_serve_change()（给 reconciler 用）

M2.3 单测

• test_db_serving.py
  • upsert 行为（同 suffix 更新不产生新 model_key 或产生新版本——此处需在实现前明确策略）
  • state 流转 + 事件记录
  • list 的过滤与排序（按 updated_at）

验收：

• DB 行为可预测；upsert/unique 语义确定并测试覆盖

---

M3 - Serving 管理 API（FastAPI）（单测驱动）

目的：先把管理 API 跑通，Ray Serve 先不接真实（reconciler 之后再接）。

M3.1 API 路由（用户）

• POST /api/v2/serve/models（Content-Type: application/yaml）
  • 入参：ServingSpec YAML
  • 出参：{model_key,state}（202）
• GET /api/v2/serve/models
  • 返回 items + openai_base_url=http://<host>:8000/v1
• GET /api/v2/serve/models/{model_key}
  • 返回 model + resolved_spec_yaml + events（分页可后置）+ serve_status（先空/占位）
• PATCH /api/v2/serve/models/{model_key}（JSON）
  • 支持 num_replicas（最小闭环）
• DELETE /api/v2/serve/models/{model_key}

M3.2 API 路由（admin，可选）

• GET /api/v2/serve/status（仅 admin token）

M3.3 错误映射（必须测试）

• YAML 解析失败：400
• spec 校验失败：422
• 越权路径：403
• 不存在 model_key：404

M3.4 单测

• test_app_serving_api.py
  • happy path：create → list → get → patch → delete
  • 多用户隔离：用户只能看到自己的 model
  • 错误码覆盖：400/403/404/422

验收：

• API reference (v3.8_api.md) 中所有管理接口可返回预期结构（Serve 未接入也能工作）

---

M4 - ServeClient 抽象 + LLMConfig builder（单测驱动）

目的：将“如何从 ResolvedServingSpec 构造 LLMConfig”固化，并把 Ray Serve 的依赖隔离到 client 里，便于 mock。

M4.1 ServeClient 接口（可 mock）

• ensure_started(http_port=8000, proxy_location="HeadOnly")
• apply_app(app_name, llm_configs)（multi-model）
• get_status()（serve.status 摘要）

M4.2 build_llm_config(resolved_spec, accelerator_type, runtime_env_defaults) 纯函数

• 写入 LLMConfig.accelerator_type（来自 dev.yaml：H20）
• deployment_config.num_replicas
• engine_kwargs.tensor_parallel_size = gpus_per_replica
• placement_group_config bundles 按 GPU 张数生成
• runtime_env.env_vars 注入（至少包含 HF cache + HF_HUB_OFFLINE=1）

M4.3 单测

• test_llm_config_builder.py
  • gpus_per_replica=1/2/4 → tensor_parallel_size 与 bundles 数量正确
  • accelerator_type 注入正确
  • runtime_env 含 HF_HUB_OFFLINE 等关键 env

验收：

• 从平台 spec 到 Ray Serve LLMConfig 的映射规则稳定，有单测锁定

---

M5 - Serving Reconciler（状态机 + 资源预检查）（单测驱动）

目的：实现声明式对齐：DB → Serve；同时提供可解释的 QUEUED/FAILED 状态。

M5.1 状态机（最小闭环）

• QUEUED：等待 apply
• DEPLOYING：已触发 apply，等待 Serve running/healthy
• RUNNING：Serve status running
• FAILED：apply 或 status 失败（写 error_summary + event）
• DELETING：等待从 app 中移除
• DELETED：完成删除（可选保留记录）

M5.2 资源预检查

• needed_total_gpus = sum(num_replicas*gpus_per_replica)（最小可用预检查）
• ray.available_resources()["GPU"]（或更稳健的 per-node 统计）不足时：
  • 保持 QUEUED
  • 记录 PENDING_RESOURCES event

M5.3 reconcile 策略（multi-model app）

• tick 读取 active models，构建全量 llm_configs
• 处理 deleting：从 configs 中移除对应 model，再 apply

M5.4 单测（mock ServeClient + mock ray resources）

• test_serving_reconciler.py
  • 新增模型：apply_app 被调用；state 进入 DEPLOYING
  • 删除模型：apply_app configs 不包含该模型
  • GPU 不足：不 apply；state 仍 QUEUED；event 写入
  • apply 抛异常：state FAILED；error_summary 写入

验收：

• reconciler 行为在纯单测环境可验证；失败可解释

---

M6 - 真实集成（h1）：Ray Serve 启动 + 推理闭环（E2E）

目的：在 dev/h1 环境真正跑通：部署模型 → /v1/models 可见 → chat/completions 成功 → 删除后消失。

M6.1 compose/端口

• src/mvp/docker-compose.yaml：ray_head 增加 8000:8000

M6.2 镜像依赖（若 M0 发现缺失）

• 在 argus-ray-node 镜像中补齐 ray[serve,llm]（版本与现有 Ray 对齐，避免升级 Ray 导致不兼容）
  • 推荐优先补齐 ray[llm]（包含 ray.serve.llm 依赖闭包，如 gymnasium），再按需补 ray[serve]
  • 验证点：python3 -c "from ray.serve.llm import LLMConfig, build_openai_app; print('serve_llm_ok')"

M6.3 E2E 脚本（幂等）

• 新增 scripts/run_all_v38_serving.sh：
  • 起 compose（确保 Serve 端口可用）
  • 起 API
  • 创建 user + token
  • POST /api/v2/serve/models 创建 1GPU 模型
  • 轮询模型 state 到 RUNNING
  • curl http://127.0.0.1:8000/v1/models 验证包含 <prefix>-<suffix>
  • curl http://127.0.0.1:8000/v1/chat/completions 进行最小推理
  • DELETE /api/v2/serve/models/{model_key} 下线
  • 再轮询 /v1/models 不包含

验收：

• E2E 可重复跑通（至少两次连续跑不需要人工清理）

---

M7 - WebUI（Serving 页面）（单测驱动）

目的：给用户可视化的模型管理页面（最小必要功能）。

M7.1 页面

• Sidebar 增加 Serving
• /ui/serving：列表 + 状态 + 操作（delete/scale）
• /ui/serving/new：YAML 输入 + submit
• /ui/serving/{model_key}：详情（resolved spec、events、OpenAI 调用示例）

M7.2 单测

• test_ui_serving.py：路由 200、关键链接存在、包含 openai_base_url=8000

验收：

• WebUI 覆盖 create/list/detail/scale/delete 的主链路

---

M8 - 文档与验收用例（交付）

目的：给用户/运维一套可复用的运行方式与排障路径。

• 更新 specs/mvp/v3.8/v3.8_progress.md（按 milestone 记录）
• 补充 README（可选）：端口说明、推理 API 无鉴权警示、模型路径约定
• 验收清单（checklist）：
  • 单测通过
  • h1 E2E 通过
  • UI 主链路可操作