LanceDB Node.js 全文字段检索中的 FtsToken 接口:分词输出结构与源码实现解析

原创2026-09-22 10:47:381,811 阅读
文章标签:向量数据库数据库全文检索数据湖多模态嵌入式数据库列式数据库

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 绑定为分界,调用链如下:

  1. TypeScript 层:tokenize() 或 table.tokenize() 将参数透传给 napi-rs 生成的原生函数。
  2. 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 结构体返回。
  3. 内核层: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" 保留。

实战要点与最佳实践

  1. 先调试、后建索引:利用不依赖表的 tokenize() 函数,先验证 baseTokenizer、stem、removeStopWords 等组合的输出是否符合预期,再用完全相同的参数调用 Index.fts 建索引,可避免查询与索引分词不一致。
  2. 善用 position 排除干扰:分词结果中的 position 保持原文序号,可用于校验 token 间的原始间距,评估短语查询的可行性。
  3. 理解分词器取舍:simple 按空白与标点切分并默认做规范化;whitespace 仅按空白切分;raw 将整段文本视为单个 token(适合精确串匹配);ngram 用于子串级召回;icu / icu/split 提供多语言词典切词;jieba/* 与 lindera/* 为模型化分词器,需本地模型文件支持(详见 nodejs/lancedb/indices.ts 中的 BaseTokenizer 类型定义)。
  4. 注意互斥参数:Table.tokenize() 的 column 与 indexName 必须恰好指定一个,否则抛错;顶层 tokenize() 则通过 baseTokenizer 显式指定分词器。
  5. 位置与短语查询联动:若你的业务不需要短语查询,可在建索引时关闭 withPosition 以换取更小的索引体积和更快的构建速度;一旦关闭,查询侧的位置信息也无法用于短语匹配。

FtsToken 虽然只有两个字段,却是连接"查询文本"与"索引词条"的关键数据契约。理解它的 text(规范化后的词条)与 position(原文位置序号),是正确使用 LanceDB 全文检索、特别是短语查询与分词一致性调试的基础。

登录后查看全文
lancedb