# MVP v2.0 API 设计（最小可用）

v2.0 的 API 目标是：把 v1.1 的“脚本提交”变成“服务化提交”，并在服务侧实现队列/重试/状态聚合。

约束：
- 内部 token 鉴权（简单即可）。
- Ray Job 提交必须使用 **Ray Python SDK**（`JobSubmissionClient`），不使用 `requests` 手写 HTTP。
- 输出与状态必须落盘到 NFS（容器内 `/private`）。

---

## 1. 鉴权

- Header：`Authorization: Bearer <INTERNAL_TOKEN>`
- v2.0 不做用户体系与权限隔离；token 只是“防误用”。
- 配置建议：复用 `src/mvp/v1.1/py/configs/dev.yaml` 并在 `v2.auth.token_env` 指定 token 环境变量名。

## 1.1 运行位置（dev 示例）

- 服务进程运行在 **Ray head 容器**（便于访问 Ray Job server）。
- 宿主机侧用脚本控制（`docker exec`）：
  - `src/mvp/v2.0/scripts/20_start_api.sh`
  - `src/mvp/v2.0/scripts/21_stop_api.sh`
  - `src/mvp/v2.0/scripts/22_status_api.sh`
- 远程机目录约定（示例）：`argus@h1:/home2/argus/infra/mvp/v2/`，容器内挂载到 `/workspace/mvp/v2/`。

---

## 2. 资源与 ID 约定

### 2.1 task_id（服务层主 ID）

- 格式建议：`mvp2-<workload>-<YYYYMMDD>-<HHMMSS>-<suffix>`
  - 示例：`mvp2-ppo-20251223-143201-7f3a`

### 2.2 ray_submission_id（attempt 级 ID）

- 由 service 派生：`<task_id>--a<NN>`
  - 示例：`mvp2-ppo-20251223-143201-7f3a--a01`

好处：
- Ray 的 submission id 自带 task_id，可直接从 Ray dashboard 反查到服务侧任务。
- `/private/jobs/<ray_submission_id>/...` 目录天然隔离且可读。

---

## 3. JobSpec（请求体）

v2.0 **要求 JobSpec 使用 v1.1 同款 YAML**（字段与语义保持一致），服务端接收 YAML 文本并解析后入库（同时原样保存 `jobspec_yaml` 便于审计/复现）。

最小字段（示例 YAML）：

```yaml
workload: "ppo"
submission_id: ""            # v2.0 服务端会忽略/覆盖（由 task_id 派生 ray_submission_id）
code_path: "/private/common/code/verl/verl_repo"
model_id: "Qwen/Qwen2.5-0.5B-Instruct"
train_file: "/private/datasets/gsm8k/train.parquet"
val_file: "/private/datasets/gsm8k/test.parquet"
nnodes: 2
n_gpus_per_node: 4
total_epochs: 1
total_training_steps: 10
save_freq: 10
test_freq: -1
trainer_device: null         # 仅 sft 使用（通常 "cpu"）
```

说明：
- `trainer_device` 仅对 `sft` 生效（通常为 `cpu`，避免 driver 无 GPU）。
- `val_file` 可为 `null`（例如 SFT）。

---

## 4. API 端点

### 4.1 提交任务

`POST /api/v2/tasks`

Request body：
- **raw JobSpec YAML**（与 v1.1 jobspec YAML 结构一致）

Headers：
- `Content-Type: application/yaml`（或 `text/yaml`）

Response：
```json
{
  "task_id": "mvp2-ppo-20251223-143201-7f3a",
  "state": "QUEUED"
}
```

### 4.2 查询任务（聚合状态）

`GET /api/v2/tasks/{task_id}`

Response（示例）：
```json
{
  "task_id": "mvp2-ppo-20251223-143201-7f3a",
  "workload": "ppo",
  "state": "RUNNING",
  "desired_resources": {"nnodes": 2, "n_gpus_per_node": 4, "total_gpus": 8},
  "latest_attempt": {
    "attempt_no": 1,
    "ray_submission_id": "mvp2-ppo-20251223-143201-7f3a--a01",
    "ray_status": "RUNNING",
    "start_time": "2025-12-23T14:32:10+08:00"
  },
  "error_summary": null
}
```

### 4.3 列出 attempts

`GET /api/v2/tasks/{task_id}/attempts`

Response：
```json
{
  "task_id": "mvp2-ppo-20251223-143201-7f3a",
  "attempts": [
    {
      "attempt_no": 1,
      "ray_submission_id": "mvp2-ppo-20251223-143201-7f3a--a01",
      "ray_status": "FAILED",
      "failure_kind": "INSUFFICIENT_RESOURCES",
      "message": "Total available GPUs 0 is less than total desired GPUs 8",
      "start_time": "...",
      "end_time": "..."
    }
  ]
}
```

### 4.4 取消任务

`POST /api/v2/tasks/{task_id}:cancel`

行为：
- 若 task 处于 `SUBMITTED/RUNNING`：调用 Ray Jobs SDK `stop_job(ray_submission_id)` 并标记 `CANCELED`
- 若处于 `QUEUED/PENDING_RESOURCES`：直接标记 `CANCELED`（不提交）

Response：
```json
{"task_id":"...","state":"CANCELED"}
```

### 4.5 获取日志

`GET /api/v2/tasks/{task_id}/logs?attempt=latest&tail=2000`

返回：
- `text/plain`（直接透传 Ray Job logs tail）

说明：
- v2.0 先用 Ray SDK `get_job_logs()`。
- 若需要更稳定的归档，可在 scheduler 定期抓取并落盘（v2.1+）。

### 4.6 列出队列（运维/调试）

`GET /api/v2/queue`

Response：
```json
{
  "pending": [{"task_id":"...","state":"PENDING_RESOURCES","next_run_at":"..."}],
  "running": [{"task_id":"...","ray_submission_id":"..."}]
}
```

---

## 5. 错误码（最小）

- `400`：jobspec 缺字段/非法
- `401`：token 不正确
- `404`：task 不存在
- `409`：状态冲突（例如已终态又 cancel）
- `500`：服务内部错误

---

## 6. SQLite 持久化（API 可见性）

v2.0 服务端使用 SQLite 持久化保存：
- tasks（`task_id`、`state`、`jobspec_yaml`、`next_run_at`、`latest_attempt_no` 等）
- attempts（`ray_submission_id`、`ray_status`、失败原因等）

因此：
- `GET /api/v2/tasks/{task_id}` 的数据来自 SQLite（再叠加 Ray 状态同步的结果）。
- 进程重启后，队列可恢复，`PENDING_RESOURCES` 的任务会在 `next_run_at` 到期后继续尝试提交。