接口定义
基于相似度匹配的查询方式,search() 接口据输入的 1 到 N 向量数据,查找存储在数据库中的相似性向量,返回指定的 Top K 个最相似的文档。
def search(self,database_name: str,collection_name: str,vectors: Union[List[List[float]], ndarray],filter: Union[Filter, str] = None,params=None,retrieve_vector: bool = False,limit: int = 10,output_fields: Optional[List[str]] = None,timeout: Optional[float] = None,) -> List[List[Dict]]
使用示例
import tcvectordbfrom tcvectordb.model.document import Document, Filter, SearchParams# search topn similary documents with filter# vectors 指定了检索的向量数据# filter 指定了过滤条件# params 指定索引类型对应的查询参数,HNSW 类型需要设置 ef,指定查询的遍历范围;IVF 系列需要设置 nprobe,指定查询的单位数量# retrieve_vector 指定是否输出向量字段# limit 指定返回最相似的 Top K 条结果。如果插入的数据不足 K 条,则返回实际插入的 Document 数量。# output_fields 指定输出字段doc_lists = client.search(database_name='db-test',collection_name='book-vector',vectors=[[0.3123, 0.43, 0.213],[0.315, 0.4, 0.216],[0.40, 0.38, 0.26]],# filter=Filter(Filter.In("bookName",["三国演义", "西游记"])).And(Filter.Include("tags",["曹操", "孙悟空"])),filter='bookName in ("三国演义","西游记") and (tags include ("曹操","孙悟空"))',params=SearchParams(ef=200),retrieve_vector=True,limit=3,output_fields=['bookName','author'])for i, docs in enumerate(doc_lists):print(i)for doc in docs:print(doc)
入参描述
参数名 | 是否必选 | 参数含义 | 配置方法 |
database_name | 是 | 指定检索的数据库名。 | Database 命名要求如下: 只能使用英文字母,数字,下划线_、中划线-,并以英文字母开头。 长度要求:[1,128]。 |
collection_name | 是 | 指定检索的集合名 | Collection 命名要求如下: 只能使用英文字母,数字,下划线_、中划线-,并以英文字母开头。 长度要求:[1,128]。 |
vectors | 是 | 表示要查询的向量列表。 | 数组元素数量最大为20,即每次最多允许传入20个向量。相似性检索返回每一个向量的 Top K 个相似数据。 |
filter | 否 | 设置查询过滤条件。 | Filter 的表达式格式为 '<field_name><operator><value>',多个表达式之间支持 and(与)、or(或)、not(非)关系。具体信息,请参见 Filter 条件表达式。其中 <field_name>:表示要过滤的字段名。 <operator>:表示要使用的运算符。 string :匹配单个字符串值(=)、匹配任意一个字符串值(in)、排除所有字符串值(not in)。其对应的 Value 必须使用英文双引号括起来。 unit64:大于(>)、大于等于(>=)、等于(=)、小于(<)、小于等于(<=)。例如:expired_time > 1623388524。 array:数组类型,包含数组元素之一(include)、排除数组元素之一(exclude)、全包含数组元素(include all)。例如,name include (\\"Bob\\", \\"Jack\\")。 <value>:表示要匹配的值。 示例: Filter('author="jerry"').And('page>20')。 |
params | 否 | 指定索引查询参数。 | 索引类型不同,检索时,所需配置的参数不同。 FLAT :无需指定参数。 HNSW 类型:需配置参数 ef,指定需要访问向量的数目。取值范围[1,32768],默认为10。 IVF 系列:需设置参数 nprobe ,指定所需查询的单位数量。取值范围[1,nlist],其中 nlist 在创建 Collection 时已设置,可通过 list_collections() 查看。 |
retrieve_vector | 否 | 标识是否需要返回向量值。 | 取值如下所示: True:需要。 False:不需要。默认为 False。 |
limit | 是 | 指定返回最相似的 Top K 的 K 的值。 | 如果插入的数据不足 K 条,则返回实际插入的 Document 数量。 |
output_fields | 否 | 配置需返回的字段。 | 以数组形式配置需返回的字段。若不配置,返回所有字段。 说明: output_fields 与 retrieve_vector 参数均可以配置是否输出向量值,二者任意一个配置需输出向量字段,则将输出向量字段。 |
timeout | 否 | 请求超时时间。 | 单位:秒。 默认值:VectorDBClient() 接口配置的 timeout 时长。 取值范围大于等于0。 |
出参描述
检索结果,如下所示。
说明:
输出结果的顺序,与搜索时设置的 vectors 配置的向量值的顺序一致。如下示例,0下面的三行结果对应
[0.3123, 0.43, 0.213]
向量的相似度查询结果。1下面的三行结果对应[0.315, 0.4, 0.216]
的查询结果。每一个查询结果都返回 TopK 条相似度计算的结果。其中,K 为 limit 设置的数值,如果插入的数据不足 K 条,则返回实际插入的 Document 数量。
检索结果会按照与查询向量的相似程度进行排列,相似度最高的结果会排在最前面,相似度最低的结果则排在最后面。相似程度则通过 L2(欧几里得距离)、IP(内积)或 COSINE(余弦相似度)计算得出的分数来衡量,输出参数 score 表示相似性计算分数。其中,欧式距离(L2)计算所得的分数越小与搜索值越相似;而余弦相似度(COSINE)与内积(IP) 计算所得的分数越大与搜索值越相似。
0{'id': '0001', 'score': 0.9714228510856628, 'vector': [0.21230000257492065, 0.23000000417232513, 0.21299999952316284], 'sparse_vector': [[2, 0.9599999785423279], [5, 0.5299999713897705], [100, 0.4429999887943268]], 'author': '罗贯中', 'bookName': '三国演义'}{'id': '0002', 'score': 0.9668837785720825, 'vector': [0.21230000257492065, 0.2199999988079071, 0.21299999952316284], 'sparse_vector': [[2, 0.9700000286102295], [5, 0.5400000214576721], [100, 0.4440000057220459]], 'author': '吴承恩', 'bookName': '西游记'}1{'id': '0001', 'score': 0.9784632325172424, 'vector': [0.21230000257492065, 0.23000000417232513, 0.21299999952316284], 'sparse_vector': [[2, 0.9599999785423279], [5, 0.5299999713897705], [100, 0.4429999887943268]], 'author': '罗贯中', 'bookName': '三国演义'}{'id': '0002', 'score': 0.9747834205627441, 'vector': [0.21230000257492065, 0.2199999988079071, 0.21299999952316284], 'sparse_vector': [[2, 0.9700000286102295], [5, 0.5400000214576721], [100, 0.4440000057220459]], 'author': '吴承恩', 'bookName': '西游记'}2{'id': '0001', 'score': 0.9860693216323853, 'vector': [0.21230000257492065, 0.23000000417232513, 0.21299999952316284], 'sparse_vector': [[2, 0.9599999785423279], [5, 0.5299999713897705], [100, 0.4429999887943268]], 'author': '罗贯中', 'bookName': '三国演义'}{'id': '0002', 'score': 0.9852011203765869, 'vector': [0.21230000257492065, 0.2199999988079071, 0.21299999952316284], 'sparse_vector': [[2, 0.9700000286102295], [5, 0.5400000214576721], [100, 0.4440000057220459]], 'author': '吴承恩', 'bookName': '西游记'}
参数名 | 参数含义 |
id | Document 的 ID 信息。 |
vector | Document 的向量值。 |
score | 表示查询向量与检索结果向量之间的相似性计算分数。 |
author、page、section | Document 其他自定义的标量字段。 |