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

单路稀疏向量相似度检索

最近更新时间：2025-07-01 10:19:42

我的收藏

本页目录：

接口定义

本接口fulltext_search()基于稀疏向量实现全文检索，对查询词与文档内容进行匹配，并按相关度排序结果。
def fulltext_search(self,
                    database_name: str,
                    collection_name: str,
                    data: SparseVector,
                    field_name: str = 'sparse_vector',
                    filter: Union[Filter, str] = None,
                    retrieve_vector: Optional[bool] = None,
                    output_fields: Optional[List[str]] = None,
                    limit: Optional[int] = None,
                    terminate_after: Optional[int] = None,
                    cutoff_frequency: Optional[float] = None,
                    **kwargs) -> List[Dict]:

使用示例

fulltext_search() 完整的代码示例，请参见 fulltext_search.py。
import json
from typing import List
from tcvdb_text.encoder.bm25 import BM25Encoder

## 初始化稀疏向量编码器
bm25 = BM25Encoder.default('zh')
## 稀疏向量相似性检索
res = client.fulltext_search(
    database_name='db-test',
    collection_name='sparse-vector-test',
    data=bm25.encode_queries('什么是腾讯云数据库'),
    field_name="sparse_vector",
    filter=None,
    retrieve_vector=False,
    # output_fields=['id', 'sparse_vector', 'text'],
    limit=10,
    # terminate_after=4000,
    # cutoff_frequency=0.1,
)
print(json.dumps(res, indent=2, ensure_ascii=False))

入参描述

参数
是否必选
参数含义
配置方法及要求
database_name
是
指定检索的数据库名。
Database 命名要求如下：
只能使用英文字母，数字，下划线_、中划线-，并以英文字母开头。
长度要求：[1,128]。
collection_name
是
指定检索的集合名。
Collection 命名要求如下：
只能使用英文字母，数字，下划线_、中划线-，并以英文字母开头。
长度要求：[1,128]。
match
否
稀疏向量检索配置。
field_name：稀疏向量的字段名，例如：sparse_vector。
data：检索的稀疏向量，当前仅支持输入一个稀疏向量。
terminate_after：设置检索数量上限，即检索数量超过 terminate_after 值之后，提前终止检索行为，可以有效的控制速率，在数据量较大的情况下，推荐经验值：4000。
cutoff_frequency：设置高频词出现的频次或频率上限，即词频大于 cutoff_frequency 的值之后，该关键词被忽略。
频数：可指定关键词出现的频数，取值为正整数，范围为[1,+∞]。
频率：可指定为关键词出现的频率，取值范围为[0,1]的小数。例如：0.8。
说明：
cutoff_frequency 可以排序阶段去掉高频词，在数据量较大的情况下（>=50w）推荐值：0.1。
filter
否
设置 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>：表示要匹配的值。
retrieve_vector
否
标识是否需要返回检索结果的向量值。
True：需要。
False：不需要。默认为 False。
limit
是
指定最终返回最相似的 Top K 条数据的 K 的值。
K 为大于0的正整数。
output_fields
否
配置需返回的字段。
以数组形式配置需返回的字段。若不配置，返回所有字段。
说明：
output_fields 与 retrieve_vector 参数均可以配置是否输出向量值，二者任意一个配置需输出向量字段，则将输出向量字段。
输出 Json 字段时，output_fields 仅支持指定 Json 字段的名称，而不支持直接指定 Json 字段内部的键（key）。例如，写入"a": {"b": "test", "c": 12}，output_fields 只能指定返回整个 "a" 字段，而无法单独指定返回 "a.b" 。

出参描述

[
  {
    "id": "0001",
    "score": 0.75646,
    "text": "腾讯云向量数据库（Tencent Cloud VectorDB）是一款全托管的自研企业级分布式数据库服务，专用于存储、索引、检索、管理由深度神经网络或其他机器学习模型生成的大量多维嵌入向量。"
  },
  {
    "id": "0004",
    "score": 0.71671,
    "text": "腾讯云向量数据库（Tencent Cloud VectorDB）作为一种专门存储和检索向量数据的服务提供给用户， 在高性能、高可用、大规模、低成本、简单易用、稳定可靠等方面体现出显著优势。 "
  },
  {
    "id": "0002",
    "score": 0.26303,
    "text": "作为专门为处理输入向量查询而设计的数据库，它支持多种索引类型和相似度计算方法，单索引支持10亿级向量规模，高达百万级 QPS 及毫秒级查询延迟。"
  }
]
参数名
子参数
参数含义
documents
id
Document 的 ID 信息。
sparse_vector
Document 的稀疏向量。
score
表示查询向量与检索结果向量之间的相似性计算分数。
other_scalar_field
Document 其他自定义的标量字段。例如：author、bookName、page 等。

中国站
目录