本地模型上传

使用Keystone Token先创建上传任务，使用返回的 endpoint、files[].uploadToken 和文件标识上传，所有文件完成后调用 complete，等待打包发布完成。文件字节流由独立 tus 服务接收。

任务管理接口通过 x-keystone-token 请求头携带有效 Keystone Token。文件上传入口采用不同的校验方式：创建 tus 上传资源时，在 Upload-Metadata 中携带专用 uploadToken；仅携带 x-keystone-token 不能替代 uploadToken。

relativePath 必须以 rootName/ 开头，不允许绝对路径、目录穿越或重复路径；sizeBytes 不得为负。默认最多 20000 个文件、总计 2 TiB。

resume 的清单必须与原任务匹配；上传未完成调用 complete 返回 409 upload_incomplete。发布失败可调用 retry，具体允许状态由任务控制。

任务状态包含 created、uploading、paused、uploaded、packing、publishing、succeeded、failed、deleting、cancelled、expired。

方法	路径（产品接口统一前缀 /api/v1）	功能
POST	/model-upload-tasks	创建本地模型上传任务
GET	/model-upload-tasks/{id}	获取本地上传任务
GET	/model-upload-tasks/{id}/files	分页查询上传文件
POST	/model-upload-tasks/{id}/pause	暂停上传任务
POST	/model-upload-tasks/{id}/resume	恢复上传任务
POST	/model-upload-tasks/{id}/complete	提交上传完成
POST	/model-upload-tasks/{id}/retry	重试制品发布
DELETE	/model-upload-tasks/{id}	取消本地上传任务

创建本地模型上传任务

功能介绍

创建本地模型上传任务。

访问要求：通过 x-keystone-token 携带有效 Keystone Token；需要对应资源写权限，并受项目、所有者、公共或共享资源规则限制。

URI

POST /api/v1/model-upload-tasks

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
repositoryId	string	是	模型仓库 ID
name	string	是	显示名称
description	string	否	描述；空值时可能省略
lora	boolean	否	LoRA 配置；空值时可能省略
rootName	string	是	上传根目录名称，从所选文件的相对路径提取。
files	array<modelartifactupload.ManifestFile>	是	非空文件清单，从所选模型目录生成。
files[].relativePath	string	是	以 rootName/ 开头的相对路径
files[].sizeBytes	int64	是	文件字节数，不得为负
files[].lastModified	int64	否	文件修改时间标记，恢复时保持原值

响应消息

参数	参数类型	描述
task	modelartifactupload.Task	模型任务类型或导入任务对象
files	array<modelartifactupload.File>	文件清单
endpoint	string	文件上传入口，默认 /beacon/uploads/files/；相对地址按服务源站解析

创建和恢复任务返回的文件对象除文件信息外，还包含以下上传相关字段：

参数	参数类型	描述
files[].id	string	文件 ID，用于创建 tus 上传资源
files[].relativePath	string	含根目录的相对路径
files[].sizeBytes	int64	文件总字节数
files[].uploadToken	string	专用上传凭证，创建 tus 上传资源时放入 Upload-Metadata
files[].uploadTokenExpiresAt	string(date-time)	专用上传凭证过期时间，默认有效期为 1800 秒，以服务配置和响应为准
files[].tusUploadId	string	已绑定的 tus 上传 ID，未建立时可省略
files[].tusUploadUrl	string	已记录的 tus 上传地址，尚未记录时可省略

uploadToken 并非 Keystone Token。创建任务或调用 resume 获取凭证时仍需通过普通 API 的 Keystone 认证。

请求示例

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

{
  "repositoryId": "repository-id",
  "name": "本地模型",
  "rootName": "model",
  "files": [
    {
      "relativePath": "model/config.json",
      "sizeBytes": 1024
    }
  ]
}

正常响应示例

HTTP/1.1 201
Content-Type: application/json

{
  "task": {
    "id": "id-example",
    "modelArtifactId": "modelArtifactId-example",
    "repositoryId": "repositoryId-example",
    "rootName": "",
    "status": "created",
    "totalFiles": 0,
    "completedFiles": 0,
    "totalBytes": 0,
    "completedBytes": 0,
    "progressPercent": 0,
    "retryCount": 0,
    "version": 1,
    "createdAt": "2026-09-21T00:00:00Z",
    "updatedAt": "2026-09-21T00:00:00Z"
  },
  "files": [
    {
      "id": "id-example",
      "relativePath": "",
      "artifactPath": "",
      "sizeBytes": 0,
      "uploadedBytes": 0,
      "progressPercent": 0,
      "status": "created",
      "createdAt": "2026-09-21T00:00:00Z",
      "updatedAt": "2026-09-21T00:00:00Z"
    }
  ],
  "endpoint": "https://service.example.com"
}

创建任务后，使用响应中的 endpoint 创建每个文件的 tus 上传资源。以下示例使用当前默认网关前缀，文件传输接口不属于 /api/v1 路径。

创建文件上传请求：

POST https://{host}/beacon/uploads/files/
Tus-Resumable: 1.0.0
Upload-Length: 1024
Upload-Metadata: taskId <Base64任务ID>,fileId <Base64文件ID>,relativePath <Base64相对路径>,uploadToken <Base64上传Token>
Content-Length: 0

元数据值使用 UTF-8 字节的标准 Base64 编码，尖括号是需要替换的占位符。taskId 使用 task.id，fileId 使用对应 files[].id，relativePath、uploadToken 使用同一文件的响应值；Upload-Length 必须等于该文件的 sizeBytes。Base64 编码不等于加密。

服务端通过 pre-create hook 校验 uploadToken 的签名、有效期、任务和文件绑定，并检查项目归属、文件路径、大小及任务状态。缺失或无效 uploadToken 返回 401 invalid upload token。此请求不要求额外携带 Keystone Token，单独携带有效 Keystone Token 仍不能通过上传创建校验。

创建成功返回：

HTTP/1.1 201 Created
Tus-Resumable: 1.0.0
Location: https://{host}/beacon/uploads/files/{upload-id}

使用 Location 查询已接收字节数：

HEAD https://{host}/beacon/uploads/files/{upload-id}
Tus-Resumable: 1.0.0

HTTP/1.1 200 OK
Tus-Resumable: 1.0.0
Upload-Length: 1024
Upload-Offset: 0

按服务端偏移发送文件分片：

PATCH https://{host}/beacon/uploads/files/{upload-id}
Tus-Resumable: 1.0.0
Content-Type: application/offset+octet-stream
Upload-Offset: 0
Content-Length: 512

<文件开始位置的 512 字节原始二进制内容>

HTTP/1.1 204 No Content
Tus-Resumable: 1.0.0
Upload-Offset: 512

继续从返回的偏移上传剩余内容，直到 Upload-Offset 等于 Upload-Length。PATCH 请求体是原始文件字节，不是 JSON 或 multipart/form-data。网络中断后先 HEAD 查询实际偏移，再续传。

当前 HEAD、PATCH 示例未携带认证头，与现有实现和实测一致。不要将请求成功理解为 Keystone Token 已被验证；当前即使携带错误的 x-keystone-token，续传仍可能成功。uploadToken 到期不能据此推断已创建上传 URL 的续传会被拒绝。

以上 201、200、204 为文件传输响应，和本节创建任务 API 的响应分开处理。文件传输错误可能来自网关或 tus 服务，不保证采用任务 API 的 JSON 错误封装。

状态码与错误码

成功状态码：201。

HTTP	error	说明
403	forbidden	write permission required
400	invalid_manifest	malformed upload manifest
500	internal_error	failed to create upload credentials
503	backend_unavailable	model upload service is not configured
502	backend_unavailable	详细原因由 message 返回。
404	not_found	upload task not found
409	capacity_exceeded	model repository capacity would be exceeded
409	upload_not_resumable	详细原因由 message 返回。
409	upload_incomplete	not all files are uploaded
409	upload_task_conflict	详细原因由 message 返回。

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

获取本地上传任务

功能介绍

获取本地上传任务。

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

URI

GET /api/v1/model-upload-tasks/{id}

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

请求消息

无请求体。

响应消息

参数	参数类型	描述
id	string	资源唯一标识
modelArtifactId	string	模型制品 ID
projectId	string	所属项目 ID；空值时可能省略
repositoryId	string	模型仓库 ID
ownerUserId	string	创建者用户 ID；空值时可能省略
rootName	string	上传根目录名称
status	string	资源状态；具体取值见业务规则
failureStage	string	失败阶段；空值时可能省略
totalFiles	integer	文件总数
completedFiles	integer	已完成文件数
totalBytes	int64	总字节数
completedBytes	int64	已完成字节数
lastProgressAt	string(date-time) / null	最近进度更新时间；空值时可能省略
progressPercent	integer	进度百分比
workerId	string	执行工作节点 ID；空值时可能省略
retryCount	integer	重试次数
version	int64	并发控制版本
errorMessage	string	错误详情；空值时可能省略
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339
uploadCompletedAt	string(date-time) / null	文件上传完成时间；空值时可能省略
publishStartedAt	string(date-time) / null	发布开始时间；空值时可能省略
finishedAt	string(date-time) / null	结束时间；空值时可能省略
expiresAt	string(date-time) / null	到期时间；空值时可能省略

请求示例

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

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "id": "id-example",
  "modelArtifactId": "modelArtifactId-example",
  "repositoryId": "repositoryId-example",
  "rootName": "",
  "status": "created",
  "totalFiles": 0,
  "completedFiles": 0,
  "totalBytes": 0,
  "completedBytes": 0,
  "progressPercent": 0,
  "retryCount": 0,
  "version": 1,
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
404	not_found	upload task not found
403	forbidden	repository is read-only
400	invalid_manifest	详细原因由 message 返回。
409	capacity_exceeded	model repository capacity would be exceeded
409	upload_not_resumable	详细原因由 message 返回。
409	upload_incomplete	not all files are uploaded
409	upload_task_conflict	详细原因由 message 返回。
500	internal_error	model upload operation failed

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

分页查询上传文件

功能介绍

分页查询上传文件。

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

URI

GET /api/v1/model-upload-tasks/{id}/files

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

查询参数

参数	类型	必选	描述
page	integer	否	页码，从 1 开始
page_size	integer	否	每页数量；默认 200，最多 1000

请求消息

无请求体。

响应消息

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

请求示例

GET https://{endpoint}/api/v1/model-upload-tasks/resource-id/files?page=1&page_size=20
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "items": [
    {
      "id": "id-example",
      "relativePath": "",
      "artifactPath": "",
      "sizeBytes": 0,
      "uploadedBytes": 0,
      "progressPercent": 0,
      "status": "created",
      "createdAt": "2026-09-21T00:00:00Z",
      "updatedAt": "2026-09-21T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 1
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
404	not_found	upload task not found
403	forbidden	repository is read-only
400	invalid_manifest	详细原因由 message 返回。
409	capacity_exceeded	model repository capacity would be exceeded
409	upload_not_resumable	详细原因由 message 返回。
409	upload_incomplete	not all files are uploaded
409	upload_task_conflict	详细原因由 message 返回。
500	internal_error	model upload operation failed

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

暂停上传任务

功能介绍

暂停上传任务。

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

URI

POST /api/v1/model-upload-tasks/{id}/pause

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

请求消息

无请求体。

响应消息

参数	参数类型	描述
id	string	资源唯一标识
modelArtifactId	string	模型制品 ID
projectId	string	所属项目 ID；空值时可能省略
repositoryId	string	模型仓库 ID
ownerUserId	string	创建者用户 ID；空值时可能省略
rootName	string	上传根目录名称
status	string	资源状态；具体取值见业务规则
failureStage	string	失败阶段；空值时可能省略
totalFiles	integer	文件总数
completedFiles	integer	已完成文件数
totalBytes	int64	总字节数
completedBytes	int64	已完成字节数
lastProgressAt	string(date-time) / null	最近进度更新时间；空值时可能省略
progressPercent	integer	进度百分比
workerId	string	执行工作节点 ID；空值时可能省略
retryCount	integer	重试次数
version	int64	并发控制版本
errorMessage	string	错误详情；空值时可能省略
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339
uploadCompletedAt	string(date-time) / null	文件上传完成时间；空值时可能省略
publishStartedAt	string(date-time) / null	发布开始时间；空值时可能省略
finishedAt	string(date-time) / null	结束时间；空值时可能省略
expiresAt	string(date-time) / null	到期时间；空值时可能省略

请求示例

POST https://{endpoint}/api/v1/model-upload-tasks/resource-id/pause
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "id": "id-example",
  "modelArtifactId": "modelArtifactId-example",
  "repositoryId": "repositoryId-example",
  "rootName": "",
  "status": "created",
  "totalFiles": 0,
  "completedFiles": 0,
  "totalBytes": 0,
  "completedBytes": 0,
  "progressPercent": 0,
  "retryCount": 0,
  "version": 1,
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
403	forbidden	write permission required
404	not_found	upload task not found
400	invalid_manifest	详细原因由 message 返回。
409	capacity_exceeded	model repository capacity would be exceeded
409	upload_not_resumable	详细原因由 message 返回。
409	upload_incomplete	not all files are uploaded
409	upload_task_conflict	详细原因由 message 返回。
500	internal_error	model upload operation failed

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

恢复上传任务

功能介绍

恢复上传任务。

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

URI

POST /api/v1/model-upload-tasks/{id}/resume

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

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
files	array<modelartifactupload.ManifestFile>	是	文件清单

响应消息

参数	参数类型	描述
task	modelartifactupload.Task	模型任务类型或导入任务对象
files	array<modelartifactupload.File>	文件清单
endpoint	string	上传服务地址或服务端点

请求示例

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

{
  "files": [
    {
      "relativePath": "model/config.json",
      "sizeBytes": 1024
    }
  ]
}

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "task": {
    "id": "id-example",
    "modelArtifactId": "modelArtifactId-example",
    "repositoryId": "repositoryId-example",
    "rootName": "",
    "status": "created",
    "totalFiles": 0,
    "completedFiles": 0,
    "totalBytes": 0,
    "completedBytes": 0,
    "progressPercent": 0,
    "retryCount": 0,
    "version": 1,
    "createdAt": "2026-09-21T00:00:00Z",
    "updatedAt": "2026-09-21T00:00:00Z"
  },
  "files": [
    {
      "id": "id-example",
      "relativePath": "",
      "artifactPath": "",
      "sizeBytes": 0,
      "uploadedBytes": 0,
      "progressPercent": 0,
      "status": "created",
      "createdAt": "2026-09-21T00:00:00Z",
      "updatedAt": "2026-09-21T00:00:00Z"
    }
  ],
  "endpoint": "https://service.example.com"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
400	invalid_manifest	malformed upload manifest
500	internal_error	failed to create resume credentials
503	backend_unavailable	model upload service is not configured
502	backend_unavailable	详细原因由 message 返回。
404	not_found	upload task not found
403	forbidden	repository is read-only
409	capacity_exceeded	model repository capacity would be exceeded
409	upload_not_resumable	详细原因由 message 返回。
409	upload_incomplete	not all files are uploaded
409	upload_task_conflict	详细原因由 message 返回。

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

提交上传完成

功能介绍

提交上传完成。

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

URI

POST /api/v1/model-upload-tasks/{id}/complete

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

请求消息

无请求体。

响应消息

参数	参数类型	描述
id	string	资源唯一标识
modelArtifactId	string	模型制品 ID
projectId	string	所属项目 ID；空值时可能省略
repositoryId	string	模型仓库 ID
ownerUserId	string	创建者用户 ID；空值时可能省略
rootName	string	上传根目录名称
status	string	资源状态；具体取值见业务规则
failureStage	string	失败阶段；空值时可能省略
totalFiles	integer	文件总数
completedFiles	integer	已完成文件数
totalBytes	int64	总字节数
completedBytes	int64	已完成字节数
lastProgressAt	string(date-time) / null	最近进度更新时间；空值时可能省略
progressPercent	integer	进度百分比
workerId	string	执行工作节点 ID；空值时可能省略
retryCount	integer	重试次数
version	int64	并发控制版本
errorMessage	string	错误详情；空值时可能省略
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339
uploadCompletedAt	string(date-time) / null	文件上传完成时间；空值时可能省略
publishStartedAt	string(date-time) / null	发布开始时间；空值时可能省略
finishedAt	string(date-time) / null	结束时间；空值时可能省略
expiresAt	string(date-time) / null	到期时间；空值时可能省略

请求示例

POST https://{endpoint}/api/v1/model-upload-tasks/resource-id/complete
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "id": "id-example",
  "modelArtifactId": "modelArtifactId-example",
  "repositoryId": "repositoryId-example",
  "rootName": "",
  "status": "created",
  "totalFiles": 0,
  "completedFiles": 0,
  "totalBytes": 0,
  "completedBytes": 0,
  "progressPercent": 0,
  "retryCount": 0,
  "version": 1,
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
502	backend_unavailable	详细原因由 message 返回。
404	not_found	upload task not found
403	forbidden	repository is read-only
400	invalid_manifest	详细原因由 message 返回。
409	capacity_exceeded	model repository capacity would be exceeded
409	upload_not_resumable	详细原因由 message 返回。
409	upload_incomplete	not all files are uploaded
409	upload_task_conflict	详细原因由 message 返回。
500	internal_error	model upload operation failed

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

重试制品发布

功能介绍

重试制品发布。

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

URI

POST /api/v1/model-upload-tasks/{id}/retry

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

请求消息

无请求体。

响应消息

参数	参数类型	描述
id	string	资源唯一标识
modelArtifactId	string	模型制品 ID
projectId	string	所属项目 ID；空值时可能省略
repositoryId	string	模型仓库 ID
ownerUserId	string	创建者用户 ID；空值时可能省略
rootName	string	上传根目录名称
status	string	资源状态；具体取值见业务规则
failureStage	string	失败阶段；空值时可能省略
totalFiles	integer	文件总数
completedFiles	integer	已完成文件数
totalBytes	int64	总字节数
completedBytes	int64	已完成字节数
lastProgressAt	string(date-time) / null	最近进度更新时间；空值时可能省略
progressPercent	integer	进度百分比
workerId	string	执行工作节点 ID；空值时可能省略
retryCount	integer	重试次数
version	int64	并发控制版本
errorMessage	string	错误详情；空值时可能省略
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339
uploadCompletedAt	string(date-time) / null	文件上传完成时间；空值时可能省略
publishStartedAt	string(date-time) / null	发布开始时间；空值时可能省略
finishedAt	string(date-time) / null	结束时间；空值时可能省略
expiresAt	string(date-time) / null	到期时间；空值时可能省略

请求示例

POST https://{endpoint}/api/v1/model-upload-tasks/resource-id/retry
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "id": "id-example",
  "modelArtifactId": "modelArtifactId-example",
  "repositoryId": "repositoryId-example",
  "rootName": "",
  "status": "created",
  "totalFiles": 0,
  "completedFiles": 0,
  "totalBytes": 0,
  "completedBytes": 0,
  "progressPercent": 0,
  "retryCount": 0,
  "version": 1,
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
403	forbidden	write permission required
502	backend_unavailable	详细原因由 message 返回。
404	not_found	upload task not found
400	invalid_manifest	详细原因由 message 返回。
409	capacity_exceeded	model repository capacity would be exceeded
409	upload_not_resumable	详细原因由 message 返回。
409	upload_incomplete	not all files are uploaded
409	upload_task_conflict	详细原因由 message 返回。
500	internal_error	model upload operation failed

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

取消本地上传任务

功能介绍

取消本地上传任务。

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

URI

DELETE /api/v1/model-upload-tasks/{id}

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

请求消息

无请求体。

响应消息

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

请求示例

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

正常响应示例

HTTP/1.1 204 No Content

状态码与错误码

成功状态码：204。

HTTP	error	说明
403	forbidden	write permission required
404	not_found	upload task not found
400	invalid_manifest	详细原因由 message 返回。
409	capacity_exceeded	model repository capacity would be exceeded
409	upload_not_resumable	详细原因由 message 返回。
409	upload_incomplete	not all files are uploaded
409	upload_task_conflict	详细原因由 message 返回。
500	internal_error	model upload operation failed

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