# MVP v3.8 详细设计方案：Ray Serve（vLLM）模型动态部署与管理

> 基线：当前已具备 v3.7 能力（训练平台 + W&B + SFTPGo + WebUI/API + Ray stateless pool，训练侧默认 rollout=vllm）。  
> v3.8 目标：在同一套 Ray 集群上，引入 **Ray Serve LLM（后端 vLLM）** 的模型推理服务能力，并通过 WebUI/API 动态管理模型生命周期。

## 0. 需求范围（来自 requirements.md）

1) 通过 Ray Serve（后端 vLLM）动态拉起 LLM，支持**多模型 application** 部署  
2) 默认一个模型 1 个 replica，用户可配置多个  
3) 用户可删除（下线）模型  
4) 用户可指定模型使用几张 GPU  
5) WebUI 可配置、查看模型列表、查看详情  
6) 模型路径可用 common，也可用 user 路径（本地路径）

## 1. 总体架构

### 1.1 组件关系

v3.8 在现有“训练平台”之上新增一个 **Serving 子系统**：

- **API server（现有）**
  - 新增 Serving API（模型部署/删除/扩缩容/状态）
  - 新增 Serving 后台线程（reconciler）：周期性对齐 DB 与 Ray Serve 实际状态
- **SQLite（现有）**
  - 新增 `serve_models`、`serve_events` 等表，保存声明式配置与状态
- **Ray 集群（现有 stateless pool）**
  - 复用现有 head/worker 容器
  - 在集群内启动 Ray Serve（controller + proxy + deployments）
- **Ray Serve LLM（新增）**
  - 通过 `ray.serve.llm.build_openai_app` 构建一个 OpenAI-compatible app
  - app 内包含多个 `LLMConfig`（每个对应一个模型）

### 1.2 为什么选择“单个 multi-model application”

Ray Serve 支持 multi-app，但在 dev/docker 场景下多个 app 的 route_prefix 管理更复杂；同时 requirements 要求“多模型 application 部署”，因此 v3.8 采用：

- 一个固定的 app：`argus_llm_app`（名字可配置）
- route_prefix 固定为 `/`（对外暴露 `/v1/...` OpenAI 接口）
- 每个模型对应一个 `LLMConfig`，通过 `model_id` 区分（即 OpenAI API 里的 `model` 字段）

这样对用户而言最直观：

- base_url 固定：`http://<host>:8000/v1`
- `model=` 选择不同模型（`/v1/models` 自动列出）

## 2. Ray Serve 部署策略（dev/h1 约束）

### 2.1 HTTP 入口端口与 docker compose

Ray Serve 默认 HTTP 端口是 `8000`。v3.8 约定：

- 在 **head 容器** 映射 `8000:8000`
- API server 仍在 `8080`
- Ray Dashboard 在 `8265`

原因：在单机多容器 docker 环境里，如果让 proxy “每个节点都起”，会出现多个容器同时想绑定同一个 host 端口的问题（不可行）。因此 v3.8 推荐：

- Serve proxy 位置设为 **HeadOnly**（只在 head 上提供 HTTP 入口）
- GPU replica 仍运行在 worker 上（proxy 只转发，不跑推理）

> 需要注意：
> - Serve 的 HTTP 配置（host/port/proxy_location）是 **Ray 集群全局配置**，启动后无法动态修改，因此应当在平台启动时一次性设定并持久化。
> - proxy Actor 需要 CPU 资源；head 节点的 `num-cpus=0` 策略可能需要在 v3.8 做小幅调整（例如给 head 保留少量 CPU），但仍通过 `entrypoint_resources` 确保训练 driver 不会被调度到 head。

#### 2.1.1 compose 预期改动（v3.8 实现时落地）

- `src/mvp/docker-compose.yaml`（ray_head）新增：
  - `ports: - "8000:8000"`

> worker 容器不暴露 8000（避免 host 端口冲突），由 head proxy 统一对外提供入口。

### 2.2 启动/配置方式（Python SDK 优先）

v3.8 采用 Ray Serve Python SDK：

- `ray.init(address="auto")`
- `serve.start(proxy_location="HeadOnly", http_options={"host":"0.0.0.0","port":8000})`（一次性全局配置）
- `serve.run(app, name=<app_name>, route_prefix="/")`
- `serve.delete(name=<app_name>)`（必要时）
- `serve.status()` 查询集群/应用状态

理由：

- 避免在平台内部引入额外 REST client 依赖（并减少跨版本 REST schema 不稳定风险）
- API server 本身运行在 head 容器内，可直接 `ray.init(address="auto")` 连接现有集群

> 另：Ray Dashboard 暴露 Serve REST API（`PUT /api/serve/applications/` 等）可作为备选方案，但 v3.8 先不以它为主通路。

### 2.3 依赖与镜像假设

v3.8 依赖：

- `ray[serve]`（Serve Controller/Proxy）
- `ray[llm]`（Ray Serve LLM 的 `ray.serve.llm` 模块）
- vLLM（推理引擎）

由于 v3.7 已切换到 `verlai/verl:vllm011.latest`，预期镜像内包含 vLLM；但 `ray.serve.llm` 是否开箱即用需要在实现阶段确认。
若缺失，v3.8 将在 `argus-ray-node` 镜像构建阶段补充 `pip install "ray[serve,llm]"`（或按官方建议的最小依赖）并做版本锁定。

### 2.4 Serving 配置（dev.yaml）

v3.8 新增一段 serving 配置，至少包含：

```yaml
serving:
  serve:
    http_port: 8000              # 固定 8000
    proxy_location: HeadOnly     # dev/docker 下推荐
  llm:
    accelerator_type: H20        # dev 环境填写 H20（对应 ray.serve.llm.LLMConfig.accelerator_type）
```

说明：
- `accelerator_type` 是 Ray Serve LLM 的 `LLMConfig.accelerator_type` 字段，用于表达“该模型运行在哪类加速卡上”。在 dev/h1 环境我们固定为 `H20`。
- v3.8 不把 `accelerator_type` 暴露给普通用户编辑（避免误配）；由部署环境配置统一决定。

## 3. 模型配置与资源映射

### 3.1 关键配置对象：`ray.serve.llm.LLMConfig`

每个模型部署由一个 `LLMConfig` 描述，关键字段（v3.8 用到的子集）：

- `model_loading_config`
  - `model_id`: 对外展示/请求时用的模型名（唯一 key）
  - `model_source`: HF repo id / S3 / **local path**
- `accelerator_type`
  - 从 `dev.yaml` 的 `serving.llm.accelerator_type` 读取（dev/h1: `H20`）
- `deployment_config`
  - `num_replicas` 或 `autoscaling_config`（v3.8 先用固定 `num_replicas`）
  - `ray_actor_options`（CPU/资源约束）
- `engine_kwargs`
  - vLLM 相关参数（`max_model_len`、`gpu_memory_utilization` 等）
- `placement_group_config`
  - 控制 vLLM engine workers 使用的资源 bundle（用于多 GPU / 跨节点）
- `runtime_env`
  - 注入 HF cache、离线开关等环境变量

### 3.2 GPU 张数（gpus_per_replica）如何落到 LLMConfig

v3.8 把用户输入的：

- `gpus_per_replica = N`

映射为：

- `engine_kwargs.tensor_parallel_size = N`（单机/跨机张量并行，Ray Serve LLM 官方示例写法）
- `placement_group_config = {"bundles": [{"GPU": 1, "CPU": <cpu_per_gpu>}] * N, "strategy": "PACK"}`

并在 `engine_kwargs` 中保留 vLLM 其他参数（`max_model_len`、`gpu_memory_utilization` 等）。

> 兼容性说明：Ray Serve LLM/Serve LLM 仍处于快速演进阶段；v3.8 会以我们线上实际 Ray 版本为准做最小适配与回归测试。

### 3.2.1 跨节点场景（N > 单机 GPU）

Ray Serve LLM 默认使用 `PACK` 策略，优先把 GPU worker 放在尽量少的节点上；如果单机放不下，会自动 spill 到其它节点，从而支持跨节点张量并行（TP）部署。

### 3.3 replica 数（num_replicas）

v3.8 默认：

- `num_replicas = 1`

允许用户在 UI 中设置为 `>=1`。  
多 replica 会线性消耗 GPU（`num_replicas * gpus_per_replica`），需要做资源预检查。

### 3.4 模型路径与宏替换（common / user）

v3.8 支持两类模型来源：

1) **common**
- 典型为 `/private/hf/...`（共享 HF cache / snapshot）

2) **user**
- `/private/users/<user_id>/models/...`
- 以及用户训练输出（例如 `jobs/<sid>/checkpoints/.../huggingface`）

为保证 UI 易用，沿用平台已有的宏语义：

- `$HOME` → `/private/users/<user_id>`
- `$HOME/common/hf` → `/private/hf`

并进行路径校验：

- 允许前缀：`/private/hf`、`/private/users/<user_id>/`
- 拒绝：越权访问其他用户目录、或访问系统敏感路径

### 3.5 离线模式（避免 HF mirror 429）

v3.7 训练侧已验证 `HF_HUB_OFFLINE=1` 的必要性。v3.8 Serving 侧同样默认注入：

- `HF_HOME=/private/hf`
- `HUGGINGFACE_HUB_CACHE=/private/hf/hub`
- `TRANSFORMERS_CACHE=/private/hf/transformers`
- `HF_HUB_OFFLINE=1`
- `HF_ENDPOINT=https://hf-mirror.com`（可保留，但离线模式下不应触发网络）

并建议用户在 ServingSpec 中尽量填写 **local path** 作为 `model_source`，而不是直接 repo id。

## 4. 平台数据模型（SQLite）

新增两张主表：

### 4.1 `serve_models`

每一行代表一个“声明式模型部署”：

- `model_key`（平台内部唯一 ID，便于重命名/去重）
- `user_id`
- `model_id`（对外 OpenAI model 名称，要求 per-app 唯一）
- `model_source`（本地路径或 repo id，存 resolved 后的结果）
- `num_replicas`
- `gpus_per_replica`
- `engine_kwargs_json`（可选）
- `state`：`QUEUED | DEPLOYING | RUNNING | FAILED | DELETING | DELETED`
- `serve_app_name`（默认 `argus_llm_app`）
- `created_at / updated_at`
- `error_summary`

### 4.2 `serve_events`

记录关键事件与排障信息（类似 task_events）：

- `id`
- `model_key`
- `event_type`（DEPLOY_REQUESTED/DEPLOY_APPLIED/STATUS_SYNC/DELETE_REQUESTED/...）
- `payload_json`
- `created_at`

## 5. API 设计（新增）

在现有 `Authorization: Bearer <user_token>` 的认证体系下，新增 Serving API（路径仅示意，具体在实现时与现有 `api/v2` 对齐）。

### 5.1 用户接口

- `POST /api/v2/serve/models`
  - body: YAML 或 JSON（v3.8 先用 YAML 与现有 TaskSpec 一致）
  - 创建/更新（upsert）一个模型配置，进入 `QUEUED`
- `GET /api/v2/serve/models`
  - 列出当前用户的模型列表（含 state、资源、endpoint）
- `GET /api/v2/serve/models/{model_key}`
  - 详情：完整 spec + 最近事件 + Serve status 摘要
- `PATCH /api/v2/serve/models/{model_key}`
  - 修改 `num_replicas`、或 engine_kwargs（可选）
- `DELETE /api/v2/serve/models/{model_key}`
  - 下线模型（进入 `DELETING`）

### 5.2 系统接口（admin）

- `GET /api/v2/serve/status`（admin）
  - 返回 `serve.status()` 的摘要（集群级 / app 级）

### 5.3 对外推理 endpoint

固定输出到 UI/接口中：

- `openai_base_url = http://<host>:8000/v1`
- 支持：
  - `/v1/chat/completions`
  - `/v1/completions`
  - `/v1/embeddings`
  - `/v1/models`

> v3.8 不做额外网关与鉴权（保持与现有 dev 环境一致）；若后续需要，可在 v3.9+ 引入 token 校验/反向代理。

### 5.4 `model_id` 前缀策略（user_id-）

为避免多用户冲突并保持可读性：

v3.8 采用“**user_id + 日期小时分钟**”作为稳定前缀，以降低冲突并便于快速定位创建时间：

- 用户在 UI/API 中仅填写 `model_id_suffix`（或仍用字段名 `model_id`，但语义为 suffix）
- 平台计算实际对外 `model_id`：
  - `prefix = f"{user_id}-{YYYYMMDDHHMM}"`
  - `model_id = f"{prefix}-{model_id_suffix}"`
- 在列表/详情中同时展示：
  - `model_id_suffix`（用户输入）
  - `model_id_prefix`（平台生成，例如 `alice-202601061235`）
  - `model_id`（对外 OpenAI 名称）

## 6. 后台执行模型（Serving Reconciler）

v3.8 参考任务 scheduler 的模式，引入一个轻量的 reconciler：

- tick 周期（例如 5s）
- 每次 tick：
  1) 拉取 DB 中 `QUEUED/DEPLOYING/RUNNING/DELETING` 的模型
  2) 调用 `serve.status()` 读取当前 app 及 deployments 状态
 3) 若存在 `QUEUED` 或需要变更的模型：构建新的 multi-model app（包含全部 `RUNNING/DEPLOYING/QUEUED` 的模型配置）并 `serve.run(...)`
 4) 若存在 `DELETING`：从 app 配置中移除对应模型，并 `serve.run(...)` 应用变更
 5) 更新每个模型的 state（依据 Serve status）

重要行为说明（multi-model app 的代价）：
- 每次“新增/删除/改 replicas”都会触发对同一个 app 的一次 `serve.run(...)` 更新；
- Ray Serve 会尽量做增量更新，但在某些版本/配置下可能导致 ingress/router 短暂重启；
- v3.8 先接受该代价（满足需求闭环优先）；若后续需要“删除某模型不影响其它模型”，可演进为“每模型一个 app + 单独 route_prefix”的方案。

资源预检查：
- 在 apply 前使用 `ray.available_resources()` 做粗粒度 GPU 预检查：
  - 需要 GPU 总量 = `sum(num_replicas * gpus_per_replica)`（仅对“新增/扩容的差量”更精确）
- 若不足：
  - 模型保持 `QUEUED`，记录事件 `PENDING_RESOURCES`
  - 用户 UI 显示“资源不足，等待释放”

> v3.8 不引入更复杂的抢占/优先级。Serving 与 Training 会竞争 GPU；用户需要自行规划资源（或后续版本引入统一调度）。

## 7. WebUI 设计（新增 Serving 页面）

新增侧边栏入口：**Serving**

### 7.1 Serving 列表页

- 展示字段：
  - model_id
  - user_id（仅 admin 可见）
  - replicas / gpus_per_replica / total_gpus
  - state（RUNNING/DEPLOYING/QUEUED/FAILED）
  - 操作：Scale（修改 replicas）、Delete

### 7.2 Serving 创建/编辑页

两种模式（与 New Task 类似，先做 YAML 模式即可）：

示例 YAML（v3.8）：

```yaml
model_id: qwen-0.5b
model_source: $HOME/common/hf/hub/models--Qwen--Qwen2.5-0.5B-Instruct/snapshots/<sha>
num_replicas: 1
gpus_per_replica: 1
# engine_kwargs:
#   max_model_len: 8192
#   gpu_memory_utilization: 0.9
```

### 7.3 Serving 详情页

- 完整配置（resolved spec）
- Serve status 摘要（deployments 状态、replica 健康）
- OpenAI 调用示例（python openai client）

## 8. 验收标准（v3.8）

1) 部署：
- 一键部署一个模型（1 replica、1 GPU）成功，状态变为 RUNNING
- `/v1/models` 可列出该模型

2) 扩缩容：
- 修改 `num_replicas` 生效（Serve status 看到副本数变化）

3) 多模型：
- 同一个 app 内能同时部署 2 个模型（不同 model_id）
- 通过 OpenAI 接口用不同 `model=` 请求可得到响应

4) 下线：
- 删除某模型后 `/v1/models` 不再出现

5) 模型路径：
- 支持 `/private/hf/...`（common）与 `/private/users/<user>/...`（user）两类本地路径

6) 资源不足可解释：
- 当 GPU 不足时，模型进入 `QUEUED` 并在 UI/详情中提示“资源不足”

## 9. 待确认点（请你评审时确认）

已确认（来自评审）：

1) 推理端口固定使用 `8000`（Ray Serve 默认端口）。
2) 对外暴露的 OpenAI 接口 **不与现有 token 体系绑定**（v3.8 不做推理侧鉴权）。
3) `model_id` 命名规则：平台统一加 `user_id + 日期小时分钟` 前缀，用户在 UI 里只填写后缀部分。

> 说明：这样可以避免跨用户 model_id 冲突，同时在 OpenAI API 的 `model=` 字段上自然可读。