更新知识库

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

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

调用前准备

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

下方示例使用：

• $AI_STUDIO_API_KEY：实际个人访问令牌，通过 X-API-Key Header 传递。

• $WORKSPACE_ID：目标工作区 ID，通过 X-Workspace-ID Header 传递，同时作为路径中的 workspace_id。

• $KNOWLEDGE_BASE_ID：要更新的知识库 ID。

路径参数

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

请求体

所有字段均为可选；只更新请求中提供的字段。

参数	类型	是否必填	说明
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	object（对象数组）	否	替换全部关联资产。每项必须提供 type，并至少提供 id 或 uri。
default_retrieval_profile_ref	string	否	默认检索配置引用。
tags	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://moi.matrixorigin.cn/newmoi/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": ["产品", "文档", "已审核"]
  }'

成功响应

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

{
  "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"
  }
}

响应字段如下。

字段	类型	说明
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	object（对象数组）	关联资产；未设置时不返回。
data.default_retrieval_profile_ref	string	默认检索配置引用；未设置时不返回。
data.tags	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 错误

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

后续操作

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

最后更新于 2026 年 8 月 22 日