Hugging Face Tokenizers 怎样保存自定义词表

如果你在领域语料中加入了产品名、缩写或代码标记，Hugging Face Tokenizers 的“自定义词表”通常有两种情况：给现有 Tokenizer 追加词条，或者重新训练一套词表。前者只需保存更新后的 Tokenizer 状态；后者要把训练得到的完整序列化结果保存下来。最稳妥的做法，是先明确保存对象，再选择 Tokenizer.save() 或 Transformers 的 save_pretrained()。

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

本文只讨论词表状态的保存与重新加载，不展开训练语料清洗、模型微调或推理性能。下面的打印结果是示例说明，不代表某台机器的实际运行结果。

一、先区分追加词条和重新训练词表

我在接入领域词条时，最容易踩的坑是把“新增几个 token”和“换一套词表”当成同一件事。add_tokens()解决的是前者：在现有分词流程上追加词条，返回实际新增的数量；如果词条已经存在，数量不会按重复项累加。重新训练则要通过训练器或 train_from_iterator() 生成新的词表状态，保存时不能只留一个手写的词条列表。

二、追加领域词条后保存 tokenizer.json

如果目标只是让产品名、接口名或领域缩写保持为独立词元，可以直接对已有 Tokenizer 调用 add_tokens()，然后把完整对象保存为 JSON。不要只把新增字符串写入文本文件，否则原来的模型、预分词器、后处理器和特殊词元配置都没有被一起保存。

from tokenizers import Tokenizer

# 从已有文件恢复完整的分词流程，再追加领域词条。
tokenizer = Tokenizer.from_file("base-tokenizer.json")
added = tokenizer.add_tokens(["订单号", "SKU_CODE", "warehouse_id"])

# 保存完整序列化状态，而不是只保存新增词条列表。
tokenizer.save("custom-tokenizer.json", pretty=True)
print(f"实际新增词条数: {added}")

added适合写入日志或发布记录，用来区分“调用成功”和“确实增加了多少词条”。pretty=True只影响 JSON 的可读格式，不改变词表语义；生产环境也可以省略它以减少文件体积。

三、重新加载后再交给 Transformers

保存后要复用，先用 Tokenizer.from_file()重新打开原生 JSON，再对一段包含新增词条的文本进行编码。这个检查只是在确认文件能被正确读取和映射，不等于模型已经拥有对应的词嵌入。

from tokenizers import Tokenizer

# 重新加载保存后的完整 Tokenizer 配置。
restored = Tokenizer.from_file("custom-tokenizer.json")
encoding = restored.encode("订单号 SKU_CODE")

# 输出词元与 id，便于确认自定义词条仍在映射范围内。
print(encoding.tokens)
print(encoding.ids)

如果后续代码使用 Transformers，可以把这个原生文件交给 PreTrainedTokenizerFast，再保存为一个目录。目录方式适合和模型配置、特殊词元映射一起交付；不要把原生 JSON 路径和 Transformers 目录混写成同一个文件名约定。

from transformers import PreTrainedTokenizerFast

# 将原生 Tokenizers 文件接入 Transformers 的快速分词器封装。
fast_tokenizer = PreTrainedTokenizerFast(tokenizer_file="custom-tokenizer.json")

# 目录保存封装后的状态，便于后续从目录整体恢复。
fast_tokenizer.save_pretrained("custom-tokenizer-hf")

四、保存后不生效时先看这几个边界

• 新增数量为零：先看 add_tokens()的返回值，零通常表示词条已存在，或输入没有形成新的词元。
• 只保存了词条文本：重新加载需要的是完整的 tokenizer.json，还要保留原来的模型、预分词器与后处理设置。
• 能分词但模型报尺寸错误：新增词条后，模型的词嵌入矩阵是否同步扩容属于模型侧问题，不能靠再次保存 Tokenizer 解决。
• 特殊词元混在普通词条里：需要特殊行为时，应使用对应的 special token 配置或 Transformers 的添加接口，不能只把字符串写进普通列表。

可以把落地清单压缩成三句话：追加词条用 add_tokens()，原生复用保存 tokenizer.json，接入 Transformers 再用 save_pretrained() 保存目录。这样文件职责清楚，后续排查也不会把“词表已保存”和“模型已适配”混为一谈。

总结与常见问题

Hugging Face Tokenizers 保存自定义词表的关键，是保存完整 Tokenizer 状态，而不是单独保存新增字符串。对现有对象追加词条后调用 save()；需要复用时用 from_file()载入；交给 Transformers 时再用 save_pretrained()保存目录。

重新加载后为什么新增词条没有按预期出现？

先确认读取的是刚保存的完整 JSON，再查看 add_tokens()的新增数量和编码结果；若词条本来已存在，返回数量为零并不代表保存失败。

保存 Tokenizer 后还需要改模型吗？

如果新增了词条并让模型使用它们，通常还要在模型侧同步词嵌入尺寸。Tokenizer 文件负责词元映射，不能替代模型参数变更。