知识检索与问答

检索与问答协议

知识开放接口分为轻量检索、结构化检索和知识问答。问答使用知识库配置的对话模型，调用方将本轮检索结果传入问答请求，供回答及出处回放使用。

一、接口列表

接口	返回内容
POST /v1/rag/lite-search	合并后的检索文本
POST /v1/rag/search	命中片段、来源与评分
POST /v1/rag/chat	基于所传资料组织的模型回答

使用超级密钥，或覆盖目标知识库的资源密钥。知识库需开启 API，目标库的归属、租户与开放状态都会校验。

二、结构化检索

curl "$AI_API_BASE/v1/rag/search" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "knowledgeIds":["<知识库主键>"],
    "text":"服务受理时间是什么？",
    "maxResults":5,
    "minSimilarity":0.7
  }'

knowledgeIds 支持多个库，密钥必须覆盖所有目标。多库结果合并后统一排序，再按 maxResults 截取。

请求字段	类型	说明
knowledgeIds	string[]	目标知识库主键列表，显式传入需要检索的库
text	string	本轮检索问题
maxResults	integer	最大返回条数，未传或不大于 0 时取 5
minSimilarity	number	最低向量相似度，0–1，未传或不大于 0 时取 0.7；只作用于向量召回，不按重排分过滤
rerank	boolean	是否重排。false 关闭重排；未传或为 true 时跟随知识库配置
rerankModel	string	重排模型的模型标识（用途为重排），未传时取知识库配置的重排模型

重排模型的确定顺序：rerank 为 false 时不重排；传入 rerankModel 时使用该模型；否则按 knowledgeIds 顺序取第一个配置了重排模型的知识库，均未配置时不重排。重排时服务端先放大向量召回的候选数，再按相关性重新排序，规则见 知识处理与检索引擎。

命中内容在统一响应的 data 列表中，每条包括：

响应字段	类型	说明
knowledgeId、documentId、segmentId	string	来源标识
embeddingId	string	向量标识
text、auxText	string	命中正文与分段补充内容
fileName、fileUrl	string	来源文件
score	number	最终排序分：经过重排时为重排相关性，未重排时为向量相似度
vectorScore	number	向量相似度
rerankScore	number	重排相关性；未重排时为 -1
recallRank	integer	重排前在候选池中的向量名次，从 1 开始；未重排时为 -1
metadata	object	检索元数据

rerankScore 与 recallRank 未重排时为空值，按平台的空值序列化配置 blade.jackson.null-to-empty 输出为 -1。以 recallRank 大于 0 判断本次结果经过了重排；重排调用失败时，结果按向量相似度返回，这两个字段同样为 -1。

以下为经过重排的返回示例，其中主键、文本和评分为协议示例：

{
  "code": 200,
  "success": true,
  "data": [{
    "knowledgeId": "<知识库主键>",
    "documentId": "<文档主键>",
    "segmentId": "<分段主键>",
    "embeddingId": "<向量标识>",
    "fileName": "DOCS_青禾服务说明.md",
    "text": "青禾在线客服的服务时间为工作日 09:00—18:00。",
    "auxText": "二、服务时间",
    "score": 0.93,
    "vectorScore": 0.86,
    "rerankScore": 0.93,
    "recallRank": 3,
    "metadata": {}
  }],
  "msg": "操作成功"
}

结果还可包含 fileUrl。问答的 sources 只提交该接口声明的出处字段。lite-search 接收相同的请求字段并按相同规则检索与重排，将合并文本放在统一响应的 data 字符串中。

调整召回

先检查资料是否完成向量化，再调整数量和相似度。没有命中时，优先核对问题措辞与资料内容，补齐资料后再检索。对比重排效果时，以 rerank: false 再检索一次，对照两次结果的顺序。

资料上传、预览与摄取属于管理端接口，不在开放接口范围内；其解析方式参数 ocr 见 知识处理与检索引擎 的视觉识别一节。

三、知识问答

POST /v1/rag/chat 使用以下请求结构：

{
  "knowledgeId":"<知识库主键>",
  "messages":[{"role":"user","content":"服务受理时间是什么？"}],
  "sources":[
    {
      "knowledgeId":"<检索返回值>",
      "documentId":"<检索返回值>",
      "segmentId":"<检索返回值>",
      "fileName":"<检索返回值>",
      "text":"<检索返回的原始片段>",
      "score":0.93
    }
  ],
  "stream":true
}

将上一步命中项映射到 sources，score 取检索返回值。服务端组织知识助手说明，对话模型取自知识库配置，请求体不包含模型字段。

问答字段	类型	说明
knowledgeId	string	本轮问答使用的知识库
messages	array	当前消息，结构沿用对话消息模型
sources	object[]	检索命中：知识库、文档、分段、文件名、正文、补充内容与评分
conversationId	string	首轮省略，续接使用返回值
conversationToken	string	随会话返回，匿名入口续接需要
memory	object	enabled 与 maxTurns，含义同模型对话
stream	boolean	true 为 SSE，其余为同步

同步返回 BladeChatResponse，流式逐帧返回相同对话协议的增量对象，见 模型对话与图像生成 与 响应协议与异常处理。

四、会话与出处

首轮读取会话标识，后续请求带上 conversationId，并为本轮问题重新提供检索结果。出处链接到本轮返回的文档和分段，每轮回答只引用本轮检索结果。

操作见 命中测试与知识问答。