Gemma 4 Chat Template完全指南：Tool Calling与Thinking模式进阶技巧

Gemma 4 Chat Template完全指南Tool Calling与Thinking模式进阶技巧gemma-4-26B-A4B-it-w4a4-mxfp4是 Google Gemma 426B 激活 4B 的 MoE 多模态模型的 W4A4 MXFP4 量化版本专为 vLLM Ascend 部署优化在 GPQA Diamond 上仍保持 81.31% 的高精度。这篇文章聚焦它最实用的两大能力——Chat Template 中的 Tool Calling工具调用与 Thinking思考模式带你快速掌握特殊 Token、enable_thinking参数和多轮工具闭环的进阶用法。 建议先 clone 仓库到本地配合文中文件路径边看边学git clone https://gitcode.com/Eco-Tech/gemma-4-26B-A4B-it-w4a4-mxfp41. 为什么 Chat Template 值得深入研究很多人拿到模型只会对话其实模型能不能可靠地调工具、能不能先想后答几乎全部由 Chat Template 决定。本仓库的 chat_template.jinja 是 Gemma 4 的官方 Canonical 模板官方注释明确写了它的定位Template: Google Gemma 4 Canonical Chat Template Context: Fixed tool-calling loops, turn closures, and thinking content-ordering.也就是说它专门修复了三类高频痛点工具调用循环断裂、轮次turn未正确闭合、思考内容与正文的顺序错乱。下表是本仓库与本文最相关的文件建议收藏文件作用chat_template.jinjaJinja 聊天模板定义对话/工具/思考的拼接规则tokenizer_config.json特殊 Token 定义与输出解析规则response_schemageneration_config.json默认采样参数temperature: 1.0、top_k: 64、top_p: 0.95config.json模型结构128 专家 MoE激活 8 个、262144 上下文gemma-4-26B-A4B-it_best_practice.yamlMXFP4/MXFP8 量化配方注意力 MXFP8 专家 MXFP4 补充该模型是多模态架构模板同样内置了\|image\|、\|audio\|、\|video\|占位符多模态输入会自动替换成这些特殊 Token。2. 核心机制特殊 Token 一览先建立全局认知Gemma 4 的对话由一套结构化标记驱动全部定义在 tokenizer_config.json 中Token作用\|turn/turn\|一轮对话的开始 / 结束turn 即发言回合\|channel/channel\|思考通道的开始 / 结束\|think\|开启思考模式的总开关 Token系统轮开头\|tool/tool\|工具声明块的开始 / 结束\|tool_call/tool_call\|模型发起调用的开始 / 结束\|tool_response/tool_response\|工具执行结果的开始 / 结束\|\|字符串值的转义定界符Gemma 4 的引号一个普通单轮对话渲染后的骨架是这样的用特殊 Token 标注bos|turnsystem 你是一个乐于助人的助手。 turn| |turnuser 帮我查一下今天的天气 turn| |turnmodel |channelthought channel| 今天北京晴26℃。 turn|三条关键规则帮你建立正确的直觉一切皆轮次每段发言都被\|turn角色 ... turn\|包住角色只有system、user、model思考与正文分通道思考写在\|channelthought ... channel\|里正文在通道外字符串必须用\|\|包裹这是 Gemma 4 独有的转义约定模板渲染和输出解析都依赖它。3. Tool Calling 完全指南让模型学会动手3.1 第一步声明你的工具传入tools参数后模板会把每个函数定义包进\|tool ... tool\|块统一放在首个 system 轮里chat_template.jinja。声明长这样|tool declaration:get_weather{description:||查询指定城市的实时天气||,parameters:{ properties:{city:{description:||城市名||,type:||STRING||}}, required:[||city||], type:||OBJECT||} } tool|注意几个细节类型统一大写STRING、OBJECT、ARRAY字符串值用\|\|包裹模板会自动按字母序排序参数dictsort并支持嵌套对象、数组、enum、nullable等完整 JSON Schema 特性chat_template.jinja。3.2 第二步模型发起调用tool_call当模型决定调用工具时它会输出call:函数名{参数}格式chat_template.jinja|tool_callcall:get_weather{city:||北京||}\ tool_call|⚠️新手最常踩的坑传入历史消息里的function.arguments必须是已解析的 JSON 对象不能是字符串模板会直接抛出明确错误chat_template.jinjachat_template: tool_calls[].function.arguments must be a JSON object (mapping), not a string. Deserialize arguments before passing to the template.解法把框架OpenAI SDK、vLLM 等返回的arguments字符串先json.loads反序列化再回填到对话历史。3.3 第三步回填工具结果完成闭环工具执行后把结果作为role: tool的消息回填模板会渲染成响应块chat_template.jinja|tool_responseresponse:get_weather{value:{city:||北京||,temp:26}}tool_response|模板会自动通过tool_call_id把结果和对应的tool_calls[].id匹配起来chat_template.jinja多路并行调用时也不会张冠李戴。3.4 进阶技巧多轮闭环 并行调用 思考联动完整的多轮工具对话渲染后是这样的结构注意工具调用与思考被合并进同一个 model 轮|turnmodel |channelthought 用户想查天气需要调用 get_weather 工具 channel| |tool_callcall:get_weather{city:||北京||}\ tool_call| |tool_responseresponse:get_weather{value:26} tool_response| |channelthought 查到了26 度直接回答 channel| 今天北京 26℃适合出行。 turn|三个进阶点思考会跟着循环走每次发起调用前模板都允许模型先写一段 thought 再决定调哪个工具chat_template.jinja 会在工具结果后追加\|channelthought——这正是先想后调能力的来源连续两条 assistant 消息如思考一轮 回答一轮会被自动合并进同一个 model 轮chat_template.jinja你不必手动拼工具结果支持多模态content里混入image/audio/video类型时会自动插入\|image\|等占位符chat_template.jinja。3.5 输出怎么解析别写正则用内置 schema好消息是解析规则已经内置在 tokenizer 配置里无需手写正则。tokenizer_config.json 的response_schema定义了x-regex: (\|channelthought\n(?Pthinking.*?)channel\|)? (?Ptool_calls\|tool_call.*tool_call\|)? (?Pcontent...)?即模型输出被拆成三段thinking、tool_callscall:名称{参数}且参数按gemma4-tool-call解析器解析、content。现代推理框架会自动按此 schema 结构化返回你直接拿到thinking、tool_calls、content三个字段即可。4. Thinking 模式完全指南让模型先想后答4.1 如何开启一个参数搞定模板读取两个布尔参数默认均为falsechat_template.jinjatext processor.apply_chat_template( messages, toolstools, # 可选工具声明 enable_thinkingTrue, # 开启思考模式 preserve_thinkingFalse, # 多轮历史是否保留旧思考 add_generation_promptTrue, )enable_thinkingTrue模板在首个 system 轮最顶部注入\|think\|Tokenchat_template.jinja模型随后会输出完整思考过程enable_thinkingFalse默认生成提示里会输出一个空的思考占位\|channelthought\nchannel\|chat_template.jinja作用是抑制模型输出思考让回答更直接。 小技巧在 vLLM 等服务端部署中这两个参数通常通过请求体的extra_body透传给模板例如{enable_thinking: true, preserve_thinking: true}。4.2 preserve_thinking多轮对话的隐藏参数长对话里模型上一轮想明白的推理链条如解题步骤、工具调用的判断依据其实很有价值。preserve_thinkingFalse默认历史消息里的思考内容会被丢弃只保留最终回答——省 Token、省钱、快preserve_thinkingTrue历史思考以\|channelthought ... channel\|形式带回上下文chat_template.jinja复杂多步任务数学证明、代码调试、长链条工具编排中连贯性更好。⚖️ 权衡保留思考 ≈ 更聪明的上下文但会显著增加输入 Token 数。建议简单问答关闭、复杂推理开启。4.3 Thinking × Tool Calling推荐的满血组合最强大的 Agent 形态 先思考再调工具看到结果后再思考场景推荐配置简单客服/闲聊enable_thinkingFalse单步查数据天气、库存enable_thinkingFalse tools多步 Agent检索→过滤→汇总enable_thinkingTrue tools数学/代码/复杂规划enable_thinkingTruepreserve_thinkingTrue4.4 成本与延迟的取舍开启思考模式后每轮响应会多一段思考 Token✅收益推理类任务如本模型 GPQA Diamond 精度 81.31%见 README.md准确率明显更高❌代价首 Token 延迟变高、Token 消耗变大。实用策略先用思考模式跑通任务验证正确性再对高频简单请求关闭思考按场景分流。5. 常见问题排查新手必看❓ Q1模型不思考或思考内容跑到了正文里检查enable_thinking是否真的传到了模板。关闭时生成提示必须带空思考占位符chat_template.jinja否则模型可能误入思考通道。❓ Q2报错arguments must be a JSON object (mapping), not a stringtool_calls[].function.arguments传成了字符串。先json.loads()反序列化再回填历史chat_template.jinja。❓ Q3工具调用后模型失忆或循环调用确认工具结果是否以role: tool 正确tool_call_id回填且content非空模板会自动用tool_call_id对齐结果chat_template.jinja。❓ Q4如何自定义输出格式不建议改 chat_template.jinja。它是官方 Canonical 版本且与 tokenizer_config.json 的response_schema/response_template严格对应——改一头坏两头。❓ Q5部署有额外要求吗该量化版针对 Ascend 平台验证8 × Ascend 950DTDocker vLLM Ascend量化脚本见 README.md 与配方 gemma-4-26B-A4B-it_best_practice.yaml。6. 结语一份可执行的进阶清单✅ 按 tokenizer_config.json 理解特殊 Token建立轮次 通道 工具块的心智模型 ✅ 工具声明注意类型大写 \|\|字符串转义✅ 回填历史时arguments一律先反序列化成对象 ✅ 简单任务关思考省钱省时复杂任务enable_thinkingTrue提精度 ✅ 多步 Agent 用preserve_thinkingTrue保住推理链 ✅ 解析输出交给内置response_schema不手写正则掌握 Chat Template 的这套语法你就真正解锁了 Gemma 4 作为 Agent 内核的全部潜力。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考