Hugging Face chat template 怎么排查：add_generation_prompt、special tokens 与生成结果错位

模型换了一个 checkpoint，推理代码却完全没动，结果却从“正常回答”变成了复读用户问题。排查这类现象时，先别急着调 temperature 或 top_p：Hugging Face Transformers 里，消息列表最终会被 chat template 转成模型真正看到的 token 序列，少一个 assistant 起始标记，或者把 special tokens 加了两次，输出就可能从第一步开始走偏。

这类生成错位的问题绝大多数和采样参数无关，优先核对 chat template 的渲染结果、标记拼接规则，90%以上的场景都能快速定位根因。

先用 token 数量确认问题发生在哪一层

我更习惯把一次推理拆成三段看：消息对象、模板渲染结果、模型输入张量。只看最后生成的中文句子，很难判断是模型能力变化，还是输入在进入模型前已经多了一段控制标记。

下面用一个小消息列表做基线。tokenizer.apply_chat_template 会按照当前 tokenizer 自带的模板处理角色和结束标记，tokenize=True 则直接返回可以喂给模型的 token 张量。

from transformers import AutoTokenizer

model_name = "HuggingFaceH4/zephyr-7b-beta"
tokenizer = AutoTokenizer.from_pretrained(model_name)
messages = [
    {"role": "system", "content": "回答要短，并给出一个可验证的命令。"},
    {"role": "user", "content": "怎么确认 chat template 没有重复 special tokens？"},
]

rendered = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True,
)
model_inputs = tokenizer.apply_chat_template(
    messages,
    tokenize=True,
    add_generation_prompt=True,
    return_tensors="pt",
)
print(rendered)
print("input_tokens:", model_inputs.shape[-1])

这一步的基线至少要记住两项：渲染文本最后是不是 assistant 起始标记，输入 token 数量是否符合预期。模型换了以后，先对比这两项，比盯着生成长度更快。

add_generation_prompt 决定模型从谁的消息继续

聊天模型本质上还是在一段 token 序列后继续生成。消息列表停在 user 角色时，如果不追加生成提示，部分模板只会把序列停在用户消息的结束位置，模型没有明确看到“现在轮到 assistant 回答”的边界。

without_prefix = tokenizer.apply_chat_template(
    messages, tokenize=False, add_generation_prompt=False
)
with_prefix = tokenizer.apply_chat_template(
    messages, tokenize=False, add_generation_prompt=True
)

print("without:", repr(without_prefix[-80:]))
print("with   :", repr(with_prefix[-80:]))

不要把某个模型的具体控制字符串硬编码到业务代码里。不同模型的 assistant header 不一定相同，正确做法是让 tokenizer 的模板决定它是什么，并把渲染后的末尾片段记到调试日志中。

手动分词时最容易踩到 special tokens 重复

常见的兼容写法是先让模板输出字符串，再调用 tokenizer 进行分词。这时模板已经可能写入 BOS、EOS 或角色控制标记，第二次分词如果继续默认添加 special tokens，就会把它们再包一层。

rendered = tokenizer.apply_chat_template(
    messages, tokenize=False, add_generation_prompt=True
)
encoded = tokenizer(
    rendered,
    add_special_tokens=False,
    return_tensors="pt",
)
print(encoded["input_ids"].shape[-1])

如果不需要中间文本，直接使用 tokenize=True 更省心，因为模板和分词在同一次调用里完成。两条路径都能工作，但不要把“模板字符串 + 默认分词”当成无条件等价的替代品。

assistant 预填内容不要和新回复前缀叠加

另一种容易混淆的场景是：最后一条消息已经是 assistant，代码想让模型接着这段内容往下写。这不是“再开一个 assistant 回复”，而是继续当前消息，因此应使用 continue_final_message。

prefill = [
    {"role": "user", "content": "给出一个 JSON 对象，只保留 name 字段。"},
    {"role": "assistant", "content": "{"},
]
formatted = tokenizer.apply_chat_template(
    prefill,
    tokenize=False,
    continue_final_message=True,
)
print(repr(formatted[-100:]))

add_generation_prompt 的作用是追加新的 assistant 起始标记，continue_final_message 的作用是去掉末条消息的结束边界，让生成接在已有内容后面。两者同时传入会产生冲突，排查时先问清楚：你是在开启新回答，还是在补齐已有回答。

用三项验收数据把模板问题和模型问题分开

最小验收脚本不需要跑很长的生成。固定同一组 messages，分别记录渲染文本尾部、输入 token 数量和首个新 token 片段；换 checkpoint 或改模板后，只要这三项能解释清楚，再去调采样参数才有意义。

def inspect_prompt(tokenizer, messages):
    text = tokenizer.apply_chat_template(
        messages, tokenize=False, add_generation_prompt=True
    )
    ids = tokenizer(text, add_special_tokens=False)["input_ids"]
    return {
        "token_count": len(ids),
        "tail": text[-120:],
        "last_ids": ids[-8:],
    }

print(inspect_prompt(tokenizer, messages))

如果 token 数量突然多出一两个边界标记，先回到模板和分词参数；如果输入一致而首个新 token 仍然不同，才继续检查模型权重、dtype、采样器和停止条件。

常见问题

为什么同一份 messages 不同模型渲染出来的文本不一样？

chat template 存在 tokenizer 的配置中，不同模型可以使用不同的角色标记、换行和结束 token。不要直接复制另一个模型的控制字符串，先打印当前 tokenizer 的 chat_template 和渲染结果。

什么时候应该用 add_generation_prompt？

最后一条消息通常是 user、准备开启新的 assistant 回复时使用它。它会让模板追加表示 assistant 开始的控制片段。

continue_final_message 能和 add_generation_prompt 一起传吗？

不能把它们当成叠加开关。前者继续最后一条已有消息，后者开启一条新的 assistant 消息；需要预填时只保留前者。

为什么 tokenize=False 后的结果比直接 tokenize=True 长？

先检查二次分词是否默认添加了 special tokens。模板已经写入边界标记时，手动分词通常要设置 add_special_tokens=False，再比较两条路径的 token 数量。

把模板验收放在采样参数之前

chat template 是推理链路里很小、却很容易被忽略的一层。固定 messages，打印末尾前缀，记录 token 数量，再确认是否重复 special tokens，通常几分钟就能把“模型突然变笨”的问题缩小到输入边界。等输入序列稳定后，再讨论 temperature、top_p 或停止条件，调试结果才不会被错误模板掩盖。