文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>向量数据库>SDK 参考>Python SDK>Document 操作>基于向量数据相似度检索

基于向量数据相似度检索

最近更新时间：2025-07-30 12:07:52

我的收藏

本页目录：

接口定义

基于相似度匹配的查询方式，search() 接口据输入的1到 N 向量数据，查找存储在数据库中的相似性向量，返回指定的 Top K 个最相似的文档。
def search(
    vectors: List[List[float]] | Any,
    filter: Filter | str = None,
    params: Any | None = None,
    retrieve_vector: bool = False,
    limit: int = 10,
    output_fields: List[str] | None = None,
    timeout: float | None = None,
    return_pd_object: bool = False,
    radius: float | None = None
) -> List[List[Dict | Document]]

使用示例

基于向量数据相似性检索
二进制向量数据相似性检索
Json 类型数据相似性检索
import tcvectordb
from 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)
输出信息，如下所示。
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': '西游记'}
import tcvectordb
from 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='bin-vector',
            # vectors=[binary_to_uint8([0, 0, 0, 0, 0, 0, 0, 0,  1, 1, 0, 1, 1, 1, 0, 1])],
            vectors=[[12, 21],[12, 30]],
            retrieve_vector=True,
            limit=3,
            output_fields=['bookName']
        )        
for i, docs in enumerate(doc_lists):
    print(i)
    for doc in docs:
       print(doc)
输出信息，如下所示。 
0
{'id': '0001', 'score': 8.0, 'vector': [229.0, 0.0], 'bookName': '西游记'}
{'id': '0002', 'score': 8.0, 'vector': [203.0, 0.0], 'bookName': '西游记'}
{'id': '0003', 'score': 8.0, 'vector': [16.0, 210.0], 'bookName': '三国演义'}
1
{'id': '0003', 'score': 7.0, 'vector': [16.0, 210.0], 'bookName': '三国演义'}
{'id': '0001', 'score': 9.0, 'vector': [229.0, 0.0], 'bookName': '西游记'}
{'id': '0002', 'score': 9.0, 'vector': [203.0, 0.0], 'bookName': '西游记'}
import tcvectordb
from 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='coll-json-autoid',
            vectors=[[0.3123],[0.315],[0.40]],
            filter='bookInfo.bookName in ("三国演义","西游记")',
            params=SearchParams(ef=200),
            retrieve_vector=True,
            limit=3,
            output_fields=['bookInfo','id']
        )        
for i, docs in enumerate(doc_lists):
    print(i)
    for doc in docs:
       print(doc)
检索结果，如下所示。
0
{'id': 'E3AB9477-670E-3025-B9BE-189A8DBF3944', 'vector': [0.4000000059604645], 'score': 0.12492, 'bookInfo': {'bookName': '三国演义', 'author': '罗贯中'}}
{'id': 'D7678BA3-6485-EAC4-59FD-B4AC3D5D033A', 'vector': [0.30000001192092896], 'score': 0.09369, 'bookInfo': {'bookName': '西游记', 'author': '吴承恩'}}
{'id': '23D97B7E-411F-3BEC-4D91-0732FD8710D1', 'vector': [0.30000001192092896], 'score': 0.09369, 'bookInfo': {'bookName': '西游记', 'author': '吴承恩'}}
1
{'id': 'E3AB9477-670E-3025-B9BE-189A8DBF3944', 'vector': [0.4000000059604645], 'score': 0.126, 'bookInfo': {'bookName': '三国演义', 'author': '罗贯中'}}
{'id': 'D7678BA3-6485-EAC4-59FD-B4AC3D5D033A', 'vector': [0.30000001192092896], 'score': 0.0945, 'bookInfo': {'bookName': '西游记', 'author': '吴承恩'}}
{'id': '23D97B7E-411F-3BEC-4D91-0732FD8710D1', 'vector': [0.30000001192092896], 'score': 0.0945, 'bookInfo': {'bookName': '西游记', 'author': '吴承恩'}}
2
{'id': 'E3AB9477-670E-3025-B9BE-189A8DBF3944', 'vector': [0.4000000059604645], 'score': 0.16, 'bookInfo': {'bookName': '三国演义', 'author': '罗贯中'}}
{'id': 'D7678BA3-6485-EAC4-59FD-B4AC3D5D033A', 'vector': [0.30000001192092896], 'score': 0.12, 'bookInfo': {'bookName': '西游记', 'author': '吴承恩'}}
{'id': '23D97B7E-411F-3BEC-4D91-0732FD8710D1', 'vector': [0.30000001192092896], 'score': 0.12, 'bookInfo': {'bookName': '西游记', 'author': '吴承恩'}}

入参描述

参数名
是否必选
参数含义
配置方法
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 必须使用英文双引号括起来。
uint64：大于（>）、大于等于（>=）、等于（=）、小于（<）、小于等于（<=）、不等于（!=）。例如：expired_time > 1623388524。
array：数组类型，包含数组元素之一（include）、排除数组元素之一（exclude）、全包含数组元素（include all）。例如，name include (\\"Bob\\", \\"Jack\\")。
json：json 类型的 Filter 表达式语法和 json 字段的键值类型保持一致。若访问 Json 对象中的键，使用点（.）符号连接。例如：Json 类型的字段 bookInfo ，其键 bookName 的 Filter 表达式如下所示。更多信息，请参见Json 类型表达式。
filter_param='bookInfo.bookName in ("三国演义","西游记")'
<value>：表示要匹配的值。
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 数量。
radius
否
指定相似性检索半径。
指定相似性检索的半径范围。每一种相似性计算方法的检索半径范围如下所示。
IP：检索结果返回满足 score >= radius 的数据。此时，radius 取值范围为 (-∞, +∞)。
COSINE：检索结果返回满足 score >= radius 的数据。此时，radius 取值范围为 [-1, 1]。
L2：检索结果返回满足 score <= radius 的数据。此时，radius 取值范围为 [0, +∞)。
说明：
支持的索引类型为：FLAT、IVF 系列。
检索结果将限定在指定的检索半径内，并根据您设置的 'limit' 参数值来确定返回结果的数量。
output_fields
否
配置需返回的字段。
以数组形式配置需返回的字段。若不配置，返回所有字段。
说明：
output_fields 与 retrieve_vector 参数均可以配置是否输出向量值，二者任意一个配置需输出向量字段，则将输出向量字段。
输出 Json 字段时，output_fields 仅支持指定 Json 字段的名称，而不支持直接指定 Json 字段内部的键（key）。例如，写入"a": {"b": "test", "c": 12}，output_fields 只能指定返回整个 "a" 字段，而无法单独指定返回 "a.b" 。
timeout
否
请求超时时间。
单位：秒。
默认值：VectorDBClient() 接口配置的 timeout 时长。
取值范围大于等于0。

出参描述

检索结果，如下所示。
说明：
输出结果的顺序，与搜索时设置的 vectors 配置的向量值的顺序一致。如下示例，0下面的三行结果对应[0.3123, 0.43, 0.213]向量的相似度查询结果。1下面的三行结果对应[0.315, 0.4, 0.216]的查询结果。
每一个查询结果都返回 TopK 条相似度计算的结果。其中，K 为 limit 设置的数值，如果插入的数据不足 K 条，则返回实际插入的 Document 数量。
检索结果会按照与查询向量的相似程度进行排列，相似度最高的结果会排在最前面，相似度最低的结果则排在最后面。
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
表示查询向量与检索结果向量之间的相似性计算分数。欧式距离（L2）与汉明距离（Hamming Distance）计算所得的分数越小与搜索值越相似；而余弦相似度（COSINE）与内积（IP） 计算所得的分数越大与搜索值越相似。
author、page、section
Document 其他自定义的标量字段。
中国站
目录