全文索引
一种基于倒排索引的文本检索机制 — 支持自然语言查询、短语匹配和布尔表达式，使用 BM25 相关性评分排序。
全文索引是一种专门用于高效的文本内容检索的数据结构。
它将文本字段拆分为词项（Token），构建倒排映射，使得按关键词查找 Document 无需逐条扫描，结合 BM25 评分实现按相关性排序的文本检索。
何时使用全文索引
当你需要对文本内容进行关键词检索并按相关性排序时，应使用全文索引。它在以下场景中表现出色：
- ✅ 自然语言查询：用户输入日常用语搜索内容
- ✅ 精确短语匹配：
"向量数据库"匹配完整短语而非单独的词 - ✅ 布尔检索：
+机器学习 -深度学习指定必须包含或排除的词项 - ✅ 中文文本检索：使用 Jieba 分词器处理中文及中英混合文本
- ✅ 纯文本场景：无需向量字段即可建立全文检索 Collection
全文索引与倒排索引的区别：倒排索引用于标量字段的精确过滤（如 status = "active"），而全文索引用于文本内容的关键词检索与相关性排序。
工作原理
假设你有一个包含文章内容的 Collection：
| Doc ID | Content |
|---|---|
| 1 | 机器学习模型的训练与优化 |
| 2 | 深度学习在自然语言处理中的应用 |
| 3 | 向量数据库与机器学习的结合 |
分词
全文索引首先通过分词器将文本拆分为 Token。以 Jieba 分词器为例：
| Doc ID | Token 列表 |
|---|---|
| 1 | [机器学习, 模型, 训练, 优化] |
| 2 | [深度学习, 自然语言处理, 应用] |
| 3 | [向量, 数据库, 机器学习, 结合] |
BM25 评分
查询"机器学习"时，全文索引直接定位到包含该词项的 Document [1, 3]，然后使用 BM25 算法计算每个 Document 的相关性评分。
BM25 综合考虑以下因素对结果排序：
| 因素 | 影响 |
|---|---|
| 词频（TF） | 词项在 Document 中出现越多，评分越高（存在衰减） |
| 逆文档频率（IDF） | 词项在整个 Collection 中越罕见，权重越高 |
| 文档长度 | 较短的 Document 中出现同一词项，评分相对更高 |
WAND 优化
当查询包含多个词项（如"机器学习 自然语言处理"）时，全文索引使用 WAND（Weak AND） 算法优化检索性能：
- 为每个词项预计算评分上界
- 跳过不可能进入 top-k 结果的 Document
- 结合 Block-Max 策略，以 128 个 Document 为一个块进行快速跳跃
这使得在大规模数据集上也能高效返回 top-k 结果，无需对所有候选 Document 完整评分。
分词器
分词器决定了文本如何被拆分为词项，直接影响检索效果。索引和查询使用相同的分词配置。详见分词器。
关键参数
索引构建参数
| 参数 | 说明 | 调优建议 |
|---|---|---|
tokenizer_name | 分词器，用于将文本拆分为可检索 Token | 英文或类英文文本用 standard，需要保留空白切分语义时用 whitespace，中文或中英混合文本用 jieba |
filters | 分词后的 Token 过滤器 | 英文或类英文文本建议保留 lowercase，以获得大小写无关的匹配 |
extra_params | 分词器专用 JSON 配置 | 用于自定义 Jieba 词典，或设置 max_token_length 等分词器专用限制 |
查询参数
| 参数 | 说明 | 调优建议 |
|---|---|---|
match_string / matchString | 由字段分词器处理的自然语言查询文本 | 适合简单的用户输入搜索 |
query_string / queryString | 支持短语和布尔运算符的结构化查询表达式 | 当调用方需要显式指定必选词、排除词、分组或短语时使用 |
default_operator / defaultOperator | 裸词之间的默认布尔运算符 | 需要更高召回时使用 OR，希望每个裸词都必须匹配时使用 AND |
与向量搜索的关系
全文索引和向量索引解决的是不同维度的检索需求：
| 维度 | 全文索引 | 向量索引 |
|---|---|---|
| 匹配方式 | 精确关键词匹配 | 语义相似度 |
| 输入 | 文本关键词 | 向量 Embedding |
| 排序依据 | BM25 评分 | 距离/相似度 |
| 典型场景 | "包含这些关键词的文档" | "和这段内容语义相近的文档" |
在 Zvec 中，全文检索和向量检索在单个查询路线中互斥：同一个 Query / ZVecQuery 不应同时设置 fts 和 vector / id。如需结合关键词匹配与语义检索，请使用多条查询路线配合重排序，或分别执行查询后在应用层合并结果。
权衡
- ⚠️ 存储开销：倒排映射、词频统计和位置信息需要额外存储空间。
- ⚠️ 写放大：每次写操作都需要分词并更新倒排索引，增加写入延迟。
- ⚠️ 分词器依赖：检索效果与分词质量直接相关 — 中文文本需要使用 Jieba 分词器而非 Standard 分词器。