Transformers 中的 Tokenizers 快分词器接入指南从 tokenizer_object 到 tokenizer_file 的完整实践【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers本文以 fast_tokenizers.md 为核心骨架结合当前仓库中PreTrainedTokenizerFast的源码实现系统讲解如何把用 Tokenizers 库独立训练出来的分词器无缝接入 Transformers 生态。读完本文你将掌握两种官方加载方式tokenizer_object与tokenizer_file的完整用法、背后的源码原理以及保存、复用与在 Transformers 内直接训练快分词器的进阶技巧。一、为什么需要把 Tokenizers 的分词器接入 Transformers Transformers 中的快分词器Fast Tokenizer由PreTrainedTokenizerFast类提供它的底层实现完全依赖 Tokenizers 库——一个用 Rust 编写的高性能分词库。相比纯 Python 实现的慢分词器快分词器在批处理、编码速度与内存占用上具有显著优势并且原生支持对齐alignment、偏移量offset mapping等特性是Pipeline与训练流程中推荐使用的默认实现。从源码看PreTrainedTokenizerFast实际上就是TokenizersBackend的别名PreTrainedTokenizerFast TokenizersBackend而TokenizersBackend继承自PreTrainedTokenizerBase是仓库中所有模型快分词器如BertTokenizerFast、LlamaTokenizerFast的共同基类。因此用 Tokenizers 训练出的任何分词器对象都可以被PreTrainedTokenizerFast包装从而立刻获得 Transformers 分词器共享的全部方法——__call__、encode、tokenize、decode、batch_encode_plus、save_pretrained等等。本文将从零开始用一个可运行的完整示例带你走通整条链路。二、第一步用 Tokenizers 训练一个基础分词器在接入 Transformers 之前我们先用 Tokenizers 库创建一个哑dummy分词器作为演示素材。下面的代码完整来自官方文档它使用BPE模型配合Whitespace预分词器在自定义文件列表上完成训练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])) trainer BpeTrainer(special_tokens[[UNK], [CLS], [SEP], [PAD], [MASK]]) tokenizer.pre_tokenizer Whitespace() files [...] # 例如 [train1.txt, train2.txt, ...] 的文本文件路径列表 tokenizer.train(files, trainer)几个值得注意的要点模型类型这里用的是BPE而 Tokenizers 还提供Unigram、WordLevel、WordPiece等模型。当前仓库源码中的MODEL_TO_TRAINER_MAPPING正好与之对应见 tokenization_utils_tokenizers.pyMODEL_TO_TRAINER_MAPPING { BPE: BpeTrainer, Unigram: UnigramTrainer, WordLevel: WordLevelTrainer, WordPiece: WordPieceTrainer, }这意味着无论你训练哪种模型后续都能被 Transformers 正确识别与加载。特殊 tokenBpeTrainer(special_tokens[...])会在训练时把[UNK]、[CLS]、[SEP]、[PAD]、[MASK]预留进词表这些 token 在接入 Transformers 后会被自动映射为对应的特殊 token 属性。训练数据tokenizer.train(files, trainer)接受一个文本文件路径列表。除了train Tokenizers 还提供train_from_iterator方法这一点在后面在 Transformers 内直接训练一节还会用到。训练完成后我们就拥有了一个可用的分词器对象。接下来有两种方式把它接入 Transformers直接从对象加载或先序列化为 JSON 文件再从文件加载。三、方式一从 tokenizer 对象直接加载tokenizer_object Transformers 的PreTrainedTokenizerFast类接受tokenizer_object参数可以直接用内存中的 Tokenizers 分词器对象完成实例化from transformers import PreTrainedTokenizerFast fast_tokenizer PreTrainedTokenizerFast(tokenizer_objecttokenizer)实例化之后这个fast_tokenizer就拥有了 Transformers 分词器的全部方法可以直接用于编码文本、批处理或配合Trainer、Pipeline使用。更多通用方法说明见 Tokenizer 主类文档。源码原理在TokenizersBackend.__init__中tokenizer_object的处理逻辑位于 tokenization_utils_tokenizers.pytokenizer_object kwargs.pop(tokenizer_object, None) gguf_file kwargs.pop(gguf_file, None) fast_tokenizer_file kwargs.pop(tokenizer_file, None) ... fast_tokenizer None if tokenizer_object is not None: fast_tokenizer copy.deepcopy(tokenizer_object) elif fast_tokenizer_file is not None and os.path.isfile(fast_tokenizer_file): # We have a serialization from tokenizers which let us directly build the backend fast_tokenizer TokenizerFast.from_file(fast_tokenizer_file)可以看到两个关键细节优先级tokenizer_object优先于tokenizer_file被处理两者同时传入时以对象为准。深拷贝源码使用copy.deepcopy(tokenizer_object)复制传入的对象避免外部对象与内部后端共享可变状态保证 Transformers 侧对 tokenizer 的后续修改如add_special_tokens、add_tokens不会意外污染你原来训练的 Rust 对象。四、方式二从 JSON 文件加载tokenizer_file对象加载方式适合在同一个进程内即训即用而生产环境通常希望把训练好的分词器序列化保存供后续或其它进程复用。 Tokenizers 提供了save方法将分词器完整导出为一个 JSON 文件tokenizer.save(tokenizer.json)保存出的tokenizer.json是 Tokenizers 的标准序列化格式它完整记录了模型的词表vocab、合并规则merges、预分词器、归一化器、后处理器以及训练时设置的 padding/truncation 配置。随后把该文件的路径通过tokenizer_file参数传给PreTrainedTokenizerFastfrom transformers import PreTrainedTokenizerFast fast_tokenizer PreTrainedTokenizerFast(tokenizer_filetokenizer.json)这样加载出的对象与方式一完全等价同样具备 Transformers 分词器的全部能力。源码原理在__init__的分支中tokenizer_file走的是TokenizerFast.from_file(fast_tokenizer_file)路径直接用 Rust 后端反序列化 JSON。而在更高层的convert_to_native_format类方法见 tokenization_utils_tokenizers.py中还包含一条更精细的解析逻辑当目标类有自定义__init__需要重建后端时它会从 JSON 中提取post_processor、padding、truncation以及precompiled_charsmap等配置并透传给下游——这正是许多模型专用 fast tokenizer如 T5、XLNet能从同一个tokenizer.json正确恢复行为的原因。五、保存与复用save_pretrained / from_pretrainedtokenizer.save()只是 Tokenizers 层面的序列化一旦包装成PreTrainedTokenizerFast你还可以使用 Transformers 标准的save_pretrained把分词器连同配置一起保存为完整的模型仓库目录之后用from_pretrained一键加载。save_pretrained的实现位于 tokenization_utils_tokenizers.py。# 保存到目录会生成 tokenizer.json、tokenizer_config.json、special_tokens_map.json 等 fast_tokenizer.save_pretrained(my_fast_tokenizer/) # 从目录或 Hub 仓库加载 from transformers import PreTrainedTokenizerFast reloaded PreTrainedTokenizerFast.from_pretrained(my_fast_tokenizer/)这一流程的关键常量定义在 tokenization_utils_tokenizers.pyTOKENIZER_FILE tokenizer.json SPECIAL_TOKENS_MAP_FILE special_tokens_map.json TOKENIZER_CONFIG_FILE tokenizer_config.json TIKTOKEN_VOCAB_FILE tokenizer.model也就是说save_pretrained会把当前后端序列化为标准的tokenizer.json并额外写出tokenizer_config.json与special_tokens_map.json——前者记录初始化参数init_kwargs后者记录特殊 token 的映射关系。因此当你用tokenizer_object方式加载时如果设置了unk_token、pad_token等属性它们也会被一并持久化保证下次加载时行为一致。小贴士tokenizer.save(tokenizer.json)与save_pretrained产出的都是tokenizer.json区别在于前者只有序列化数据后者则包含 Transformers 侧需要的全套配置文件更推荐用于模型仓库的组织方式。六、进阶在 Transformers 内直接训练快分词器除了把外部训练好的 tokenizer 装进来TokenizersBackend还提供了train_new_from_iterator类方法可以直接从一个PreTrainedTokenizerFast实例出发、基于文本迭代器训练出新分词器。其实现位于 tokenization_utils_tokenizers.py核心流程如下trainer_class MODEL_TO_TRAINER_MAPPING[tokenizer_json[model][type]] trainer trainer_class(vocab_sizevocab_size, special_tokensspecial_tokens, **kwargs) tokenizer.train_from_iterator(text_iterator, lengthlength, trainertrainer)典型用法是从一个已有的预训练分词器例如 BERT 的 WordPiece出发在新领域语料上训练一个同模型类型的新词表from transformers import AutoTokenizer old_tokenizer AutoTokenizer.from_pretrained(bert-base-uncased) trainer old_tokenizer.train_new_from_iterator(text_iterator, vocab_size30000) new_tokenizer trainer.get_pre_tokenizer() # 或直接使用返回的新分词器对象需要说明train_new_from_iterator只继承原有分词器的模型类型与预分词配置如Whitespace、ByteLevel等词表与合并规则则完全由新语料重新学习。训练返回的新 tokenizer 同样可以通过tokenizer_object包装或直接继续使用。若训练后需要调整特殊 token可结合add_special_tokens/add_tokens完成。七、补充慢分词器到快分词器的转换机制除了 Tokenizers 训练产物Transformers 仓库还内置了一套慢转快slow-to-fast转换体系位于 convert_slow_tokenizer.py。当模型仓库只提供 SentencePiece 的.model文件、vocab.txt或 tiktoken 词表而没有tokenizer.json时convert_to_native_format会按优先级依次尝试见 tokenization_utils_tokenizers.pyTekken 词表Mistral 系调用MistralConverter转换SentencePiece 模型.model后缀调用SentencePieceExtractor与各模型专属的SpmConverter失败时回退到TikTokenConverter标准 vocab/merges 文件直接读取vocab.txt与merges.txt并为 BPE 模型自动生成 mergesgenerate_merges跳过特殊 token。这套机制意味着即使你只有传统的慢分词器权重文件AutoTokenizer.from_pretrained也能在后台构建出对应的快分词器后端。而本文介绍的tokenizer_object/tokenizer_file两种方式则是从 Tokenizers 生态直接进入 Transformers 的最短路径。八、常见问题与注意事项tokenizer_object与tokenizer_file同时传入源码中对象优先于文件文件分支仅在对象为None时触发。特殊 token 一致性训练时的special_tokens列表决定了[CLS]、[SEP]等 token 的词表位置。加载后如发现 Transformers 侧pad_token等属性缺失请手动设置例如fast_tokenizer.pad_token [PAD]再执行save_pretrained持久化。文件路径有效性tokenizer_file分支要求os.path.isfile(fast_tokenizer_file)为真路径不存在时不会自动回退到对象加载请先确认 JSON 文件已正确生成。Unigram 模型的 JSON 解析convert_to_native_format对 UnigramSentencePiece模型保留了完整的from_file加载路径因为该模型在 Rust 侧初始化时要求非空词表这是加载如 Albert、T5 等 SentencePiece 系 fast tokenizer 时需要留意的底层限制。深拷贝语义tokenizer_object传入的对象会被copy.deepcopy外部后续修改不会同步到 Transformers 内部反之亦然——如有同步需求请重新实例化。结语从 Tokenizers 到 Transformers 的桥接非常轻量训练好的分词器对象用一行PreTrainedTokenizerFast(tokenizer_object...)即可接入序列化后的 JSON 文件用PreTrainedTokenizerFast(tokenizer_file...)同样一行搞定。二者的底层都由 TokenizersBackend 统一接管并在save_pretrained/from_pretrained的配合下形成训练 → 保存 → 加载 → 复用的完整闭环。结合仓库中的转换体系与train_new_from_iterator无论你手头是 Tokenizers 训练产物、传统慢分词器权重还是想直接在 Transformers 内重训词表都能找到对应的官方路径。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考