llama.cpp 源码完全拆解（十二）：对话模板与消息解析——minja 如何渲染、差分解析器如何学会一套未知模板

模板不兼容时的补丁

真实世界的模板并不总是能被一个精简的 Jinja 实现直接跑通。common_chat_templates_init() 里有两段带注释的字符串替换，专门处理已知模板：

• GPT-OSS 模板里有一段 {%- if "<|channel|>analysis<|message|>" in message.content or ... %}，llama.cpp 会把它替换成 {%- if false %}。
• 某些使用 [TOOL_CALLS] 的模板里有一段对 message['content'] is none or ... 的判断，也会被替换成 {%- if false %}。

源码把这两处称为临时 hack，理由是“防止模板抛错”，并附了对应的 PR 讨论链接。它不是在对模型语义做裁剪，而是在 minja 尚未覆盖某些表达式写法时，让模板至少能完成初始化。读到这类代码时应该记住：模板引擎的能力边界会直接变成框架的兼容性负担；每多支持一种 Jinja 语法，就少一处硬编码补丁。

选模板

如果请求里带了工具，并且模型提供了 tool_use 模板，就优先用 tool_use；否则用默认模板。这个设计允许模型把“普通对话”和“工具调用”写成两套格式，而不必在一个模板里塞满条件分支。

整理消息

模板不是总能处理 OpenAI 消息的所有形状，所以渲染前有一组 workaround：

• developer 角色映射成 system，GPT-OSS 除外，因为它的模板自己处理 developer。
• 模板能力表标记为不支持 system 角色时，由 workaround 把系统消息改写进首条用户消息，按模板期望的结构降级。
• 模板要求工具调用消息的 content 非空时，把 null 补成空字符串。
• 模板要求参数是对象时，把 arguments 字符串解析成 JSON。

这些逻辑写在 common_chat_templates_apply_jinja() 里，而不是散落在各模型实现中。它们共同说明一件事：模板不是“只读字符串”，它会假设消息的形状；框架要么满足假设，要么在渲染前修正消息。

准备变量

传给模板的上下文至少包含：

1
{
2
  "messages": [...],
3
  "tools": [...],
4
  "bos_token": "...",
5
  "eos_token": "...",
6
  "enable_thinking": true,
7
  "add_generation_prompt": true
8
}

此外还有 chat_template_kwargs 里的自定义键、json_schema、parallel_tool_calls、tool_choice，以及 common_chat_extra_context() 提供的额外变量。bos_token 和 eos_token 在渲染后会再被强制覆盖成模型词表里的值，避免客户端伪造。

enable_thinking 是一个很典型的模板开关。Qwen3 一类模板会根据它决定生成提示里是否带思考起始标签；llama.cpp 在服务端先探测模板是否支持这个变量，再决定是否把用户设置传进去。

执行与收集

jinja::runtime::execute(prog) 返回一个值，gather_string_parts() 把它拆成若干字符串片段。关键在于：这些片段不是简单拼接，而是带着 is_input 标记。

jinja::global_from_json(ctx, inp, inputs.mark_input) 在把消息 JSON 注入模板上下文时，会把来自用户消息的字符串标记成“输入”。模板把这些字符串插入到输出里时，片段继承标记。最终得到的是 common_chat_prompt：

1
struct common_chat_prompt_part {
2
    std::string text;
3
    bool is_input; // 来自用户输入，内部的特殊 token 不能被解析
4
};

common_chat_prompt::str() 负责把片段拼成完整文本。看起来只是字符串拼接，但 is_input 的存在让下一步的分词能够区别对待模板文本和用户文本。

分词

common_chat_input_tokenize() 调用 common_tokenize(vocab, text, false, true)：第二个参数表示不额外添加 BOS，第四个参数表示解析特殊 token。然后它逐 token 取 piece，检查拼接回去是否与原文一致；如果分词器的规范化让文本对不上，就退回“只保留文本、不给 token”的模式。

这个细节很重要。聊天模板的输出里，模板自己写的 <|im_end|> 必须被识别成特殊 token；而用户输入里的同样字样必须当成普通文字。如果整段文本不加区分地按特殊 token 解析，用户只要在消息里写一个 <|im_end|>，就能提前结束回合，甚至伪造下一条消息的角色。is_input 就是这条边界。

生成提示的差分

common_chat_template_generation_prompt() 的实现很有意思：它把同一组消息渲染两次，一次 add_generation_prompt=false，一次 true，然后取两个结果的最长公共前缀，返回后半段。

1
size_t prefix_len = 0;
2
size_t min_size = std::min(no_gen_prompt.size(), gen_prompt.size());
3
while (prefix_len < min_size && no_gen_prompt[prefix_len] == gen_prompt[prefix_len]) {
4
    prefix_len++;
5
}
6
return gen_prompt.substr(prefix_len);

这样得到的不是硬编码的 "<|im_start|>assistant\n"，而是模板自己产生的增量。后面解析模型输出时，这段增量会被重新前置到输出文本里，保证解析器看到的开头与模型生成时的上下文一致。

差分法还顺带解决了两个棘手情况。第一，有些模板的生成提示不是单一标记，而是一段复合文本：先闭合上一条消息的结束符，再打开助手角色头，例如 <|im_end|>\n<|im_start|>assistant\n。如果按“结束符 + 角色头”两段硬编码，任何模板改动都会失配；差分法直接拿模板的真实输出，天然包含所有片段。第二，有些模板在生成提示里带上采样参数提示，例如要求输出 JSON 时追加一句“请只输出 JSON”，这种模板语义只有模板自己知道，框架无法枚举。差分法不关心这些片段代表什么，只关心它们在完整渲染结果中的位置。

需要区分的是，生成提示的差分结果只用于“解析时补回上下文”和“采样器判断当前回合”，并不参与分词。真正的输入 token 仍然来自带 add_generation_prompt=true 的完整渲染，生成提示是其中一部分，不重复添加。

图源：作者依据 llama.cpp common/chat.h、common/chat.cpp 绘制。

它能推断出什么

autoparser 的分析结果由几组枚举描述：

• reasoning_mode：NONE、TAG_BASED、TOOLS_ONLY。判断模板有没有思考段、思考段是标签包裹还是只在工具调用时出现。
• content_mode：PLAIN、ALWAYS_WRAPPED、WRAPPED_WITH_REASONING。判断正文有没有包装标签、包装是否只在有思考内容时出现。
• tool_format：NONE、JSON_NATIVE、TAG_WITH_JSON、TAG_WITH_TAGGED。判断工具调用是纯 JSON、标签包 JSON，还是标签包“参数标签”。
• call_id_position：NONE、PRE_FUNC_NAME、BETWEEN_FUNC_AND_ARGS、POST_ARGS。判断调用 ID 相对函数名和参数的位置。

这些枚举不是最终解析器，而是“解析器生成器的输入”。peg_generator::generate_parser() 根据分析结果拼出一台 PEG 状态机，描述模型输出应该长什么样。

图源：作者依据 llama.cpp common/chat-diff-analyzer.cpp 与 common/chat-auto-parser.h 绘制。

差分分析的具体探针

analyze_template() 依次构造几个分析器：

1
reasoning = analyze_reasoning(tmpl, jinja_caps.supports_tool_calls);
2
content   = analyze_content(tmpl, reasoning);
3
tools     = analyze_tools(jinja_caps.supports_tool_calls ? analyze_tools(tmpl, jinja_caps, reasoning) : analyze_tools());
4
assistant_start = detect_assistant_start_marker(tmpl);
5
user_start      = detect_user_start_marker(tmpl);

detect_assistant_start_marker() 比较“只有用户消息”和“用户消息 + 助手消息”两次渲染。后者比前者多出来的块里，助手内容之前的文本就是助手消息的起始标记。detect_user_start_marker() 用类似办法找用户消息的起始标记，必要时再加一条助手消息做隔离。

analyze_reasoning 的探针更细：

• 比较“助手有 content”和“助手有 reasoning_content”两种消息，看思考字符串出现在输出的什么位置，从而得到思考起止标签。
• 比较 enable_thinking=true 和 false 的生成提示，判断模板是否真的根据这个开关改变输出。
• 检查思考段是总会出现，还是只在工具调用前出现。

analyze_tools 先用一条带工具调用的助手消息做“大海捞针”，找到函数名和参数名出现的位置，再按位置关系分类：

• 函数名和参数都包在 JSON 对象里，是 JSON_NATIVE。
• 函数名有标签、参数是 JSON，是 TAG_WITH_JSON。
• 函数名有标签、每个参数也有自己的标签，是 TAG_WITH_TAGGED。

然后它继续找并行调用的分隔标记、参数之间的分隔符、调用 ID 的位置。源码里对每种格式都有对应的 build_tool_parser_*，把分析结果翻译成 PEG 表达式。

专用 handler 优先

差分分析不是万能的。模板里如果有复杂的条件分支、宏、或者依赖运行时状态，探针可能得不到稳定差异。llama.cpp 的策略是“先匹配专用 handler，再退回自动解析器”：

1
if (auto result = common_chat_try_specialized_template(tmpl, params)) {
2
    return *result;
3
}
4
if (!tmpl.analysis) {
5
    throw std::invalid_argument("Unable to generate parser for this template. ...");
6
}

common_chat_template_detect_params_init() 用模板源码里的特征字符串识别模型家族。源码中能看到的例子包括 GPT-OSS 的 <|channel|>、Kimi K2 的 <|tool_calls_section_begin|>、Kimi K3 的 <|open|>/<|close|>/<|end_of_msg|>、DeepSeek V3.2/V4 的 ｜DSML｜、Qwen3-Coder 的 <tool_call><function=...>、Gemma4 的 <|tool_call>call:、MiniMax-M3 的 ]<]minimax[>[，以及 Cohere2 MoE、Ling 3.0、Functionary v3.2 等。

这份列表本身就是一份“聊天格式演化史”：每加一个模型家族，就多一段特征匹配和一套手写解析。自动解析器负责覆盖长尾，专用 handler 负责覆盖那些自动分析容易误判的主流模型。两者并存，说明“完全从模板推断格式”在工程上仍是一个有边界的方案。

分析失败时怎么办

如果模板既没有专用 handler，差分分析又失败，common_chat_templates_apply_jinja() 会抛出 Unable to generate parser for this template。这不是一个可以静默降级的错误：没有解析器，框架就不知道模型输出里的哪一段是正文、哪一段是工具调用，流式回传也无法正确切分。

实践中的处理方式有三种：给模板加专用 handler、简化模板让差分分析能通过、或者绕过聊天接口直接走 completion。前两种属于框架维护者的工作，第三种属于部署者的退路。

差分分析失败的原因通常集中在几类：

• 模板分支过多。同一组消息在不同条件下渲染出完全不同的结构，探针只改一个变量时，差异被条件分支淹没，前缀/后缀差分无法定位。
• 宏与自定义函数。Jinja 的 macro 或运行时注册的函数把格式化逻辑藏起来，差分只能看到结果，无法判断某段文本是结构标记还是内容。
• 依赖外部上下文。模板读取时间、请求 ID 之类的变量，两次渲染的公共前缀被这些变量打断。
• 模板对空值处理不唯一。某些字段缺省时，模板走另一条完全不同的分支，导致探针的 baseline 与变体根本不在同一个结构里。

专用 handler 之所以存在，很大程度上就是为了覆盖这几类“差分分析不友好”的主流模板。它们的实现通常是对已知格式的 PEG 规则做少量参数化，而不是重新跑一遍分析。也就是说，框架在这里付出的维护成本，是把解析逻辑与模型家族绑定；换来的是确定性和可预测性。

模板更新带来的解析器漂移

模型提供方经常在不大改架构的情况下微调模板：新增一个角色别名、调整思考标签、改变工具调用的包裹方式。llama.cpp 的专用 handler 靠特征字符串识别，模板特征一旦变化，可能从“命中专用 handler”退化成“走差分分析”，也可能反过来。前者通常结果不变或略有差异，后者可能因为分析器对新特征不敏感而生成错误的 PEG。

这也是为什么 common_chat_template_detect_params_init() 里的特征匹配写得非常具体：GPT-OSS 必须同时出现 <|channel|> 和 <|constrain|>xml；Kimi K3 必须同时出现 <|open|>、<|close|> 和 <|end_of_msg|>；DeepSeek V4.1 的检测甚至注明“标签名带有前导空格，且模板不再声明 dsml_token 变量”。条件越精确，误判越少，但漏判也越多。维护者需要在两者之间持续校准。

对部署者而言，这意味着“升级模型文件”不等于“只换权重”。模板变化可能改变前缀、改变解析器和采样约束；灰度发布时应该同时对比模板哈希、能力表和一条真实工具调用请求的解析结果。

session 与增量

服务端不会每次流式片段都重新构造解析器。common_chat_session 在请求开始时保存模板应用结果：

1
common_chat_session::common_chat_session(
2
    const common_chat_templates * tmpls,
3
    const llama_vocab * vocab,
4
    const common_chat_templates_inputs & inputs,
5
    const common_chat_session_params & params);

它缓存 prompt_parts、grammar_text、stops、generation_prompt_text、thinking_start/ends、parser_params 和消息分隔符。feed() 把新片段追加到累积输入，调用部分解析；finish() 做完整解析。这样流式解析的状态只维护一份，不会随着 token 增长反复复制整个会话。

common_chat_msg_diff::compute_diffs() 则负责计算前后两条消息的差异，用于工具调用这类结构化字段的增量回传。正文可以逐字发，工具调用不能每来一个字符就重发整个 JSON；差异计算让服务端只发送新增的部分。

三类输出

最终回传给客户端的内容通常分三类：

• content：普通正文，逐 token 增量。
• reasoning_content：思考内容，是否回传取决于模板能力和服务端配置。
• tool_calls：工具调用，包含 id、name、arguments 增量。

这三类在模板层是同一段文本，在解析层被拆开。拆分的依据不是模型名字，而是模板分析得到的起止标记、内容模式和工具格式。换句话说，模板决定了“模型怎么写”，解析器决定了“框架怎么读”。

历史思考内容的成本

preserve_reasoning 是另一个与模板强相关的开关。多轮对话里，历史助手消息可能带 reasoning_content。模板可以选择把它渲染进下一轮上下文，也可以丢弃。保留的好处是模型能看到自己之前的推理链；代价是上下文变长，KV Cache 占用按 token 数线性增长：

其中 $L$ 是层数，$H_{\mathrm{kv}}$ 是 KV 头数，$d_h$ 是每个头的维度，$n_{\mathrm{tok}}$ 是上下文 token 数，$b$ 是每个元素的字节数。系数 2 来自 K 和 V 两份缓存。对 GQA 模型，$H_{\mathrm{kv}}$ 远小于注意力头数，这就是分组查询注意力能把长上下文成本压下来的原因；但即便如此，历史思考内容仍然会实打实地占 token 预算。llama.cpp 在模板能力允许时默认保留，并给出关闭开关，正是把“推理质量”和“显存/吞吐”之间的取舍交给部署者。

模板层的可观测性

模板问题通常不会在启动时报错，而是在某类请求上悄悄退化。llama.cpp 提供了几条观测手段，值得在部署时打开：

• --verbose 或服务端 trace 日志会打印 chat template, example_format: ...，把模板渲染的一个示例格式打出来。第一眼就能看出角色标记、生成提示和特殊 token 是否符合预期。
• /props 返回模板源码与能力表，chat_template_caps 直接给出 supports_parallel_tool_calls、supports_object_arguments 等布尔值；客户端可以据此选择是否发送 tools 数组。
• common_chat_format_name() 把分析出的格式枚举转成字符串，日志里出现 PEG_NATIVE、PEG_GEMMA4、CONTENT_ONLY 时，可以判断当前走的是专用 handler 还是通用解析器。

线上排查“模型不调用工具”时，最有效的第一步不是改 prompt，而是确认三件事：模板是不是 tool_use 版本、能力位是否支持工具调用、解析器是不是把工具段正确读出。三者任一为假，模型输出再正确，客户端也看不到 tool_calls。

BOS/EOS 到底谁说了算

模板里经常出现 {{ bos_token }}。如果框架在分词时又自动加一次 BOS，序列开头就会出现两个 BOS。llama.cpp 的做法是：模板变量从词表取，分词时 add_special=false，渲染后再根据 add_bos/add_eos 去掉模板自己加的 BOS/EOS，保证最终只加一次。

这看似是细节，实际上是模板移植中最常见的错误来源。不同模型的模板对 BOS 的处理不一致：有的模板自己写 BOS，有的依赖 tokenizer 自动加。框架必须选一种口径，并在渲染和分词之间做去重。

模板一变，前缀缓存就失效

前缀缓存的前提是“新请求的 token 前缀与旧请求完全一致”。模板是 prompt 的一部分，模板版本、chat_template_kwargs、enable_thinking、工具列表的顺序，任何一个变化都会改变开头 token。服务端如果把模板哈希排除在缓存键之外，就会出现“缓存命中但内容错误”的严重问题。

llama.cpp 的 slot 缓存按 token 序列匹配，模板变化会自然导致前缀不匹配；但在多租户服务里，还需要把模板版本纳入更上层的缓存键。vLLM 的 prefix caching、SGLang 的 RadixCache 也是同样的道理：模板是前缀的一部分，不是元数据。

工具参数的字符串/对象二象性

OpenAI 协议里 tool_calls[].function.arguments 是 JSON 字符串；很多模板却期望它是一个对象，直接写 message['tool_calls'][0]['function']['arguments']['city']。llama.cpp 用 supports_object_arguments 能力位判断模板要哪一种，渲染前做转换。框架如果不做这一步，模板会在运行时抛“字符串不能按对象索引”的错误，或者渲染出双重转义的 JSON。

并行工具调用与调用 ID

并行工具调用要求模板能渲染多个调用，解析器能识别调用之间的分隔符和每个调用的 ID。差分分析专门有探针找 per_call_start、per_call_end 和 call_id_position；专用 handler 则按模型家族写死。部署时如果发现模型明明支持并行调用，框架却只回传一个，首先应该检查模板能力位和解析器是否匹配。

结构化输出与工具调用不能同时硬约束

common_chat_templates_apply_jinja() 里有一条明确的检查：

1
if (params.tool_choice != COMMON_CHAT_TOOL_CHOICE_NONE && !params.grammar.empty()) {
2
    throw std::runtime_error("Cannot specify grammar with tools");
3
}

原因是两套语法约束可能互相矛盾：工具调用要求输出特定标签包裹的 JSON，而用户给的 grammar 可能要求输出另一套结构。框架选择直接报错，而不是悄悄忽略其中一个。这个设计提醒部署者：结构化输出和工具调用是两种不同的约束来源，需要明确优先级。

思考标签必须保留

如果采样器把 <think>、</think> 当成普通文本过滤掉，模型输出的思考段就会失去边界，解析器无法把 reasoning_content 和 content 分开。preserved_tokens 的作用就是把模板分析出的标记加入保留列表。这个问题在自定义采样器或二次开发时最容易出现。

工具结果消息的拼装顺序

工具调用是一个两步协议：助手先输出 tool_calls，客户端执行后把结果作为 tool 消息送回。模板通常假设这两步严格相邻：assistant(tool_calls) 后面紧跟 tool(tool_call_id, content)。如果中间插入一条普通用户消息，或者 tool_call_id 对不上，模板渲染出的结构就会让模型看到一个“没有对应调用的结果”，轻则忽略结果，重则把结果当成用户陈述继续闲聊。

common_chat_msg 保留 tool_name 和 tool_call_id 两个字段，就是为了让模板能按 ID 关联。渲染前，框架不会替客户端重排消息；它假设调用方按协议给出了正确的顺序。这一点在自建 Agent 循环时经常被忽略：并行调用返回多个结果时，结果消息要逐个对应，而不是合并成一条。

不同模板对结果消息的写法差异也很大：有的用 <|tool_response|> 包裹，有的用 tool 角色加 JSON，有的要求结果里带函数名。llama.cpp 通过 tool_use 模板和消息字段把这些差异交给模板处理；框架只保证字段不丢。

模板覆盖的边界

--chat-template 可以覆盖模型自带模板，--chat-template chatml 可以强制使用内置 ChatML。这两个开关在调试时很有用，但不应该被当成“万能适配器”。

模板是模型训练数据的一部分。指令微调模型见过的角色标记、工具语法、停止符，是它学会“什么时候停、什么时候调用工具”的依据。用一个格式不同的模板去套模型，最坏情况不是报错，而是模型仍然能生成流畅文本，却不再遵守工具协议和停止条件。判断一个模板能不能用，应该看三件事：特殊 token 是否在词表里、生成提示是否与训练格式一致、工具调用语法是否与模型见过的样本一致。

对服务端来说，模板覆盖还意味着前缀缓存失效和解析器重新分析。覆盖后的模板如果命中不了专用 handler，就会走差分分析；分析失败时聊天接口直接不可用。因此模板覆盖应该与模型版本绑定，而不是作为运行时的临时开关。