# 知识库检索 - OpenBatchRetrieveKnowledgeBase #### 功能介绍 提供多知识库并行检索能力，支持语义、关键词、混合及FAQ四种检索模式，并允许自定义相似度阈值与返回结果数量，实现精准高效的信息匹配。 **适用场景**： - 同时从多个知识库或文档集合中搜索相关内容。 - 在预设的问答列表中快速定位最相关的答案（FAQ检索）。 - 通过混合模式或调整阈值，兼顾搜索结果的准确性和全面性。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-agentarts0/agentarts_07_0003.html)。 #### URI POST /v2/{project_id}/knowledge-bases/retrieve 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | project_id | 是 | String | **参数解释**： 当前租户项目ID。 获取方法请参考[获取项目ID](https://support.huaweicloud.com/api-agentarts0/agentarts_07_0018.html)。 **约束限制**： 不涉及。 **取值范围**： 由英文，数字，"-"，"_"组成，不超过64位字符。 **默认取值**： 不涉及。 | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是 | String | **参数解释**： 用户Token。 通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | Content-Type | 是 | String | **参数解释**： 发送的实体的MIME类型。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： application/json。 | 表3请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | knowledge_base_ids | 是 | Array of strings | **参数解释**： 知识库ID列表。 **约束限制**： 免费版最多可同时检索1个知识库，企业版最多同时检索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。 | | image_mask_policy | 否 | String | **参数解释**： 知识检索结果切片中，对图片标签进行处理和保留的具体方式。 **约束限制**： 该功能要求被检索的知识库本身支持返回图片信息。 **取值范围**： - RETAIN_IMAGE_ID：保留图片ID，格式：{KI\|image_id}。 - RETAIN_PLACEHOLDER：保留占位符，格式：{KI\|N}，N为序号。 - REMOVE_IMAGE：移除图片（即替换为空字符串）。 **默认取值**： REMOVE_IMAGE。 | #### 响应参数 **状态码：200** 表4响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | total | Integer | **参数解释**： 检索结果总数。 **取值范围**： 不涉及。 | | retrieve_result_list | Array of [RetrievalResultInfo] objects | **参数解释**： 检索结果列表。 **取值范围**： 不涉及。 | 表5RetrievalResultInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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。 **取值范围**： 不涉及。 | | image_ids | Array of strings | **参数解释**： 检索到的图片列表（需知识库支持），与content中的图片占位符{KI\|N}保持一一对应关系，N为图片索引值，从0开始。 **取值范围**： 不涉及。 说明： 图片的有效期为7天。 | #### 请求示例 - 知识库检索。 ``` { "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, "image_mask_policy" : "RETAIN_PLACEHOLDER" } } ``` #### 响应示例 **状态码：200** 知识库检索结果。 ``` { "total" : 1, "retrieve_result_list" : [ { "file_id" : "687c7914cbddcc8702cb6698f6230...", "title" : "test", "chunk_id" : "840003a72d6f4325958920e52c5a9...", "content" : "测试检索召回内容，测试图片{KI|1}，测试图片{KI|2}。", "similarity" : 0.9785156, "knowledge_base_id" : "bad2ef8771e6443096b528a8a7gh....", "image_ids" : [ "df7d169bd3d111f0b3f9fa163e5ce...", "eab3e004d3d111f0b3f9fa163e5ce..." ] } ] } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 知识库检索结果。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-agentarts0/ErrorCode.html)。