LanceDB Node.js 全文字段检索中的 FtsToken 接口:分词输出结构与源码实现解析
LanceDB Node.js 全文字段检索中的 FtsToken 接口:分词输出结构与源码实现解析
本篇技术指南围绕 LanceDB Node.js 客户端中由全文检索(FTS)索引分词器产出的 FtsToken 接口展开,说明其 text 与 position 两个字段的确切含义、在查询匹配链路中的作用,以及它们如何贯穿 TypeScript 类型定义、napi-rs 绑定与 Rust 内核的完整调用链。读完本文,你将掌握通过 tokenize() 函数与 Table.tokenize() 方法获取分词结果的方法,并理解分词选项(如词干化、停用词、n-gram)如何影响最终输出的 token 文本与位置。
FtsToken 接口:一次分词调用的返回值契约
FtsToken 是 LanceDB Node.js 客户端中描述"由全文检索索引上配置的分词器产出的单个 token"的接口,定义于 TypeScript 源码 nodejs/lancedb/table.ts,并由 @lancedb/lancedb 包通过 nodejs/lancedb/index.ts 对外导出。其完整结构如下:
/** Token produced by the tokenizer configured on a full-text search index. */
export interface FtsToken {
/** Token text after tokenizer filters have been applied. */
text: string;
/** Token position used by full-text query matching. */
position: number;
}
该接口只有两个字段,但它们分别对应全文检索索引中最重要的两类信息:
text: string:经过分词器过滤器处理之后的 token 文本。所谓"过滤器"包括小写化(lowercase)、词干化(stemming)、停用词移除(stop words removal)、ASCII 折叠(ascii folding)等——也就是说,text不一定是原文中的原始单词,而是经过规范化后的形式,用于与索引中的词条(term)精确匹配。position: number:token 在原始查询文本中的位置序号,用于全文查询的匹配逻辑(尤其是短语查询)。位置信息使得 LanceDB 能够判断多个 token 在原文中是否相邻出现,从而支持短语级别的匹配。
FtsToken 的产生入口:两种 tokenize 调用方式
FtsToken[] 是分词操作的统一返回类型。在 Node.js 客户端中,存在两个入口会产生 FtsToken 数组:
1. 顶层 tokenize() 函数:不依赖表与索引的纯分词
@lancedb/lancedb 包导出一个独立的 tokenize(query, options?) 异步函数(见 nodejs/lancedb/index.ts):
export async function tokenize(
query: string,
options?: Partial<TokenizeOptions>,
): Promise<FtsToken[]> {
return await nativeTokenize(
query,
options?.baseTokenizer,
options?.language,
options?.maxTokenLength,
options?.lowercase,
options?.stem,
options?.removeStopWords,
options?.customStopWords,
options?.asciiFolding,
options?.ngramMinLength,
options?.ngramMaxLength,
options?.prefixOnly,
);
}
官方文档 docs/src/js/functions/tokenize.md 明确指出:该函数"不需要表或 FTS 索引即可运行",且其分词选项与 Index.fts 的配置完全一致(见 Index.fts 文档 与 TokenizeOptions 接口文档)。这在调试场景中非常实用——你可以先不建索引、不连表,仅凭一段文本验证某套分词配置会产出怎样的 token 序列,再决定是否用相同配置构建 FTS 索引。
TokenizeOptions 支持的分词控制项(定义于 nodejs/lancedb/index.ts)包括:
| 选项 | 类型 | 说明 |
|---|---|---|
baseTokenizer |
BaseTokenizer |
基础分词器,默认 "simple" |
language |
string |
词干化与停用词使用的语言 |
maxTokenLength |
number |
最大 token 长度,超过的被忽略 |
lowercase |
boolean |
是否小写化 token |
stem |
boolean |
是否做词干化 |
removeStopWords |
boolean |
是否移除停用词 |
customStopWords |
string[] |
自定义停用词表,覆盖内置语言列表(仅在 removeStopWords 为 true 时生效) |
asciiFolding |
boolean |
是否折叠 ASCII 字符 |
ngramMinLength / ngramMaxLength |
number |
n-gram 分词器的最小/最大长度 |
prefixOnly |
boolean |
n-gram 分词器是否只输出 token 前缀 |
2. Table.tokenize() 方法:使用索引已配置的分词器
当表上已建有 FTS 索引时,可以调用 Table.tokenize()(TypeScript 声明见 nodejs/lancedb/table.ts),让分词严格复用索引构建时配置的分词器,从而保证"分词结果 = 索引词条",避免查询分词与索引分词不一致导致的召回问题:
abstract tokenize(
query: string,
options: TokenizeTableOptions,
): Promise<FtsToken[]>;
TokenizeTableOptions 是一个互斥联合类型(见 nodejs/lancedb/table.ts):要么指定 column(使用该 FTS 索引列的分词器),要么指定 indexName(使用该命名 FTS 索引的分词器),二者必须且只能提供一个。此外,官方文档说明:基于模型的 tokenizer(如 jieba/* 和 lindera/*)在表间切换时会重建,且本地必须存在相同的分词模型文件。
从 TypeScript 到 Rust 内核:FtsToken 的完整调用链
FtsToken 并不是一个仅存在于类型层面的"空壳"接口,它对应着 LanceDB Rust 内核 lancedb::tokenize 的真实输出。以 napi-rs 绑定为分界,调用链如下:
- TypeScript 层:
tokenize()或table.tokenize()将参数透传给 napi-rs 生成的原生函数。 - napi-rs 绑定层:
nodejs/src/index.rs中的tokenize(nodejs/src/index.rs)接收全部 12 个分词参数,构造FtsIndexBuilder,依次应用base_tokenizer、language(不支持的语言会直接报错)、max_token_length、lower_case、stem、remove_stop_words、custom_stop_words、ascii_folding、ngram_min_length、ngram_max_length、ngram_prefix_only,最后调用内核函数lancedb_tokenize(&query, &opts),把结果逐项map(FtsToken::from)转成 napi 结构体返回。 - 内核层:
Table.tokenize对应的绑定在 nodejs/src/table.rs,它要求column与index_name恰好指定一个(否则报错"Specify exactly one of 'column' or 'indexName'"),分别路由到table.tokenize_with_column(&query, column)或table.tokenize(&query, index_name)。
也就是说,FtsToken.text 是内核分词器(基于 tantivy 生态)经过过滤器链之后的最终词条,FtsToken.position 则是该词条在输入文本中的序号——这套数据最终会与 FTS 索引中存储的倒排列表和位置信息(withPosition)配合使用。
position 字段的价值:短语查询与位置索引
为什么 FtsToken 要携带 position?这与 FTS 索引构建选项 withPosition 直接相关。在 FtsOptions 文档 与源码 nodejs/lancedb/indices.ts 中可以看到:
withPosition默认为true,索引会存储 token 在文本中的位置,从而支持短语查询(phrase query);- 若设为
false,索引更小、构建更快,但无法支持短语查询。
因此,FtsToken.position 就是查询分词阶段产出的位置序列,它必须与索引侧的 withPosition 语义对齐:只有在两边都具备位置信息时,诸如"相邻词匹配""短语精确匹配"这类需要词序信息的查询才能正确执行。
测试用例实证:分词输出形态一览
仓库测试 nodejs/test/table.test.ts 给出了 FtsToken 最直观的行为证据:
simple 分词器 + 默认词干化/停用词处理,对 "Running in cafés" 分词:
const simpleTokens = await table.tokenize("Running in cafés", {
column: "text",
});
// 期望结果:
// [{ text: "run", position: 0 }, { text: "cafe", position: 2 }]
可以看到:"Running" 被小写化并词干化为 "run"(position 0),"cafés" 被折叠/词干化为 "cafe"(position 2),而停用词 "in" 被移除——注意其后续 token 的 position 仍是 2 而非 1,说明 position 记录的是 token 在原文中的原始序号,而非过滤后的序号。
ICU 分词器对 "Hello, こんにちは世界!" 分词(关闭词干化与停用词):
// [{ text: "hello", position: 0 },
// { text: "こんにちは", position: 1 },
// { text: "世界", position: 2 }]
说明 icu 分词器具备跨语言(中、日、英混合文本)的词典式切词能力。
直接调用顶层 tokenize() 得到的结果与 Table.tokenize() 完全一致,验证了两条入口共用同一套内核逻辑。
自定义停用词(nodejs/test/table.test.ts):
const tokens = await tokenize("the lance data", {
stem: false,
removeStopWords: true,
customStopWords: ["lance"],
});
// tokens.map(t => t.text) => ["the", "data"]
当 customStopWords 提供时,它会替换内置的 language 停用词表(空数组则显式表示无停用词),此处 "lance" 被移除而 "the" 保留。
实战要点与最佳实践
- 先调试、后建索引:利用不依赖表的
tokenize()函数,先验证baseTokenizer、stem、removeStopWords等组合的输出是否符合预期,再用完全相同的参数调用Index.fts建索引,可避免查询与索引分词不一致。 - 善用 position 排除干扰:分词结果中的 position 保持原文序号,可用于校验 token 间的原始间距,评估短语查询的可行性。
- 理解分词器取舍:
simple按空白与标点切分并默认做规范化;whitespace仅按空白切分;raw将整段文本视为单个 token(适合精确串匹配);ngram用于子串级召回;icu/icu/split提供多语言词典切词;jieba/*与lindera/*为模型化分词器,需本地模型文件支持(详见 nodejs/lancedb/indices.ts 中的BaseTokenizer类型定义)。 - 注意互斥参数:
Table.tokenize()的column与indexName必须恰好指定一个,否则抛错;顶层tokenize()则通过baseTokenizer显式指定分词器。 - 位置与短语查询联动:若你的业务不需要短语查询,可在建索引时关闭
withPosition以换取更小的索引体积和更快的构建速度;一旦关闭,查询侧的位置信息也无法用于短语匹配。
FtsToken 虽然只有两个字段,却是连接"查询文本"与"索引词条"的关键数据契约。理解它的 text(规范化后的词条)与 position(原文位置序号),是正确使用 LanceDB 全文检索、特别是短语查询与分词一致性调试的基础。