ValueError: unk_token should not be set in dumping mode when additional_special_tokens is None

快速结论：这个报错/异常通常出现在加载那些 tokenizer_config.json 里同时带有 additional_special_tokens 和 extra_special_tokens 两个键的 checkpoint 时，Transformers 在 from_pretrained 过程中会把 additional_special_tokens 弹出后丢弃，导致 tokenizer 收到两个键都为 None 的尴尬状态，对依赖 additional_special_tokens is None 分支判断的 trust_remote_code tokenizer 就会直接抛错。优先确认你的 checkpoint 的 tokenizer_config.json 是否同时包含这两个键，以及是否升级到包含修复 PR 的版本。

适用环境：Issue 中已确认的信息为：Transformers 5.14.1 复现，5.17.0 仍然复现；Platform 为 Linux-6.12.58-82.121.amzn2023.x86_64；Python 3.12.11；huggingface_hub 1.26.0；Safetensors 0.8.0；Accelerate 1.14.0；PyTorch 2.11.0+cu130；tokenizers 0.22.2；tiktoken 0.13.0。回归引入于 b76caaa88d9d（#43230，v5.1.0），v5.0.0 不受影响。

最快修复方案：Issue 中尚未在正式发布版落地一步修复；社区已在 PR #47848 中提交了针对 tokenization_utils_base.py 的受保护转换写法和回归测试，维护者回复“should be merged within a day”。在 PR 合入并发布新版本前，可以优先尝试：升级到包含该 PR 的 Transformers 版本；若无法升级，可在本地把 tokenizer 初始化时的 additional_special_tokens 显式转成 extra_special_tokens 传入（属于绕过思路，不是官方已验证的一步修复）。

注意事项：该问题的第二种表现是静默正确性 bug，即被 checkpoint 明确声明为 special 的 token 不再被当作 special，而 len(tokenizer) 与普通文本的 encode() 结果不变，只有 all_special_tokens / all_special_ids 会缩小，因此很容易被忽略。Issue 中列出的受影响 checkpoint（如 allenai/Molmo2-8B、baidu/ERNIE-4.5-*、mistralai/Mistral-Large-3-675B 等）只是本地缓存语料的统计，不代表全部；是否受影响仍需以自己 checkpoint 的 tokenizer_config.json 实际内容为准。

问题场景

用户在 Transformers 5.x 上通过 AutoTokenizer.from_pretrained 加载 checkpoint，或直接调用公开的 add_special_tokens() API 时触发该问题。触发条件是 checkpoint 的 tokenizer_config.json 中同时存在非空的 additional_special_tokens 以及 extra_special_tokens 键。对于 trust_remote_code 的 tokenizer（其 __init__ 会按 additional_special_tokens is None 分支判断），会走“未提供 special tokens、自动推断”的路径并抛出异常；对于其他 tokenizer，则是静默丢失 special token 标记。

报错原文

ValueError: unk_token should not be set in dumping mode when additional_special_tokens is None

原因分析

Issue 中给出的根因是 src/transformers/tokenization_utils_base.py 中两个 v5 向后兼容垫片使用了如下表达式，把已废弃的 additional_special_tokens 参数转换成 extra_special_tokens：

init_kwargs.setdefault("extra_special_tokens", init_kwargs.pop("additional_special_tokens"))

Python 会在调用前先求值所有参数，所以 .pop(...) 总会执行。当 extra_special_tokens 已经存在（例如 tokenizer_config.json 同时带有两个键）时，setdefault 不会覆盖已有值，被弹出的 additional_special_tokens 列表直接被丢弃，最终 tokenizer 两个键都拿不到。

受影响的位置是第 1813 行（PreTrainedTokenizerBase._from_pretrained，影响每次 from_pretrained 加载）和第 1169 行（PreTrainedTokenizerBase.add_special_tokens，影响公开 API）。同一文件第 997 行 PreTrainedTokenizerBase.__init__ 已经使用了正确的显式保护写法，因此三处转换逻辑不一致。回归由 b76caaa88d9d（#43230，2026-01-29 合入）引入，影响 v5.1.0 到当前 main，v5.0.0 不受影响。

环境排查

确认 Transformers 版本：Issue 在 5.14.1 复现，5.17.0 仍复现，v5.0.0 不受影响。
确认 Python 版本：Issue 环境为 3.12.11。
确认 PyTorch 版本：Issue 环境为 2.11.0+cu130。
确认 tokenizers 版本：Issue 环境为 0.22.2；tiktoken 0.13.0。
确认 huggingface_hub 1.26.0、Safetensors 0.8.0、Accelerate 1.14.0。
检查出问题的 checkpoint 的 tokenizer_config.json 是否同时包含 additional_special_tokens 与 extra_special_tokens 两个键。
确认 tokenizer 是否使用 trust_remote_code，这类 tokenizer 更容易触发硬失败。

解决步骤

先定位 checkpoint：打开对应 tokenizer_config.json，确认是否同时存在非空的 additional_special_tokens 和 extra_special_tokens。
若确认命中，优先升级到包含修复 PR #47848 的 Transformers 版本。维护者回复该 PR 预计一天内合入。
若暂时无法升级，可优先尝试的绕过方式：在本地加载 tokenizer 之前，先将配置文件中的 additional_special_tokens 合并进 extra_special_tokens，避免两个键同时存在；或显式把期望的 special tokens 通过 extra_special_tokens 传给 tokenizer 初始化。
对使用 trust_remote_code 的 tokenizer，如果其 __init__ 以 additional_special_tokens is None 做分支，可优先尝试在调用侧显式传入 special tokens，避免走到自动推断路径。
若上述方式都无法解决，保持版本信息、完整报错堆栈和 tokenizer_config.json 关键片段，在原 Issue 或 PR #47848 下反馈验证结果。

验证方法

加载 tokenizer 后检查 all_special_tokens 和 all_special_ids，确认 checkpoint 在 additional_special_tokens 中声明的 token 仍然出现在这两个属性中，而不仅仅看 len(tokenizer) 或普通文本的 encode() 输出——后者即使出问题也不会变化。Issue 评论中提到的手工复现方式也可复用：保存任意 tokenizer 后手工向 tokenizer_config.json 同时写入两个键，重载并检查 _extra_special_tokens 以及被丢弃的 token 是否重新出现在 special tokens 集合中。