Qwen3.8-2.4T-A95B chat_template.jinja 源码剖析:工具调用与思考控制的 Jinja 模板如何编写
Qwen3.8-2.4T-A95B chat_template.jinja 源码剖析:工具调用与思考控制的 Jinja 模板如何编写
Qwen3.8-2.4T-A95B 是千问最新一代开源 2.4T 参数 MoE 大模型,其 chat_template.jinja 对话模板文件是理解它「工具调用」与「思考控制」两大核心能力的关键。本文面向新手,逐段拆解这份 142 行的 Jinja 模板,讲清楚它如何把一条消息列表拼装成模型能读懂的提示词,以及工具调用格式与思考深度控制逻辑是如何编写的。
一、chat_template.jinja:对话与模型提示词之间的「翻译官」 📌
在调用 Qwen3.8-2.4T-A95B 这类大模型时,你传入的是一组消息(system / user / assistant / tool),而模型真正接收的是「一整段拼接好的文本」。这中间的转换工作,就由 Jinja 模板文件 chat_template.jinja 完成——它定义了:
- 每类消息该包装成什么样式的标签;
- 工具声明和工具调用以什么格式书写;
- 思考过程(
think标签)何时保留、何时省略。
💡 除了独立文件外,同一份模板也内嵌在 tokenizer_config.json 中,推理框架(vLLM、SGLang 等)加载时会直接读取。
先认识一下这个模型
| 项目 | 规格 | 出处 |
|---|---|---|
| 架构 | MoE(512 专家,激活 10+1 个) | config.json |
| 参数量 | 2.4T 总参数 / 95B 激活 | README.md |
| 层数 | 92 层(线性注意力 + 全注意力混合) | config.json |
| 上下文 | 原生 262,144 tokens | README.md |
| 关键约束 | 纯文本模型,思考模式不可关闭 | README.md |
Jinja 语法速查表
读模板前,只需认识这几个符号(完整模板见 chat_template.jinja):
| 写法 | 作用 |
|---|---|
{{ 变量 }} |
输出变量内容 |
{% if %} / {% for %} |
条件判断与循环 |
{%- ... -%} |
修剪空白(控制输出里有多余空格) |
{% macro %} |
定义可复用的小函数 |
变量 | 过滤器 |
对变量做处理,如 tojson 转 JSON |
raise_exception('...') |
参数不合法时主动报错 |
模板运行时可用的变量有:messages(消息列表)、tools(工具定义)、add_generation_prompt(是否追加生成引导),以及思考控制三开关 enable_thinking、reasoning_effort、preserve_thinking。
二、模板结构拆解:消息拼装的五步流水线 ⚙️
整份 chat_template.jinja 可以按执行顺序拆成 5 个区块,建议对照源码阅读:
| 区块 | 行号 | 职责 |
|---|---|---|
① render_content 宏 |
L1-L17 | 统一渲染消息内容(字符串或 {"text": ...} 分片列表) |
| ② 参数校验 | L18-L33 | 检查消息非空、思考开关、推理强度是否合法 |
| ③ 系统提示词构建 | L34-L64 | 有工具时生成「工具声明 + 格式约束」,无工具时拼普通 system |
| ④ 多步工具检测 | L65-L78 | 倒序扫描,定位最后一条「真正的用户提问」 |
| ⑤ 逐条消息渲染 + 生成引导 | L79-L142 | 按角色渲染每条消息,最后追加 `assistant |
| ` 触发回答 |
几个值得新手注意的设计点:
- 内容渲染收口:无论消息内容是字符串还是分片列表,都经过
render_content这一个宏输出,遇到其他类型直接抛错(L1-L17),避免脏数据悄悄进入提示词。 - 严格校验:
messages为空、enable_thinking=False、reasoning_effort不在允许值内,都会立刻raise_exception报错,而不是静默降级——这让问题在「模板渲染阶段」就暴露出来。 - system 必须置顶:system 消息不是第一条时直接报错(L81-L84)。
三、工具调用格式:XML 风格对话如何渲染 🔧
Qwen3.8-2.4T-A95B 的工具调用采用 XML 标签风格(tool_call / tool_response),模板在三个地方与之配合:
1️⃣ 系统提示词里声明工具(L34-L52)
只要传入了 tools,模板就会生成一段固定的「工具说明书」:先把每个工具定义用 tojson 序列化放进 <tools> 块,再附上一段 <IMPORTANT> 格式约束,明确要求模型「调用函数时只按指定格式回复」。片段如下:
{{- "# Tools\n\nYou have access to the following functions:\n\n<tools>" }}
{%- for tool in tools %}
{{- "\n" }}
{{- tool | tojson }}
{%- endfor %}
{{- "\n</tools>" }}
2️⃣ assistant 消息里渲染 tool_calls(L98-L122)
如果 assistant 消息带 tool_calls 字段,模板会逐条拼出调用块:函数名进 <function=...>,参数逐个包装成 <parameter=名> 块。细节处理很讲究:
- 字符串参数原样输出;数字、布尔等非字符串参数自动
tojson(L115); - 一条消息里可有多个
tool_calls,连续拼接多个<function>块。
渲染后效果大致如下(工具返回结果被包进 user 轮次):
user
What's the weather in Hangzhou?
assistant
Let me check the weather.
<tool_response>
Sunny, 26°C
</tool_response>
user
assistant
Hangzhou is sunny today, 26°C.
3️⃣ 工具结果作为 tool 角色回填(L124-L135)
tool 角色的内容会被包进 tool_response 标签,并且自动套一层 user 轮次——连续的多个工具结果共享同一个 user 块,一轮工具结束才闭合。这样多步工具调用(模型 → 工具 → 模型 → 工具)在提示词里就形成了干净的交替结构。
💡 配套的「多步工具检测」(L65-L78)会倒序扫描消息:如果某条 user 消息整体被包在
tool_response标签里,说明它其实是工具回填结果而非真人提问。模板据此定位最后一条真正的用户提问;若整个会话连一条真提问都没有,直接抛出No user query found in messages.。
四、思考控制三开关:enable_thinking / reasoning_effort / preserve_thinking 🧠
Qwen3.8 的每次回答都自动以 think 标签开头(README 中明确 thinking 不可禁用),模板用三个参数精细控制思考行为:
| 参数 | 默认值 | 允许取值 | 作用 | 位置 |
|---|---|---|---|---|
enable_thinking |
True | 仅 True | 显式传 False 会直接报错 | L21-L23 |
reasoning_effort |
xhigh |
xhigh / medium / low |
注入不同思考指令,调节思考深度 | L24-L33 |
preserve_thinking |
True | True / False | 多轮对话中是否保留历史 think 内容 |
L88-L97 |
① 思考不可关闭,直接抛错(L21-L23):
{%- if enable_thinking is defined and enable_thinking is false %}
{{- raise_exception('Disabling thinking is not supported.') }}
{%- endif %}
这与 README.md 的说明一致:该模型所有交互都必须带思考,禁止关闭。
② reasoning_effort 用「软指令」控制深度(L24-L33):模板把参数与一段自然语言指令绑定,并拼进系统提示词开头:
{%- set resolved_reasoning_effort = reasoning_effort|default('xhigh') %}
{%- if resolved_reasoning_effort not in ('xhigh', 'medium', 'low') %}
{{- raise_exception('Unexpected reasoning effort ' ~ reasoning_effort ~ '...') }}
{%- endif %}
xhigh(默认):注入「仔细验证关键假设、权衡替代方案、优先保证正确性」的指令;low:注入「思考简短聚焦、直奔结论」的指令;medium:不注入额外指令,走模型默认行为。
这种「提示词工程 + 白名单校验」的写法,是控制大模型推理预算很实用的模式。
③ preserve_thinking 控制历史思考的去留(L88-L97):渲染历史 assistant 消息时,模板按条件决定写不写 think 块——preserve_thinking 为 True(或未传)时保留;设为 False 时,只有位于最后一条真正用户提问之后的 assistant 消息(即当前工具循环中的回复)保留思考,更早的历史思考一律丢弃,从而给长会话省下大量 token。
④ 生成引导(L140-L142):add_generation_prompt 为真时,末尾固定追加:
{{- 'assistant
' }}
这就是「回答永远先思考」的结构保证——生成从 think 内部开始,模型必须先写思考再写正式回答。
五、常见报错速查表:Jinja 模板避坑指南 ⚠️
模板内置了 6 处主动报错,遇到对应提示就能快速定位问题:
| 报错信息 | 触发条件 |
|---|---|
No messages provided. |
messages 传了空列表 |
Disabling thinking is not supported. |
显式传入 enable_thinking=False |
Unexpected reasoning effort ... |
reasoning_effort 不是 xhigh / medium / low |
No user query found in messages. |
所有 user 消息都是工具回填,没有真人提问 |
System message must be at the beginning. |
system 消息没放在第一条 |
Unexpected message role. |
出现 system / user / assistant / tool 之外的角色 |
六、关键要点回顾 ✅
- 模板是「格式契约」:Qwen3.8 的工具调用、思考标签全部由 chat_template.jinja 定义,自研推理框架时要保证渲染逻辑与它一致,模型才能稳定输出
tool_call/think结构。 - 工具调用走 XML 风格:工具定义 JSON 序列化进系统提示词的
<tools>块(L34-L52),调用用tool_call+function+parameter嵌套标签(L98-L122),结果回填为tool角色。 - 思考三件套:
enable_thinking只能为 True;reasoning_effort(xhigh/medium/low)通过注入指令调节深度;preserve_thinking决定多轮历史中思考内容的保留策略。 - 采样参数建议:
temperature=1.0, top_p=0.95, top_k=20,见 generation_config.json 与 README.md。 - 文件导航:模板主体见 chat_template.jinja,架构参数见 config.json,词表见 tokenizer.json,权重分片索引见 model.safetensors.index.json。
读懂这份模板,你就掌握了为大模型「设计对话协议」的完整思路——校验、声明、渲染、控制,四步缺一不可。