LoRA adapter 合并后 tokenizer 配置如何核对

LoRA 合并完成后，最容易漏掉的不是权重文件，而是 tokenizer。merge_and_unload() 会把 adapter 层合入基础模型并返回一个普通 Transformers 模型；它不会替你判断该用哪个 tokenizer，也不会把 tokenizer 配置自动写进输出目录。稳妥做法是：从 adapter 配置确认基础模型来源，加载训练时使用的 tokenizer，模型和 tokenizer 一起保存，再重新加载核对。

先确认合并模型和 tokenizer 来自同一套基础模型

PEFT 的 adapter checkpoint 通常只保存增量参数和配置，合并时仍需要原始基础模型。第一步不要从输出目录反推 tokenizer，而是读取 adapter 配置中的 base_model_name_or_path，用它加载基础 tokenizer。训练期间如果额外添加过控制 token，则应优先使用训练脚本最后保存的 tokenizer 目录，而不是重新下载一个“看起来同名”的基础版本。

官方参考地址：https://huggingface.co/docs/peft/main/developer_guides/checkpoint

下面的示例只展示核对逻辑，不代表已经在本机执行：

from pathlib import Path
from peft import PeftConfig, PeftModel
from transformers import AutoModelForCausalLM, AutoTokenizer

adapter_dir = Path("./adapter")
merged_dir = Path("./merged-model")

# 读取 adapter 记录的基础模型来源，避免合并到错误的底座。
peft_config = PeftConfig.from_pretrained(adapter_dir)
tokenizer = AutoTokenizer.from_pretrained(peft_config.base_model_name_or_path)
base_model = AutoModelForCausalLM.from_pretrained(peft_config.base_model_name_or_path)
peft_model = PeftModel.from_pretrained(base_model, adapter_dir)

# merge_and_unload 返回普通模型；它不是原地修改，因此必须接住返回值。
merged_model = peft_model.merge_and_unload(safe_merge=True)
merged_model.save_pretrained(merged_dir)
tokenizer.save_pretrained(merged_dir)

核对 tokenizer 配置时，不要只比较词表长度

重新加载输出目录后，先比较长度，再比较会改变输入语义的字段。len(tokenizer) 包含基础词表和 added tokens；tokenizer.vocab_size 在部分实现中只代表基础词表，所以不要拿这两个值直接当成同一个指标。对生成模型，pad_token_id、eos_token_id、bos_token_id、unk_token_id 和 padding_side 是最值得留存的配置。

官方参考地址：https://huggingface.co/docs/transformers/main_classes/tokenizer

def tokenizer_snapshot(tokenizer):
    # 用稳定字段做快照，便于合并前后或训练目录与输出目录之间比较。
    return {
        "length": len(tokenizer),
        "special_tokens_map": tokenizer.special_tokens_map,
        "special_token_ids": {
            "pad": tokenizer.pad_token_id,
            "bos": tokenizer.bos_token_id,
            "eos": tokenizer.eos_token_id,
            "unk": tokenizer.unk_token_id,
        },
        "padding_side": tokenizer.padding_side,
        "truncation_side": tokenizer.truncation_side,
        "model_max_length": tokenizer.model_max_length,
        "added_vocab": tokenizer.get_added_vocab(),
    }

before = tokenizer_snapshot(tokenizer)
reloaded = AutoTokenizer.from_pretrained(merged_dir)
after = tokenizer_snapshot(reloaded)

# 先报告差异，再决定是否阻断发布；差异比静默覆盖更容易定位问题。
if before != after:
    raise ValueError({"tokenizer_changed": True, "before": before, "after": after})

如果只是 special_tokens_map 的序列化顺序不同，不要只比较 JSON 文本；应比较 token 名称、ID 和 added vocabulary 的实际映射。真正危险的是同一个字符串在合并前后得到不同 ID，或者 pad/eos 被换成了另一个 token。

新增 token 时，要把词表长度和嵌入尺寸一起核对

如果训练脚本调用过 add_tokens() 或 add_special_tokens()，仅保存 tokenizer 还不够。官方示例要求随后调用 model.resize_token_embeddings(len(tokenizer))，否则 tokenizer 可能产生超出模型嵌入范围的 ID。合并后可检查：

• len(reloaded_tokenizer) 是否等于训练阶段的 tokenizer 长度；
• merged_model.get_input_embeddings().num_embeddings 是否覆盖这组 ID；
• 使用了权重绑定的模型，输入嵌入与输出头是否仍符合该模型的设计。

vocab_length = len(reloaded)
embedding_rows = merged_model.get_input_embeddings().num_embeddings

# 新增 token 必须有对应的嵌入行；否则生成阶段可能出现 index out of range。
if embedding_rows 

交付前的四项检查清单

最后把模型配置、权重分片和 tokenizer 文件放在同一个交付目录，并保留一份快照差异。这样排查线上输入异常时，可以先判断是权重合并问题，还是 tokenizer 目录被替换、漏传或与模型版本错配。

常见问题

merge_and_unload 会自动保存 tokenizer 吗？

不会。它处理的是 PEFT adapter 与基础模型权重；tokenizer 需要显式调用 save_pretrained()。

tokenizer 的长度和 vocab_size 为什么可能不同？

部分 tokenizer 实现把 added tokens 计入 len(tokenizer)，而 vocab_size 只表示基础词表。检查嵌入尺寸时应以完整长度为准。

合并后输出目录能加载，是否就代表配置正确？

不一定。目录可加载只说明文件格式基本完整，还要比较特殊 token、added vocabulary、padding 配置，并做一次短文本编码。