Tokenizers normalizers.Sequence 怎样组合规范化规则

在做文本分类、检索或语言模型预处理时，规范化往往不是一个动作：可能先拆分 Unicode 字符，再统一大小写，最后去掉重音符号。Tokenizers 的 normalizers.Sequence 适合把这些动作组成一条固定链路。它接收一个 Normalizer 列表，并严格按照列表顺序执行；因此真正需要设计的是“哪些规则”和“它们的先后关系”。

官方地址：https://huggingface.co/docs/tokenizers/api/normalizers

Sequence 不是一套自动推断规则的清洗器，而是一个有顺序的组合器。先把每个规范化动作单独想清楚，再把它们按训练数据所需的顺序放入列表，通常最容易维护。

一、先理解 Sequence 组合了什么

官方 API 将 Sequence 定义为把多个规范化器串联起来。构造函数的参数是 List[Normalizer]，列表中的每个对象都会参与同一次规范化，顺序就是列表顺序。它解决的是组合和调度，不负责替你决定大小写、Unicode 分解或空白处理策略。

可以把它看成一条文本入口：原始字符串先交给第一个规则，第一步的结果再交给第二个规则，直到列表结束。这样做的好处是，单个规则仍然可以独立替换，最终的 tokenizer 配置也能用一段代码完整表达。

二、用三个规则组成一条基础链

如果目标是把带重音的拉丁文本变成更容易统一处理的形式，可以用 NFD 拆分字符，用 Lowercase 做 Unicode 感知的小写化，再用 StripAccents 去掉组合重音。官方文档给出的组合示例就是这类思路。

from tokenizers import normalizers
from tokenizers.normalizers import NFD, Lowercase, StripAccents

# 先拆分 Unicode 字符，再统一大小写，最后移除组合重音。
normalizer = normalizers.Sequence([
    NFD(),
    Lowercase(),
    StripAccents(),
])

# normalize_str 只返回文本结果，适合先观察规范化效果。
text = normalizer.normalize_str("Héllo Wörld")
print(text)  # 结果示意：hello world

这里的关键不是三个类名本身，而是列表表达的契约：StripAccents 通常要放在 NFD 后面，因为它要处理由分解产生的组合重音。规则换成别的领域逻辑时，也应该先确认前一步是否已经准备好了后一步所需的输入形态。

三、先用 normalize_str 观察链路结果

写入正式 tokenizer 前，可以先调用 normalize_str 检查一组代表性输入。这个方法适合查看最终字符串，但官方文档也特别区分了它与 normalize：前者用于得到文本结果，不保留可用于偏移量转换的对齐信息；如果后续需要处理原文与规范化文本的 offsets，就要按组件提供的 API 选择更合适的调用方式。

samples = [
    "Héllò hôw are ü?",
    "  Mixed CASE  ",
    "already plain",
]

for sample in samples:
    # 每个样本都经过同一条链，便于比较规则顺序带来的统一效果。
    normalized = normalizer.normalize_str(sample)
    print(repr(sample), "->", repr(normalized))

观察时不要只准备一个漂亮样例。至少加入已经是小写的文本、带组合字符的文本以及包含首尾空白的文本。若链中没有 Strip，首尾空白不会因为使用了 Sequence 就自动消失；组合器不会替你增加未列出的规则。

四、把组合器挂到 Tokenizer

确定链路后，再把它赋给 tokenizer 的 normalizer 属性。规范化是 tokenization pipeline 的前置环节，后面还会接 pre-tokenizer、model 和 decoder。赋值的重点是让同一套规则进入真正的编码入口，而不是只在调试脚本里调用一次。

from tokenizers import Tokenizer, normalizers
from tokenizers.models import WordPiece
from tokenizers.normalizers import NFD, Lowercase, StripAccents

tokenizer = Tokenizer(WordPiece(unk_token="[UNK]"))

# 训练或推理都要使用同一条规范化链，避免输入前处理不一致。
tokenizer.normalizer = normalizers.Sequence([
    NFD(),
    Lowercase(),
    StripAccents(),
])

# 这里只展示挂接位置；词表、pre-tokenizer 和训练配置仍需按项目补齐。
print(tokenizer.normalizer.normalize_str("Héllo"))

如果已经有一个训练完成的 tokenizer，修改它的规范化方式会改变进入模型的文本形态，进而可能改变词表命中和训练分布。官方 pipeline 文档建议：改变 tokenizer 的 normalization 方式后，通常应重新训练。不要把“代码能运行”误认为“旧词表仍然适配”。

五、顺序为什么是 Sequence 的核心

列表顺序不是装饰信息。以分解和去重音为例，NFD 先把某些预组字符拆成基础字符与组合标记，StripAccents 才有机会移除这些标记。若把依赖前置条件的规则放在前面，可能得不到预期结果；即使两个规则都能运行，结果也可能因为中间形态不同而不同。

落地时可以用下面的顺序表做设计记录：

六、几个容易误用的边界

• 空列表不是默认清洗：Sequence([]) 不会凭空添加大小写、空白或 Unicode 规则。需要什么，就显式列出什么。
• 规则不会自动去重：同一个 Normalizer 重复放入列表，应该由作者确认是否有意为之；组合器只负责按顺序调用。
• 不要把 normalize_str 当作 offsets 方案：它主要用于观察字符串结果，涉及原文位置映射时要重新评估调用方式。
• 不要把规范化当作分词：Sequence 只组合 Normalizer，pre-tokenizer 和 model 仍然是独立配置。
• 改变链路要同步训练：如果训练时和推理时的规范化顺序不同，即使模型与词表没有报错，输入分布也可能已经改变。

七、适合落地的配置清单

1. 先写清楚输入希望变成什么样，不要从类名堆叠开始。
2. 给每个 Normalizer 标注前置条件，尤其是分解、替换和去重音之间的依赖。
3. 用 normalize_str 对普通样本、边界字符和已有规范化文本做对照观察。
4. 确认后再赋值给 tokenizer.normalizer，并让训练、评估、推理共用同一份配置。
5. 若需要 offsets、原文回溯或特殊字符保留，单独评估对应组件，不要只增加 Sequence 成员。

八、总结

normalizers.Sequence 的价值在于把多个规范化器组合成一个可读、可复用、顺序明确的入口。最实用的用法是：先按数据目标选择规则，再按前置条件排列列表，用 normalize_str 观察结果，最后挂到 tokenizer.normalizer。它不会自动猜测清洗策略，也不会替代 pre-tokenizer、model 或训练配置；把这几个边界分开，链路才容易长期维护。

相关问题

• StripAccents 为什么通常放在 NFD 后面？
• Sequence 和 pre-tokenizer 的组合关系是什么？
• 修改 tokenizer.normalizer 后为什么可能需要重新训练？
• 什么时候应该选择 NFC、NFD 或兼容分解规则？