推理引擎

资源未配置 Kubernetes 时可仅维护目录；配置 Kubernetes 时会创建或更新 KServe 引擎对象。201 并不保证运行环境已经就绪。

已被部署引用的引擎不允许修改受保护配置或删除；使用 inUse 判断引用状态，并处理 409 engine_in_use。

方法	路径（产品接口统一前缀 /api/v1）	功能
GET	/engines	查询推理引擎
POST	/engines	创建推理引擎
GET	/engines/{id}	获取推理引擎详情
PATCH	/engines/{id}	更新推理引擎
DELETE	/engines/{id}	删除推理引擎

查询推理引擎

功能介绍

查询推理引擎。

访问要求：有效 Token；需要对应资源读权限，并受项目、所有者、公共或共享资源规则限制。

URI

GET /api/v1/engines

查询参数

参数	类型	必选	描述
page	integer	否	页码，从 1 开始
page_size	integer	否	每页数量；建议显式传入，例如 20；省略时部分列表返回全部

请求消息

无请求体。

响应消息

参数	参数类型	描述
items	array<engine.response>	结果列表
total	integer	匹配总数
page	integer	页码，从 1 开始
page_size	integer	每页数量

请求示例

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

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "items": [
    {
      "id": "id-example",
      "name": "示例资源",
      "description": "",
      "projectId": "projectId-example",
      "ownerUserId": "ownerUserId-example",
      "backend": {
        "catalog": "",
        "type": "",
        "id": "id-example"
      },
      "spec": {},
      "inUse": true,
      "createdAt": "2026-09-21T00:00:00Z",
      "updatedAt": "2026-09-21T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 1
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
500	internal_error	failed to list engines
401	unauthorized	authentication required

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

创建推理引擎

功能介绍

创建推理引擎。

访问要求：有效 Token；需要对应资源写权限，并受项目、所有者、公共或共享资源规则限制。

URI

POST /api/v1/engines

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
name	string	是	显示名称
description	string	否	描述
image	string	是	容器镜像完整地址，应包含仓库路径及标签。
engineImageId	string	否	镜像资源 ID；使用完整 image 地址创建时不需要提供。
architecture	string	是	运行架构，amd64 或 arm64；创建流程默认选择 amd64。
runtime	string	是	推理运行时，须选择有效类型。
command	array	否	容器启动命令数组
args	array	否	容器启动参数数组
env	array<engine.EnvVar>	否	环境变量数组
resources	engine.Resources / null	是	资源配置，须包含 cpu 和 memory；选择加速器时还需提供对应 GPU 配置。
nodeSelector	map<string, string>	否	节点选择标签
yaml	string	否	自定义 YAML 配置
labels	map<string, string>	是	须包含 visibility，取值 private 或 public。

参数	参数类型	是否必选	描述
resources.cpu	string	是	CPU 数量，不能为空。
resources.memory	string	是	内存容量，包含单位，例如 16Gi。
resources.gpu	string	条件必选	选择 GPU 产品时必选，为大于等于 1 的整数数量。
resources.gpuProduct	string	条件必选	使用 GPU 时指定 GPU 产品。
resources.gpuResource	string	条件必选	所选 GPU 产品提供资源名称时，需携带该资源名称。

上述资源子字段以创建或完整替换资源配置为前提。镜像仓库与镜像标签在提交时组合为 image，不是独立的请求参数。

响应消息

参数	参数类型	描述
id	string	资源唯一标识
name	string	显示名称
description	string	描述
projectId	string	所属项目 ID
projectName	string	项目名称；空值时可能省略
domainId	string	所属部门 ID；空值时可能省略
domainName	string	部门名称；空值时可能省略
ownerUserId	string	创建者用户 ID
ownerName	string	创建者名称；空值时可能省略
backend	engine.backendRef	后端资源标识
spec	engine.Spec	资源配置快照
labels	map<string, string>	标签键值对；空值时可能省略
inUse	boolean	是否正被其他资源引用
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339

请求示例

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

{
  "name": "vllm-engine",
  "image": "registry.example.com/ai/vllm:approved",
  "runtime": "vllm",
  "resources": {
    "cpu": "4",
    "memory": "16Gi"
  },
  "architecture": "amd64",
  "labels": {
    "visibility": "private"
  }
}

正常响应示例

HTTP/1.1 201
Content-Type: application/json

{
  "id": "id-example",
  "name": "示例资源",
  "description": "",
  "projectId": "projectId-example",
  "ownerUserId": "ownerUserId-example",
  "backend": {
    "catalog": "",
    "type": "",
    "id": "id-example"
  },
  "spec": {},
  "inUse": true,
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：201。

HTTP	error	说明
400	invalid_request	malformed JSON body
403	forbidden	public engine is read-only for current tenant
500	internal_error	failed to encode engine spec
401	unauthorized	missing project-scoped token; re-authenticate with a project scope
404	not_found	详细原因由 message 返回。
409	conflict	an engine with that name already exists in the namespace
422	invalid_request	详细原因由 message 返回。
502	backend_unavailable	kubernetes API unavailable

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

获取推理引擎详情

功能介绍

获取推理引擎详情。

访问要求：有效 Token；需要对应资源读权限，并受项目、所有者、公共或共享资源规则限制。

URI

GET /api/v1/engines/{id}

参数	类型	必选	描述
id	string	是	目标资源 ID

请求消息

无请求体。

响应消息

参数	参数类型	描述
id	string	资源唯一标识
name	string	显示名称
description	string	描述
projectId	string	所属项目 ID
projectName	string	项目名称；空值时可能省略
domainId	string	所属部门 ID；空值时可能省略
domainName	string	部门名称；空值时可能省略
ownerUserId	string	创建者用户 ID
ownerName	string	创建者名称；空值时可能省略
backend	engine.backendRef	后端资源标识
spec	engine.Spec	资源配置快照
labels	map<string, string>	标签键值对；空值时可能省略
inUse	boolean	是否正被其他资源引用
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339

请求示例

GET https://{endpoint}/api/v1/engines/resource-id
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "id": "id-example",
  "name": "示例资源",
  "description": "",
  "projectId": "projectId-example",
  "ownerUserId": "ownerUserId-example",
  "backend": {
    "catalog": "",
    "type": "",
    "id": "id-example"
  },
  "spec": {},
  "inUse": true,
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	authentication required
404	not_found	engine not found
409	conflict	engine already exists
403	forbidden	public engine is read-only for current tenant
400	invalid_request	engine visibility cannot be changed; create a new engine instead
500	internal_error	internal server error

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

更新推理引擎

功能介绍

更新推理引擎。

访问要求：有效 Token；需要对应资源写权限，并受项目、所有者、公共或共享资源规则限制。

URI

PATCH /api/v1/engines/{id}

参数	类型	必选	描述
id	string	是	目标资源 ID

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
name	string / null	否	显示名称
description	string / null	否	描述
status	string / null	否	资源状态；具体取值见业务规则
image	string / null	否	修改时须提供包含仓库路径和标签的完整镜像地址。
architecture	string / null	否	加速器架构
runtime	string / null	否	修改运行时时提供，不能为空。
command	array / null	否	容器启动命令数组
args	array / null	否	容器启动参数数组
env	array<engine.EnvVar> / null	否	环境变量数组
resources	engine.Resources / null	否	省略时不修改；替换资源配置时须提供 cpu、memory，GPU 子字段要求与创建一致。
yaml	string / null	否	自定义 YAML 配置
labels	map<string, string> / null	否	省略时不修改；visibility 不允许变更，若提供须与原值一致。

响应消息

参数	参数类型	描述
id	string	资源唯一标识
name	string	显示名称
description	string	描述
projectId	string	所属项目 ID
projectName	string	项目名称；空值时可能省略
domainId	string	所属部门 ID；空值时可能省略
domainName	string	部门名称；空值时可能省略
ownerUserId	string	创建者用户 ID
ownerName	string	创建者名称；空值时可能省略
backend	engine.backendRef	后端资源标识
spec	engine.Spec	资源配置快照
labels	map<string, string>	标签键值对；空值时可能省略
inUse	boolean	是否正被其他资源引用
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339

请求示例

PATCH https://{endpoint}/api/v1/engines/resource-id
x-keystone-token: <Keystone Token>
Content-Type: application/json

{
  "name": "更新后的名称"
}

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "id": "id-example",
  "name": "示例资源",
  "description": "",
  "projectId": "projectId-example",
  "ownerUserId": "ownerUserId-example",
  "backend": {
    "catalog": "",
    "type": "",
    "id": "id-example"
  },
  "spec": {},
  "inUse": true,
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
400	invalid_request	malformed JSON body
500	internal_error	failed to resolve engine references
409	engine_in_use	engine is referenced by a deployment and cannot be modified; delete the referencing deployment(s) first
401	unauthorized	missing project-scoped token; re-authenticate with a project scope
422	invalid_request	engine has no valid backend reference
403	forbidden	write permission required
404	not_found	engine not found
409	conflict	engine already exists
502	backend_unavailable	kubernetes API unavailable

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

删除推理引擎

功能介绍

删除推理引擎。

访问要求：有效 Token；需要对应资源写权限，并受项目、所有者、公共或共享资源规则限制。

URI

DELETE /api/v1/engines/{id}

参数	类型	必选	描述
id	string	是	目标资源 ID

请求消息

无请求体。

响应消息

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

请求示例

DELETE https://{endpoint}/api/v1/engines/resource-id
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 204 No Content

状态码与错误码

成功状态码：204。

HTTP	error	说明
500	internal_error	failed to resolve engine references
409	engine_in_use	engine is referenced by a deployment and cannot be deleted; delete the referencing deployment(s) first
401	unauthorized	missing project-scoped token; re-authenticate with a project scope
403	forbidden	write permission required
404	not_found	engine not found
409	conflict	engine already exists
400	invalid_request	engine visibility cannot be changed; create a new engine instead
422	invalid_request	详细原因由 message 返回。
502	backend_unavailable	kubernetes API unavailable

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。