Appearance
知识库 API
模块说明
本页汇总知识库（Knowledge）模块的 OpenAPI 接口。
- 模块前缀：
/knowledge - 基地址请参考：快速开始
知识库以「知识库（knowledge） + 数据集（dataset） + 分段（segment）」三级组织，第三方调用方通常只关心知识检索，因此当前一期开放：发现（list / detail）+ 检索（retrieve）共三个接口。
TIP
URL 中的 :knowledge_id 为 UUID 字符串，可通过知识库列表接口获取。
接口目录
| 接口 | 方法 | 路径 | 说明 |
|---|---|---|---|
| 知识库列表 | GET | /knowledge | 列出当前 workspace 可见的全部知识库 |
| 知识库详情 | GET | /knowledge/:knowledge_id | 返回知识库元数据与默认检索配置摘要 |
| 知识检索 | POST | /knowledge/:knowledge_id/retrieve | 在指定知识库内执行召回，返回命中分段 |
请求头（公共）
| 参数名 | 必填 | 说明 |
|---|---|---|
| Authorization | 是 | 鉴权凭证，格式 Bearer sk_xxx |
统一响应格式
json
{
"code": 200,
"data": {},
"message": "",
"trace_id": "xxx"
}数据模型概念
知识库模块的资源分为三级：
| 概念 | 说明 |
|---|---|
| 知识库（knowledge） | 顶层资源，承载业务语义（如「华西医疗百科」），是检索请求的入口 |
| 数据集（dataset） | 知识库内的数据来源单元，一个文件 / 表格 / 图片包构成一个数据集 |
| 分段（segment） | 数据集切分后的最小检索单位，命中结果以分段为单位返回 |
知识库分为三种类型，影响数据集结构与分段内容语义：
type | 类型 | 说明 |
|---|---|---|
1 | 文档集 | 文本类知识库（PDF、Word、Markdown 等切分后入库） |
2 | 表格集 | 结构化数据知识库，分段内容为行级数据拼接 |
3 | 图片集 | 图片标注知识库，分段对应图片描述/标注内容，命中结果额外返回 image 字段 |
注意事项
- 当前一期仅开放只读检索类接口，知识库 / 数据集 / 分段的创建与维护需在管理控制台完成。
- 检索接口对禁用知识库返回
records=[]而非错误，便于调用方做空兜底；如需感知禁用状态请改调知识库详情。 - 知识库
type=2（表格集）与type=3（图片集）的命中分段content字段语义有差异：表格集为行内容拼接、图片集为图片描述/标注；segment_id/dataset_id字段语义保持一致。 - 图片集场景下，请优先使用
records[].image.annotation_id而非records[].segment_id作为图片业务外键：segment_id是后端分段表的内部 ID，未来可能因索引重建/段合并发生变化；annotation_id与图片实体一一对应，是稳定契约。 - 鉴权类错误（401/403）由网关直接返回，不会进入业务错误清单。详见错误处理。