创建知识库

创建智能体可引用的知识库元数据。此接口不执行文件解析、索引或检索；这些操作由其他资源操作或工具接口处理。

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

调用前准备

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

catalog_asset_refs[].uri 不能包含凭据或敏感查询参数；catalog_asset_refs[].config 和 metadata 也不能包含密钥或提供商运行、会话引用。路径中的工作区和当前用户由服务端确定，无需在请求体中传入。

请求体

请求示例

curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/knowledge-bases" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "产品文档",
    "description": "已审核的产品资料",
    "status": "active",
    "source_type": "catalog_resource",
    "catalog_asset_refs": [
      {
        "type": "catalog",
        "id": "<CATALOG_ID>",
        "role": "source"
      }
    ],
    "visibility": "workspace",
    "index_status": "ready",
    "tags": ["产品", "文档"]
  }'

字段说明

请求字段

字段	类型	必填	说明
name	string	是	知识库名称，长度不得超过 128。
id	string	否	知识库 ID。未提供时由服务端生成。
description	string	否	知识库说明，长度不得超过 4096。
status	string	否	状态：draft、active、disabled 或 archived；未提供时为 draft。
source_type	string	否	来源类型：manual、catalog_resource、file_collection、external_drive 或 connector_export；未提供时为 manual。
catalog_asset_refs	array of object	否	关联的 Catalog 资产。成员说明见关联资产字段。
default_retrieval_profile_ref	string	否	默认检索配置引用。
tags	array of string	否	标签。
owner_user_id	string	否	资源所有者 ID。未提供时使用当前用户 ID。
visibility	string	否	可见范围：private 或 workspace；未提供时为 private。
index_status	string	否	索引状态：empty、indexing、ready 或 failed；未提供时为 empty。
last_indexed_at	string	否	最近索引时间，采用 RFC 3339 格式。
last_index_error	string	否	最近索引错误信息，长度不得超过 4096。
labels	object	否	字符串键值标签。
annotations	object	否	字符串键值注释。
metadata	object	否	扩展元数据。不得包含密钥、提供商运行信息或会话引用。

关联资产字段

catalog_asset_refs 中的每一项描述一个关联资产。type 为必填字段，id 和 uri 至少填写一个。

字段	类型	必填	说明
type	string	是	资产类型。
id	string	条件必填	资产 ID；未填写 uri 时必填。
uri	string	条件必填	资产 URI；未填写 id 时必填。
version	string	否	资产版本。
role	string	否	资产关联角色。
config	object	否	资产配置。

请求参数

请求示例

curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/knowledge-bases" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "产品文档",
    "description": "已审核的产品资料",
    "status": "active",
    "source_type": "catalog_resource",
    "catalog_asset_refs": [
      {
        "type": "catalog",
        "id": "<CATALOG_ID>",
        "role": "source"
      }
    ],
    "visibility": "workspace",
    "index_status": "ready",
    "tags": ["产品", "文档"]
  }'

参数说明

路径参数

字段	类型	必填	说明
workspace_id	string	是	当前工作区 ID，必须与 X-Workspace-ID 一致。

成功响应

响应示例

{
  "code": 0,
  "data": {
    "id": "kb_01",
    "workspace_id": "ws_01",
    "name": "产品文档",
    "description": "已审核的产品资料",
    "status": "active",
    "source_type": "catalog_resource",
    "catalog_asset_refs": [
      {
        "type": "catalog",
        "id": "cat_01",
        "role": "source"
      }
    ],
    "tags": ["产品", "文档"],
    "owner_user_id": "user_01",
    "visibility": "workspace",
    "index_status": "ready",
    "version": 1,
    "created_by": "user_01",
    "updated_by": "user_01",
    "created_at": "2026-08-18T01:00:00Z",
    "updated_at": "2026-08-18T01:00:00Z"
  }
}

字段说明

成功时返回 201。data 为新建的知识库元数据；创建成功不表示内容已完成解析或索引。

通用字段

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

响应数据

字段	类型	说明
data.id	string	知识库 ID。
data.workspace_id	string	所属工作区 ID。
data.name	string	知识库名称和说明；未设置说明时不返回 description。
data.description	string	知识库名称和说明；未设置说明时不返回 description。
data.status	string	知识库状态。
data.source_type	string	知识库来源类型。
data.catalog_asset_refs	array of object	关联的 Catalog 资产；未设置时不返回。成员说明见关联资产字段。
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	资源版本，创建时为 1。
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。
409	4（ALREADY_EXISTS）	当前工作区中已存在相同知识库 ID。建议：使用新的 ID，或改为查询和更新已有知识库。
503	15（UNAVAILABLE）	知识库服务暂不可用。建议：稍后重试。

后续操作

保存 data.id，再调用查询知识库详情确认元数据。

最后更新于 2026 年 9 月 11 日