全文检索

全文检索通过匹配文本内容来查找 Document，使用 BM25 相关性评分进行排序。支持自然语言查询、精确短语匹配和布尔运算符。

前提条件

本指南假设你已经打开了一个 Collection，并准备好了一个 collection 对象。

定义全文检索字段

要对字段启用全文检索，需要添加一个 FieldSchema 并将 FtsIndexParam 作为其 index_param。该字段的数据类型必须为 STRING。

import zvec

fts_field = zvec.FieldSchema(  
    name="content",
    data_type=zvec.DataType.STRING,
    nullable=False,
    index_param=zvec.FtsIndexParam(
        tokenizer_name="jieba",   # 使用 Jieba 中文分词器
    ),
)

FtsIndexParam 参数

执行全文检索

Zvec 提供两种全文检索的查询模式，均通过 Query 中的 Fts 对象使用：

1. Match String — 自然语言输入，自动分词
2. Query String — 支持布尔运算符的高级表达式语法

Match String

使用 match_string 进行自然语言查询。输入为纯文本，无需任何特殊语法或转义。它会使用该字段配置的分词器进行分词，Token 之间使用默认运算符（默认为 OR）组合。

from zvec.model.param.query import Fts, Query

result = collection.query(  
    queries=Query(
        field_name="content",
        fts=Fts(match_string="机器学习"),  
    ),
    topk=5,
)
print(result)

使用默认的 OR 运算符时，将返回包含"机器"或"学习"（或两者都包含）的 Document，按 BM25 相关性评分排序。

Query String

使用 query_string 进行高级查询，支持显式布尔运算符、必需/排除词项和精确短语匹配。

from zvec.model.param.query import Fts, Query

result = collection.query(  
    queries=Query(
        field_name="content",
        fts=Fts(query_string='+学习 -神经网络 "向量搜索"'),  
    ),
    topk=5,
)
print(result)

使用默认的 OR 运算符时，文档必须匹配“学习”，并排除匹配“神经网络”的文档。“向量搜索”是可选短语，命中时会计入相关性评分。

查询语法参考

以下运算符可在 query_string 表达式中使用：

查询参数

默认运算符

默认情况下，match_string 和 query_string 中相邻的裸词项使用 OR 组合。要改为 AND，可通过 param 字段传入 FtsQueryParam：

import zvec
from zvec.model.param.query import Fts, Query

result = collection.query(
    queries=Query(
        field_name="content",
        fts=Fts(match_string="机器学习"),
        param=zvec.FtsQueryParam(default_operator="AND"),  
    ),
    topk=5,
)

设置 default_operator="AND" 后，仅返回同时包含"机器"和"学习"的 Document。

结合标量过滤

可以将全文检索与标量过滤结合使用以缩小结果范围：

from zvec.model.param.query import Fts, Query

result = collection.query(
    queries=Query(
        field_name="content",
        fts=Fts(match_string="机器学习"),
    ),
    filter="category = '技术'",  
    topk=5,
)

分词器

Zvec 提供四种内置分词器，通过 FtsIndexParam 为每个字段单独配置。

Standard 分词器

默认分词器。它实现了 Unicode UAX #29 词边界规则，行为类似 Elasticsearch standard tokenizer。对于 CJK 表意文字，standard 会输出单字 Token；如果需要中文词级检索，通常应使用 jieba。

zvec.FtsIndexParam(tokenizer_name="standard", filters=["lowercase"])

配置（通过 extra_params JSON）：

N-gram 分词器

默认配置下，ngram 将 zvec 切为 zv、ve 和 ec。因此，搜索 ve 可以命中包含 zvec 的文档。

Whitespace 分词器

仅在空白字符处拆分文本。适用于需要保留 Token 内标点符号的场景。

zvec.FtsIndexParam(tokenizer_name="whitespace", filters=["lowercase"])

Jieba 分词器

需要按词检索中文或中英混合文本时，选择 jieba。分词器默认使用原生库内置的词典和 HMM 模型。

zvec.FtsIndexParam(
    tokenizer_name="jieba",
    filters=["lowercase"],
)

配置（通过 extra_params JSON）：

Token 过滤器

Token 过滤器在分词后按 filters 数组顺序应用。索引构建和查询使用同一套过滤器配置。

英文文本通常可以使用 lowercase、stemmer 组合，让大小写和词形变化不影响匹配。类英文文本或包含重音符号的文本还可以加入 ascii_folding，以获得重音无关匹配。

Lowercase 过滤器

"lowercase" 将所有 Token 转换为 Unicode 小写。

ASCII Folding 过滤器

"ascii_folding" 将 Unicode 字符折叠为 ASCII 等价形式。

Stemmer 过滤器

"stemmer" 使用 Snowball 词干提取器归一化词形，默认语言为 "english"。

zvec.FtsIndexParam(
    tokenizer_name="standard",
    filters=["lowercase", "stemmer"],
    extra_params='{"stemmer_lang": "english"}',
)

Stemmer 配置（通过 extra_params JSON）：

约束