在使用 vLLM 部署大语言模型(如 Qwen、DeepSeek、Llama 等)进行对话服务时,聊天模板(Chat Template) 是一个关键配置。它决定了模型如何理解用户输入、系统指令以及多轮对话的结构。
本文将介绍:
- 什么是聊天模板
- vLLM 对聊天模板的要求
- 如何为模型添加或自定义聊天模板
- 示例代码:从 LLaMA-Factory 提取并修复模板
一、什么是聊天模板?
聊天模板是一个 Jinja2 格式的模板字符串,用于将多轮对话(如用户输入、助手回复、系统提示)拼接成模型可以理解的输入格式。
例如,一个典型的聊天模板可能如下:
{% for message in messages %}
{% if message['role'] == 'user' %}
<|user|>{{ message['content'] }}<|end|>
{% elif message['role'] == 'assistant' %}
<|assistant|>{{ message['content'] }}<|end|>
{% endif %}
{% endfor %}
<|assistant|>
这个模板告诉模型:用户和助手的内容分别用什么标记包裹,如何拼接,以及模型应从哪个角色继续生成。
二、vLLM 对聊天模板的要求
vLLM 要求模型在 tokenizer_config.json
中必须包含 chat_template
字段。否则,vLLM 的 OpenAI 兼容 API 将无法处理聊天请求,会报错:
"Chat template is not defined for this model."
解决方案:
- 模型自带模板:如
NousResearch/Meta-Llama-3-8B-Instruct
,已经内置了聊天模板。 - 手动指定模板:使用
--chat-template
参数传入模板文件路径或模板字符串。 - 使用社区模板:vLLM 提供了一些常见模型的模板,位于
examples/
目录下。
三、LMDeploy 的模板支持(补充)
LMDeploy 也支持自定义对话模板,支持两种方式:
- 使用内置模板:通过
lmdeploy list
查看支持的模板名。 - 自定义模板:通过 JSON 文件配置模板字段,支持覆盖或注册新模板。
四、实战:从 LLaMA-Factory 提取并修复模板
以下是一个 Python 脚本,展示如何从 LLaMA-Factory 中提取 qwen
模板,并修复分词器的 chat_template
字段:
# mytest.py
import sys
import os
# 添加项目根目录到 Python 路径
root_dir = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
sys.path.append(root_dir)
from llamafactory.data.template import TEMPLATES
from transformers import AutoTokenizer
# 1. 加载分词器
tokenizer = AutoTokenizer.from_pretrained("/root/autodl-tmp/llm/deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B")
# 2. 获取模板对象
template_name = "qwen" # 可替换为其他模板名
template = TEMPLATES[template_name]
# 3. 修复分词器的 Jinja 模板
template.fix_jinja_template(tokenizer)
# 4. 输出模板内容
print("=" * 40)
print(f"Template [{template_name}] 的 Jinja 格式:")
print("=" * 40)
print(tokenizer.chat_template)
输出示例:
========================================
Template [qwen] 的 Jinja 格式:
========================================
{% for message in messages %}{% if message['role'] == 'user' %}<|im_start|>user
{{ message['content'] }}<|im_end|>
{% elif message['role'] == 'assistant' %}<|im_start|>assistant
{{ message['content'] }}<|im_end|>
{% endif %}{% endfor %}<|im_start|>assistant
五、在 vLLM 中使用模板部署模型
将上述模板保存为文件,例如 qwen-chat-template.jinja
,然后使用 vLLM 启动服务:
vllm serve /path/to/your/model \
--chat-template ./qwen-chat-template.jinja \
--served-model-name qwen-chat \
--max-model-len 2048
现在你就可以通过 OpenAI 兼容 API 进行对话了!
六、总结
工具 | 是否支持模板 | 模板来源 | 推荐方式 |
---|---|---|---|
vLLM | ✅ 支持 | 模型自带或手动指定 | --chat-template |
LMDeploy | ✅ 支持 | 内置或 JSON 配置 | JSON 文件 |
七、参考资料
- vLLM 官方文档:https://docs.vllm.ai/
- LLaMA-Factory 模板定义:https://github.com/hiyouga/LLaMA-Factory
- Hugging Face Chat Template 文档:https://huggingface.co/docs/transformers/main/en/chat_templating