Qwen3.8-2.4T-A95B chat_template.jinja 源码剖析:工具调用与思考控制的 Jinja 模板如何编写

原创2026-10-18 21:10:241,889 阅读

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 之外的角色

六、关键要点回顾 ✅

  1. 模板是「格式契约」:Qwen3.8 的工具调用、思考标签全部由 chat_template.jinja 定义,自研推理框架时要保证渲染逻辑与它一致,模型才能稳定输出 tool_call / think 结构。
  2. 工具调用走 XML 风格:工具定义 JSON 序列化进系统提示词的 <tools> 块(L34-L52),调用用 tool_call + function + parameter 嵌套标签(L98-L122),结果回填为 tool 角色。
  3. 思考三件套:enable_thinking 只能为 True;reasoning_effort(xhigh/medium/low)通过注入指令调节深度;preserve_thinking 决定多轮历史中思考内容的保留策略。
  4. 采样参数建议:temperature=1.0, top_p=0.95, top_k=20,见 generation_config.json 与 README.md。
  5. 文件导航:模板主体见 chat_template.jinja,架构参数见 config.json,词表见 tokenizer.json,权重分片索引见 model.safetensors.index.json。

读懂这份模板,你就掌握了为大模型「设计对话协议」的完整思路——校验、声明、渲染、控制,四步缺一不可。

登录后查看全文
Qwen3.8-2.4T-A95B