全文检索通过匹配文本内容来查找 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` 参数

参数	类型	默认值	描述
`tokenizer_name`	`str`	`"standard"`	用于将文本拆分为 Token 的分词器。可选值：`"standard"`、`"whitespace"`、`"jieba"`。详见分词器。
`filters`	`list[str]`	`["lowercase"]`	分词后按顺序应用的 Token 过滤器。目前仅支持 `"lowercase"`。
`extra_params`	`str`	`""`	分词器特定配置的 JSON 字符串（例如 Jieba 字典路径）。

Zvec 支持纯全文检索的 Collection — 可以创建仅包含文本字段、不包含向量字段的 Collection。

执行全文检索

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

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

Match String

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

Match String 查询

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 进行高级查询，支持显式布尔运算符、必需/排除词项和精确短语匹配。

带运算符的 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)

此查询要求必须包含"学习"，排除"神经网络"，并匹配精确短语"向量搜索"。

query_string 和 match_string 互斥 — 每个 Fts 对象中必须且只能提供其中一个。

查询语法参考

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

语法	含义	示例
`term`	匹配单个词项	`vector`
`"phrase"`	匹配精确短语（词序和相邻性）	`"machine learning"`
`+term`	词项必须出现在 Document 中	`+vector`
`-term`	词项不得出现在 Document 中	`-slow`
`a AND b`	两个词项都必须匹配	`vector AND search`
`a OR b`	任一词项匹配即可	`vector OR embedding`
`a NOT b`	匹配 `a` 但排除匹配 `b` 的 Document	`learning NOT deep`
`(expr)`	分组子表达式	`(vector OR embedding) AND search`
`+(expr)`	分组必须匹配	`+(vector OR embedding)`
`-(expr)`	分组不得匹配	`-(slow AND outdated)`

运算符优先级：AND / NOT 的绑定优先级高于 OR。没有显式运算符的相邻词项使用 default_operator 设置进行组合（默认为 OR）。

对于混合使用多种运算符的复杂查询，建议使用 () 显式分组以避免非预期结果。

不支持前置否定 — NOT term 和单独的 -term 都需要至少一个肯定词项。请使用 a NOT b 或将 -term 与肯定词项组合使用（例如 a -b）。

查询参数

参数	描述
`topk`	返回评分最高的 Document 数量。
`filter`	可选的类 SQL 布尔表达式，用于限制结果。详见条件过滤。
`output_fields`	可选的标量字段名称列表，用于指定结果中包含的字段。如果省略，返回所有标量字段。

默认运算符

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

使用 AND 作为默认运算符

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。

query_string 中的显式运算符（AND、OR、+、-）不受 default_operator 影响 — 它仅控制相邻裸词项的组合方式。

结合标量过滤

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

全文检索 + 标量过滤

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

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

全文检索和向量检索在单个查询路线中互斥。同一个 Query / ZVecQuery 不应同时设置 fts 和 vector / id；如需结合两者，请使用多条查询路线配合重排序，或分别执行查询后在应用层合并结果。

分词器

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

分词器	名称	描述
Standard	`"standard"`	按非字母数字字符拆分文本。适用于大多数拉丁字母语言。（默认）
Whitespace	`"whitespace"`	仅按空白字符（空格、制表符、换行符）拆分文本。保留 Token 内的标点符号。
Jieba	`"jieba"`	基于 cppjieba 的中文分词。支持中英文混合文本。

Standard 分词器

默认分词器。在非字母数字字符的边界处将文本拆分为 Token，并丢弃分隔符。

Standard 分词器

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

配置（通过 extra_params JSON）：

参数	类型	默认值	描述
`max_token_length`	`int`	`255`	最大 Token 长度。超过此长度的 Token 将被丢弃。

Whitespace 分词器

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

Whitespace 分词器

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

Jieba 分词器

中文分词器，同时支持中英文混合文本。

Python SDK 内置了默认的 Jieba 字典 — Jieba 分词器无需额外配置即可开箱使用。仅在需要自定义字典时才需设置 jieba_dict_dir。

Jieba 分词器

zvec.FtsIndexParam(
    tokenizer_name="jieba",
    filters=["lowercase"],
    extra_params='{"jieba_dict_dir": "/path/to/jieba/dict"}',
)

配置（通过 extra_params JSON）：

参数	类型	默认值	描述
`jieba_dict_dir`	`str`	—	包含 `jieba.dict.utf8` 和 `hmm_model.utf8` 的目录。也可通过 `ZVEC_JIEBA_DICT_DIR` 环境变量设置。
`user_dict_path`	`str`	—	自定义用户词典文件的路径。
`cut_mode`	`str`	`"search"`	分词模式：`"search"`（细粒度，推荐用于搜索）、`"mix"`、`"full"` 或 `"hmm"`。各模式详情请参阅 cppjieba 文档。

jieba_dict_dir 解析优先级（使用第一个非空值）：

FtsIndexParam 中的 extra_params 指定的路径
ZVEC_JIEBA_DICT_DIR 环境变量
通过 zvec.init(jieba_dict_dir=...) 或 zvec.set_default_jieba_dict_dir() 设置的全局默认值
Python SDK 内置字典（import zvec 时自动注册）

Token 过滤器

Token 过滤器在分词后按顺序应用。目前仅提供一种过滤器：

过滤器	描述
`"lowercase"`	将所有 Token 转换为 ASCII 小写。

约束

全文检索和向量检索在单个查询路线中互斥 — 同一个 Query / ZVecQuery 不应同时设置 fts 和 vector / id。
query_string 和 match_string 在单个 Fts 对象中互斥。
全文检索字段不支持 Alter Column。
不支持前置否定（NOT term 或单独的 -term）— 至少需要一个肯定词项。

全文检索

示例 Collection 设置

本页目录