Transformers 聊天模板怎么用？把角色消息转成模型输入

把多轮聊天传给本地模型时，角色消息列表通常需要转换成模型训练时使用的格式。Transformers 的 apply_chat_template 可以完成转换，避免自己猜角色分隔符。下面用 Qwen2.5-0.5B-Instruct 的分词器，把 system 和 user 消息转成准备生成的输入；本篇只检查模板和 token，不下载模型权重或生成回答。

选择自带模板的聊天检查点

先安装 transformers==4.57.1。首次运行需要网络下载分词文件，已经保存完整文件时可以使用本地目录。选择 Qwen2.5-0.5B-Instruct 官方模型卡对应的检查点，卡片提供了同模型的聊天模板示例。模板必须与实际加载的模型对应，不能把别的模型的角色标记照搬过来。

from transformers import AutoTokenizer

checkpoint = "Qwen/Qwen2.5-0.5B-Instruct"
tokenizer = AutoTokenizer.from_pretrained(checkpoint)
if not tokenizer.chat_template:
    raise RuntimeError("检查点没有自带聊天模板，先查模型文档")

messages = [
    {"role": "system", "content": "只给出简短回答。"},
    {"role": "user", "content": "解释 token 是什么。"},
]
rendered = tokenizer.apply_chat_template(
    messages, tokenize=False, add_generation_prompt=True
)
print(rendered)

direct_ids = tokenizer.apply_chat_template(
    messages, tokenize=True, add_generation_prompt=True
)
second_step_ids = tokenizer(rendered, add_special_tokens=False)["input_ids"]
assert direct_ids == second_step_ids
print("输入 token 数:", len(direct_ids))

检查角色、结束符和回答起点

两条消息是人为编写的格式演示，不是模型的实际回答。在本地 Python 3.11、Transformers 4.57.1 检查中，渲染结果如下；本次只运行分词和模板转换。

<|im_start|>system
只给出简短回答。<|im_end|>
<|im_start|>user
解释 token 是什么。<|im_end|>
<|im_start|>assistant

验证方法是看 system、user 的顺序与内容都保留，各条已有消息有结束标记，最后停在 assistant 的回答起点，并且两种分词路径的 ID 列表一致。Transformers 聊天模板文档说明，add_generation_prompt=True 为支持它的模板添加开始新 assistant 消息的标记；有的模型不需要该标记，参数可能没有效果。

避免两次添加特殊 token

先得到字符串再分词时，使用 add_special_tokens=False。官方文档明确指出模板通常已经包含必要的特殊 token，再次默认添加可能造成重复。更直接的路径是 apply_chat_template(..., tokenize=True)，让模板方法一次完成。

若下一步需要 PyTorch 张量，可以在已安装 PyTorch 的环境调用 apply_chat_template(messages, tokenize=True, add_generation_prompt=True, return_tensors="pt", return_dict=True)。将得到的输入交给同一个检查点的模型。这里没有运行模型推理，因此不提供回答质量、耗时或硬件需求结论。

模板报错时按症状修复

• 提示没有 chat_template：先看加载的是不是聊天模型的 tokenizer。不要随便手写模板让报错消失，须找到对应检查点的训练格式。
• 角色不被支持：看该模型对 system、user、assistant 顺序的要求；示例中的三种角色不是所有模型都接受的统一合同。
• 希望续写已经开始的 assistant 内容：按官方文档使用 continue_final_message=True，同时关闭 add_generation_prompt。两者分别表示续写末条和开始新条，不能同时开启。
• 输入 token 数比预期多：检查重复特殊 token、重复历史消息和模板加入的角色标记。不要只数 user 文本。

模板转换通过只说明输入格式可解释；模型能否遵循 system 内容、回答是否可靠，还要在实际模型和任务上单独验证。建议先保留本例的 ID 一致性断言，再加入一轮真实对话，避免在整个应用接入后才发现模板不匹配。