Gemma-3-4b_rai_1.8.0_npu_16K 对话模板实战：chat_template.jinja 与特殊 Token 的正确打开方式

本仓库是 AMD 针对 Ryzen AI NPU 发布的Gemma 3 4B多模态模型部署包（Ryzen AI 1.8.0，Token Fusion 16K 上下文）。要跑通对话，绕不开两样东西：对话模板chat_template.jinja 和特殊 Token定义。本文将带你逐段看懂这份模板的渲染逻辑，并给出一张特殊 Token 速查表，帮助新手快速上手 NPU 端推理。

一、仓库结构速览：对话相关文件都在哪

打开仓库，与「对话格式」直接相关的文件有这几个：

其余如 model.onnx、gemma-3-embedding.onnx、partitioned/gemma-3-vision.onnx 是拆分后的 ONNX 模型，以及一批dd_metastate_*文件（NPU 融合元数据），它们与模板无关，了解即可。

💡 依据 README.md 的描述，该模型经 Quark 量化（AWQ / Group 128 / UINT4 权重）与 OGA Model Builder 构建，最终面向 NPU 部署，支持 16K 上下文融合。

二、chat_template.jinja 逐段拆解

Gemma 3 的模板比一般模型多两个细节：system 消息会被"吸进"第一条 user 消息，以及严格校验角色交替。

1. 开头：注入<bos>并处理 system 消息

模板第一行固定输出{{ bos_token }}。随后检查messages[0]是否是system角色：

• 是 system：把 system 内容存为first_user_prefix（内容后追加两个换行），从第 2 条消息开始循环；
• 不是 system：前缀置空，全部消息进入循环。

这就是为什么 Gemma 3 的 prompt 里看不到独立的system段——它实际上拼在第一个 user 轮的前面。

2. 循环体：角色校验与model角色名

模板核心循环位于 chat_template.jinja#L17-L27，逻辑有三点：

1. 角色必须交替：user / assistant 必须严格轮流出现，否则直接raise_exception("Conversation roles must alternate user/assistant/user/assistant/...")，避免拼出非法 prompt；
2. assistant 改名 model：Gemma 系列用model而非assistant作为响应角色；
3. 逐轮包裹：每条消息渲染为<start_of_turn>角色名+ 内容 +<end_of_turn>。

3. 多模态：<start_of_image>占位符

当消息 content 是列表时，模板会遍历其中每一项：type == 'image'的项渲染为<start_of_image>，type == 'text'的项渲染其文本内容。这与 processor_config.json 的图像流水线、partitioned/ 目录下的视觉模型配合，完成"图 + 文"混合输入。

4. 结尾：生成提示

若add_generation_prompt为真，模板末尾再补一段<start_of_turn>model，示意模型开始生成。

渲染效果大致如下（以"你好"为例）：

<bos><start_of_turn>user 你是AMD官方客服 你好 <end_of_turn> <start_of_turn>model

可以看到 system 提示被合并进了第一条 user 轮，这正是 Gemma 3 模板的标志性行为。

三、特殊 Token 速查表

结合 special_tokens_map.json 和 tokenizer_config.json 的added_tokens_decoder，关键 Token 一览：

其中<start_of_turn>/<end_of_turn>的注册位置见 tokenizer_config.json#L846-L860。

四、推理引擎侧：genai_config.json 如何衔接 Token

onnxruntime-genai 引擎并不直接读模板，而是靠 genai_config.json 里的字段对齐：

• bos_token_id: 2：与模板开头的<bos>一致（见 genai_config.json#L3）；
• eos_token_id: [1, 106]：停止生成监听两个 Token——<eos>（ID 1）和<end_of_turn>（ID 106），模型说完一轮即自动收尾；
• pad_token_id: 0：与<pad>对应；
• context_length: 131072：词表 262208，完整上下文上限 128K。

🧠 另外注意 genai_config.json#L13-L17 中hybrid_opt_max_seq_length: "4096"，对应仓库根目录下一组按 256/512/1024/…/4096 长度分桶的dd_metastate_*融合元数据文件——这就是标题里16K（Token Fusion 16K）在工程上的落地形式：NPU 侧按序列长度分桶预融合，首次运行后还会生成cache/缓存。

五、新手常见踩坑清单 ⚠️

1. 自己手写 prompt 不加<start_of_turn>：绕过模板直接拼文本，模型容易不回答或格式错乱；
2. system 消息放错位置：system 只能作为第一条消息，且会被并入首轮 user 内容；
3. 角色不交替：连续两条 user 消息会触发模板异常，这不是 bug 而是保护机制；
4. 以为 eos 只有一个：停止条件是[1, 106]双 Token，自定义解码循环时两个都要监听；
5. 修改模板或 Token 映射：该仓库为只读发布包，ONNX 与 NPU 融合元数据均已按现有词表固化，改动不会生效。

六、小结

理解Gemma 3 对话模板的关键就三句话：system 并入首轮、assistant 叫 model、轮次用<start_of_turn>/<end_of_turn>包裹。再对照 special_tokens_map.json 的 Token 表和 genai_config.json 的引擎配置，你就能完整解释 NPU 上每一次推理的输入长什么样。掌握这套「模板 + Token」的正确打开方式，是玩转 Ryzen AI 本地多模态推理的第一步。