huggingface-tokenizers

HuggingFace Tokenizers 是 Hugging Face 提供的高性能分词库，核心以 Rust 实现，并提供 Python 与 Node.js 绑定，兼顾 Rust 的性能与 Python 的易用性。

用途 该库用于训练和使用 BPE、WordPiece、Unigram 等分词器，适合以下场景：需要极快分词速度（官方称 CPU 上 1GB 文本可在 20 秒内完成分词）；从零训练自定义分词器；需要对齐追踪（token 到原文位置的映射）；构建生产级 NLP 流水线；高效分词大规模语料。官方称其比纯 Python 实现快 10–100 倍。

主要能力

• 加载预训练分词器：通过 Tokenizer.from_pretrained() 从 Hugging Face Hub 加载，例如 bert-base-uncased，可编码文本得到 tokens 与 ids，并可解码回文本。
• 训练自定义分词器：支持 BPE、WordPiece、Unigram 等模型，可配置词表大小、特殊 token、最小频率等参数，并保存为 JSON 文件。
• 完整分词流水线：Normalization（归一化）→ Pre-tokenization（预分词）→ Model（模型）→ Post-processing（后处理）。
• 归一化组件：NFD、NFC、NFKD、NFKC、Lowercase、StripAccents、Strip、Replace 等。
• 预分词组件：Whitespace、ByteLevel、Punctuation、Digits、Metaspace 等。
• 后处理组件：TemplateProcessing，可添加 [CLS]、[SEP]、<|endoftext|>、<s>、</s> 等特殊 token 模板。
• 对齐追踪：通过 output.offsets 获取每个 token 在原文中的起止位置，适用于命名实体识别、问答抽取、token 分类等。
• 批处理与填充：enable_padding、enable_truncation、encode_batch 等。
• 与 transformers 集成：AutoTokenizer 默认使用快速分词器，可通过 backend_tokenizer 访问底层 tokenizers.Tokenizer；也可用 PreTrainedTokenizerFast 包装自定义分词器。
• 大数据集训练：train_from_iterator 支持从迭代器训练，适合大规模语料。
• 多进程：可结合 multiprocessing.Pool 并行编码，官方称 8 核可获 5–8 倍加速。

使用方式 安装：pip install tokenizers；如需与 transformers 集成：pip install tokenizers transformers。 加载预训练分词器示例： from tokenizers import Tokenizer tokenizer = Tokenizer.from_pretrained("bert-base-uncased") output = tokenizer.encode("Hello, how are you?") print(output.tokens) print(output.ids) text = tokenizer.decode(output.ids) 训练自定义 BPE 分词器示例： from tokenizers import Tokenizer from tokenizers.models import BPE from tokenizers.trainers import BpeTrainer from tokenizers.pre_tokenizers import Whitespace tokenizer = Tokenizer(BPE(unk_token="[UNK]")) tokenizer.pre_tokenizer = Whitespace() trainer = BpeTrainer(vocab_size=30000, special_tokens=["[UNK]", "[CLS]", "[SEP]", "[PAD]", "[MASK]"], min_frequency=2) files = ["train.txt", "validation.txt"] tokenizer.train(files, trainer) tokenizer.save("my-tokenizer.json") 官方给出的训练时间参考：100MB 语料约 1–2 分钟，1GB 约 10–20 分钟。

适用场景

• 需要高速分词的大规模文本处理。
• 从零训练领域专用分词器。
• 需要 token 与原文位置对齐的 NER、问答、token 分类任务。
• 与 transformers 配合构建生产级 NLP 流水线。

限制与替代 官方建议在以下情况考虑替代方案：SentencePiece（语言无关，被 T5/ALBERT 使用）、tiktoken（OpenAI 的 BPE 分词器，用于 GPT 模型）、transformers AutoTokenizer（仅加载预训练，内部使用本库）。

性能参考（官方数据）

• 分词速度：纯 Python 处理 1GB 约 20 分钟（约 50 MB/min）；HF Tokenizers 约 15 秒（约 4 GB/min），约 80 倍加速。
• 训练速度（16 核 CPU，英文维基百科）：10MB 语料 BPE(30k) 约 15 秒、WordPiece(30k) 约 18 秒、Unigram(8k) 约 25 秒；100MB 分别约 1.5 分钟、2 分钟、4 分钟；1GB 分别约 15 分钟、20 分钟、40 分钟。
• 内存：加载分词器约 10MB；训练 BPE(30k) 约 200MB；编码 100 万句约 500MB。

支持的预训练分词器（通过 from_pretrained()） BERT 系列：bert-base-uncased、bert-large-cased、distilbert-base-uncased、roberta-base、roberta-large；GPT 系列：gpt2、gpt2-medium、gpt2-large、distilgpt2；T5 系列：t5-small、t5-base、t5-large、google/flan-t5-xxl；其他：facebook/bart-base、facebook/mbart-large-cc25、albert-base-v2、albert-xlarge-v2、xlm-roberta-base、xlm-roberta-large。完整列表见 https://huggingface.co/models?library=tokenizers。

资源 文档：https://huggingface.co/docs/tokenizers GitHub：https://github.com/huggingface/tokenizers 版本：0.20.0+ 课程：https://huggingface.co/learn/nlp-course/chapter6/1 论文：BPE (Sennrich et al., 2016)、WordPiece (Schuster & Nakajima, 2012)。

其他说明 资料中提供了面向智能体的操作流程与故障处理建议（如 CUDA 显存不足、损失为 NaN、版本 API 缺失、输入参数不明确等），并强调不得编造结果、参数、标识符、引用或统计，运行前需确认版本相关细节，涉及费用、共享 GPU、个人或患者数据及不可撤销操作前应先询问。