文档首页/ 智能体平台 Versatile/ API参考/ API/ 知识库/ 知识库检索
更新时间：2025-11-24 GMT+08:00
在线调试
CLI示例
查看PDF
分享

知识库检索

功能介绍

提供多知识库并行检索能力，支持语义、关键词、混合及FAQ四种检索模式，并允许自定义相似度阈值与返回结果数量，实现精准高效的信息匹配。

适用场景：

  • 同时从多个知识库或文档集合中搜索相关内容。

  • 在预设的问答列表中快速定位最相关的答案（FAQ检索）。

  • 通过混合模式或调整阈值，兼顾搜索结果的准确性和全面性。

URI

POST /v2/{project_id}/knowledge-bases/retrieve

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

参数解释：

当前租户项目ID。

获取方法请参考获取项目ID。

约束限制：

不涉及。

取值范围：

由英文，数字，“-”，“_”组成，不超过64位字符。

默认取值：

不涉及。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

是

String

参数解释：

用户Token。通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表3 请求Body参数

参数

是否必选

参数类型

描述

knowledge_base_ids

是

Array of strings

参数解释：

知识库ID列表。

约束限制：

最多可同时检索3个知识库。

取值范围：

不涉及。

默认取值：

不涉及。

query

是

String

参数解释：

用户输入的问题或关键词。

约束限制：

不涉及。

取值范围：

长度 1 至 4096 字符。

默认取值：

不涉及。

search_mode

否

String

参数解释：

检索策略模式。

约束限制：

不涉及。

取值范围：

  • doc：语义检索。

  • keyword：关键词检索。

  • mix：混合检索。

  • faq：FAQ检索。

默认取值：

doc。

top_k

否

Integer

参数解释：

每个知识库最多返回的检索结果数量。

约束限制：

若传入小数，系统会默认截断小数部分。

取值范围：

1 至 100（含）。

默认取值：

10。

similarity_threshold

否

Float

参数解释：

检索结果的最低相关度得分，低于此值的片段将被过滤。

约束限制：

不涉及。

取值范围：

[0.0, 1.0]，包含两端。

默认取值：

0.5。

响应参数

状态码：200

表4 响应Body参数

参数

参数类型

描述

total

Integer

参数解释：

检索结果总数。

取值范围：

不涉及。

retrieve_result_list

Array of RetrievalResultInfo objects

参数解释：

检索结果列表。

取值范围：

不涉及。
表5 RetrievalResultInfo

参数

参数类型

描述

file_id

String

参数解释：

文件ID（或FAQ ID）。

取值范围：

不涉及。

title

String

参数解释：

文档标题（如果是FAQ，返回QUESTION）。

取值范围：

不涉及。

chunk_id

String

参数解释：

分片ID。

取值范围：

不涉及。

content

String

参数解释：

文本内容（如果是FAQ，返回ANSWER）。

取值范围：

不涉及。

similarity

Float

参数解释：

相似度。

取值范围：

[0.0, 1.0]，包含两端。

knowledge_base_id

String

参数解释：

知识库ID。

取值范围：

不涉及。

请求示例

  • 知识库检索。

    {
  "method" : "POST",
  "url" : "https://api.example.com/v2/{project_id}/knowledge-bases/retrieve",
  "headers" : {
    "Content-Type" : "application/json",
    "X-Auth-Token" : "TEST-TOKEN******"
  },
  "body" : {
    "knowledge_base_ids" : [ "bad2ef8771e6443096b528a8a7gh...." ],
    "query" : "测试检索问题。",
    "search_mode" : "DOC",
    "top_k" : 10,
    "similarity_threshold" : 0.5
  }
}

响应示例

状态码：200

知识库检索结果。

{
  "total" : 1,
  "retrieve_result_list" : [ {
    "file_id" : "687c7914cbddcc8702cb6698f6230...",
    "title" : "test",
    "chunk_id" : "840003a72d6f4325958920e52c5a9...",
    "content" : "测试检索召回内容。",
    "similarity" : 0.9785156,
    "knowledge_base_id" : "b56c5138-96e3-4630-8381-7846dfdbcdd5"
  } ]
}

状态码

状态码

描述

200

知识库检索结果。

错误码

请参见错误码。

父主题： 知识库

相关文档