# 混合搜索 - HybridSearch #### 功能介绍 基于相似度匹配的查询方式，用于查找与给定多个向量进行相似性搜索，支持密集向量，稀疏向量等多路召回，并对结果进行重排处理，最终返回指定的 Top K 个最相似的 Entity。 #### URI POST /v1/entities/hybrid-search #### 请求参数 表1请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | store_name | 是 | String | **参数解释：** 知识仓实例名称，region内唯一。 **约束限制：** 长度范围为3到63个字符，支持小写字母、数字、中划线（ - ），第一个字符只能够是小写字母，中划线（ - ）不得出现在字符串末尾。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | collection_name | 是 | String | **参数解释：** collection名称，知识仓内唯一。 **约束限制：** 长度范围为1到255个字符，支持字母、数字、中划线（ - ）和下划线（ _ ），大小写敏感。第一个字符只能够是下划线（ _ ）和字母，中划线（ - ）不得出现在字符串末尾。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | output_fields | 否 | Array of strings | **参数解释：** field名称列表，配置需与搜索结果一起返回的字段。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** *\[ \]*，不返回任何额外的字段数据。 | | top_k | 否 | Integer | **参数解释：** 返回的entity个数限制。可以将此参数与offset结合使用以启用分页。 **约束限制：** 1.与offset取值的总和应小于16384。 2.当sub_search数量为1时，以sub_search中的top_k和offset为准。 **取值范围：** *\[1, 16384\]* **默认取值:** 10 | | offset | 否 | Integer | **参数解释：** 在搜索结果中跳过的记录数。可以将此参数与 top_k 参数结合使用以启用分页。 **约束限制：** 1.与top_k取值的总和应小于16384。 2.当sub_search数量为1时，以sub_search中的top_k和offset为准。 **取值范围：** 大于等于0 **默认取值：** 0 | | sub_search | 是 | Array of [sub_search] objects | **参数解释：** rerank策略。 **约束限制：** 不涉及 **取值范围：** 不涉及。 **默认取值：** 默认使用rrf算法。 | | rerank | 否 | [rerank] object | 参数解释： rerank策略。 约束限制： 不涉及 取值范围： 不涉及。 默认取值: 默认使用rrf算法。 | 表2sub_search | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | vector_field | 是 | String | **参数解释：** 要搜索的向量字段名称。 **约束限制：** 必须是collection field schema中存在的向量字段名称。 **取值范围：** 不涉及。 **默认取值:** 不涉及。 | | vector | 是 | Array of objects | **参数解释：** 要搜索的向量字段数据。 **约束限制：** 与collection field schema中定义的对应向量字段的类型和维度一致。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | top_k | 否 | Integer | **参数解释：** 返回的entity个数限制。可以将此参数与offset结合使用以启用分页。 **约束限制：** 当sub_search数量为1时，top_k与offset取值的总和应小于16384。 **取值范围：** *\[1, 16384\]* **默认取值：** 10 | | offset | 否 | Integer | **参数解释：** 在搜索结果中跳过的记录数。可以将此参数与 top_k 参数结合使用以启用分页。 **约束限制：** 1.与top_k取值的总和应小于16384。 2.当sub_search数量为1时才生效。 **取值范围：** 大于等于0 **默认取值:** 0 | | filter | 否 | String | **参数解释：** 用于过滤匹配entity的标量过滤条件。可以将此设置为空字符串以跳过标量过滤。 **约束限制：** 要构建标量过滤条件，请参阅filter表达式规则。 **取值范围：** 不涉及。 **默认取值：** 空字符串，不进行标量过滤。 | | params | 否 | Map\ | **参数解释：** 额外的搜索参数配置。 可以配置的参数： - ef: 每个查询的邻居候选集大小。候选集越大，搜索的精度越高，但是搜索时间也会随之增加。（仅对HNSW索引类型生效） - search_list: 候选列表的大小，越大召回率越高，但性能会下降。（仅对HANNS索引类型生效） - cut_off_frequency: 通过停用词出现频率决定是否作为查询结果。（仅对稀疏向量搜索生效） **约束限制：** 不涉及。 **取值范围：** 当sub_search数量为1时： ef: \[top_k + offset, int32_max\] search_list: \[top_k + offset, int32_max\] cut_off_frequency：\[0, 1.0\] 当sub_search数量大于1时： ef: \[top_k, int32_max\] search_list: \[top_k, int32_max\] cut_off_frequency：\[0, 1.0\] **默认取值:** 当sub_search数量为1时： ef: top_k + offset search_list: top_k + offset cut_off_frequency: 0 当sub_search数量大于1时： ef: top_k search_list: top_k cut_off_frequency: 0 | 表3rerank | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | strategy | 是 | String | **参数解释：** 重排序的策略名称。 **约束限制：** 不涉及 **取值范围：** *\["weighted", "rrf"\]* 默认取值: "rrf" | | params | 否 | Map\ | **参数解释：** rerank策略的算法参数。 可以设置的参数： - k：平滑值。（仅对rrf策略生效） - weights：各个向量搜索结果的权值。（仅对weighted策略生效，且当策略为weighted时该参数必填） - weights：\[0, 1\] - k：(0, 16384) - k：60 重排序的策略名称。 **约束限制：** 不涉及。 **取值范围：** **默认取值：** | #### 响应参数 **状态码：200** 表4响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | code | String | **参数解释：** 返回码。参见错误码章节。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值:** 不涉及。 | | message | String | **参数解释：** 描述信息 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值:** 不涉及。 | | data | [entities_data] object | **参数解释：** 响应数据。 **约束限制：** 不涉及。 | 表5entities_data | 参数 | 参数类型 | 描述 | |:---|:---|:---| | entities | Array of [entity] objects | **参数解释：** 查询到的信息。 **约束限制：** 不涉及。 | 表6entity | 参数 | 参数类型 | 描述 | |:---|:---|:---| | {自定义key} | Map\ | **参数解释：** collection中的一个基本结构化数据实体，包含向量和标量等字段数据。 **约束限制：** 必须满足目标collection field schema。 **取值范围：** 不涉及。 **默认取值:** 不涉及。 | **状态码：400** 表7响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | code | String | **参数解释：** 返回码。参见错误码章节。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值:** 不涉及。 | | message | String | **参数解释：** 描述信息。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值:** 不涉及。 | #### 请求示例 ``` /v1/entities/hybrid-search { "store_name" : "test-storename", "collection_name" : "test-collection-sparse", "output_fields" : [ "vector", "scalar" ], "sub_search" : [ { "vector_field" : "vector", "top_k" : 10, "vector" : [ [ 0.3123, 0.43, 0.213 ] ], "filter" : "pk > 0", "params" : { "search_list" : 100 } }, { "vector_field" : "sparse_vector", "top_k" : 10, "vector" : [ { "123" : 0.3, "234" : 0.5 } ], "filter" : "pk > 100", "params" : { "cut_off_frequency" : 1 } } ], "top_k" : 2, "offset" : 0, "rerank" : { "strategy" : "rrf", "params" : { "k" : 60 } } } ``` #### 响应示例 **状态码：200** 搜索成功 ``` { "code" : "LMS.00000000", "data" : { "entities" : [ { "distance" : 0.016393442, "id" : 3, "scalar" : "文档3", "vector" : [ 0.314, 0.251, 0.236 ] }, { "distance" : 0.016129032, "id" : 1, "scalar" : "文档1", "vector" : [ 0.324, 0.21, 0.2456 ] } ] }, "message" : "search entities success" } ``` **状态码：400** 搜索失败 ``` { "code" : "LMS.00001001", "message" : "ErrInvalidParameter : the input parameter is incorrect." } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 搜索成功 | | 400 | 搜索失败 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-dwr/ErrorCode.html)。