模型部署

模型部署将推理引擎与模型文件组合为可运行的推理服务。创建、更新、启动和停止接口在提交工作负载变更后即返回，实际状态由 KServe 异步收敛；调用方应通过详情接口中的 status、ready、stopped 和 conditions 判断部署是否最终可用。

部署是项目级资源。普通调用方只能访问当前项目的部署，具有全局读取权限的管理员可以查看所有项目的部署。创建部署时可以引用当前项目或公共的推理引擎、模型和模型文件，但这些关联资源的可见性必须一致。

创建部署至少需要 name 和 engineId，并且必须通过 artifactId 或 modelUri 解析出模型 OCI URI。replicas 省略或小于 1 时按 1 处理。更新接口不能替换已经部署的 modelId、artifactId 或 modelUri；如需更换模型文件，应创建新的部署。

部署响应中的 spec.endpoint 是集群内访问地址，仅在 KServe 已报告工作负载 Service 后返回，不能将其视为面向公网的推理地址。日志接口返回纯文本，follow=true 或 follow=1 时持续输出；终端接口使用 WebSocket。

方法	路径（产品接口统一前缀 /api/v1）	功能
GET	/deployments	查询模型部署
POST	/deployments	创建模型部署
GET	/deployments/api-schemas	查询部署支持的 API 协议
GET	/deployments/{id}	获取模型部署详情
PATCH	/deployments/{id}	更新模型部署配置
POST	/deployments/{id}/stop	停止部署
POST	/deployments/{id}/start	启动部署
DELETE	/deployments/{id}	删除模型部署
GET	/deployments/{id}/pods	查询部署 Pod
GET	/deployments/{id}/logs	读取或持续跟踪容器日志
GET	/deployments/{id}/metrics	查询部署监控指标
GET	/deployments/{id}/exec	建立 WebSocket 终端会话

查询模型部署

功能介绍

分页查询调用方有权查看的模型部署。普通调用方返回当前项目的部署；具有全局读取权限的管理员可以返回所有项目的部署。

列表响应提供部署的目录状态和配置快照，不读取实时 ready 和 conditions。需要判断工作负载的实时状态时，应调用部署详情接口。

访问要求：有效 Token；需要模型部署读取权限。

URI

GET /api/v1/deployments

查询参数

参数	类型	必选	描述
page	integer	否	页码，从 1 开始；省略或小于 1 时按 1 返回
page_size	integer	否	每页数量，最大 200；省略或传 0 时返回全部匹配项，响应中的 page_size 为 0

请求消息

无请求体。

响应消息

参数	参数类型	描述
items	array	部署列表；对象字段与部署详情基本一致，但不包含实时 ready 和 conditions
total	integer	匹配条件的部署总数
page	integer	当前页码
page_size	integer	请求的每页数量；未限制时为 0

请求示例

GET https://{endpoint}/api/v1/deployments?page=1&page_size=20
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": [
    {
      "id": "deployment-7f3a",
      "name": "qwen-chat",
      "description": "Qwen 对话模型",
      "status": "ready",
      "projectId": "project-a",
      "ownerUserId": "user-a",
      "backend": {
        "catalog": "k8s",
        "type": "LLMInferenceService",
        "id": "project-a/qwen-chat"
      },
      "spec": {
        "architecture": "amd64",
        "k8sName": "qwen-chat",
        "engineId": "engine-vllm",
        "engineName": "vLLM",
        "engineConfigName": "vllm-config",
        "modelId": "model-qwen",
        "artifactId": "artifact-qwen",
        "artifactName": "Qwen2.5-7B-Instruct",
        "modelUri": "oci://registry.example.com/models/qwen@sha256:0123456789abcdef",
        "modelName": "qwen2.5-7b-instruct",
        "replicas": 1,
        "endpoint": "http://qwen-chat-kserve-workload-svc.project-a.svc.cluster.local:8000"
      },
      "stopped": false,
      "labels": {
        "beacon.io/runtime": "vllm"
      },
      "createdAt": "2026-09-21T00:00:00Z",
      "updatedAt": "2026-09-21T00:05:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型部署读取权限
500	internal_error	查询部署列表失败

错误返回格式见调用方式。

创建模型部署

功能介绍

在当前项目中创建模型部署，并提交对应的 KServe 工作负载。接口成功仅表示部署资源已经创建，初始 status 为 pending；应继续查询详情，直到 status 变为 ready，或者根据 conditions 处理异常。

访问要求：有效 Token；需要模型部署写入权限。平台已配置 Kubernetes 时，还需要项目作用域令牌。

URI

POST /api/v1/deployments

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
name	string	是	部署显示名称；去除首尾空白后不能为空，同时用于生成 Kubernetes 工作负载名称
description	string	否	部署说明
engineId	string	是	推理引擎 ID；可以引用当前项目或公共引擎
modelId	string	否	来源模型 ID，用于记录模型关联关系
artifactId	string	条件必选	模型文件 ID；与 modelUri 至少提供一种。提供后优先从该模型文件解析 OCI URI
modelUri	string	条件必选	模型 OCI URI；未提供可解析的 artifactId 时必选。省略 oci:// 前缀时服务端会自动补全
modelName	string	否	推理服务对外标识的模型名称；引擎引用 SERVED_MODEL_NAME 时建议提供
replicas	integer	否	期望副本数；省略或小于 1 时按 1 处理
image	string	否	覆盖引擎默认值的容器镜像
command	array	否	覆盖引擎默认值的容器启动命令
args	array	否	覆盖引擎默认值的容器启动参数
env	array	否	覆盖或补充的容器环境变量
resources	object / null	否	覆盖引擎默认值的计算资源配置
kvCacheOffloading	object / null	否	KV Cache CPU 卸载配置，仅适用于使用加速器资源的 vLLM 引擎
labels	object	否	部署标签，键和值均为字符串；系统管理的标签可能被补充或覆盖
lora	object / null	否	LoRA 适配器配置，仅适用于 vLLM 引擎

参数	参数类型	是否必选	描述
env[].name	string	是	环境变量名称
env[].value	string	是	环境变量值
resources.cpu	string	否	Kubernetes CPU quantity，例如 4 或 500m
resources.memory	string	否	Kubernetes 内存 quantity，例如 16Gi
resources.gpu	string	否	加速器数量；非空值会覆盖引擎中的加速器配置
kvCacheOffloading.cpu	string	条件必选	用于卸载 KV Cache 的正数内存 quantity，例如 8Gi
kvCacheOffloading.evictionPolicy	string	否	淘汰策略：lru 或 arc；省略时使用 lru
lora.adapters	array	否	LoRA 适配器列表；省略或传空数组表示不加载适配器
lora.adapters[].name	string	是	适配器名称；同一部署内必须唯一
lora.adapters[].modelId	string	否	适配器来源模型 ID
lora.adapters[].artifactId	string	是	LoRA 模型文件 ID；文件必须已就绪、带有 LoRA 标识并使用摘要固定的 OCI URI

当同时提供 engineId、modelId、artifactId 或 LoRA 模型文件时，这些资源必须全部为公共资源，或全部为当前项目的私有资源。kvCacheOffloading 不能与命令、参数、环境变量或引擎 YAML 中手工配置的 --kv-transfer-config 同时使用。

响应消息

参数	参数类型	描述
id	string	部署唯一标识
name	string	部署显示名称
description	string	部署说明
status	string	部署状态；创建成功时为 pending
projectId	string	所属项目 ID
projectName	string	项目名称；空值时省略
domainId	string	所属域 ID；空值时省略
domainName	string	所属域名称；空值时省略
ownerUserId	string	创建者用户 ID
ownerName	string	创建者名称；空值时省略
backend	object	后端工作负载引用，包含 catalog、type 和 id
spec	object	部署配置快照；字段与请求配置及服务端解析出的引擎、模型文件信息对应
stopped	boolean	是否已完全停止；创建成功时为 false
labels	object	部署标签；空值时省略
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339

创建响应不包含实时 ready 和 conditions。这些字段需要通过详情接口读取。

请求示例

POST https://{endpoint}/api/v1/deployments
x-keystone-token: <Keystone Token>
Content-Type: application/json

{
  "name": "qwen-chat",
  "description": "Qwen 对话模型",
  "engineId": "engine-vllm",
  "modelId": "model-qwen",
  "artifactId": "artifact-qwen",
  "modelName": "qwen2.5-7b-instruct",
  "replicas": 1
}

正常响应示例

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "deployment-7f3a",
  "name": "qwen-chat",
  "description": "Qwen 对话模型",
  "status": "pending",
  "projectId": "project-a",
  "ownerUserId": "user-a",
  "backend": {
    "catalog": "k8s",
    "type": "LLMInferenceService",
    "id": "project-a/qwen-chat"
  },
  "spec": {
    "architecture": "amd64",
    "k8sName": "qwen-chat",
    "engineId": "engine-vllm",
    "engineName": "vLLM",
    "engineConfigName": "vllm-config",
    "modelId": "model-qwen",
    "artifactId": "artifact-qwen",
    "artifactName": "Qwen2.5-7B-Instruct",
    "modelUri": "oci://registry.example.com/models/qwen@sha256:0123456789abcdef",
    "modelName": "qwen2.5-7b-instruct",
    "replicas": 1
  },
  "stopped": false,
  "labels": {
    "beacon.io/runtime": "vllm"
  },
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：201。

HTTP	error	说明
400	invalid_request	请求体格式错误、必填字段缺失、关联资源不存在或部署配置不符合要求；具体原因见 message
401	unauthorized	未认证，或缺少项目作用域令牌
403	forbidden	无模型部署写入权限，或 Kubernetes 拒绝操作
404	not_found	目标 Kubernetes 命名空间或对象不存在
409	conflict	同名工作负载或部署资源已存在
422	invalid_request	引擎后端引用无效，或 Kubernetes 拒绝工作负载配置
502	backend_unavailable	Kubernetes API 不可用
500	internal_error	创建部署失败

错误返回格式见调用方式。

查询部署支持的 API 协议

功能介绍

一次查询调用方可见的所有部署分别支持哪些推理 API 协议，可用于创建 AI 服务提供者时筛选部署和选择协议。当前协议值为 OpenAI 或 Cohere。

服务端根据部署工作负载实际暴露的接口确定协议。如果工作负载尚未就绪、已停止或无法访问，则返回兼容性默认值 OpenAI，并将 unreachable 标记为 true。因此该结果用于辅助配置，不代表部署当前已经可以处理推理请求。

访问要求：有效 Token；需要模型部署读取权限。

URI

GET /api/v1/deployments/api-schemas

请求消息

无请求体。

响应消息

参数	类型	描述
items	object	以部署 ID 为键的协议查询结果
items.{deploymentId}.schemas	array	部署支持的协议列表，取值为 OpenAI、Cohere
items.{deploymentId}.recommended	string	推荐使用的协议；支持 OpenAI 时优先推荐 OpenAI
items.{deploymentId}.unreachable	boolean	是否因工作负载不可访问而使用默认结果；值为 false 时省略

请求示例

GET https://{endpoint}/api/v1/deployments/api-schemas
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": {
    "deployment-7f3a": {
      "schemas": [
        "OpenAI"
      ],
      "recommended": "OpenAI"
    },
    "deployment-8b2c": {
      "schemas": [
        "OpenAI"
      ],
      "recommended": "OpenAI",
      "unreachable": true
    }
  }
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型部署读取权限
500	internal_error	查询部署列表失败

错误返回格式见调用方式。

获取模型部署详情

功能介绍

获取指定部署的配置及实时运行状态。服务端会读取 KServe 工作负载，更新 ready、conditions、status 和集群内访问地址；工作负载暂时无法读取时，仍可能返回目录中保存的部署信息。

访问要求：有效 Token；需要模型部署读取权限。普通调用方只能读取当前项目的部署，具有全局读取权限的管理员可以读取其他项目的部署。

URI

GET /api/v1/deployments/{id}

参数	类型	必选	描述
id	string	是	部署 ID

请求消息

无请求体。

响应消息

参数	参数类型	描述
id	string	部署唯一标识
name	string	部署显示名称
description	string	部署说明
status	string	部署状态：pending、ready、stopping 或 stopped
projectId	string	所属项目 ID
projectName	string	项目名称；空值时省略
domainId	string	所属域 ID；空值时省略
domainName	string	所属域名称；空值时省略
ownerUserId	string	创建者用户 ID
ownerName	string	创建者名称；空值时省略
backend	object	后端工作负载引用，包含 catalog、type 和 id
spec	object	部署配置快照，主要字段见下表
ready	string	KServe Ready 条件值：True、False 或 Unknown；无法读取时可能省略
stopped	boolean	工作负载是否已完全停止；stopping 阶段仍为 false
conditions	array	KServe 状态条件；无条件信息时省略
labels	object	部署标签；空值时省略
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339

参数	参数类型	描述
spec.architecture	string	工作负载架构，当前为 amd64 或 arm64
spec.k8sName	string	Kubernetes 工作负载名称
spec.engineId	string	推理引擎 ID
spec.engineName	string	推理引擎名称
spec.engineConfigName	string	引擎对应的 KServe 配置名称
spec.modelId	string	来源模型 ID；未关联时省略
spec.artifactId	string	模型文件 ID；未关联时省略
spec.artifactName	string	模型文件名称；未关联时省略
spec.modelUri	string	实际部署的模型 OCI URI
spec.modelName	string	推理服务使用的模型名称；空值时省略
spec.lora	object	已解析的 LoRA 适配器配置；未配置时省略
spec.lora.adapters[].name	string	LoRA 适配器名称
spec.lora.adapters[].modelId	string	适配器来源模型 ID；未关联时省略
spec.lora.adapters[].artifactId	string	LoRA 模型文件 ID
spec.lora.adapters[].uri	string	服务端从模型文件解析出的、使用摘要固定的 OCI URI
spec.replicas	integer	期望副本数
spec.image	string	部署级镜像覆盖；未配置时省略
spec.command	array	部署级启动命令覆盖；未配置时省略
spec.args	array	部署级启动参数覆盖；未配置时省略
spec.env	array	部署级环境变量；未配置时省略
spec.resources	object	部署级计算资源覆盖；未配置时省略
spec.kvCacheOffloading	object	KV Cache CPU 卸载配置；未配置时省略
spec.endpoint	string	集群内工作负载地址；尚未就绪或已停止时省略
conditions[].type	string	条件类型
conditions[].status	string	条件状态
conditions[].reason	string	条件原因；空值时省略
conditions[].message	string	条件说明；空值时省略
conditions[].lastTransitionTime	string(date-time)	最近转换时间；空值时省略

请求示例

GET https://{endpoint}/api/v1/deployments/deployment-7f3a
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "deployment-7f3a",
  "name": "qwen-chat",
  "description": "Qwen 对话模型",
  "status": "ready",
  "projectId": "project-a",
  "ownerUserId": "user-a",
  "backend": {
    "catalog": "k8s",
    "type": "LLMInferenceService",
    "id": "project-a/qwen-chat"
  },
  "spec": {
    "architecture": "amd64",
    "k8sName": "qwen-chat",
    "engineId": "engine-vllm",
    "engineName": "vLLM",
    "engineConfigName": "vllm-config",
    "modelId": "model-qwen",
    "artifactId": "artifact-qwen",
    "artifactName": "Qwen2.5-7B-Instruct",
    "modelUri": "oci://registry.example.com/models/qwen@sha256:0123456789abcdef",
    "modelName": "qwen2.5-7b-instruct",
    "replicas": 1,
    "endpoint": "http://qwen-chat-kserve-workload-svc.project-a.svc.cluster.local:8000"
  },
  "ready": "True",
  "stopped": false,
  "conditions": [
    {
      "type": "Ready",
      "status": "True",
      "lastTransitionTime": "2026-09-21T00:05:00Z"
    }
  ],
  "labels": {
    "beacon.io/runtime": "vllm"
  },
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:05:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型部署读取权限
404	not_found	部署不存在或无权访问该项目的部署
500	internal_error	读取部署失败

错误返回格式见调用方式。

更新模型部署配置

功能介绍

按字段更新部署。省略的字段保持不变；修改运行配置后，KServe 会异步更新工作负载，响应中的 status 变为 pending。仅修改 name 或 description 时不会重命名或重启已有 Kubernetes 工作负载。

此接口不能替换 modelId、artifactId、modelUri、resources 或 labels。如需更换模型文件，应创建新的部署。

访问要求：有效 Token；需要当前项目的模型部署写入权限。修改运行配置且平台已配置 Kubernetes 时，还需要项目作用域令牌。

URI

PATCH /api/v1/deployments/{id}

参数	类型	必选	描述
id	string	是	部署 ID

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
name	string	否	新的显示名称；去除首尾空白后不能为空，不会修改 Kubernetes 工作负载名称
description	string	否	新的部署说明
engineId	string	否	新的推理引擎 ID；必须与已部署的模型文件具有相同可见性
modelName	string	否	新的服务模型名称；空字符串表示清空
replicas	integer	否	新的期望副本数，必须大于等于 1
image	string	否	新的容器镜像覆盖；空字符串表示恢复使用引擎默认值
command	array	否	新的启动命令覆盖；空数组表示清除覆盖
args	array	否	新的启动参数覆盖；空数组表示清除覆盖
env	array	否	新的环境变量数组；空数组表示清除部署级环境变量
kvCacheOffloading	object / null	否	新的 KV Cache CPU 卸载配置；null 表示关闭，省略表示不修改
lora	object / null	否	新的 LoRA 配置；null 或空 adapters 数组表示清除，省略表示不修改

env、kvCacheOffloading 和 lora 的子字段及约束与创建接口相同。切换到非 vLLM 引擎前，必须先移除已配置的 LoRA 适配器。

响应消息

返回更新后的部署对象，字段与“获取模型部署详情”相同，但该响应不读取实时工作负载，因此通常不包含 ready 和 conditions。运行配置发生变化时，status 为 pending。

请求示例

PATCH https://{endpoint}/api/v1/deployments/deployment-7f3a
x-keystone-token: <Keystone Token>
Content-Type: application/json

{
  "replicas": 2,
  "modelName": "qwen-chat-v2"
}

正常响应示例

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "deployment-7f3a",
  "name": "qwen-chat",
  "description": "Qwen 对话模型",
  "status": "pending",
  "projectId": "project-a",
  "ownerUserId": "user-a",
  "backend": {
    "catalog": "k8s",
    "type": "LLMInferenceService",
    "id": "project-a/qwen-chat"
  },
  "spec": {
    "architecture": "amd64",
    "k8sName": "qwen-chat",
    "engineId": "engine-vllm",
    "engineName": "vLLM",
    "engineConfigName": "vllm-config",
    "modelId": "model-qwen",
    "artifactId": "artifact-qwen",
    "artifactName": "Qwen2.5-7B-Instruct",
    "modelUri": "oci://registry.example.com/models/qwen@sha256:0123456789abcdef",
    "modelName": "qwen-chat-v2",
    "replicas": 2
  },
  "stopped": false,
  "labels": {
    "beacon.io/runtime": "vllm"
  },
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T01:00:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
400	invalid_request	请求体格式错误、字段取值无效或关联资源不符合要求；具体原因见 message
401	unauthorized	未认证，或修改工作负载时缺少项目作用域令牌
403	forbidden	无模型部署写入权限，或 Kubernetes 拒绝操作
404	not_found	部署、引擎或目标 Kubernetes 对象不存在
409	conflict	更新与当前资源状态冲突
422	invalid_request	后端引用无效，或 Kubernetes 拒绝工作负载配置
502	backend_unavailable	Kubernetes API 不可用
500	internal_error	更新部署失败

错误返回格式见调用方式。

停止部署

功能介绍

请求 KServe 停止指定部署。服务端保留部署配置和期望副本数，以便后续按原配置启动。

停止是异步过程。请求后如果 Pod 尚未全部退出，响应中的 status 为 stopping 且 stopped 为 false；Pod 全部退出后，详情接口返回 status: stopped 和 stopped: true。

访问要求：有效 Token 和项目作用域令牌；需要当前项目的模型部署写入权限。

URI

POST /api/v1/deployments/{id}/stop

参数	类型	必选	描述
id	string	是	部署 ID

请求消息

无请求体。

响应消息

返回已提交停止请求的部署对象，字段与“获取模型部署详情”相同，但不包含实时 ready 和 conditions。

请求示例

POST https://{endpoint}/api/v1/deployments/deployment-7f3a/stop
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "deployment-7f3a",
  "name": "qwen-chat",
  "description": "Qwen 对话模型",
  "status": "stopping",
  "projectId": "project-a",
  "ownerUserId": "user-a",
  "backend": {
    "catalog": "k8s",
    "type": "LLMInferenceService",
    "id": "project-a/qwen-chat"
  },
  "spec": {
    "architecture": "amd64",
    "k8sName": "qwen-chat",
    "engineId": "engine-vllm",
    "engineName": "vLLM",
    "modelUri": "oci://registry.example.com/models/qwen@sha256:0123456789abcdef",
    "replicas": 1,
    "endpoint": "http://qwen-chat-kserve-workload-svc.project-a.svc.cluster.local:8000"
  },
  "stopped": false,
  "labels": {
    "beacon.io/runtime": "vllm"
  },
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T02:00:00Z"
}

如果停止请求提交时工作负载 Pod 已经全部退出，接口可直接返回 status: stopped 和 stopped: true。

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	未认证或缺少项目作用域令牌
403	forbidden	无模型部署写入权限，或 Kubernetes 拒绝操作
404	not_found	部署或目标 Kubernetes 对象不存在
409	conflict	Kubernetes 更新发生冲突
422	invalid_backend / invalid_request	部署没有有效工作负载，或 Kubernetes 拒绝请求
502	backend_unavailable	Kubernetes API 不可用
503	unavailable	Kubernetes 未配置
500	internal_error	停止部署失败

错误返回格式见调用方式。

启动部署

功能介绍

移除部署的停止标记，请求 KServe 按原有配置重新创建工作负载。接口返回时 status 为 pending、stopped 为 false，实际就绪仍需通过详情接口确认。

访问要求：有效 Token 和项目作用域令牌；需要当前项目的模型部署写入权限。

URI

POST /api/v1/deployments/{id}/start

参数	类型	必选	描述
id	string	是	部署 ID

请求消息

无请求体。

响应消息

返回已提交启动请求的部署对象，字段与“获取模型部署详情”相同，但不包含实时 ready 和 conditions。

请求示例

POST https://{endpoint}/api/v1/deployments/deployment-7f3a/start
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "deployment-7f3a",
  "name": "qwen-chat",
  "description": "Qwen 对话模型",
  "status": "pending",
  "projectId": "project-a",
  "ownerUserId": "user-a",
  "backend": {
    "catalog": "k8s",
    "type": "LLMInferenceService",
    "id": "project-a/qwen-chat"
  },
  "spec": {
    "architecture": "amd64",
    "k8sName": "qwen-chat",
    "engineId": "engine-vllm",
    "engineName": "vLLM",
    "modelUri": "oci://registry.example.com/models/qwen@sha256:0123456789abcdef",
    "replicas": 1
  },
  "stopped": false,
  "labels": {
    "beacon.io/runtime": "vllm"
  },
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T03:00:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	未认证或缺少项目作用域令牌
403	forbidden	无模型部署写入权限，或 Kubernetes 拒绝操作
404	not_found	部署或目标 Kubernetes 对象不存在
409	conflict	Kubernetes 更新发生冲突
422	invalid_backend / invalid_request	部署没有有效工作负载，或 Kubernetes 拒绝请求
502	backend_unavailable	Kubernetes API 不可用
503	unavailable	Kubernetes 未配置
500	internal_error	启动部署失败

错误返回格式见调用方式。

删除模型部署

功能介绍

删除当前项目中的模型部署。配置 Kubernetes 时，服务端先删除对应的 KServe 工作负载，再将部署记录标记为已删除。该操作不会删除关联的推理引擎、模型或模型文件。

访问要求：有效 Token；需要当前项目的模型部署写入权限。配置 Kubernetes 时还需要项目作用域令牌。

URI

DELETE /api/v1/deployments/{id}

参数	类型	必选	描述
id	string	是	部署 ID

请求消息

无请求体。

响应消息

成功返回 204 No Content，无响应体。

请求示例

DELETE https://{endpoint}/api/v1/deployments/deployment-7f3a
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 204 No Content

状态码与错误码

成功状态码：204。

HTTP	error	说明
401	unauthorized	未认证，或配置 Kubernetes 时缺少项目作用域令牌
403	forbidden	无模型部署写入权限，或 Kubernetes 拒绝操作
404	not_found	部署或目标 Kubernetes 对象不存在
409	conflict	Kubernetes 删除操作发生冲突
422	invalid_request	Kubernetes 拒绝删除请求
502	backend_unavailable	Kubernetes API 不可用
500	internal_error	删除部署失败

错误返回格式见调用方式。

查询部署 Pod

功能介绍

查询指定部署当前的工作负载 Pod 及其容器状态，可用于选择日志或终端会话的目标 Pod 和容器。已成功结束的历史 Pod 不在结果中。

访问要求：有效 Token；需要模型部署读取权限。

URI

GET /api/v1/deployments/{id}/pods

参数	类型	必选	描述
id	string	是	部署 ID

请求消息

无请求体。

响应消息

参数	参数类型	描述
items	array	当前工作负载 Pod 列表，按 Pod 名称排序
items[].name	string	Pod 名称
items[].phase	string	Kubernetes Pod phase，例如 Pending、Running 或 Failed
items[].status	string	便于展示的详细状态，例如 Running、PodInitializing 或 CrashLoopBackOff
items[].nodeName	string	所在节点名称；未调度时省略
items[].startTime	string(date-time)	Pod 启动时间；尚未启动时省略
items[].containers	array	容器列表
items[].containers[].name	string	容器名称
items[].containers[].image	string	容器镜像；空值时省略
items[].containers[].imageId	string	已运行镜像 ID；空值时省略
items[].containers[].ready	boolean	容器是否就绪
items[].containers[].restartCount	integer	容器重启次数
items[].containers[].state	string	running、waiting 或 terminated；状态未知时省略

请求示例

GET https://{endpoint}/api/v1/deployments/deployment-7f3a/pods
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": [
    {
      "name": "qwen-chat-kserve-6d7c9f8b6d-abcde",
      "phase": "Running",
      "status": "Running",
      "nodeName": "worker-01",
      "startTime": "2026-09-21T00:04:00Z",
      "containers": [
        {
          "name": "main",
          "image": "registry.example.com/vllm:v1",
          "ready": true,
          "restartCount": 0,
          "state": "running"
        }
      ]
    }
  ]
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型部署读取权限，或 Kubernetes 拒绝操作
404	not_found	部署或目标 Kubernetes 对象不存在
422	invalid_backend / invalid_request	部署没有有效工作负载，或 Kubernetes 拒绝请求
502	backend_unavailable	Kubernetes API 不可用
503	unavailable	Kubernetes 未配置
500	internal_error	查询 Pod 失败

错误返回格式见调用方式。

读取或持续跟踪容器日志

功能介绍

读取部署容器最近的日志，或保持 HTTP 连接持续接收新增日志。单 Pod 部署可以省略 pod；存在多个 Pod 时必须先通过 Pod 查询接口选择目标。建议始终显式传入 container。

访问要求：有效 Token；需要模型部署读取权限。

URI

GET /api/v1/deployments/{id}/logs

参数	类型	必选	描述
id	string	是	部署 ID

查询参数

参数	类型	必选	描述
pod	string	条件必选	Pod 名称；部署当前存在多个 Pod 时必选，且必须属于该部署
container	string	否	容器名称；建议使用 Pod 查询接口返回的容器名称
follow	boolean / integer	否	true 或 1 表示持续跟踪；其他值表示仅读取当前日志
tailLines	integer	否	返回末尾日志行数；省略、无法解析或小于等于 0 时为 500

请求消息

无请求体。

响应消息

成功响应的 Content-Type 为 text/plain; charset=utf-8。未开启 follow 时连接在当前日志返回完毕后结束；开启后服务端逐块写入新日志，直到客户端断开或日志流结束。

请求示例

GET https://{endpoint}/api/v1/deployments/deployment-7f3a/logs?pod=qwen-chat-kserve-6d7c9f8b6d-abcde&container=main&tailLines=200
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
X-Accel-Buffering: no

INFO model loaded
INFO server listening on :8000

状态码与错误码

成功状态码：200。

HTTP	error	说明
400	pod_required	部署存在多个 Pod，但未指定 pod
400	invalid_pod	指定的 Pod 不属于该部署
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型部署读取权限，或 Kubernetes 拒绝操作
404	no_pods	部署当前没有工作负载 Pod
404	not_found	部署、Pod、容器或目标 Kubernetes 对象不存在
422	invalid_backend / invalid_request	部署没有有效工作负载，或 Kubernetes 拒绝请求
502	backend_unavailable	Kubernetes API 不可用
503	unavailable	Kubernetes 未配置
500	internal_error	读取日志失败

错误返回格式见调用方式。

查询部署监控指标

功能介绍

查询指定部署在最近时间窗口内的 CPU、内存和网络时间序列。传入 runtime=vllm 时还会查询 vLLM 的延迟与吞吐量指标；如果部署尚未报告工作负载 Service，则仍返回通用资源指标，但省略 vllm。

访问要求：有效 Token；需要模型部署读取权限。

URI

GET /api/v1/deployments/{id}/metrics

参数	类型	必选	描述
id	string	是	部署 ID

查询参数

参数	类型	必选	描述
range	string	否	时间窗口：5m、15m、1h 或 3h；省略或传入其他值时为 30 分钟
runtime	string	否	传 vllm 时附加查询 vLLM 指标；不区分大小写，其他值仅返回通用资源指标

请求消息

无请求体。

响应消息

每个时间序列由 [Unix 时间戳（秒）, 数值] 组成。

参数	参数类型	描述
cpu	array<[number, number]>	CPU 使用量，单位为核
memory	array<[number, number]>	内存工作集，单位为字节
netRx	array<[number, number]>	网络接收速率，单位为 bytes/s
netTx	array<[number, number]>	网络发送速率，单位为 bytes/s
stepSeconds	integer	时间序列采样步长，单位为秒；服务端按窗口生成约 60 个点，最小 15 秒
vllm	object	vLLM 指标；未请求、无工作负载 Service 或无可用数据时可能省略
vllm.ttftP50 / ttftP95 / ttftP99 / ttftAvg	array<[number, number]>	首 Token 延迟，单位为秒
vllm.tpotP50 / tpotP95 / tpotP99 / tpotAvg	array<[number, number]>	每输出 Token 延迟，单位为秒
vllm.promptThroughput	array<[number, number]>	输入 Token 吞吐量，单位为 tokens/s
vllm.generationThroughput	array<[number, number]>	输出 Token 吞吐量，单位为 tokens/s
vllm.totalThroughput	array<[number, number]>	总 Token 吞吐量，单位为 tokens/s

请求示例

GET https://{endpoint}/api/v1/deployments/deployment-7f3a/metrics?range=1h&runtime=vllm
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200 OK
Content-Type: application/json

{
  "cpu": [
    [1789948800, 0.5]
  ],
  "memory": [
    [1789948800, 8589934592]
  ],
  "netRx": [
    [1789948800, 1024]
  ],
  "netTx": [
    [1789948800, 2048]
  ],
  "stepSeconds": 60,
  "vllm": {
    "ttftP50": [
      [1789948800, 0.12]
    ],
    "ttftP95": [
      [1789948800, 0.21]
    ],
    "ttftP99": [
      [1789948800, 0.28]
    ],
    "ttftAvg": [
      [1789948800, 0.14]
    ],
    "tpotP50": [
      [1789948800, 0.018]
    ],
    "tpotP95": [
      [1789948800, 0.026]
    ],
    "tpotP99": [
      [1789948800, 0.032]
    ],
    "tpotAvg": [
      [1789948800, 0.02]
    ],
    "promptThroughput": [
      [1789948800, 180.5]
    ],
    "generationThroughput": [
      [1789948800, 72.3]
    ],
    "totalThroughput": [
      [1789948800, 252.8]
    ]
  }
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型部署读取权限
404	not_found	部署不存在或无权访问该项目的部署
422	invalid_backend	部署没有有效工作负载
502	prometheus_error	Prometheus/Thanos 查询失败，具体原因见 message
503	unavailable	Kubernetes 或监控服务未配置
500	internal_error	查询部署信息失败

错误返回格式见调用方式。

建立 WebSocket 终端会话

功能介绍

将 HTTP 连接升级为 WebSocket，并在指定部署容器中建立交互式终端。单 Pod 部署可以省略 pod；存在多个 Pod 时必须指定目标。该接口可以在容器中执行命令，权限要求高于普通读取接口。

访问要求：有效 Token；需要模型部署写入权限。

URI

GET /api/v1/deployments/{id}/exec

参数	类型	必选	描述
id	string	是	部署 ID

查询参数

参数	类型	必选	描述
pod	string	条件必选	Pod 名称；部署当前存在多个 Pod 时必选，且必须属于该部署
container	string	否	容器名称；建议使用 Pod 查询接口返回的容器名称

请求消息

客户端通过文本帧发送 JSON 消息：

字段	类型	描述
type	string	消息类型：input 或 resize
data	string	type=input 时发送到终端的输入内容
cols	integer	type=resize 时的终端列数
rows	integer	type=resize 时的终端行数

输入示例：{"type":"input","data":"ls\n"}。调整终端大小示例：{"type":"resize","cols":120,"rows":30}。

响应消息

握手成功返回 101 Switching Protocols。服务端将终端标准输出作为 WebSocket 文本帧发送；会话结束前会发送一条包含结束原因的文本帧，随后发送正常关闭帧。

请求示例

GET wss://{endpoint}/api/v1/deployments/deployment-7f3a/exec?pod=qwen-chat-kserve-6d7c9f8b6d-abcde&container=main
x-keystone-token: <Keystone Token>
Upgrade: websocket
Connection: Upgrade

正常响应示例

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

状态码与错误码

成功状态码：101。

以下错误发生在 WebSocket 升级前；升级后的执行错误通过终端文本帧和关闭帧返回。

HTTP	error	说明
400	pod_required	部署存在多个 Pod，但未指定 pod
400	invalid_pod	指定的 Pod 不属于该部署
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型部署写入权限，或 Kubernetes 拒绝操作
404	no_pods	部署当前没有工作负载 Pod
404	not_found	部署或目标 Kubernetes 对象不存在
422	invalid_backend / invalid_request	部署没有有效工作负载，或 Kubernetes 拒绝请求
502	backend_unavailable	Kubernetes API 不可用
503	unavailable	Kubernetes 未配置
500	internal_error	建立终端会话失败

错误返回格式见调用方式。