Transformers 怎样按模型 chat template 组织消息

Transformers 里，聊天消息不能只看成一串普通文本。模型训练时可能使用了 、[INST] 或其他控制 token；即使两个模型来自同一个基础模型，它们的对话格式也可能不同。解决办法是：先加载目标模型对应的 tokenizer，再把统一的 role、content 消息列表交给 apply_chat_template，不要手写另一套模板。

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

本文只讨论 apply_chat_template 的消息组织和参数边界，不展开模型量化、服务部署或具体推理框架。示例使用 Hugging Face Transformers 官方接口，图片是帮助理解关系的静态说明图，不是软件截图或运行证据。

先把消息契约固定成 role 和 content

apply_chat_template 接受的是消息列表，每条消息至少包含 role 和 content。常见角色是 system、user 和 assistant：系统消息说明行为约束，用户消息表达输入，助手消息保存历史回答。真正决定控制 token 的不是这几个英文单词本身，而是目标 tokenizer 内保存的 chat_template。

from transformers import AutoTokenizer

# 目标模型和 tokenizer 必须来自同一个模型仓库
tokenizer = AutoTokenizer.from_pretrained("HuggingFaceH4/zephyr-7b-beta")

messages = [
    {"role": "system", "content": "你是一个简洁的技术助手。"},
    {"role": "user", "content": "解释 chat template 的作用。"},
]

# 让 tokenizer 根据模型自己的模板组织控制 token
prompt = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True,
)
print(prompt)

这里的关键不是记住 Zephyr 的标记，而是保证 tokenizer 与实际要调用的模型匹配。把 A 模型的 tokenizer 生成的文本送给 B 模型，代码可能不报错，但模型看到的角色边界可能已经偏离训练格式。

按用途区分文本查看和模型输入

调试模板时，可以先用 tokenize=False 得到格式化后的字符串，观察角色标记和助手起始位置；真正送进模型时，通常直接使用 tokenize=True，让模板渲染和 token 化保持在同一个调用里。

# 用文本模式查看模板结果，便于确认角色边界
rendered = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True,
)
print(rendered)

# 推理时直接得到模型需要的 token 输入
model_inputs = tokenizer.apply_chat_template(
    messages,
    tokenize=True,
    add_generation_prompt=True,
    return_tensors="pt",
    return_dict=True,
)

# 这里的字段会交给后续 generate；不再手动二次添加 bos/eos
print(model_inputs.keys())

如果先渲染成字符串，再调用 tokenizer 的普通编码接口，可能重复加入特殊 token。官方文档特别提醒：模板通常已经包含所需特殊 token；若确实采用“先字符串、后编码”，要明确考虑 add_special_tokens=False。直接使用 tokenize=True 通常更不容易出现重复。

推理时为什么通常要加 add_generation_prompt

推理对话的最后一条消息一般是 user。模型不仅需要看到这条问题，还需要知道接下来应开始生成 assistant 消息。add_generation_prompt=True 就是把这段“助手即将开始”的模板标记补到末尾。

# 生成新回答时，让模板明确指出下一个角色是 assistant
model_inputs = tokenizer.apply_chat_template(
    messages,
    tokenize=True,
    add_generation_prompt=True,
    return_tensors="pt",
    return_dict=True,
)

# 真实项目中还要把输入移动到模型所在设备，再调用 generate
outputs = model.generate(**model_inputs, max_new_tokens=128)

# 只截取新增 token，避免把原始提示再次当成回答输出
new_tokens = outputs[:, model_inputs["input_ids"].shape[-1]:]
answer = tokenizer.batch_decode(new_tokens, skip_special_tokens=True)
print(answer[0])

不是所有模型都需要这个额外标记，有些模板对它没有影响。因此判断标准不是“所有模型都传 True”，而是查看目标 tokenizer 的模板约定，并把生成任务与已有 assistant 历史区分开。

已有 assistant 内容时要用 continue_final_message

如果最后一条消息已经是 assistant，场景可能不是“开启一条新回答”，而是希望模型继续完成这条已有内容，例如预填一个 JSON 前缀。这时 continue_final_message=True 会移除末尾结束标记，让模型接着最后一条消息生成。

prefill_messages = [
    {"role": "user", "content": "请输出一个 JSON 对象。"},
    # assistant 内容是预填前缀，模型需要在它后面继续写
    {"role": "assistant", "content": '{"name": "'},
]

formatted = tokenizer.apply_chat_template(
    prefill_messages,
    tokenize=True,
    continue_final_message=True,
    return_tensors="pt",
    return_dict=True,
)

# continue_final_message 与 add_generation_prompt 不能同时使用
outputs = model.generate(**formatted, max_new_tokens=64)

两者的语义相反：add_generation_prompt 开始一条新的 assistant 消息，continue_final_message 则继续最后一条消息。把它们同时传入会产生参数冲突，遇到预填场景应明确选择后者。

训练预处理不要把 generation prompt 混进去

训练数据的每条样本通常已经包含完整的 user 和 assistant 内容，目标是把它格式化成与模型训练约定一致的序列。此时 add_generation_prompt=False 更合适，因为训练样本并不是在等待一个新的 assistant 空位。

def format_chat(example):
    # 训练样本已有完整回答，不额外打开新的 assistant 起点
    return {
        "text": tokenizer.apply_chat_template(
            example["messages"],
            tokenize=False,
            add_generation_prompt=False,
        )
    }

# 交给数据集 map；这里只负责把消息转换成模板文本
formatted_dataset = dataset.map(format_chat)
print(formatted_dataset[0]["text"])

训练和推理使用的是同一个模板契约，但最后一个参数的目的不同：推理要提示模型开始回答，训练要保留样本本身的完整对话。把推理参数原样复制到训练预处理，可能在每条样本末尾多出一个没有目标文本的 assistant 起点。

不同模型之间怎样降低模板错配风险

可以把模型调用拆成三个边界：消息边界、模板边界和输入边界。消息层只维护业务对象；模板层只由目标 tokenizer 负责；输入层只接收 apply_chat_template 返回的文本或 token。这样更换模型时主要替换 tokenizer 和模型标识，不需要在业务代码里重写控制 token。

上线前可以把上表变成代码评审清单：模型和 tokenizer 是否同源；消息是否保持稳定的 role/content 结构；推理、预填和训练是否只选择一种末尾语义；是否避免把模板已经提供的特殊 token 再加一遍。这个清单比为每个模型维护一段手写字符串更容易迁移。

常见问题

为什么同一组 messages 换模型后输出风格会变差？

消息对象相同不代表序列化结果相同。模型可能使用不同的角色控制 token，必须使用该模型自己的 tokenizer 和 chat template。

tokenize=False 适合直接传给 generate 吗？

它返回的是格式化文本，通常还需要按正确的特殊 token 规则再编码。直接推理更建议使用 tokenize=True，避免重复添加模板里的特殊 token。

add_generation_prompt 和 continue_final_message 怎么选？

新开一条 assistant 回答用前者；已有 assistant 前缀需要续写用后者，两者不要同时使用。

为什么训练时通常关闭 add_generation_prompt？

训练样本已经带有完整回答，额外加一个新的 assistant 起点没有帮助，还可能让样本末尾多出不需要的控制标记。

把 apply_chat_template 当作模型适配边界，业务代码只维护清晰的消息对象，推理和训练分别选择对应的末尾参数，就能在更换聊天模型时减少格式不兼容问题。