# 向量查询 - SearchEntities #### 功能介绍 基于相似度匹配的查询方式，用于查找与给定查询向量相似的向量。返回指定的 Top K 个最相似的 Entity。 #### URI POST /v1/entities/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结合使用以启用分页。 **约束限制：** 与offset取值的总和应小于16384。 **取值范围：** *\[1, 16384\]* **默认取值:** 10 | | offset | 否 | Integer | **参数解释：** 在搜索结果中跳过的记录数。可以将此参数与 top_k 参数结合使用以启用分页。 **约束限制：** 与top_k取值的总和应小于16384。 **取值范围：** 大于等于0 **默认取值：** 0 | | filter | 否 | String | **参数解释：** 用于过滤匹配entity的标量过滤条件。可以将此设置为空字符串以跳过标量过滤。 **约束限制：** 要构建标量过滤条件，请参阅filter表达式规则。 **取值范围：** 不涉及。 **默认取值：** 空字符串，不进行标量过滤。 | | vector | 是 | Array of floats | **参数解释：** 要搜索的向量字段数据。 **约束限制：** 与collection field schema中定义的对应向量字段的类型和维度一致。 **取值范围：** 不涉及。 **默认取值:** 不涉及。 | | vector_field | 是 | String | **参数解释：** 要搜索的向量字段名称。 **约束限制：** 必须是collection field schema中存在的向量字段名称。 **取值范围：** 不涉及。 **默认取值:** 不涉及。 | | params | 否 | Map\ | **参数解释：** 额外的搜索参数配置。 可以配置的参数： - ef: 每个查询的邻居候选集大小。候选集越大，搜索的精度越高，但是搜索时间也会随之增加。（仅对HNSW索引类型生效） - search_list: 候选列表的大小，越大召回率越高，但性能会下降。（仅对HANNS索引类型生效） - radius：向量相似度范围查询的外圈半径，若指定则进行相似度范围查询。 - range_filter: 向量相似度范围查询的内圈半径，向量相似度查询将过滤与查询相似度或距离在radius和range_filter参数范围内的所有向量。仅当指定radius时，该参数才生效，进行相似度范围查询时，建议根据metric_type指定该参数。 对于距离metric，如L2，范围搜索将搜索距离在\[range_filter, radius)范围内的向量，如果range_filter未指定则搜索距离在\[0, radius)范围内的向量。 对于相似度metric，如IP和COSINE，范围搜索将搜索相似度在(radius, range_filter\]范围内的向量，如果range_filter未指定则分别搜索相似度在(radius, +∞\]和(radius, 1.0\]范围内的向量。 **约束限制：** 不涉及。 **取值范围：** ef: \[top_k + offset, int32_max\] search_list: \[top_k + offset, int32_max\] **默认取值:** ef: top_k + offset search_list: topk_k + offset | #### 响应参数 **状态码：200** 表2响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | code | String | **参数解释：** 返回码。参见错误码章节。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值:** 不涉及。 | | message | String | **参数解释：** 描述信息 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值:** 不涉及。 | | data | [entities_data] object | **参数解释：** 响应数据。 **约束限制：** 不涉及。 | 表3entities_data | 参数 | 参数类型 | 描述 | |:---|:---|:---| | entities | Array of [entity] objects | **参数解释：** 查询到的信息。 **约束限制：** 不涉及。 | 表4entity | 参数 | 参数类型 | 描述 | |:---|:---|:---| | {自定义key} | Map\ | **参数解释：** collection中的一个基本结构化数据实体，包含向量和标量等字段数据。 **约束限制：** 必须满足目标collection field schema。 **取值范围：** 不涉及。 **默认取值:** 不涉及。 | **状态码：400** 表5响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | code | String | **参数解释：** 返回码。参见错误码章节。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值:** 不涉及。 | | message | String | **参数解释：** 描述信息。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值:** 不涉及。 | #### 请求示例 ``` /v1/entities/search { "store_name" : "test-storename", "collection_name" : "test-collection", "output_fields" : [ "vector", "scalar" ], "filter" : "pk > 0", "vector" : [ 0.3123, 0.43, 0.213 ], "vector_field" : "vector", "top_k" : 2, "offset" : 0, "params" : { "search_list" : 200 } } ``` #### 响应示例 **状态码：200** 搜索成功 ``` { "code" : "LMS.00000000", "data" : { "entities" : [ { "distance" : 0.049599655, "id" : 1, "scalar" : "文档1", "vector" : [ 0.324, 0.21, 0.2456 ] }, { "distance" : 0.049599655, "id" : 3, "scalar" : "文档3", "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)。