307 lines
13 KiB
Markdown
307 lines
13 KiB
Markdown
# MVP v2.0 开发计划（服务化入口 + 队列调度 + Ray Jobs SDK）
|
||
|
||
目标：在 v1.1（脚本 + Ray Jobs SDK）已验收通过的基础上，交付一个**可独立运行的最小“服务层”**：
|
||
- 用户通过 **HTTP API** 提交训练任务（PPO/GRPO/SFT）。
|
||
- 服务层分配一个**人类易读的任务 ID**（`task_id`），并把任务放入队列。
|
||
- 后台调度器在资源满足时再向 Ray 集群提交 Ray Job，并持续追踪 Ray Job 状态。
|
||
- 针对 `verl` 的 **fail-fast 资源预检查**（资源不足直接 `ValueError` 失败）做“服务级重试/排队”，避免用户反复手工提交。
|
||
|
||
> 约束继承 v1.1：head 不跑训练；driver 必须落到 worker；共享存储只考虑 NFS（容器内 `/private`）。
|
||
|
||
---
|
||
|
||
## 1. 背景：为什么 v2.0 需要“服务层调度”
|
||
|
||
在 v1.1 中我们通过 Ray Job 提交 `verl` 训练任务。`verl` PPO/GRPO 在初始化 worker 时会创建资源池，并做一次 fail-fast 的资源检查：
|
||
- 触发点：`ResourcePoolManager.create_resource_pool()` 末尾调用 `_check_resource_available()`
|
||
- `_check_resource_available()` 使用 `ray._private.state.available_resources_per_node()` 统计“可用 GPU/NPU”，如果不足则直接抛异常：
|
||
- `ValueError: Total available GPUs 0 is less than total desired GPUs 8`
|
||
|
||
这是一种合理的选择（避免 Ray 层面无限 pending/卡死），但会带来一个平台侧问题：
|
||
- 当集群暂时没有足够资源时，用户提交会“立刻失败”，需要手动重试。
|
||
|
||
因此 v2.0 的服务层要提供：
|
||
- **队列 + gang 约束**：资源不满足则任务在服务层 pending（不提交到 Ray）。
|
||
- **状态追踪**：一旦提交到 Ray，持续获取 Ray Job 状态并回传给用户。
|
||
- **资源不足的“自动重试”**：即使发生 race（提交时资源够、启动时被抢走），也能识别该类失败并延迟重试。
|
||
|
||
---
|
||
|
||
## 2. v2.0 交付范围（Scope）
|
||
|
||
### 2.1 必做（MVP v2.0）
|
||
|
||
1) **HTTP API**（内部 token）：
|
||
- 提交任务、查询任务、取消任务、拉取日志（最小可用）。
|
||
2) **任务队列与调度器**：
|
||
- FIFO（先到先服务），无配额/公平性（留给 v3+）。
|
||
- gang：按 `nnodes` + `n_gpus_per_node` 的固定资源需求“全有才提交”。
|
||
3) **Ray Jobs SDK 集成**（不使用 `requests` 自己拼 HTTP）：
|
||
- 通过 `ray.job_submission.JobSubmissionClient` submit/status/stop/logs。
|
||
4) **可观测/可排障最小集**：
|
||
- 每个 task/attempt 落盘配置、提交载荷、Ray 返回的 `submission_id`、关键日志。
|
||
5) **失败策略**：
|
||
- 识别 “资源不足 fail-fast” 类失败 → 转为 `PENDING_RESOURCES` 并延迟重试。
|
||
- 其他失败保持 `FAILED`（不自动重试，避免掩盖错误）。
|
||
|
||
### 2.2 不做（v2.0 不实现）
|
||
|
||
- 多租户/配额/优先级/公平性调度（v3）。
|
||
- Pipeline（多 job 串联）（v3+）。
|
||
- 完整 UI（v3+，v2.0 可只提供 OpenAPI/Swagger）。
|
||
- K8s 编排（明确不做，仍是 Native Ray）。
|
||
|
||
---
|
||
|
||
## 2.3 工程原则（开闭原则 / 复用 v1.1）
|
||
|
||
v2.0 研发遵循开闭原则（Open/Closed Principle）：
|
||
- **对扩展开放**：新增“服务层（API + scheduler + SQLite）”能力以支持排队、重试、状态聚合。
|
||
- **对修改关闭**：尽量不改动 v1.1 已经稳定可用的 Ray Jobs SDK 提交链路代码。
|
||
|
||
落地方式：
|
||
- 将 `src/mvp/v1.1/py/mvp_v11/` 作为“成熟可用提交层”，原样拷贝到 `src/mvp/v2.0/py/mvp_v11/` 供 v2.0 复用。
|
||
- v2.0 的新增功能全部在新模块实现（例如 `src/mvp/v2.0/py/mvp_v2/`），通过组合/封装来调用 `mvp_v11`，避免在旧代码中掺杂平台逻辑。
|
||
|
||
---
|
||
|
||
## 3. 总体架构（v2.0）
|
||
|
||
### 3.1 组件
|
||
|
||
- **mvp-api**（HTTP Server）
|
||
- 接收 JobSpec（结构化字段保持与 v1.1 一致的语义）
|
||
- 生成 `task_id` 并写入持久化
|
||
- 提供 query/cancel/logs
|
||
|
||
- **mvp-scheduler**（后台调度器，可与 api 同进程也可拆进程）
|
||
- 轮询队列：对 `PENDING_RESOURCES` 的任务做资源判断
|
||
- 资源满足 → 调用 Ray Jobs SDK 提交 → 记录 `ray_submission_id`
|
||
- 对 `SUBMITTED/RUNNING` 的任务持续同步 Ray Job 状态
|
||
- 如果 Ray Job 失败且命中资源不足模式 → 延迟重试
|
||
|
||
> 部署建议：v2.0 先在 **head 容器**内运行该服务（dev/prod 行为一致；生产环境只能 ssh 进入容器纳管）。
|
||
|
||
### 3.4 dev 环境目录约定（示例）
|
||
|
||
以当前远程开发机为例（`argus@h1`）：
|
||
- 宿主机目录：`/home2/argus/infra/mvp/v2/`
|
||
- 容器内挂载：`/workspace/mvp/v2/`
|
||
- 共享 NFS：容器内统一为 `/private/`（与 v1.1 保持一致）
|
||
|
||
> 注意：服务脚本（`v2/scripts/*.sh`）应在**宿主机**执行，通过 `docker exec` 控制 head 容器；训练 driver 仍通过 Ray entrypoint_resources 强制落到 worker。
|
||
|
||
### 3.2 与 Ray/容器的关系
|
||
|
||
- 服务进程运行在 head（或等价能访问 head 的 Job server 地址）。
|
||
- 提交时仍使用 v1.1 的强约束：
|
||
- head：`--num-cpus=0 --num-gpus=0`
|
||
- worker：`--resources='{\"worker_node\": 100}'`
|
||
- job entrypoint：`entrypoint_resources={\"worker_node\": 1}` 强制 driver 落 worker
|
||
|
||
---
|
||
|
||
## 3.3 配置约定（复用 v1.1 dev.yaml 并扩展）
|
||
|
||
v2.0 的服务层（API + scheduler）建议复用 v1.1 已存在的 RayConfig 文件：
|
||
- `src/mvp/v1.1/py/configs/dev.yaml`
|
||
|
||
原因：
|
||
- 其中已包含 v1.1 运行所需的 Ray 基础配置（Ray Job server address、entrypoint_resources、runtime_env 等），v2.0 也需要同样的信息来提交 Ray Jobs。
|
||
|
||
扩展方式：
|
||
- 在该 YAML 中新增一个顶层 `v2:` section，存放 v2 服务专属配置（API 监听、SQLite 路径、scheduler 间隔等）。
|
||
- v1.1 submitter 只读取 `address/shared_root/entrypoint_* /runtime_env/user_code_path`，会忽略 `v2:` 之类的额外字段；因此不会破坏 v1.1。
|
||
|
||
最小新增项建议（示例）：
|
||
- `v2.api.host` / `v2.api.port`
|
||
- `v2.auth.token_env`（内部 token 环境变量名）
|
||
- `v2.sqlite.db_path`（建议 `/private/common/db/mvp_v2.sqlite3`）
|
||
- `v2.scheduler.tick_s` / `v2.scheduler.retry_interval_s` / `v2.scheduler.max_running_tasks`
|
||
|
||
---
|
||
|
||
## 4. 核心数据模型（Task / Attempt）
|
||
|
||
### 4.1 Task（用户视角的任务）
|
||
|
||
- `task_id`：**人类易读**且唯一，例如：
|
||
- `mvp2-ppo-20251223-143201-7f3a`
|
||
- `workload`：`ppo|grpo|sft`
|
||
- `jobspec`：提交参数（**保持 v1.1 的 jobspec YAML 字段与语义**；服务端解析 YAML 后入库）
|
||
- `state`：见第 5 节状态机
|
||
- `created_at` / `updated_at`
|
||
- `latest_attempt`：指向当前 attempt
|
||
- `attempts[]`：历史尝试列表
|
||
- `error_summary`：面向用户的简短错误（最后一次失败原因）
|
||
|
||
### 4.2 Attempt（一次真实的 Ray Job 提交）
|
||
|
||
- `attempt_no`：从 1 开始递增
|
||
- `ray_submission_id`：建议派生自 task_id：
|
||
- `ray_submission_id = <task_id>--a01`
|
||
- 好处：Ray 侧输出目录天然可读、可追溯
|
||
- `status`：Ray Job 状态（PENDING/RUNNING/SUCCEEDED/FAILED/STOPPED）
|
||
- `start_time` / `end_time`
|
||
- `exit_code`（如可取）
|
||
- `failure_kind`（枚举）：
|
||
- `INSUFFICIENT_RESOURCES`（匹配 “Total available GPUs … less than total desired …”）
|
||
- `USER_ERROR`（配置/数据路径错误等）
|
||
- `RUNTIME_ERROR`（代码异常）
|
||
- `UNKNOWN`
|
||
|
||
---
|
||
|
||
## 5. 状态机（服务侧）
|
||
|
||
建议最小状态集：
|
||
|
||
- `QUEUED`：已入队，尚未进行资源判断
|
||
- `PENDING_RESOURCES`：资源不足，等待（服务侧 pending，不提交 Ray）
|
||
- `SUBMITTING`：正在向 Ray 提交 attempt
|
||
- `SUBMITTED`：Ray 已接受 submission（拿到 `ray_submission_id`）
|
||
- `RUNNING`：Ray Job RUNNING
|
||
- `SUCCEEDED`：任务成功（终态）
|
||
- `FAILED`：任务失败（终态，除非命中“资源不足重试策略”）
|
||
- `CANCELED`：用户取消（终态）
|
||
|
||
关键转换：
|
||
- `QUEUED -> PENDING_RESOURCES`：资源不足
|
||
- `QUEUED/PENDING_RESOURCES -> SUBMITTING`：资源满足
|
||
- `SUBMITTING -> SUBMITTED`：提交成功
|
||
- `SUBMITTED -> RUNNING`：Ray 状态推进
|
||
- `SUBMITTED/RUNNING -> SUCCEEDED|FAILED`：Ray 终态
|
||
- `FAILED (INSUFFICIENT_RESOURCES) -> PENDING_RESOURCES`：进入延迟重试（attempt_no+1）
|
||
|
||
---
|
||
|
||
## 6. 调度策略（v2.0）
|
||
|
||
### 6.1 资源计算（对齐 verl 的“可用资源”口径）
|
||
|
||
由于 verl 使用 `ray._private.state.available_resources_per_node()` 做“可用资源”统计，
|
||
v2.0 的 scheduler 应该尽量使用相同口径，避免：
|
||
- 我们认为够了 → 实际 verl 认为不够（仍 fail-fast）
|
||
- 我们认为不够 → 实际够了（浪费）
|
||
|
||
策略（建议）：
|
||
1) scheduler 周期性获取 per-node 可用 GPU
|
||
2) 计算 total_available_gpus = sum(node_gpu_available)
|
||
3) 任务需求 total_required_gpus = nnodes * n_gpus_per_node
|
||
4) 如果 `total_available_gpus < total_required_gpus` → `PENDING_RESOURCES`
|
||
|
||
注意：v2.0 先只做总量判断；节点级分配（保证每个 node 恰好 n_gpus_per_node）可作为 v2.1+（资源池/标签/节点纳管）增强点。
|
||
|
||
### 6.2 排队与并发
|
||
|
||
- 默认 FIFO。
|
||
- 并发度：允许同时跑多个任务，但必须保证资源足够。
|
||
- 简化实现：如果任务默认都吃满 8 卡，则 scheduler 实际上一次只能跑一个。
|
||
- 若未来支持小任务（1*1、1*4），可以自然并发。
|
||
|
||
### 6.3 重试策略（资源不足）
|
||
|
||
当出现下面模式时判定为 `INSUFFICIENT_RESOURCES`：
|
||
- Ray Job `status=FAILED`
|
||
- `JobDetails.message` 或 `job logs` 中匹配：
|
||
- `Total available GPUs` 且 `less than total desired`
|
||
|
||
处理：
|
||
- 将 task 置为 `PENDING_RESOURCES`
|
||
- `next_run_at = now + 60s`（固定间隔；v2.1 可改指数退避）
|
||
- attempt_no++ 后重提（新 submission id）
|
||
|
||
---
|
||
|
||
## 7. SQLite 持久化（队列/状态/attempt）
|
||
|
||
v2.0 引入一个**最小但可恢复的持久化层**：使用 SQLite 保存任务队列与状态，确保：
|
||
- api/scheduler 进程重启后，队列不丢；
|
||
- task/attempt 历史可追溯；
|
||
- 能实现“服务侧 pending + 延迟重试”的确定性行为。
|
||
|
||
### 7.1 存放位置
|
||
|
||
建议路径（容器内）：
|
||
- `DB_PATH=/private/common/db/mvp_v2.sqlite3`
|
||
|
||
说明：
|
||
- v2.0 默认单实例服务（单 writer），SQLite 足够。
|
||
- 生产环境若 NFS 上的 SQLite 有锁/性能风险，v2.1+ 再演进到 Postgres/Redis；v2.0 先以“可回放/可恢复”为第一目标。
|
||
|
||
### 7.2 表设计（建议最小集合）
|
||
|
||
- `tasks`
|
||
- `task_id` (PK)
|
||
- `workload`
|
||
- `state`（服务侧状态机）
|
||
- `jobspec_yaml`（原始 YAML 文本，原样落盘便于审计/复现）
|
||
- `created_at`, `updated_at`
|
||
- `next_run_at`（用于 `PENDING_RESOURCES` 的延迟重试）
|
||
- `error_summary`
|
||
- `latest_attempt_no`
|
||
|
||
- `attempts`
|
||
- `task_id` (FK)
|
||
- `attempt_no`
|
||
- `ray_submission_id`
|
||
- `ray_status`
|
||
- `failure_kind`
|
||
- `message`（截断后的关键信息）
|
||
- `start_time`, `end_time`
|
||
|
||
- `events`（可选，但非常利于排障）
|
||
- `id` (PK)
|
||
- `task_id`
|
||
- `ts`
|
||
- `event_type`（STATE_TRANSITION / SUBMIT / RAY_STATUS_SYNC / RETRY_SCHEDULED 等）
|
||
- `payload_json`
|
||
|
||
### 7.3 调度循环（与 SQLite 的交互）
|
||
|
||
scheduler 每个 tick 做三件事：
|
||
1) **挑选可运行任务**（FIFO + next_run_at）：
|
||
- `state IN ('QUEUED','PENDING_RESOURCES') AND next_run_at <= now`
|
||
2) **资源判断**（对齐 verl 的可用资源口径）：
|
||
- 不满足：更新 `state='PENDING_RESOURCES'`，并写入 `next_run_at=now+60s`
|
||
3) **提交 Ray Job 并追踪**：
|
||
- 提交成功：写入 `attempts` 并更新 `tasks.latest_attempt_no`、`state='SUBMITTED'`
|
||
- 周期性同步 Ray 状态：`SUBMITTED/RUNNING -> SUCCEEDED/FAILED`
|
||
- 若失败命中资源不足模式：`FAILED -> PENDING_RESOURCES` + 计划下次重试
|
||
|
||
---
|
||
|
||
## 8. 接口与验收（DoD）
|
||
|
||
### 8.1 API 能力（最小集合）
|
||
|
||
详见 `specs/mvp/v2.0/v2_api.md`。
|
||
|
||
### 8.2 验收口径（DoD）
|
||
|
||
1) API 提交 PPO/GRPO/SFT，返回 `task_id`，并在 NFS 上创建任务目录。
|
||
2) 当集群忙（GPU 不足）时：
|
||
- task 状态为 `PENDING_RESOURCES`（不是 FAILED）
|
||
- 一旦资源释放，任务自动变为 `SUBMITTED/RUNNING`
|
||
3) 当 race 导致触发 verl fail-fast：
|
||
- attempt 标记为 `INSUFFICIENT_RESOURCES`
|
||
- task 回到 `PENDING_RESOURCES`，并在 60s 后自动重试
|
||
4) 通过 API 查询 task 能看到：
|
||
- 当前 state
|
||
- 最新 attempt 的 `ray_submission_id`
|
||
- attempt 历史（至少包含开始/结束/失败原因）
|
||
5) Cancel 能停止正在运行的 Ray Job（调用 Ray Jobs SDK stop）
|
||
|
||
---
|
||
|
||
## 9. v2.0 交付物建议（目录）
|
||
|
||
`specs/mvp/v2.0/`（本目录）：
|
||
- `v2_plan.md`：总体设计与开发计划（本文件）
|
||
- `v2_api.md`：API 详细定义（请求/响应/字段/错误码）
|
||
|
||
代码建议位置（后续实现时）：
|
||
- `src/mvp/v2.0/`
|
||
- `py/`：API server + scheduler
|
||
- `scripts/`：启动/停止/查看状态（仍沿用 v1.1 的 compose/cluster 逻辑）
|