Method 与 URL
查找与给定查询向量相似的向量:
POST https://{实例访问 IP 地址}:{实例网络端口}/document/search
。支持根据指定 id 或向量数值进行相似度检索,返回指定的 Top K 个最相似的 Document。
支持根据主键 id(Document ID)或向量数值,搭配自定义的标量字段的 Filter 表达式一并进行相似度检索。
配置 Embedding 参数,支持输入原始文本检索与输入文本相似的文档,同时,支持搭配标量字段的 Filter 表达式一并检索。
说明:
search 接口支持根据主键 id(Document ID)、向量 vector 以及文本进行检索。id、vector、文本仅需指定其中一个即可。
使用示例
如果使用腾讯云向量数据库(Tencent Cloud VectorDB)的 Embedding 功能,基于 /document/upsert 写入的原始文本,在集合 book-emb 中,使用 /document/search 接口查询与输入文本
'天下大势,分久必合,合久必分'
最相似,且满足过滤条件的 Top3 数据。因写入文本数据为高维数据,不便于显示,则设置 retrieveVector 参数为 false,检索信息不显示向量数据。curl -i -X POST \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\http://10.0.X.X:80/document/search \\-d '{"database": "db-test","collection": "book-emb","search": {"embeddingItems": ["天下大势,分久必合,合久必分"],"limit": 3,"params": {"ef": 200},"retrieveVector": false,"filter": "bookName in (\\"三国演义\\",\\"西游记\\")","outputFields": ["id","author","text","bookName"]}}'
说明:
返回 Top K 条相似度计算的结果。其中,K 为 limit 设置的数值,如果检索的数据不足 K 条,则返回实际检索的 Document 数量。
检索结果会按照与查询向量的相似程度进行排列,相似度最高的结果会排在最前面,相似度最低的结果则排在最后面。相似程度则通过 L2(欧几里得距离)、IP(内积)或 COSINE(余弦相似度)计算得出的分数来衡量,输出参数 score 表示相似性计算分数。其中,欧式距离(L2)计算所得的分数越小与搜索值越相似;而余弦相似度(COSINE)与 内积(IP) 计算所得的分数越大与搜索值越相似。
{"code": 0,"msg": "operation success","embeddingExtraInfo":{"tokenUsed":14},"documents": [[{"id": "0001","score": 0.9792741537094116,"bookName": "三国演义","author": "罗贯中","text": "话说天下大势,分久必合,合久必分。"},{"id": "0002","score": 0.7909858226776123,"bookName": "西游记","author": "吴承恩","text": "混沌未分天地乱,茫茫渺渺无人间。"}]]}
基于 /document/upsert 写入的向量数据,使用 /document/search 接口在集合 book-vector 中,查询与 id(Document ID)为0001、 0002、0003最相似,且满足过滤条件的 Top3 数据。
curl -i -X POST \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\http://10.0.X.X:80/document/search \\-d '{"database": "db-test","collection": "book-vector","search": {"documentIds": ["0001","0002","0003"],"params": {"ef": 200},"retrieveVector": true,"filter": "bookName in (\\"三国演义\\",\\"西游记\\")","limit": 3}}'
说明:
每一个查询结果都返回 TopK 条相似度计算的结果。其中,K 为 limit 设置的数值,如果检索的数据不足 K 条,则返回实际的 Document 数量。
检索结果会按照与查询向量的相似程度进行排列,相似度最高的结果会排在最前面,相似度最低的结果则排在最后面。相似程度则通过 L2(欧几里得距离)、IP(内积)或 COSINE(余弦相似度)计算得出的分数来衡量,输出参数 score 表示相似性计算分数。其中,欧式距离(L2)计算所得的分数越小与搜索值越相似;而余弦相似度(COSINE)与内积(IP) 计算所得的分数越大与搜索值越相似。
{"code": 0,"msg": "operation success","documents": [[{"id": "0001","vector": [0.21230000257492066,0.23000000417232514,0.21299999952316285],"score": 1.0000001192092896,"author": "罗贯中","bookName": "三国演义","page": 21},{"id": "0002","vector": [0.21230000257492066,0.2199999988079071,0.21299999952316285],"score": 0.9997729659080505,"bookName": "西游记","author": "吴承恩","page": 22}],[{"id": "0002","vector": [0.21230000257492066,0.2199999988079071,0.21299999952316285],"score": 1.000000238418579,"author": "吴承恩","page": 22,"bookName": "西游记"},{"id": "0001","vector": [0.21230000257492066,0.23000000417232514,0.21299999952316285],"score": 0.9997729659080505,"bookName": "三国演义","author": "罗贯中","page": 21}],[{"id": "0002","vector": [0.21230000257492066,0.2199999988079071,0.21299999952316285],"score": 0.9997580051422119,"author": "吴承恩","bookName": "西游记","page": 22},{"id": "0001","vector": [0.21230000257492066,0.23000000417232514,0.21299999952316285],"score": 0.9990617632865906,"page": 21,"bookName": "三国演义","author": "罗贯中"}]]}
基于 /document/upsert 写入的向量数据,则可使用 /document/search 接口,在集合 book-vector 中,根据指定向量以及过滤条件,查找 Top 3 个相似性结果。
curl -i -X POST \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\http://10.0.X.X:80/document/search \\-d '{"database": "db-test","collection": "book-vector","search": {"vectors": [[0.3123,0.43,0.213]],"params": {"ef": 200},"filter": "bookName in (\\"三国演义\\",\\"西游记\\")","retrieveVector": true,"limit": 3}}'
说明:
返回 Top K 条相似度计算的结果。其中,K 为 limit 设置的数值,如果检索的数据不足 K 条,则返回实际检索的 Document 数量。
检索结果会按照与查询向量的相似程度进行排列,相似度最高的结果会排在最前面,相似度最低的结果则排在最后面。相似程度则通过 L2(欧几里得距离)、IP(内积)或 COSINE(余弦相似度)计算得出的分数来衡量,输出参数 score 表示相似性计算分数。其中,欧式距离(L2)计算所得的分数越小与搜索值越相似;而余弦相似度(COSINE)与内积(IP) 计算所得的分数越大与搜索值越相似。
{"code": 0,"msg": "operation success","documents": [[{"id": "0001","vector": [0.21230000257492066,0.23000000417232514,0.21299999952316285],"score": 0.9714228510856628,"page": 21,"author": "罗贯中","bookName": "三国演义"},{"id": "0002","vector": [0.21230000257492066,0.2199999988079071,0.21299999952316285],"score": 0.9668837785720825,"bookName": "西游记","author": "吴承恩","page": 22}]]}
请求参数
参数名称 | 参数含义 | 子参数 | 是否必选 | 配置方法及要求 |
database | 指定要查询的Database 名称。 | - | 是 | |
collection | 指定要查询的Collection 名称。 | - | 是 | |
readConsistency | 设置检索数据的一致性要求。 | - | 否 | 取值如下所示: strongConsistency:强一致性。 eventualConsistency:最终一致性。 |
search |
表示查询条件。
| vectors | 否 | 指定要查询的向量列表。 数组元素数量最大为20。 vectors 与 documentIds 两个字段,只需配置其中一个即可。 |
| | documentIds | 否 | 指定待查询的文档 ID 列表。数组元素数量最大为20。 注意: vectors、documentIds、embeddingItems 三个字段,只需配置其中一个即可。这三个字段任何一个可以结合 filter 字段进行混合检索。 |
| |
embeddingItems | 否 | 输入文本信息,用于检索与该文本信息相似的数据。 类型:字符串数组。 范围:数组元素最大批量为20 。 |
| | params | 否 | 索引类型不同,检索时,所需配置的参数不同。 FLAT :无需指定参数。 HNSW 类型:需配置参数 ef,指定需要访问向量的数目。取值范围[1,32768],默认为10。 IVF 系列:需设置参数 nprobe ,指定所需查询的单位数量。取值范围[1,nlist],其中 nlist 在创建 Collection 时已设置,可通过 /collection/list 查看。 |
| | filter | 否 | 使用创建 Collection 指定的 Filter 索引的字段设置查询过滤表达式。Filter 表达式格式为 <field_name><operator><value>,多个表达式之间支持 and(与)、or(或)、not(非)关系。具体信息,请参见 混合检索。其中: <field_name>:表示要过滤的字段名。 <operator>:表示要使用的运算符。 string :匹配单个字符串值(=)、排除单个字符串值(!=)、匹配任意一个字符串值(in)、排除所有字符串值(not in)。其对应的 Value 必须使用英文双引号括起来。 uint64:大于(>)、大于等于(>=)、等于(=)、小于(<)、小于等于(<=)。例如:expired_time > 1623388524。 array:数组类型,包含数组元素之一(include)、排除数组元素之一(exclude)、全包含数组元素(include all)。例如,name include (\\"Bob\\", \\"Jack\\")。 <value>:表示要匹配的值。 示例: Filter('author="jerry"').And('page>20') |
| | retrieveVector | 否 | 标识是否需要返回检索结果的向量值。 true:需要。 false:不需要。默认为 false。 |
| |
radius
| 否 | 指定相似性检索的半径范围。每一种相似性计算方法的检索半径范围如下所示。 IP:检索结果返回满足 score>=radius 的数据,此时,radius 取值范围为 (-∞, +∞)。 COSINE:检索结果返回满足 score>=radius 的数据。此时,radius 取值范围为 [-1, 1] L2:检索结果返回满足 score<=radius 的数据。此时,radius 取值范围为 [0, +∞) 说明: 支持的索引类型为:FLAT、IVF 系列。 检索结果将限定在指定的检索半径内,并根据您设置的 'limit' 参数值来确定返回结果的数量。 |
| | limit | 是 | 指定返回最相似的 Top K 条数据的 K 的值。K 为大于0 的正整数。 |
| | outputFields | 否 | 指定需要输出的字段。若不设置,将返回所有字段。 说明: retrieveVector 和 outputFields 只要有其中一个配置输出向量字段即可输出 vector。 |
输出参数
参数名 | 参数名 | 参数含义 |
embeddingExtraInfo | tokenUsed | 使用 Embedding 功能已经消耗的 Token 数量。 |
documents | id | Document 的 ID 信息。 |
| vector | Document 的向量值。 |
| score | 表示查询向量与检索结果向量之间的相似性计算分数。 |
| text | 如果该 Collection 开启 Embedding 功能,在建表时,指定文本信息的字段名,则显示该字段。 |
| other_scalar_field | Document 其他自定义的标量字段。例如:author、bookName、page 等。 |