更新知识库¶

更新知识库元数据。每次成功更新都会使 version 加一；此接口不执行文件解析或索引。

PATCH https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/knowledge-bases/{knowledge_base_id}

调用前准备¶

先查询知识库详情确认当前元数据和版本。准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

请求体¶

请求示例

curl -X PATCH "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/knowledge-bases/$KNOWLEDGE_BASE_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "产品文档（已审核）",
    "status": "active",
    "index_status": "ready",
    "tags": ["产品", "文档", "已审核"]
  }'

字段说明

请求字段

字段	类型	必填	说明
`name`	string	否	新名称，长度不得超过 128。
`description`	string	否	新说明，长度不得超过 4096。
`status`	string	否	draft、active、disabled 或 archived。
`source_type`	string	否	manual、catalog_resource、file_collection、external_drive 或 connector_export。
`catalog_asset_refs`	array of object	否	替换全部关联资产。每项必须提供 type，并至少提供 id 或 uri。
`default_retrieval_profile_ref`	string	否	默认检索配置引用。
`tags`	array of string	否	替换全部标签。
`owner_user_id`	string	否	更新所有者用户 ID。
`visibility`	string	否	private 或 workspace。
`index_status`	string	否	empty、indexing、ready 或 failed。
`last_indexed_at`	string	否	最近索引时间，采用 RFC 3339 格式。
`last_index_error`	string	否	最近索引错误信息，长度不得超过 4096。
`labels`	object	否	替换字符串键值标签。
`annotations`	object	否	替换字符串键值注释。
`metadata`	object	否	替换扩展元数据；不得包含密钥、提供商运行信息或会话引用。

请求参数¶

请求示例

curl -X PATCH "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/knowledge-bases/$KNOWLEDGE_BASE_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "产品文档（已审核）",
    "status": "active",
    "index_status": "ready",
    "tags": ["产品", "文档", "已审核"]
  }'

参数说明

路径参数

字段	类型	必填	说明
`workspace_id`	string	是	当前工作区 ID，必须与 X-Workspace-ID 一致。
`knowledge_base_id`	string	是	要更新的知识库 ID。

成功响应¶

响应示例

{
  "code": 0,
  "data": {
    "id": "kb_01",
    "workspace_id": "ws_01",
    "name": "产品文档（已审核）",
    "status": "active",
    "source_type": "catalog_resource",
    "visibility": "workspace",
    "index_status": "ready",
    "version": 2,
    "updated_by": "user_01",
    "updated_at": "2026-08-18T02:00:00Z"
  }
}

字段说明

成功时返回 200。data 为更新后的知识库元数据，data.version 比更新前增加 1。

通用字段

字段	类型	说明
`code`	integer	成功时为 0。

响应数据

字段	类型	说明
`data.id`	string	知识库 ID。
`data.workspace_id`	string	所属工作区 ID。
`data.name`	string	更新后的名称和说明；未设置说明时不返回。
`data.description`	string	更新后的名称和说明；未设置说明时不返回。
`data.status`	string	更新后的状态和来源类型。
`data.source_type`	string	更新后的状态和来源类型。
`data.catalog_asset_refs`	array of object	关联资产；未设置时不返回。
`data.default_retrieval_profile_ref`	string	默认检索配置引用；未设置时不返回。
`data.tags`	array of string	标签；未设置时不返回。
`data.owner_user_id`	string	所有者用户 ID；未设置时不返回。
`data.visibility`	string	可见范围和索引状态。
`data.index_status`	string	可见范围和索引状态。
`data.last_indexed_at`	string	最近索引时间和错误信息；未设置时不返回。
`data.last_index_error`	string	最近索引时间和错误信息；未设置时不返回。
`data.version`	integer	更新后的资源版本。
`data.labels`	object	扩展标签、注释和元数据；未设置时不返回。
`data.annotations`	object	扩展标签、注释和元数据；未设置时不返回。
`data.metadata`	object	扩展标签、注释和元数据；未设置时不返回。
`data.created_by`	string	创建者和最近更新者 ID；未设置时不返回。
`data.updated_by`	string	创建者和最近更新者 ID；未设置时不返回。
`data.created_at`	string	创建和最近更新时间，采用 RFC 3339 格式。
`data.updated_at`	string	创建和最近更新时间，采用 RFC 3339 格式。

错误响应¶

响应示例

{
  "code": 2,
  "message": "invalid knowledge base metadata"
}

字段说明

常见 HTTP 错误

字段	类型	说明
`400`	`2`（`INVALID_ARGUMENT`）	请求体无法解析，字段值或资产引用不符合要求，或元数据包含不允许的敏感引用。建议：检查请求字段和资产引用；不要传入凭据或会话信息。
`401`	`6`（`UNAUTHENTICATED`）	缺少有效身份凭据。建议：检查 API Key。
`404`	`3`（`NOT_FOUND`）	当前工作区中不存在该知识库。建议：检查 `knowledge_base_id`，或先查询知识库列表。
`503`	`15`（`UNAVAILABLE`）	知识库服务暂不可用。建议：稍后重试。

后续操作¶

调用查询知识库详情确认更新后的元数据和版本。

最后更新于 2026 年 9 月 11 日