5.8 KiB
MVP v3.8 API Reference（Serving）
说明：本节为 v3.8 新增的 Model Serving API（Ray Serve LLM / vLLM）。
认证：Serving 管理 API 复用现有 MVP API 的认证方式（Authorization: Bearer <user_token>）。
推理：对外 OpenAI endpoint 不做鉴权（v3.8 约定）。
0. 基本信息
0.1 Base URLs
- MVP API server：
http://<host>:8080 - Ray Serve OpenAI ingress（固定端口 8000）：
http://<host>:8000/v1
0.2 认证
所有 /api/v2/serve/* 接口要求：
Authorization: Bearer <user_token>
其中 user_token 由管理员通过 /api/v2/users/<user_id>/tokens 颁发（沿用现有机制）。
0.3 命名规则：model_id = user_id-YYYYMMDDHHMM-<suffix>
- 用户提交时填写
model_id（语义为 suffix，例如qwen-0.5b） - 平台生成前缀：
prefix = "<user_id>-<YYYYMMDDHHMM>"
- 平台实际对外暴露的 OpenAI model 名称为：
model_id = "<prefix>-<suffix>"- 示例：
alice-202601061235-qwen-0.5b
1. 数据结构
1.1 ServingSpec（YAML）
请求体建议使用 YAML（与 TaskSpec 一致），示例：
model_id: qwen-0.5b # 必填：suffix（平台自动加 user_id- 前缀）
model_source: $HOME/common/hf/.../<sha> # 必填：本地路径或 repo id；平台做 $HOME 宏替换与路径校验
num_replicas: 1 # 可选，默认 1
gpus_per_replica: 1 # 可选，默认 1
# engine_kwargs: # 可选：vLLM 参数透传（白名单/黑名单由实现决定）
# max_model_len: 8192
# gpu_memory_utilization: 0.9
说明：
accelerator_type不在 ServingSpec 中暴露；由平台配置（dev.yaml的serving.llm.accelerator_type）统一注入到 Ray Serve LLM 的LLMConfig.accelerator_type（dev/h1:H20）。
宏替换
$HOME→/private/users/<user_id>$HOME/common/hf→/private/hf$HOME/common/datasets→/private/datasets（serving 不强依赖，但保留一致语义）
路径校验（v3.8 约定）
model_source 允许：
/private/hf/...（common）/private/users/<user_id>/...（user）
拒绝：
- 其它用户目录
- 非
/private下路径 - 空路径或包含
..的可疑路径
1.2 ServingModel（响应体，JSON）
{
"model_key": "svc-alice-20260106-123000-abcd",
"user_id": "alice",
"model_id": "alice-202601061235-qwen-0.5b",
"model_id_suffix": "qwen-0.5b",
"model_id_prefix": "alice-202601061235",
"model_source": "/private/hf/hub/models--.../snapshots/<sha>",
"num_replicas": 1,
"gpus_per_replica": 1,
"total_gpus": 1,
"state": "RUNNING",
"endpoint": {
"openai_base_url": "http://<host>:8000/v1",
"model": "alice-202601061235-qwen-0.5b"
},
"error_summary": null,
"created_at": "2026-01-06T12:30:00Z",
"updated_at": "2026-01-06T12:31:02Z"
}
2. 管理 API（MVP API server）
2.1 Create / Upsert model
POST /api/v2/serve/models
Request
- Header:
Content-Type: application/yaml - Body: ServingSpec（YAML）
Response (202)
{
"model_key": "svc-alice-20260106-123000-abcd",
"state": "QUEUED"
}
语义：
- 创建新模型（若 suffix 不存在）
- 或更新已有模型（若同一用户同一 suffix 已存在）：更新 replicas/gpu 等配置，进入
QUEUED等待 reconciler apply
2.2 List models (current user)
GET /api/v2/serve/models
Response (200)
{
"items": [ ... ServingModel ... ],
"openai_base_url": "http://<host>:8000/v1"
}
2.3 Get model detail
GET /api/v2/serve/models/{model_key}
Response (200)
{
"model": { ... ServingModel ... },
"resolved_spec_yaml": "model_id: ...\nmodel_source: ...\n",
"events": [
{ "event_type": "DEPLOY_REQUESTED", "created_at": "...", "payload": {...} }
],
"serve_status": {
"app_name": "argus_llm_app",
"app_status": "RUNNING"
}
}
2.4 Scale replicas (PATCH)
PATCH /api/v2/serve/models/{model_key}
Request (JSON)
{ "num_replicas": 2 }
Response (200)
{ "model_key": "...", "state": "QUEUED" }
v3.8 只支持修改
num_replicas（以及可选 engine_kwargs）；gpus_per_replica若修改，可能触发重新部署。
2.5 Delete / Undeploy model
DELETE /api/v2/serve/models/{model_key}
Response (200)
{ "model_key": "...", "state": "DELETING" }
语义：从“声明式配置”中删除该模型，reconciler 会在下一轮 tick 触发 serve.run(...) 更新 app 配置并最终使其不可见。
2.6 Admin: Serve cluster status（可选）
GET /api/v2/serve/status
Response (200)
返回 serve.status() 摘要（集群级 + app 级）。
仅 admin token 可访问（沿用 v3.x admin gate）。
3. 推理 API（Ray Serve OpenAI ingress）
v3.8 不做鉴权：无需
Authorization。
3.1 List models
GET http://<host>:8000/v1/models
返回可用 model 列表（包含 alice-qwen-0.5b 这类带前缀名称）。
3.2 Chat completions
POST http://<host>:8000/v1/chat/completions
{
"model": "alice-202601061235-qwen-0.5b",
"messages": [{"role":"user","content":"Hello"}],
"stream": false
}
3.3 Completions / Embeddings
按 Ray Serve LLM OpenAI ingress 支持范围提供（v3.8 验收至少覆盖 chat）。
4. 错误码约定（MVP API server）
400 invalid yaml/spec：YAML 解析失败、字段缺失、值不合法403 forbidden：路径越权（model_source 访问其他用户目录）409 conflict：model_id_suffix 冲突（同一用户重复创建且不允许覆盖时；若选择 upsert 则不返回该错误）422 unprocessable：资源参数非法（replica/gpu <=0）500 internal：reconciler/serve 调用异常（详情记录到serve_events，并写入error_summary）