Gemma-4 Chat Template 深度解析:工具调用与思考通道如何实现

原创2026-10-17 20:28:481,699 阅读
文章标签:大模型微调模型量化

Gemma-4 Chat Template 深度解析:工具调用与思考通道如何实现

Gemma-4 E2B 的官方 Chat Template 采用 Jinja 模板实现工具调用(tool calling)与思考通道(thinking channel):<|tool_call> 声明、<|channel>thought 推理块,配合 18 个自定义特殊 token 与 gemma4 解析器。本仓库 gemma-4-e2b-it-OptiQ-4bit-decision 正是基于该模板的 4-bit 决策模型,适合在 Apple Silicon 上本地运行。

什么是 Chat Template

Chat Template(聊天模板)是大模型推理前的"翻译官":你传给它一组对话消息(user / assistant / system),它还给你一串拼接好特殊标记的纯文本——模型只认这种格式。

Gemma-4 的模板由 Google Gemma 团队发布(2026-07-09),文件注释里写明了本次修复的三个重点:🎯

Fixed tool-calling loops, turn closures, and thinking content-ordering. —— 修复了工具调用循环、轮次闭合、思考内容排序

完整模板见 chat_template.jinja,全文约 386 行,是读懂 Gemma-4 消息协议的最佳入口。

18 个特殊 token:Gemma-4 的"词汇表"

在 tokenizer_config.json 中,官方为 Gemma-4 定义了一套结构化的特殊 token(model_specific_special_tokens),全部是单 token 原子单位:

Token 作用 通道
<|turn> / <turn|> 轮次开始 / 结束 对话结构
<|channel> / <channel|> 通道开始 / 结束 思考通道
<|think|> 思考模式开关 思考
<|tool> / <tool|> 工具声明块 工具调用
<|tool_call> / <tool_call|> 工具调用块 工具调用
<|tool_response> / <tool_response|> 工具结果块 工具调用
<|" |> 字符串转义引号 通用
<|image|> <|audio|> <|video|> 多模态占位符 多模态

规律很清晰:每个语义块都是"开头 token + 内容 + 结尾 token"配对出现。这套词汇让模型生成时边界明确,解析器也能用正则精准切块。

工具调用:三段式协议

Gemma-4 的工具调用分三步走:声明 → 调用 → 回执。

1. 工具声明:写在 system 轮里

开启工具时,模板把每个工具渲染进第一条 system 消息(chat_template.jinja#L207-L215):

<|turn>system
<|tool>
declaration:get_weather{description:"Get the weather",parameters:{properties:{city:{type:<|"|>STRING<|"|>}},required:[<|"|>city<|"|>]}}
<tool|>
<turn|>

注意三个细节:

  • 参数名、字符串值、类型名都用 <|"|> 引号包裹——这是 tokenizer 的 escape token,防止 JSON 内容里的引号破坏解析;
  • 类型统一大写(STRING、ARRAY、OBJECT),由 format_parameters 宏递归渲染嵌套 schema(chat_template.jinja#L7-L91);
  • 工具可以声明 response schema,让模型知道工具会返回什么结构(chat_template.jinja#L112-L121)。

2. 工具调用:call:函数名{参数}

模型决定调用工具时,生成的是紧凑的一行式文本(chat_template.jinja#L244-L266):

<|tool_call>call:get_weather{city:"Paris"}<tool_call|>

call:name{args} 这种写法省 token 且不易歧义。配套的解析正则定义在 tokenizer 的 response_schema 中:x-regex: call:(?P<name>\w+)(?P<arguments>\{.*\}),并按 <|tool_call>(.*?)<tool_call|> 迭代切分多个调用。

还有一个贴心设计:如果传进来的 arguments 是 JSON 字符串而不是对象,模板会直接抛异常要求先反序列化(chat_template.jinja#L255-L261),避免"字符串套 JSON"的隐蔽 bug。

3. 工具回执:自动前向扫描

这是模板最"聪明"的部分。OpenAI 风格的消息流里,工具结果是一条独立的 role: "tool" 消息,而模板要求把它塞回前一条 assistant 轮次内(chat_template.jinja#L276-L320):

  1. 遇到带 tool_calls 的 assistant 消息后,模板向前扫描后续所有连续的 role: tool 消息;
  2. 通过 tool_call_id 匹配回函数名;
  3. 渲染成 <|tool_response>response:get_weather{...}<tool_response|> 并就地插入;
  4. 工具返回图片/音频/视频部件时,还会追挂 <|image|>、<|audio|>、<|video|> 占位符。

效果是:调用与回执在同一个轮次内闭环,模型看到"我问了工具 → 工具答了"是完整一段上下文,而不是被拆散的消息。同时模板也兼容 Google 原生的 tool_responses 字段写法(嵌在 assistant 消息里),两种生态都能接。

思考通道:thought 块的三个开关

Gemma-4 的推理过程不塞进正文,而是走独立的"通道"(channel):

<|channel>thought
先想想:用户要的是天气……
<channel|>

模板用三个变量控制思考行为(chat_template.jinja#L186-L187):

变量 默认 作用
enable_thinking false 开启思考:在第一条 system 轮的顶部注入 <|think|> 开关 token(L193-L196)
preserve_thinking false 跨轮保留历史 assistant 消息的思考内容(即使它们发生在更早的 user 轮之前)
reasoning / reasoning_content — 历史消息里的思考文本,被渲染回 <|channel>thought…<channel|> 通道(L238-L242)

这里有个关键的"推理守卫"逻辑(chat_template.jinja#L218-L224):模板先预扫描找到最后一条 user 消息的位置,只有出现在它之后的历史思考才默认渲染。含义是——模型不需要"回忆"很久以前的推理过程,只保留当前这轮之前的上下文,既省 token 又聚焦。

思考与工具调用如何共处

生成提示(add_generation_prompt)的收尾处理体现了官方对内容排序的考量(chat_template.jinja#L380-L386):

  • 上一步是普通对话 → 追加 <|turn>model\n,模型直接作答;
  • 上一步是 tool_call 且还没收到回执 → 追加 <|tool_response>,催模型等待/生成工具结果边界;
  • 上一步是 tool_response 且开了思考 → 追加 <|channel>thought\n,强制模型先想一步再答复。

这就是注释里说的 "thinking content-ordering" 修复:工具返回后,思考通道严格排在新回复之前,顺序不再漂移。

另外,strip_thinking 宏(chat_template.jinja#L156-L166)会在把历史 assistant 正文放回上下文时剥掉其中的思考块——正文归正文、思考归通道,互不污染。

端到端:一轮带工具对话的完整渲染

把上面拼起来,一次"查天气"对话渲染后的 token 流大致如下:

<bos>
<|turn>system
<|think|>
你是天气助手。
<|tool>declaration:get_weather{description:"Get the weather",parameters:{properties:{city:{type:<|"|>STRING<|"|>}},required:[<|"|>city<|"|>]}}<tool|>
<turn|>
<|turn>user
巴黎今天天气如何?
<turn|>
<|turn>model
<|channel>thought
用户问巴黎天气,需要调用 get_weather。
<channel|>
<|tool_call>call:get_weather{city:"Paris"}<tool_call|>
<|tool_response>response:get_weather{value:"sunny, 24C"}<tool_response|>
<turn|>
<|turn>model
<|channel>thought
工具已返回晴天 24°C,可以直接回答。
<channel|>
巴黎今天晴朗,气温 24°C。

模型侧的解析全靠 tokenizer 中的 response_schema:整段输出被 x-regex 切成 thinking、tool_calls、content 三个命名捕获组——tool_parser_type 被标记为 gemma4,推理框架据此选用对应解析器。

如何在本仓库使用

本仓库是一个决策模型(optiq lora train --decision 训练产物),完整文件清单:

文件 说明
model.safetensors 4-bit 主干(约 5.4 GB 合计)
adapters.safetensors / adapter_config.json LoRA 适配器(rank 16)
optiq/optiq_vision.safetensors 视觉侧车
joint_head.safetensors / joint_head_config.json 联合 schema 头:一次推理打分 noul / choice / score 三类问题
decision_config.json / kv_config.json 决策与 KV 配置
generation_config.json 采样参数(top_k 64、top_p 0.95,含多个 EOS id)

运行方式很简单:

pip install -U mlx-optiq
optiq serve --model mlx-community/gemma-4-e2b-it-OptiQ-4bit-decision

服务通过 /v1/systemone 暴露,官方基准成绩:400 例测试集(2000 个决策)准确率 0.802,p50 延迟 0.99s(M3 Max)。详见 README.md。

小结:官方模板的三个设计亮点

  1. 原子 token 词汇表:每个语义块都有成对 token,解析零歧义,正则即可还原结构;
  2. 工具循环自闭环:前向扫描 + tool_call_id 匹配,把回执自动拼回同一轮次,修复了历史上的"工具调用死循环"问题;
  3. 思考通道可开关、可裁剪:enable_thinking / preserve_thinking 双开关 + 最后 user 位置的推理守卫,让推理内容既不丢失也不冗余。

如果你要给自己的 Agent 接 Gemma-4,建议通读一遍 chat_template.jinja,再对照 tokenizer_config.json 里的 token 表与 response_schema——这三样东西合起来,就是 Gemma-4 完整的前后协议。

登录后查看全文
gemma-4-e2b-it-OptiQ-4bit-decision