模型导入

模型文件是保存在模型仓库中、可供模型注册和部署使用的 OCI 制品。远程导入是一项异步操作：服务端从 ModelScope 或 Hugging Face 下载文件，打包并发布到 Harbor，任务完成后模型文件状态变为 ready。

本文档同时说明远程来源解析、模型文件管理和导入任务控制。接口字段因兼容性原因继续使用 artifact、modelArtifactId 等名称，中文说明统一使用“模型文件”。本地目录上传使用另一套分片和断点续传流程，见本地模型上传。

模型文件的读取范围为当前项目和公共模型文件，不存在共享模型文件。普通项目只能修改本项目的私有模型文件；公共仓库和公共模型文件仅允许具有公共资源写权限的管理员修改。导入任务始终按当前项目隔离。

推荐的远程导入调用顺序如下：

1. 调用 /model-source-metadata 解析来源，取得规范化模型信息、文件列表和总大小。
2. 调用 /model-artifacts/import，原子创建模型文件与导入任务。
3. 使用返回的任务 ID 查询进度，必要时暂停、修改限速、恢复或重试。
4. 模型文件 status 变为 ready 后，再用于模型注册或部署。

方法	路径（产品接口统一前缀 /api/v1）	功能
GET	/model-source-metadata	通过查询参数解析远程模型信息
POST	/model-source-metadata	通过 JSON 解析远程模型信息，可指定代理
POST	/model-artifacts/import	原子创建模型文件与导入任务（推荐）
GET	/model-artifacts	查询模型文件
POST	/model-artifacts	创建模型文件记录（高级用法）
GET	/model-artifacts/{id}	获取模型文件详情
PATCH	/model-artifacts/{id}	更新模型文件元数据
GET	/model-artifacts/{id}/linked-models	查询模型文件关联的模型
DELETE	/model-artifacts/{id}	删除模型文件
POST	/model-artifacts/tasks	为已有模型文件创建导入任务（高级用法）
GET	/model-artifacts/tasks	查询指定模型文件的导入任务摘要
GET	/model-artifacts/tasks/{taskId}	获取导入任务详情
POST	/model-artifacts/tasks/{taskId}/pause	暂停导入任务
PATCH	/model-artifacts/tasks/{taskId}	修改已暂停任务的限速
POST	/model-artifacts/tasks/{taskId}/resume	恢复导入任务
POST	/model-artifacts/tasks/{taskId}/retry	重试失败的导入任务
DELETE	/model-artifacts/tasks/{taskId}	取消或删除导入任务

公共数据结构

模型文件对象

模型文件接口返回以下字段：

参数	参数类型	描述
id	string	模型文件 ID
name	string	模型文件显示名称
description	string	模型文件说明
status	string	模型文件状态，取值见状态说明
projectId	string	所属项目 ID
ownerUserId	string	创建者用户 ID
ownerName	string	创建者名称；空值时省略
labels	object	标签；空值时省略。visibility 为 private 或 public
backend	object	后端制品引用，包含 catalog、type 和 id
summary	object	模型文件来源、导入进度和 OCI 信息
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339

summary 的字段如下：

参数	参数类型	描述
repositoryId	string	所属模型仓库 ID
repositoryName	string	所属模型仓库名称
sourceType	string	来源类型：modelscope、huggingface 或 local_upload
taskType	string	关联任务类型；空值时省略
uploadTaskId	string	本地上传任务 ID；不适用于远程导入时省略
rootName	string	本地上传根目录名称；不适用于远程导入时省略
sourceName	string	来源模型名称；空值时省略
sourceUri	string	来源模型 URI
revision	string	来源版本或提交标识；空值时省略
ociRepositoryName	string	服务端生成的 OCI 仓库名称
ociUri	string	发布后的 OCI URI；尚未发布时省略
ociDigest	string	OCI 摘要；尚未发布时省略
sizeBytes	integer	模型文件总大小，单位为字节；未知时省略
downloads	integer	远程来源下载次数；未知时省略
sourceUpdatedAt	integer	远程来源最后更新时间，Unix 秒时间戳；未知时省略
stage	string	当前阶段，例如 pending、downloading、packing、publishing、succeeded 或 failed
progress	integer	总体进度百分比，范围 0～100
totalFiles	integer	文件总数；未知时省略
completedFiles	integer	已完成文件数；未知时省略
totalBytes	integer	本次处理的总字节数；未知时省略
completedBytes	integer	已完成字节数；未知时省略
readmeReady	boolean	README 是否已经可用；值为 false 时可能省略
errorMessage	string	失败原因；无错误时省略
sourceFiles	array	来源文件清单；未知时省略
sourceFiles[].name	string	文件相对路径
sourceFiles[].size	integer	文件大小，单位为字节；未知时省略
sourceFiles[].sha256	string	文件 SHA-256；未知时省略

导入任务对象

参数	参数类型	描述
id	string	导入任务 ID
modelArtifactId	string	关联的模型文件 ID
taskType	string	固定为 import_and_publish
sourceType	string	来源类型：modelscope 或 huggingface
sourceUri	string	远程模型 URI
status	string	任务状态，取值见状态说明
workerId	string	当前执行节点 ID；未分配时省略
totalBytes	integer	总字节数；未知时省略
completedBytes	integer	已完成字节数；未知时省略
progressPercent	integer	进度百分比；未知时省略
speedLimit	integer	下载限速，单位为 bytes/s；未限速时省略
downloadSpeed	integer	实时下载速度，单位为 bytes/s；没有实时数据时省略
activeTasks	integer	系统当前活跃任务数；仅待调度任务可能返回，值为 0 时省略
waitingTasksAhead	integer	当前任务之前的排队任务数；值为 0 时省略
errorMessage	string	失败原因；无错误时省略
startedAt	string(date-time)	开始执行时间；尚未开始时省略
finishedAt	string(date-time)	完成或失败时间；尚未结束时省略

状态说明

模型文件常见状态：

状态	描述
pending	已创建，等待导入任务执行
importing	正在下载远程模型文件
publishing	正在打包或发布到 Harbor
paused	关联导入任务已暂停
ready	已发布，可以用于模型注册或部署
failed	导入失败，具体原因见 summary.errorMessage
deleting	正在取消任务并清理模型文件

导入任务常见状态：

状态	描述
pending	等待执行
running	正在下载、打包或发布
paused	已收到暂停请求；workerId 清空后才能修改限速或恢复
retry_waiting	等待自动重试，也可以调用重试接口重新排队
succeeded	导入成功，对应模型文件通常为 ready
failed	导入失败，可以调用重试接口
deleting	正在取消任务并清理相关数据

典型状态转换如下：

pending → running → succeeded
            ├→ paused → pending
            ├→ failed / retry_waiting → pending
            └→ deleting

通过查询参数解析远程模型信息

功能介绍

实时读取 ModelScope 或 Hugging Face 上的模型信息，用于在创建导入任务前校验来源 URI、展示模型信息、取得文件列表和计算总大小。该接口不在 Beacon 中创建或保存任何资源。

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

URI

GET /api/v1/model-source-metadata

查询参数

参数	类型	必选	描述
sourceType	string	是	来源类型：modelscope 或 huggingface
sourceUri	string	是	模型 ID 或模型页面 URL；Hugging Face 模型 ID 例如 Qwen/Qwen2.5-0.5B-Instruct

请求消息

无请求体。

响应消息

参数	参数类型	描述
sourceType	string	来源类型
sourceUri	string	请求中的来源 URI
modelId	string	解析后的模型 ID
displayName	string	模型显示名称；空值时省略
storageSize	integer	所有已识别文件的总大小，单位为字节；未知时省略
downloads	integer	来源站点记录的下载次数；未知时省略
revision	string	来源版本或提交标识；未知时省略
lastUpdatedTime	integer	最后更新时间，Unix 秒时间戳；未知时省略
license	string	许可证；未知时省略
modelTypes	array	模型类型；未知时省略
libraries	array	依赖库；未知时省略
languages	array	支持语言；未知时省略
tags	array	远程模型标签；未知时省略
tasks	array	模型任务类型；未知时省略
publisher	string	发布者；未知时省略
files	array	文件列表；未知时省略
files[].name	string	文件相对路径
files[].size	integer	文件大小，单位为字节；未知时省略
files[].sha256	string	文件 SHA-256；来源未提供时省略

请求示例

GET https://{endpoint}/api/v1/model-source-metadata?sourceType=huggingface&sourceUri=Qwen%2FQwen2.5-0.5B-Instruct
x-keystone-token: <Keystone Token>

正常响应示例

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

{
  "sourceType": "huggingface",
  "sourceUri": "Qwen/Qwen2.5-0.5B-Instruct",
  "modelId": "Qwen/Qwen2.5-0.5B-Instruct",
  "displayName": "Qwen/Qwen2.5-0.5B-Instruct",
  "storageSize": 1073741824,
  "downloads": 1250000,
  "revision": "8de5b4c7",
  "lastUpdatedTime": 1789948800,
  "license": "apache-2.0",
  "libraries": ["transformers"],
  "tags": ["text-generation"],
  "tasks": ["text-generation"],
  "publisher": "Qwen",
  "files": [
    {
      "name": "config.json",
      "size": 735,
      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
  ]
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
400	invalid_request	sourceType 或 sourceUri 缺失、不受支持或格式无效
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型读取权限
502	upstream_error	远程站点不可访问、返回错误或响应无法解析；具体原因见 message

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

通过 JSON 解析远程模型信息

功能介绍

与 GET 接口功能相同，但使用 JSON 请求体，并允许为本次远程访问指定 HTTP/HTTPS 代理。即使不使用代理，也可以使用此接口提交 JSON。

当前权限中间件将该 POST 请求按写操作鉴权，因此需要模型写入权限；接口本身不会创建或修改资源。

URI

POST /api/v1/model-source-metadata

查询参数

参数	类型	必选	描述
sourceType	string	条件必选	请求体未提供非空值时，从查询参数读取
sourceUri	string	条件必选	请求体未提供非空值时，从查询参数读取

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
sourceType	string	条件必选	来源类型：modelscope 或 huggingface；优先于同名查询参数
sourceUri	string	条件必选	模型 ID 或模型页面 URL；优先于同名查询参数
proxyUrl	string	否	完整的 HTTP 或 HTTPS 代理 URL，例如 http://proxy.example.com:8080

响应消息

响应字段与“通过查询参数解析远程模型信息”相同。

请求示例

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

{
  "sourceType": "huggingface",
  "sourceUri": "Qwen/Qwen2.5-0.5B-Instruct",
  "proxyUrl": "http://proxy.example.com:8080"
}

正常响应示例

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

{
  "sourceType": "huggingface",
  "sourceUri": "Qwen/Qwen2.5-0.5B-Instruct",
  "modelId": "Qwen/Qwen2.5-0.5B-Instruct",
  "displayName": "Qwen/Qwen2.5-0.5B-Instruct",
  "storageSize": 1073741824,
  "revision": "8de5b4c7",
  "publisher": "Qwen",
  "files": [
    {
      "name": "config.json",
      "size": 735
    }
  ]
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
400	invalid_request	JSON 格式错误、字段缺失、来源 URI 无效或代理 URL 无效
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型写入权限
502	upstream_error	远程站点不可访问、返回错误或响应无法解析；具体原因见 message

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

原子创建模型文件与导入任务

功能介绍

在一个事务中创建模型文件及其首个远程导入任务，是第三方开发者开始远程导入时的推荐接口。201 表示两项资源已创建并进入队列，不表示模型文件已经下载完成。

artifact.sourceType、artifact.sourceUri 必须分别与 task.sourceType、task.sourceUri 完全相同。任务的 modelArtifactId 由服务端关联，不需要提交。

访问要求：有效 Token；需要模型文件写入权限。普通项目只能写入本项目的私有仓库，公共仓库需要公共资源写入权限。

URI

POST /api/v1/model-artifacts/import

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
artifact	object	是	要创建的模型文件
artifact.repositoryId	string	是	目标模型仓库 ID
artifact.name	string	是	模型文件名称
artifact.description	string	否	模型文件说明
artifact.sourceType	string	是	modelscope 或 huggingface
artifact.sourceName	string	否	来源模型显示名称
artifact.sourceUri	string	是	经过解析确认的远程模型 URI
artifact.sourceSizeBytes	integer	否	远程文件总大小，单位为字节；为保证容量校验准确，建议传入解析接口返回的正数 storageSize
artifact.labels	object	否	自定义标签；visibility 由目标仓库决定，服务端会补充或覆盖
task	object	是	导入任务配置
task.sourceType	string	是	必须与 artifact.sourceType 相同
task.sourceUri	string	是	必须与 artifact.sourceUri 相同
task.proxyUrl	string	否	HTTP/HTTPS 下载代理 URL
task.proxyEnv	object	否	代理环境变量，仅支持 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY；值不能为空或包含换行符
task.speedLimit	integer / null	否	下载限速，单位为 bytes/s；非空时必须大于 0

响应消息

参数	参数类型	描述
artifact	object	新建的模型文件对象，初始状态为 pending
task	object	新建的导入任务对象，初始状态为 pending

字段定义见“公共数据结构”。

请求示例

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

{
  "artifact": {
    "repositoryId": "repository-private",
    "name": "Qwen2.5-0.5B-Instruct",
    "description": "从 Hugging Face 导入",
    "sourceType": "huggingface",
    "sourceName": "Qwen/Qwen2.5-0.5B-Instruct",
    "sourceUri": "Qwen/Qwen2.5-0.5B-Instruct",
    "sourceSizeBytes": 1073741824
  },
  "task": {
    "sourceType": "huggingface",
    "sourceUri": "Qwen/Qwen2.5-0.5B-Instruct",
    "speedLimit": 10485760
  }
}

正常响应示例

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

{
  "artifact": {
    "id": "artifact-7f3a",
    "name": "Qwen2.5-0.5B-Instruct",
    "description": "从 Hugging Face 导入",
    "status": "pending",
    "projectId": "project-a",
    "ownerUserId": "user-a",
    "labels": {
      "visibility": "private"
    },
    "backend": {
      "catalog": "harbor",
      "type": "image",
      "id": "pending-import:artifact-7f3a"
    },
    "summary": {
      "repositoryId": "repository-private",
      "repositoryName": "私有仓库",
      "sourceType": "huggingface",
      "sourceName": "Qwen/Qwen2.5-0.5B-Instruct",
      "sourceUri": "Qwen/Qwen2.5-0.5B-Instruct",
      "ociRepositoryName": "qwen2.5-0.5b-instruct-artifact-7f3a",
      "sizeBytes": 1073741824,
      "stage": "pending"
    },
    "createdAt": "2026-09-21T00:00:00Z",
    "updatedAt": "2026-09-21T00:00:00Z"
  },
  "task": {
    "id": "task-91bc",
    "modelArtifactId": "artifact-7f3a",
    "taskType": "import_and_publish",
    "sourceType": "huggingface",
    "sourceUri": "Qwen/Qwen2.5-0.5B-Instruct",
    "status": "pending",
    "totalBytes": 1073741824,
    "speedLimit": 10485760
  }
}

状态码与错误码

成功状态码：201。

HTTP	error	说明
400	invalid_request	JSON 格式错误、必填字段缺失、来源类型不受支持、文件与任务来源不一致、代理或限速配置无效
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型文件写入权限
409	capacity_exceeded	目标仓库容量不足；详细容量信息见 details
500	internal_error	模型仓库、基础镜像或服务端配置异常，导致导入任务创建失败

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

查询模型文件

功能介绍

查询当前项目和公共模型文件。传入 repositoryId 时，服务端会先尝试同步该仓库中的 Harbor 制品；Harbor 暂时不可用或同步超时时返回已有缓存数据，其他同步错误返回 500。

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

URI

GET /api/v1/model-artifacts

查询参数

参数	类型	必选	描述
repositoryId	string	否	模型仓库 ID；提供时触发该仓库的 Harbor 同步
page	integer	否	页码，从 1 开始；省略或小于 1 时按 1 返回
page_size	integer	否	每页数量，最大 200；省略或传 0 时返回全部匹配项
status	string	否	按模型文件状态精确过滤
q	string	否	按名称、说明或来源名称进行不区分大小写的模糊搜索

请求消息

无请求体。

响应消息

参数	参数类型	描述
items	array	模型文件列表，字段见“模型文件对象”
total	integer	匹配总数
page	integer	当前页码
page_size	integer	请求的每页数量；未限制时为 0

请求示例

GET https://{endpoint}/api/v1/model-artifacts?repositoryId=repository-private&page=1&page_size=20&q=Qwen
x-keystone-token: <Keystone Token>

正常响应示例

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

{
  "items": [
    {
      "id": "artifact-7f3a",
      "name": "Qwen2.5-0.5B-Instruct",
      "description": "从 Hugging Face 导入",
      "status": "ready",
      "projectId": "project-a",
      "ownerUserId": "user-a",
      "labels": {
        "visibility": "private"
      },
      "backend": {
        "catalog": "harbor",
        "type": "image",
        "id": "registry.example.com/project-a/qwen2.5-0.5b-instruct-artifact-7f3a:v20260921000500-task-91bc"
      },
      "summary": {
        "repositoryId": "repository-private",
        "repositoryName": "私有仓库",
        "sourceType": "huggingface",
        "sourceUri": "Qwen/Qwen2.5-0.5B-Instruct",
        "ociUri": "registry.example.com/project-a/qwen2.5-0.5b-instruct-artifact-7f3a:v20260921000500-task-91bc",
        "ociDigest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
        "sizeBytes": 1073741824,
        "stage": "succeeded",
        "progress": 100,
        "readmeReady": true
      },
      "createdAt": "2026-09-21T00:00:00Z",
      "updatedAt": "2026-09-21T00:10:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型文件读取权限
500	internal_error	查询模型文件或同步 Harbor 制品失败

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

创建模型文件记录

功能介绍

只创建状态为 pending 的模型文件记录，不创建下载任务，也不会自动变为 ready。通常应改用原子导入接口；仅在调用方需要自行控制两步创建流程时使用本接口，然后调用 /model-artifacts/tasks 创建任务。

访问要求：有效 Token；需要模型文件写入权限。普通项目只能写入本项目的私有仓库，公共仓库需要公共资源写入权限。

URI

POST /api/v1/model-artifacts

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
repositoryId	string	是	目标模型仓库 ID
name	string	是	模型文件名称
description	string	否	模型文件说明
sourceType	string	是	modelscope 或 huggingface
sourceName	string	否	来源模型显示名称
sourceUri	string	是	远程模型 URI
sourceSizeBytes	integer	否	来源文件总大小，单位为字节；不能为负数，建议传入正数以便容量校验
labels	object	否	自定义标签；visibility 由目标仓库决定，服务端会补充或覆盖

响应消息

返回新建的模型文件对象，status 和 summary.stage 均为 pending。字段见“模型文件对象”。

请求示例

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

{
  "repositoryId": "repository-private",
  "name": "Qwen2.5-0.5B-Instruct",
  "sourceType": "huggingface",
  "sourceName": "Qwen/Qwen2.5-0.5B-Instruct",
  "sourceUri": "Qwen/Qwen2.5-0.5B-Instruct",
  "sourceSizeBytes": 1073741824
}

正常响应示例

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

{
  "id": "artifact-7f3a",
  "name": "Qwen2.5-0.5B-Instruct",
  "description": "",
  "status": "pending",
  "projectId": "project-a",
  "ownerUserId": "user-a",
  "labels": {
    "visibility": "private"
  },
  "backend": {
    "catalog": "harbor",
    "type": "image",
    "id": "pending-import:artifact-7f3a"
  },
  "summary": {
    "repositoryId": "repository-private",
    "repositoryName": "私有仓库",
    "sourceType": "huggingface",
    "sourceName": "Qwen/Qwen2.5-0.5B-Instruct",
    "sourceUri": "Qwen/Qwen2.5-0.5B-Instruct",
    "ociRepositoryName": "qwen2.5-0.5b-instruct-artifact-7f3a",
    "sizeBytes": 1073741824,
    "stage": "pending"
  },
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：201。

HTTP	error	说明
400	invalid_request	JSON 格式错误、必填字段缺失、来源类型不受支持或 sourceSizeBytes 为负数
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型文件写入权限，或当前调用方不能写入公共仓库
404	not_found	模型仓库不存在或不可见
409	capacity_exceeded	模型仓库容量不足
409	conflict	模型文件与已有资源冲突
500	internal_error	创建模型文件失败

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

获取模型文件详情

功能介绍

获取当前项目或公共模型文件的完整信息。

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

URI

GET /api/v1/model-artifacts/{id}

参数	类型	必选	描述
id	string	是	模型文件 ID

请求消息

无请求体。

响应消息

返回模型文件对象，字段见“公共数据结构”。

请求示例

GET https://{endpoint}/api/v1/model-artifacts/artifact-7f3a
x-keystone-token: <Keystone Token>

正常响应示例

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

{
  "id": "artifact-7f3a",
  "name": "Qwen2.5-0.5B-Instruct",
  "description": "从 Hugging Face 导入",
  "status": "ready",
  "projectId": "project-a",
  "ownerUserId": "user-a",
  "labels": {
    "visibility": "private"
  },
  "backend": {
    "catalog": "harbor",
    "type": "image",
    "id": "registry.example.com/project-a/qwen2.5-0.5b-instruct-artifact-7f3a:v20260921000500-task-91bc"
  },
  "summary": {
    "repositoryId": "repository-private",
    "repositoryName": "私有仓库",
    "sourceType": "huggingface",
    "sourceUri": "Qwen/Qwen2.5-0.5B-Instruct",
    "ociUri": "registry.example.com/project-a/qwen2.5-0.5b-instruct-artifact-7f3a:v20260921000500-task-91bc",
    "ociDigest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "sizeBytes": 1073741824,
    "stage": "succeeded",
    "progress": 100,
    "readmeReady": true
  },
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:10:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型文件读取权限
404	not_found	模型文件不存在或对当前项目不可见
500	internal_error	获取模型文件失败

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

更新模型文件元数据

功能介绍

按字段更新模型文件的名称、说明或自定义标签。标签采用合并语义：字符串值新增或覆盖标签，null 删除对应标签；未提交的标签保持不变。visibility 由所属仓库决定，不允许通过此接口修改。名称仅用于展示，修改后不会重命名已经生成的 OCI 仓库。

访问要求：有效 Token；需要模型文件写入权限。公共模型文件只允许具有公共资源写入权限的管理员更新。

URI

PATCH /api/v1/model-artifacts/{id}

参数	类型	必选	描述
id	string	是	模型文件 ID

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
name	string	否	新名称；去除首尾空白后不能为空
description	string	否	新说明；空字符串表示清空
labels	object	否	要合并的标签；值为 null 时删除该标签，不允许包含 visibility

响应消息

返回更新后的模型文件对象，字段见“公共数据结构”。

请求示例

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

{
  "name": "Qwen 对话模型",
  "labels": {
    "purpose": "chat",
    "legacy": null
  }
}

正常响应示例

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

{
  "id": "artifact-7f3a",
  "name": "Qwen 对话模型",
  "description": "从 Hugging Face 导入",
  "status": "ready",
  "projectId": "project-a",
  "ownerUserId": "user-a",
  "labels": {
    "visibility": "private",
    "purpose": "chat"
  },
  "backend": {
    "catalog": "harbor",
    "type": "image",
    "id": "registry.example.com/project-a/qwen2.5-0.5b-instruct-artifact-7f3a:v20260921000500-task-91bc"
  },
  "summary": {
    "repositoryId": "repository-private",
    "sourceType": "huggingface",
    "sourceUri": "Qwen/Qwen2.5-0.5B-Instruct",
    "ociUri": "registry.example.com/project-a/qwen2.5-0.5b-instruct-artifact-7f3a:v20260921000500-task-91bc",
    "stage": "succeeded",
    "progress": 100
  },
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T01:00:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
400	invalid_request	JSON 格式错误、名称为空、标签键为空或试图修改 visibility
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型文件写入权限，或公共模型文件对当前调用方只读
404	not_found	模型文件不存在或不可见
500	internal_error	更新模型文件失败

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

查询模型文件关联的模型

功能介绍

查询直接引用指定模型文件的模型，用于在删除前确认影响范围。返回的模型与模型文件具有相同可见性。

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

URI

GET /api/v1/model-artifacts/{id}/linked-models

参数	类型	必选	描述
id	string	是	模型文件 ID

请求消息

无请求体。

响应消息

参数	参数类型	描述
items	array	关联模型列表
items[].id	string	模型 ID
items[].name	string	模型名称

请求示例

GET https://{endpoint}/api/v1/model-artifacts/artifact-7f3a/linked-models
x-keystone-token: <Keystone Token>

正常响应示例

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

{
  "items": [
    {
      "id": "model-qwen",
      "name": "Qwen2.5"
    }
  ]
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型文件读取权限
404	not_found	模型文件不存在或不可见
500	internal_error	查询关联模型失败

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

删除模型文件

功能介绍

删除模型文件、相关导入任务以及 Harbor 中已发布的 OCI 制品。存在运行中或暂停中的任务时，接口提交取消请求并返回 204，模型文件和任务先进入 deleting，由工作节点异步停止下载并完成清理。

如果模型文件被模型引用，deleteLinkedModels=false 会保留模型、解除模型文件关联并将模型标记为不可用；deleteLinkedModels=true 会连带删除这些模型。

访问要求：有效 Token；需要模型文件写入权限。公共模型文件只允许具有公共资源写入权限的管理员删除。

URI

DELETE /api/v1/model-artifacts/{id}

参数	类型	必选	描述
id	string	是	模型文件 ID

查询参数

参数	类型	必选	描述
deleteLinkedModels	boolean	否	是否连带删除关联模型；仅 true 启用，默认 false

请求消息

无请求体。

响应消息

成功返回 204 No Content，无响应体。对于异步取消，204 仅表示删除请求已接受。

请求示例

DELETE https://{endpoint}/api/v1/model-artifacts/artifact-7f3a?deleteLinkedModels=false
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 204 No Content

状态码与错误码

成功状态码：204。

HTTP	error	说明
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型文件写入权限，或公共模型文件对当前调用方只读
404	not_found	模型文件不存在或不可见
409	conflict	并发任务状态变化或关联关系导致删除冲突
502	backend_unavailable	Harbor 不可用或拒绝删除远程 OCI 制品
500	internal_error	删除模型文件失败

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

为已有模型文件创建导入任务

功能介绍

为已经通过 POST /model-artifacts 创建的模型文件记录创建导入任务。一个模型文件同一时间只能有一个 pending、running、paused 或 retry_waiting 任务。

这是两步创建流程的第二步。常规集成应优先使用原子导入接口，避免模型文件已创建但任务创建失败。

访问要求：有效 Token；需要当前项目的模型文件写入权限。

URI

POST /api/v1/model-artifacts/tasks

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
modelArtifactId	string	是	当前项目中的模型文件 ID
sourceType	string	是	modelscope 或 huggingface
sourceUri	string	是	远程模型 URI
proxyUrl	string	否	HTTP/HTTPS 下载代理 URL
proxyEnv	object	否	代理环境变量，仅支持 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY；值不能为空或包含换行符
speedLimit	integer / null	否	下载限速，单位为 bytes/s；非空时必须大于 0

响应消息

返回新建的导入任务对象，初始 status 为 pending，taskType 为 import_and_publish。

请求示例

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

{
  "modelArtifactId": "artifact-7f3a",
  "sourceType": "huggingface",
  "sourceUri": "Qwen/Qwen2.5-0.5B-Instruct",
  "speedLimit": 10485760
}

正常响应示例

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

{
  "id": "task-91bc",
  "modelArtifactId": "artifact-7f3a",
  "taskType": "import_and_publish",
  "sourceType": "huggingface",
  "sourceUri": "Qwen/Qwen2.5-0.5B-Instruct",
  "status": "pending",
  "totalBytes": 1073741824,
  "speedLimit": 10485760
}

状态码与错误码

成功状态码：201。

HTTP	error	说明
400	invalid_request	JSON 格式错误、必填字段缺失、来源类型不受支持、代理或限速配置无效
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型文件写入权限
404	not_found	当前项目中不存在指定模型文件
409	conflict	模型文件已有活动任务
409	capacity_exceeded	模型仓库容量不足
409	base_image_missing	导入所需基础镜像缺失且自动初始化失败
502	backend_unavailable	无法验证导入所需基础镜像
500	internal_error	创建导入任务失败

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

查询指定模型文件的导入任务摘要

功能介绍

查询当前项目中一个或多个模型文件关联的导入任务摘要。每个 modelArtifactId 最多返回一项；此接口不是完整任务历史列表，也不保证返回全部历史任务。不传 modelArtifactId 时返回空列表。

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

URI

GET /api/v1/model-artifacts/tasks

查询参数

参数	类型	必选	描述
modelArtifactId	array	是	模型文件 ID，可重复传入，例如 modelArtifactId=id-a&modelArtifactId=id-b；空值和重复值会被忽略

请求消息

无请求体。

响应消息

参数	参数类型	描述
items	array	各指定模型文件返回的任务摘要，字段见“导入任务对象”
total	integer	返回的任务数量，不是历史任务总数

请求示例

GET https://{endpoint}/api/v1/model-artifacts/tasks?modelArtifactId=artifact-7f3a&modelArtifactId=artifact-8b2c
x-keystone-token: <Keystone Token>

正常响应示例

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

{
  "items": [
    {
      "id": "task-91bc",
      "modelArtifactId": "artifact-7f3a",
      "taskType": "import_and_publish",
      "sourceType": "huggingface",
      "sourceUri": "Qwen/Qwen2.5-0.5B-Instruct",
      "status": "running",
      "workerId": "worker-01",
      "totalBytes": 1073741824,
      "completedBytes": 536870912,
      "progressPercent": 40,
      "downloadSpeed": 5242880,
      "startedAt": "2026-09-21T00:01:00Z"
    }
  ],
  "total": 1
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型文件读取权限
500	internal_error	查询导入任务失败

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

获取导入任务详情

功能介绍

按任务 ID 获取当前项目中的导入任务。待调度任务还会尽可能返回活跃任务数和排队位置。

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

URI

GET /api/v1/model-artifacts/tasks/{taskId}

参数	类型	必选	描述
taskId	string	是	导入任务 ID

请求消息

无请求体。

响应消息

返回导入任务对象，字段见“公共数据结构”。

请求示例

GET https://{endpoint}/api/v1/model-artifacts/tasks/task-91bc
x-keystone-token: <Keystone Token>

正常响应示例

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

{
  "id": "task-91bc",
  "modelArtifactId": "artifact-7f3a",
  "taskType": "import_and_publish",
  "sourceType": "huggingface",
  "sourceUri": "Qwen/Qwen2.5-0.5B-Instruct",
  "status": "running",
  "workerId": "worker-01",
  "totalBytes": 1073741824,
  "completedBytes": 536870912,
  "progressPercent": 40,
  "speedLimit": 10485760,
  "downloadSpeed": 5242880,
  "startedAt": "2026-09-21T00:01:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型文件读取权限
404	not_found	当前项目中不存在该任务或关联模型文件已删除
500	internal_error	获取导入任务失败

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

暂停导入任务

功能介绍

暂停 pending 或 running 状态的任务，并保留已下载数据以便继续。接口成功后立即返回 status: paused；如果返回中仍有 workerId，表示工作节点还在退出，需等待 workerId 省略后才能修改限速或恢复。

访问要求：有效 Token；需要当前项目的模型文件写入权限。

URI

POST /api/v1/model-artifacts/tasks/{taskId}/pause

参数	类型	必选	描述
taskId	string	是	导入任务 ID

请求消息

无请求体。

响应消息

返回暂停后的导入任务对象。

请求示例

POST https://{endpoint}/api/v1/model-artifacts/tasks/task-91bc/pause
x-keystone-token: <Keystone Token>

正常响应示例

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

{
  "id": "task-91bc",
  "modelArtifactId": "artifact-7f3a",
  "taskType": "import_and_publish",
  "sourceType": "huggingface",
  "sourceUri": "Qwen/Qwen2.5-0.5B-Instruct",
  "status": "paused",
  "workerId": "worker-01",
  "totalBytes": 1073741824,
  "completedBytes": 536870912,
  "progressPercent": 40,
  "startedAt": "2026-09-21T00:01:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型文件写入权限
404	not_found	当前项目中不存在该任务
409	conflict	任务状态不是 pending 或 running，无法暂停
500	internal_error	暂停任务失败

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

修改已暂停任务的限速

功能介绍

修改已完全暂停任务的下载限速。任务必须为 paused，并且 workerId 已清空。正整数设置 bytes/s 限速，null 取消限速。

访问要求：有效 Token；需要当前项目的模型文件写入权限。

URI

PATCH /api/v1/model-artifacts/tasks/{taskId}

参数	类型	必选	描述
taskId	string	是	导入任务 ID

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
speedLimit	integer / null	否	正整数设置下载限速，单位为 bytes/s；省略或传 null 均表示取消限速

响应消息

返回更新后的任务，status 仍为 paused。

请求示例

PATCH https://{endpoint}/api/v1/model-artifacts/tasks/task-91bc
x-keystone-token: <Keystone Token>
Content-Type: application/json

{
  "speedLimit": 20971520
}

正常响应示例

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

{
  "id": "task-91bc",
  "modelArtifactId": "artifact-7f3a",
  "taskType": "import_and_publish",
  "sourceType": "huggingface",
  "sourceUri": "Qwen/Qwen2.5-0.5B-Instruct",
  "status": "paused",
  "totalBytes": 1073741824,
  "completedBytes": 536870912,
  "progressPercent": 40,
  "speedLimit": 20971520,
  "startedAt": "2026-09-21T00:01:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
400	invalid_request	JSON 格式错误，或非空 speedLimit 小于等于 0
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型文件写入权限
404	not_found	当前项目中不存在该任务
409	conflict	任务尚未完全暂停，或工作节点尚未释放任务
500	internal_error	修改任务限速失败

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

恢复导入任务

功能介绍

将已完全暂停的任务重新加入队列。任务必须为 paused 且 workerId 已清空；成功后返回 status: pending。

访问要求：有效 Token；需要当前项目的模型文件写入权限。

URI

POST /api/v1/model-artifacts/tasks/{taskId}/resume

参数	类型	必选	描述
taskId	string	是	导入任务 ID

请求消息

无请求体。

响应消息

返回重新进入队列的任务对象，status 为 pending。

请求示例

POST https://{endpoint}/api/v1/model-artifacts/tasks/task-91bc/resume
x-keystone-token: <Keystone Token>

正常响应示例

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

{
  "id": "task-91bc",
  "modelArtifactId": "artifact-7f3a",
  "taskType": "import_and_publish",
  "sourceType": "huggingface",
  "sourceUri": "Qwen/Qwen2.5-0.5B-Instruct",
  "status": "pending",
  "totalBytes": 1073741824,
  "completedBytes": 536870912,
  "progressPercent": 40,
  "speedLimit": 20971520,
  "startedAt": "2026-09-21T00:01:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型文件写入权限
404	not_found	当前项目中不存在该任务
409	conflict	任务未暂停、仍在暂停过程中或不能恢复
500	internal_error	恢复任务失败

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

重试导入任务

功能介绍

将 failed 或 retry_waiting 状态的任务重新加入队列。重试会清空旧的执行节点、进度、错误和起止时间，成功后返回 status: pending。

访问要求：有效 Token；需要当前项目的模型文件写入权限。

URI

POST /api/v1/model-artifacts/tasks/{taskId}/retry

参数	类型	必选	描述
taskId	string	是	导入任务 ID

请求消息

无请求体。

响应消息

返回重新进入队列的任务对象，status 为 pending。

请求示例

POST https://{endpoint}/api/v1/model-artifacts/tasks/task-91bc/retry
x-keystone-token: <Keystone Token>

正常响应示例

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

{
  "id": "task-91bc",
  "modelArtifactId": "artifact-7f3a",
  "taskType": "import_and_publish",
  "sourceType": "huggingface",
  "sourceUri": "Qwen/Qwen2.5-0.5B-Instruct",
  "status": "pending",
  "totalBytes": 1073741824,
  "speedLimit": 20971520
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型文件写入权限
404	not_found	当前项目中不存在该任务
409	conflict	任务状态不是 failed 或 retry_waiting
500	internal_error	重试任务失败，包括基础镜像检查失败

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

取消或删除导入任务

功能介绍

取消活动任务或删除非活动任务。对 running、paused 任务调用时，接口返回 204，任务进入 deleting，工作节点随后停止下载并清理任务及关联模型文件；这是一项异步操作。

对于 pending、retry_waiting、failed 或终态任务，服务端可以直接删除：如果关联模型文件尚未就绪，会同时删除该模型文件；如果模型文件已经就绪，则只删除任务记录。deleteLinkedModels 决定清理模型文件时如何处理引用它的模型。

访问要求：有效 Token；需要当前项目的模型文件写入权限。

URI

DELETE /api/v1/model-artifacts/tasks/{taskId}

参数	类型	必选	描述
taskId	string	是	导入任务 ID

查询参数

参数	类型	必选	描述
deleteLinkedModels	boolean	否	清理关联模型文件时是否连带删除引用它的模型；仅 true 启用，默认 false

请求消息

无请求体。

响应消息

成功返回 204 No Content，无响应体。活动任务返回 204 仅表示取消请求已接受。

请求示例

DELETE https://{endpoint}/api/v1/model-artifacts/tasks/task-91bc?deleteLinkedModels=false
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 204 No Content

状态码与错误码

成功状态码：204。

HTTP	error	说明
401	unauthorized	未认证或 Token 无效
403	forbidden	无模型文件写入权限
404	not_found	当前项目中不存在该任务或关联模型文件
409	conflict	任务状态发生并发变化，或关联模型阻止清理
500	internal_error	取消或删除任务失败

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