知识检索

接口说明

在指定知识库内基于自然语言执行召回，阻塞返回命中分段。命中策略遵循该知识库自身保存的检索配置（混合 / 向量 / 全文），同时允许通过 retrieval_model 临时覆盖 top_k 与 score_threshold。

接口路径：POST /v1/openapi/knowledge/:knowledge_id/retrieve

TIP

本接口仅支持阻塞模式，无 SSE。
当目标知识库 status=0（禁用）时，接口返回 code=200 且 records=[]，不会报错，便于调用方做兜底。

请求头

参数名	必填	说明
Content-Type	是	`application/json`
Authorization	是	鉴权凭证，格式 `Bearer sk_xxx`

请求参数

路径参数

参数	类型	必填	说明
`knowledge_id`	string	是	知识库 ID（UUID），可通过知识库列表获取

请求体

json

{
  "query": "高血压患者能不能吃布洛芬?",
  "retrieval_model": {
    "top_k": 3,
    "score_threshold_enabled": true,
    "score_threshold": 0.6
  }
}

字段	类型	必填	说明
`query`	string	是	检索语句，去首尾空格后不能为空
`retrieval_model`	object	否	临时覆盖检索参数；为空时使用知识库默认配置
`retrieval_model.top_k`	int	否	命中条数（1-10）；为 `0` 或不传视为未设置
`retrieval_model.score_threshold_enabled`	bool	否	是否启用分数阈值；为 `false` 时即便传 `score_threshold` 也不下发覆盖
`retrieval_model.score_threshold`	float	否	分数阈值（0-1）

WARNING

全文检索（retriever_type=3）原生不支持 score 阈值，传入 score_threshold 字段会被忽略。

成功响应示例

json

{
  "code": 200,
  "data": {
    "knowledge_id": "1368b2d9-60ff-48fc-9f14-0c39711896ef",
    "query": "高血压患者能不能吃布洛芬?",
    "records": [
      {
        "segment_id": "9b0b3f50-7e38-46cd-9b22-0f1e8c5ae131",
        "dataset_id": "55d4ab92-3c25-4f2b-b1d8-7c8b2c5fb501",
        "content": "布洛芬属于非甾体抗炎药 (NSAIDs)。长期或大剂量使用可能升高血压、加重水钠潴留，高血压患者应在医师指导下使用……",
        "keywords": ["布洛芬", "高血压", "非甾体抗炎药"],
        "length": 412,
        "score": 0.873
      },
      {
        "segment_id": "f1c5e8a6-1a23-4b32-9f3c-2e6c1aa9b740",
        "dataset_id": "55d4ab92-3c25-4f2b-b1d8-7c8b2c5fb501",
        "content": "高血压患者用药须知：避免使用可能导致血压升高的药物，如部分 NSAIDs、糖皮质激素……",
        "keywords": ["高血压", "用药禁忌"],
        "length": 287,
        "score": 0.812
      }
    ]
  },
  "message": "success",
  "trace_id": "1c2b23f18c73fc0540423f0c2923a654"
}

成功响应示例（图片集，含 `image` 字段）

json

{
  "code": 200,
  "data": {
    "knowledge_id": "1368b2d9-60ff-48fc-9f14-0c39711896ef",
    "query": "红烧肉",
    "records": [
      {
        "segment_id": "019e15a1-6bd9-7494-95b5-4d0afe5c5231",
        "dataset_id": "019e149b-0ca0-755a-a8aa-fb98f938c56f",
        "content": "这是一盘表面着红亮酱汁、撒有葱花的红烧肉。\n红烧肉.png\n[\"红烧肉\",\"葱花\"]",
        "keywords": ["红烧肉", "葱花"],
        "length": 42,
        "score": 0.473,
        "image": {
          "annotation_id": "019e15a1-6baa-78dc-af60-c6ac37ccd377",
          "file_id": "019e15a1-2e2b-7f10-b9a2-72b03c011a1d",
          "file_name": "红烧肉.png",
          "file_path": "https://oss.example.com/dataset/red-pork.png"
        }
      }
    ]
  },
  "message": "success",
  "trace_id": "1c2b23f18c73fc0540423f0c2923a654"
}

data 字段说明

字段	类型	说明
`knowledge_id`	string	实际检索的知识库 ID
`query`	string	实际生效的查询文本（去首尾空格后）
`records`	array	命中分段列表，按 `score` 由高到低
`records[].segment_id`	string	分段 ID。图片集场景下属于内部 ID，建议改用 `records[].image.annotation_id` 作为稳定外键
`records[].dataset_id`	string	该分段所属的数据集 ID
`records[].content`	string	分段文本内容（图片集对应图片描述/标注内容）
`records[].keywords`	`array<string>`	分段关键词
`records[].length`	int	内容字符数
`records[].score`	float	命中得分（0-1）
`records[].image`	object	仅图片集命中时返回；非图片集为 `null`（字段会被省略）
`records[].image.annotation_id`	string	图片标注 ID（推荐作为图片业务外键）
`records[].image.file_id`	string	图片文件 ID
`records[].image.file_name`	string	图片文件名
`records[].image.file_path`	string	图片访问路径（对象存储 / 公网 URL）

失败响应示例

json

{
  "code": 0,
  "data": null,
  "message": "query 不能为空",
  "trace_id": "e3302bb5788035dec7160e58d2261824"
}

业务错误清单

message（示例）	触发条件	处理建议
`缺少工作空间标识（请通过网关访问）`	请求绕过网关直连 app 层时的兜底文案；正常通过网关访问不会出现	通过网关地址访问并携带 `Authorization`，由网关注入工作空间上下文；参见认证与鉴权
`知识库ID格式错误`	URL 中 `:knowledge_id` 不是合法 UUID	通过知识库列表接口确认 ID
`知识库不存在`	`knowledge_id` 不存在或不属于当前 workspace	通过知识库列表接口确认 ID 与归属
`query 不能为空`	检索接口 `query` 字段为空 / 全空白字符	传入有效 query
`top_k 取值范围 1-10`	`retrieval_model.top_k > 10`	调整为 1-10 之间
`score_threshold 取值范围 0-1`	`retrieval_model.score_threshold` 不在 0-1 区间	调整为 0-1 之间

WARNING

鉴权类错误（401/403）由网关直接返回，不会进入本错误清单。详见错误处理。

调用示例

知识检索（使用知识库默认检索配置）

bash

curl -X POST 'https://runtime-api.invalid/v1/openapi/knowledge/1368b2d9-60ff-48fc-9f14-0c39711896ef/retrieve' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_your_api_key' \
  -d '{
    "query": "高血压患者能不能吃布洛芬?"
  }'

知识检索（覆盖 top_k 与 score 阈值）

bash

curl -X POST 'https://runtime-api.invalid/v1/openapi/knowledge/1368b2d9-60ff-48fc-9f14-0c39711896ef/retrieve' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_your_api_key' \
  -d '{
    "query": "高血压患者能不能吃布洛芬?",
    "retrieval_model": {
      "top_k": 3,
      "score_threshold_enabled": true,
      "score_threshold": 0.6
    }
  }'

注意事项

当目标知识库 status=0（禁用）时，接口返回空 records 而非错误。如需感知禁用状态，请改调知识库详情。
全文检索（retriever_type=3）原生不支持 score 阈值，传入 score_threshold 字段会被忽略。
知识库 type=2（表格集）与 type=3（图片集）的命中分段 content 字段语义存在差异：表格集为行内容拼接、图片集为图片描述/标注；segment_id / dataset_id 字段语义保持一致。
图片集场景下，请优先使用 records[].image.annotation_id 而非 records[].segment_id 作为图片业务外键：segment_id 是后端分段表的内部 ID，未来可能因索引重建/段合并发生变化；annotation_id 与图片实体一一对应，是稳定契约。

知识检索 ​

接口说明 ​

请求头 ​

请求参数 ​

路径参数 ​

请求体 ​

成功响应示例 ​

成功响应示例（图片集，含 image 字段） ​

data 字段说明 ​

失败响应示例 ​

业务错误清单 ​

调用示例 ​

知识检索（使用知识库默认检索配置） ​

知识检索（覆盖 top_k 与 score 阈值） ​

注意事项 ​

知识检索

接口说明

请求头

请求参数

路径参数

请求体

成功响应示例

成功响应示例（图片集，含 `image` 字段）

data 字段说明

失败响应示例

业务错误清单

调用示例

知识检索（使用知识库默认检索配置）

知识检索（覆盖 top_k 与 score 阈值）

注意事项