模型广场

模型、默认引擎和默认制品的可见性必须一致。公共模型的修改需要相应公共资源写权限。

创建时 modelArtifactId 与 importArtifact 互斥；importArtifact 必须给出 repositoryId、sourceType、sourceUri。

图标使用 iconData（Data URL）写入，通过 /models/{id}/icon 读取；图标响应支持 ETag 与 If-None-Match，命中时返回 304。

方法	路径（产品接口统一前缀 /api/v1）	功能
GET	/models	分页查询模型
POST	/models	创建模型
GET	/models/{id}	获取模型详情
GET	/models/{id}/icon	获取模型图标
PATCH	/models/{id}	更新模型
DELETE	/models/{id}	删除模型

分页查询模型

功能介绍

分页查询模型。

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

URI

GET /api/v1/models

查询参数

参数	类型	必选	描述
page	integer	否	页码，从 1 开始
page_size	integer	否	每页数量；默认 20，最多 200
q	string	否	关键词搜索
provider	string	否	模型提供者
modelType	string	否	模型类型
task	string	否	模型任务类型或导入任务对象
visibility	string	否	可见性筛选
status	string	否	资源状态；具体取值见业务规则
label	string	否	标签筛选
label_key	string	否	标签键筛选
label_value	string	否	标签值筛选
sort	string	否	排序表达式

请求消息

无请求体。

响应消息

参数	参数类型	描述
items	array<model.Response>	结果列表
total	integer	匹配总数
page	integer	页码，从 1 开始
page_size	integer	每页数量
facets	model.FacetOptions	模型筛选项集合

请求示例

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

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "items": [
    {
      "id": "id-example",
      "name": "示例资源",
      "description": "",
      "status": "ready",
      "projectId": "projectId-example",
      "ownerUserId": "ownerUserId-example",
      "properties": {},
      "summary": {},
      "createdAt": "2026-09-21T00:00:00Z",
      "updatedAt": "2026-09-21T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 1,
  "facets": {
    "providers": [
      ""
    ],
    "modelTypes": [
      ""
    ],
    "tasks": [
      ""
    ]
  }
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
500	internal_error	failed to list models

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

创建模型

功能介绍

创建模型。

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

URI

POST /api/v1/models

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
name	string	是	显示名称
description	string	否	描述
provider	string	否	模型提供者，可留空，也可由模型元数据填充。
sourceName	string	否	模型来源名称，可留空，也可由模型元数据填充。
modelType	string	否	模型类型，可留空，也可由模型元数据填充。
task	string	否	模型任务类型，可留空，也可由模型元数据填充。
engineId	string	否	默认推理引擎 ID，允许暂不绑定。
modelArtifactId	string	否	已有模型制品 ID，允许暂不绑定；同步导入新制品时省略。
labels	map<string, string>	是	标签键值对；创建时需包含 visibility，取值 private 或 public。其他标签可选。
iconData	string	否	图标 Data URL；支持格式及大小受校验约束；空值时可能省略
importArtifact	model.importArtifactRequest / null	条件必选	同步导入新制品时必选；不导入时省略。对象内必选字段见下表。

同步导入时的嵌套参数：

参数	参数类型	是否必选	描述
importArtifact.repositoryId	string	是	目标模型仓库 ID。
importArtifact.sourceType	string	是	modelscope 或 huggingface。
importArtifact.sourceUri	string	是	解析后的远程模型 URI，不能为空。
importArtifact.name	string	否	制品名称；省略时使用模型名称。
importArtifact.labels	object	是	包含 visibility，取值与目标仓库的可见性一致。
importArtifact.proxyUrl	string	否	启用代理时可提供的代理地址。
importArtifact.proxyEnv	object	否	启用代理时可提供的代理环境变量。
importArtifact.speedLimit	integer	否	下载限速，字节/秒；提供时必须大于 0。

嵌套表的必选性以提供 importArtifact 为前提。选择已有制品时，仓库选择用于筛选制品，不作为顶层 repositoryId 发送；不要将表单选择项当作 API 参数。

响应消息

参数	参数类型	描述
id	string	资源唯一标识
name	string	显示名称
description	string	描述
status	string	资源状态；具体取值见业务规则
projectId	string	所属项目 ID
ownerUserId	string	创建者用户 ID
ownerName	string	创建者名称；空值时可能省略
labels	map<string, string>	标签键值对；空值时可能省略
properties	model.Properties	模型属性
summary	model.Summary	摘要信息
defaultEngine	model.LinkedResource / null	默认推理引擎；空值时可能省略
defaultArtifact	model.LinkedResource / null	默认模型制品；空值时可能省略
readme	string	模型说明 Markdown；空值时可能省略
iconUrl	string	图标读取 URL；空值时可能省略
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339

请求示例

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

{
  "name": "示例模型",
  "provider": "huggingface",
  "modelType": "llm",
  "task": "text-generation",
  "labels": {
    "visibility": "private"
  }
}

正常响应示例

HTTP/1.1 201
Content-Type: application/json

{
  "id": "id-example",
  "name": "示例资源",
  "description": "",
  "status": "ready",
  "projectId": "projectId-example",
  "ownerUserId": "ownerUserId-example",
  "properties": {},
  "summary": {},
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：201。

HTTP	error	说明
403	forbidden	write permission required
400	invalid_request	malformed JSON body
409	conflict	model already exists
404	not_found	default engine or model artifact not found
409	base_image_missing	base image is missing and automatic initialization failed; configure Harbor base image before importing model files
502	backend_unavailable	base image check failed; verify Harbor base image configuration
409	capacity_exceeded	model repository capacity would be exceeded
500	internal_error	failed to create model

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

获取模型详情

功能介绍

获取模型详情。

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

URI

GET /api/v1/models/{id}

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

请求消息

无请求体。

响应消息

参数	参数类型	描述
id	string	资源唯一标识
name	string	显示名称
description	string	描述
status	string	资源状态；具体取值见业务规则
projectId	string	所属项目 ID
ownerUserId	string	创建者用户 ID
ownerName	string	创建者名称；空值时可能省略
labels	map<string, string>	标签键值对；空值时可能省略
properties	model.Properties	模型属性
summary	model.Summary	摘要信息
defaultEngine	model.LinkedResource / null	默认推理引擎；空值时可能省略
defaultArtifact	model.LinkedResource / null	默认模型制品；空值时可能省略
readme	string	模型说明 Markdown；空值时可能省略
iconUrl	string	图标读取 URL；空值时可能省略
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339

请求示例

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

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "id": "id-example",
  "name": "示例资源",
  "description": "",
  "status": "ready",
  "projectId": "projectId-example",
  "ownerUserId": "ownerUserId-example",
  "properties": {},
  "summary": {},
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
500	internal_error	failed to resolve default engine
404	not_found	model not found

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

获取模型图标

功能介绍

获取模型图标。

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

URI

GET /api/v1/models/{id}/icon

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

接口请求头

请求头	说明
If-None-Match	可选，图标 ETag 缓存校验。

请求消息

无请求体。

响应消息

200 返回图标二进制，Content-Type 为图标 MIME 类型，含 ETag / Cache-Control；304 不返回响应体。

请求示例

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

正常响应示例

HTTP/1.1 200 OK
Content-Type: image/png
ETag: "<sha256>"

<图标字节>

状态码与错误码

成功状态码：200, 304。

HTTP	error	说明
404	not_found	model not found
500	internal_error	internal server error

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

更新模型

功能介绍

更新模型。

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

URI

PATCH /api/v1/models/{id}

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

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
name	string / null	否	仅修改名称时提供，不能为空。
description	string / null	否	描述
provider	string / null	否	模型提供者
sourceName	string / null	否	模型来源名称
modelType	string / null	否	模型类型
task	string / null	否	模型任务类型或导入任务对象
engineId	string / null	否	推理引擎 ID
modelArtifactId	string / null	否	模型制品 ID
labels	map<string, string> / null	否	省略时不修改；修改可见性时须在 labels.visibility 中提供 private 或 public。
iconData	string / null	否	图标 Data URL；支持格式及大小受校验约束

更新接口允许只提交待修改字段。完整编辑表单要求名称和可见性有值，不表示每次 PATCH 必须重复发送所有字段。

响应消息

参数	参数类型	描述
id	string	资源唯一标识
name	string	显示名称
description	string	描述
status	string	资源状态；具体取值见业务规则
projectId	string	所属项目 ID
ownerUserId	string	创建者用户 ID
ownerName	string	创建者名称；空值时可能省略
labels	map<string, string>	标签键值对；空值时可能省略
properties	model.Properties	模型属性
summary	model.Summary	摘要信息
defaultEngine	model.LinkedResource / null	默认推理引擎；空值时可能省略
defaultArtifact	model.LinkedResource / null	默认模型制品；空值时可能省略
readme	string	模型说明 Markdown；空值时可能省略
iconUrl	string	图标读取 URL；空值时可能省略
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339

请求示例

PATCH https://{endpoint}/api/v1/models/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": "",
  "status": "ready",
  "projectId": "projectId-example",
  "ownerUserId": "ownerUserId-example",
  "properties": {},
  "summary": {},
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
403	forbidden	write permission required
400	invalid_request	malformed JSON body
404	not_found	default engine or model artifact not found
500	internal_error	internal server error

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

删除模型

功能介绍

删除模型。

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

URI

DELETE /api/v1/models/{id}

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

请求消息

无请求体。

响应消息

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

请求示例

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

正常响应示例

HTTP/1.1 204 No Content

状态码与错误码

成功状态码：204。

HTTP	error	说明
403	forbidden	write permission required
404	not_found	model not found
500	internal_error	internal server error

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