知识库管理

知识库是文件、文本和 QA 的归属容器。先创建或选择知识库，保存业务 code，再执行文件与文本导入、QA 管理或知识检索。

本页使用平台 API Key，读请求要求 knowledge_container=READ，写请求要求 WRITE；资源访问还受当前身份权限约束。所有示例在可信服务端执行。

资源与响应约定

数字 id 用于按主键更新/删除；code 用于文件请求的 containerId。
创建、详情、统计返回 KnowledgeContainer；列表的 data[] 使用同一模型。
创建成功不表示已存在可检索内容；还需导入资源并完成处理。
不把“删除知识库”用于验证连通性，删除会影响其关联知识资源。

创建知识库

POST /openapi/paas/v1/knowledge/container/add

创建顶级知识库，业务编码由系统生成。

权限：knowledge_container=WRITE。

请求参数

参数	JSON/表单类型	必填	说明
`name`	string	是	非空知识库名称
`category`	string	是	知识库类别，通用文档使用 COMMON；其他类型按已开通能力使用
`description`	string	否	描述
`tag`	array[string]	否	标签，最多 10 项，每项最长 20 字符
`classifyCode`	string	否	分类 code，默认 0

请求示例

curl --request POST "${BASE_URL}/openapi/paas/v1/knowledge/container/add" \
  --header "Authorization: Bearer ${AIS_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "产品知识库",
  "category": "COMMON",
  "description": "产品资料",
  "tag": [
    "产品"
  ],
  "classifyCode": "0"
}'

响应字段

顶层使用普通响应。

字段	JSON 类型	说明
`data`	object	字段完整定义见响应数据字典；示例只保留业务所需字段
`data.id`	integer	知识库主键，按 id 更新/删除时使用
`data.code`	string	知识库业务编码，文件与检索请求使用
`data.name`	string	知识库名称
`data.type`	string	容器类别，保留实际返回大小写
`data.tag`	array[string] / null	标签集合，无标签可为空
`data.totalSize`	integer / null	统计容量，字节；非统计场景可能未填充

响应示例

{
  "code": 8200,
  "message": "SUCCESS",
  "data": {
    "id": 101,
    "code": "partner_kb_001",
    "name": "产品知识库",
    "category": "COMMON",
    "type": "knowledge",
    "parentCode": "0",
    "tag": [
      "产品"
    ],
    "description": "产品资料"
  }
}

此简化接口不接受外部 code。需要保留外部编码时使用渠道初始化。保存 data.code，不从名称推导编码。

分页查询知识库

GET /openapi/paas/v1/knowledge/container/list

查询当前身份可访问的知识库。Query 参数均可选，首次接入可只传分页。

权限：knowledge_container=READ。

请求参数

参数	JSON/表单类型	必填	说明
`pageNo`	integer	否	当前页，默认 1
`pageSize`	integer	否	每页条数，默认 10
`name`	string	否	名称模糊查询
`category`	string	否	类别，使用目标知识库实际类别值
`type`	string	否	容器类型，知识库/目录，按实际返回值填写
`parentCode`	string	否	父编码
`tag`	array[string]	否	标签集合，可重复同名 Query 参数传入
`classifyCode`	string	否	分类编码
`sortField`	string	否	createTime、modifierTime、name
`sortOrder`	string	否	asc、desc

请求示例

curl --get --request GET "${BASE_URL}/openapi/paas/v1/knowledge/container/list" \
  --header "Authorization: Bearer ${AIS_API_KEY}" \
  --data-urlencode "pageNo=1" \
  --data-urlencode "pageSize=10"

响应字段

顶层使用分页响应。

字段	JSON 类型	说明
`data`	array[object]	字段完整定义见响应数据字典；示例只保留业务所需字段
`data[].id`	integer	知识库主键，按 id 更新/删除时使用
`data[].code`	string	知识库业务编码，文件与检索请求使用
`data[].name`	string	知识库名称
`data[].type`	string	容器类别，保留实际返回大小写
`data[].tag`	array[string] / null	标签集合，无标签可为空
`data[].totalSize`	integer / null	统计容量，字节；非统计场景可能未填充

响应示例

{
  "code": 8200,
  "message": "SUCCESS",
  "pageNo": 1,
  "pageSize": 10,
  "total": 1,
  "totalPage": 1,
  "data": [
    {
      "id": 101,
      "code": "partner_kb_001",
      "name": "产品知识库",
      "category": "COMMON",
      "type": "knowledge",
      "parentCode": "0",
      "tag": [
        "产品"
      ],
      "description": "产品资料"
    }
  ]
}

返回空数组是正常无匹配结果，不自动创建知识库。请求模型中的其他内部场景字段不作为本页推荐的筛选协议。

按主键查询知识库

GET /openapi/paas/v1/knowledge/container/queryById

读取一个知识库详情，不返回文件列表。

权限：knowledge_container=READ。

请求参数

参数	JSON/表单类型	必填	说明
`id`	integer	是	知识库数字主键

请求示例

curl --get --request GET "${BASE_URL}/openapi/paas/v1/knowledge/container/queryById" \
  --header "Authorization: Bearer ${AIS_API_KEY}" \
  --data-urlencode "id=101"

响应字段

顶层使用普通响应。

字段	JSON 类型	说明
`data`	object	字段完整定义见响应数据字典；示例只保留业务所需字段
`data.id`	integer	知识库主键，按 id 更新/删除时使用
`data.code`	string	知识库业务编码，文件与检索请求使用
`data.name`	string	知识库名称
`data.type`	string	容器类别，保留实际返回大小写
`data.tag`	array[string] / null	标签集合，无标签可为空
`data.totalSize`	integer / null	统计容量，字节；非统计场景可能未填充

响应示例

{
  "code": 8200,
  "message": "SUCCESS",
  "data": {
    "id": 101,
    "code": "partner_kb_001",
    "name": "产品知识库",
    "category": "COMMON",
    "type": "knowledge",
    "parentCode": "0",
    "tag": [
      "产品"
    ],
    "description": "产品资料"
  }
}

查询不到资源或权限不足时按错误处理排查；不能将无权限当成可重新创建同编码的依据。

按编码查询知识库

GET /openapi/paas/v1/knowledge/container/queryByCode

读取一个知识库详情，不返回文件列表。

权限：knowledge_container=READ。

请求参数

参数	JSON/表单类型	必填	说明
`code`	string	是	知识库 code

请求示例

curl --get --request GET "${BASE_URL}/openapi/paas/v1/knowledge/container/queryByCode" \
  --header "Authorization: Bearer ${AIS_API_KEY}" \
  --data-urlencode "code=partner_kb_001"

响应字段

顶层使用普通响应。

字段	JSON 类型	说明
`data`	object	字段完整定义见响应数据字典；示例只保留业务所需字段
`data.id`	integer	知识库主键，按 id 更新/删除时使用
`data.code`	string	知识库业务编码，文件与检索请求使用
`data.name`	string	知识库名称
`data.type`	string	容器类别，保留实际返回大小写
`data.tag`	array[string] / null	标签集合，无标签可为空
`data.totalSize`	integer / null	统计容量，字节；非统计场景可能未填充

响应示例

{
  "code": 8200,
  "message": "SUCCESS",
  "data": {
    "id": 101,
    "code": "partner_kb_001",
    "name": "产品知识库",
    "category": "COMMON",
    "type": "knowledge",
    "parentCode": "0",
    "tag": [
      "产品"
    ],
    "description": "产品资料"
  }
}

查询不到资源或权限不足时按错误处理排查；不能将无权限当成可重新创建同编码的依据。

更新知识库资料

PUT /openapi/paas/v1/knowledge/container/update

按数字主键更新知识库资料。建议先读取当前配置，再提交希望保留的完整名称、标签和分类。

权限：knowledge_container=WRITE。

请求参数

参数	JSON/表单类型	必填	说明
`id`	integer	是	知识库主键
`name`	string	是	知识库名称
`description`	string	否	描述
`tag`	array[string]	否	标签集合，最多 10 项，每项最长 20 字符
`classifyCode`	string	否	分类 code
`visibilityRange`	string	否	可见性范围
`kbKnowledgeBasePermissionReqList`	array[object]	否	完整权限条目，见数据字典；权限修改优先走专门授权流程

请求示例

curl --request PUT "${BASE_URL}/openapi/paas/v1/knowledge/container/update" \
  --header "Authorization: Bearer ${AIS_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
  "id": 101,
  "name": "产品知识库",
  "description": "更新后的产品资料",
  "tag": [
    "产品"
  ],
  "classifyCode": "0"
}'

响应字段

顶层使用普通响应。

字段	JSON 类型	说明
`data`	string	操作结果；成功时可以为空字符串，不包含新资源对象

响应示例

{
  "code": 8200,
  "message": "SUCCESS",
  "data": ""
}

该请求模型还承载解析配置与元数据扩展。不要依据响应字段自行提交未理解的配置；知识库授权请按权限查询与全量更新执行。成功 data 为结果字符串，不是更新后的对象；需要最新资料时再次查询。

按主键删除知识库

DELETE /openapi/paas/v1/knowledge/container/delete

删除指定知识库，属于破坏性操作。执行前确认目标编码、数据范围和备份。

权限：knowledge_container=WRITE。

请求参数

参数	JSON/表单类型	必填	说明
`id`	integer	是	目标知识库数字主键

请求示例

curl --get --request DELETE "${BASE_URL}/openapi/paas/v1/knowledge/container/delete" \
  --header "Authorization: Bearer ${AIS_API_KEY}" \
  --data-urlencode "id=101"

响应字段

顶层使用普通响应。

字段	JSON 类型	说明
`data`	string	操作结果；成功时可以为空字符串，不包含新资源对象

响应示例

{
  "code": 8200,
  "message": "SUCCESS",
  "data": ""
}

不支持以重复调用模拟安全重试。请求超时后先查询资源状态，确认是否已删除；不要换用另一个标识重复删除。

按编码删除知识库

DELETE /openapi/paas/v1/knowledge/container/deleteByCode

删除指定知识库，属于破坏性操作。执行前确认目标编码、数据范围和备份。

权限：knowledge_container=WRITE。

请求参数

参数	JSON/表单类型	必填	说明
`code`	string	是	目标知识库业务编码

请求示例

curl --get --request DELETE "${BASE_URL}/openapi/paas/v1/knowledge/container/deleteByCode" \
  --header "Authorization: Bearer ${AIS_API_KEY}" \
  --data-urlencode "code=partner_kb_001"

响应字段

顶层使用普通响应。

字段	JSON 类型	说明
`data`	string	操作结果；成功时可以为空字符串，不包含新资源对象

响应示例

{
  "code": 8200,
  "message": "SUCCESS",
  "data": ""
}

不支持以重复调用模拟安全重试。请求超时后先查询资源状态，确认是否已删除；不要换用另一个标识重复删除。

统计知识库容量

PUT /openapi/paas/v1/knowledge/container/statistical

触发指定知识库的容量统计，返回统计后的知识库对象。

权限：knowledge_container=READ。

请求参数

参数	JSON/表单类型	必填	说明
`id`	integer	是	知识库数字主键

请求示例

curl --request PUT "${BASE_URL}/openapi/paas/v1/knowledge/container/statistical" \
  --header "Authorization: Bearer ${AIS_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
  "id": 101
}'

响应字段

顶层使用普通响应。

字段	JSON 类型	说明
`data`	object	字段完整定义见响应数据字典；示例只保留业务所需字段
`data.id`	integer	知识库主键，按 id 更新/删除时使用
`data.code`	string	知识库业务编码，文件与检索请求使用
`data.name`	string	知识库名称
`data.type`	string	容器类别，保留实际返回大小写
`data.tag`	array[string] / null	标签集合，无标签可为空
`data.totalSize`	integer / null	统计容量，字节；非统计场景可能未填充

响应示例

{
  "code": 8200,
  "message": "SUCCESS",
  "data": {
    "id": 101,
    "code": "partner_kb_001",
    "name": "产品知识库",
    "category": "COMMON",
    "type": "knowledge",
    "parentCode": "0",
    "tag": [
      "产品"
    ],
    "description": "产品资料",
    "totalSize": 102400,
    "totalSizeDisplay": "100 KB",
    "status": 1,
    "statisticalTime": "2026-09-05T10:30:00"
  }
}

totalSize 为字节；totalSizeDisplay 为展示文本。statisticalTime 是统计时间，不是实时资源预留承诺。

分页查询知识库标签

GET /openapi/paas/v1/knowledge/container/tags

查询知识库标签及使用数量，用于筛选项展示。

权限：knowledge_container=READ。

请求参数

参数	JSON/表单类型	必填	说明
`pageNo`	integer	否	当前页，默认 1
`pageSize`	integer	否	每页条数，默认 10
`name`	string	否	标签名称筛选

请求示例

curl --get --request GET "${BASE_URL}/openapi/paas/v1/knowledge/container/tags" \
  --header "Authorization: Bearer ${AIS_API_KEY}" \
  --data-urlencode "pageNo=1" \
  --data-urlencode "pageSize=10"

响应字段

顶层使用分页响应。

字段	JSON 类型	说明
`data`	array[object]	标签分页条目
`data[].name`	string	标签名称
`data[].num`	integer	标签统计数量

响应示例

{
  "code": 8200,
  "message": "SUCCESS",
  "pageNo": 1,
  "pageSize": 10,
  "total": 1,
  "totalPage": 1,
  "data": [
    {
      "name": "产品",
      "num": 1
    }
  ]
}

标签统计不是文件分片标签。未匹配时返回空分页。

旧版章节导航

文件、QA 和分类接口已按资源拆分。以下入口保留旧版链接锚点，方便已有书签定位到新页面。

展开旧版章节对照

资源与响应约定​

创建知识库​

请求参数​

请求示例​

响应字段​

响应示例​

分页查询知识库​

请求参数​

请求示例​

响应字段​

响应示例​

按主键查询知识库​

请求参数​

请求示例​

响应字段​

响应示例​

按编码查询知识库​

请求参数​

请求示例​

响应字段​

响应示例​

更新知识库资料​

请求参数​

请求示例​

响应字段​

响应示例​

按主键删除知识库​

请求参数​

请求示例​

响应字段​

响应示例​

按编码删除知识库​

请求参数​

请求示例​

响应字段​

响应示例​

统计知识库容量​

请求参数​

请求示例​

响应字段​

响应示例​

分页查询知识库标签​

请求参数​

请求示例​

响应字段​

响应示例​

旧版章节导航​

资源与响应约定

创建知识库

请求参数

请求示例

响应字段

响应示例

分页查询知识库

请求参数

请求示例

响应字段

响应示例

按主键查询知识库

请求参数

请求示例

响应字段

响应示例

按编码查询知识库

请求参数

请求示例

响应字段

响应示例

更新知识库资料

请求参数

请求示例

响应字段

响应示例

按主键删除知识库

请求参数

请求示例

响应字段

响应示例

按编码删除知识库

请求参数

请求示例

响应字段

响应示例

统计知识库容量

请求参数

请求示例

响应字段

响应示例

分页查询知识库标签

请求参数

请求示例

响应字段

响应示例

旧版章节导航