llama.cpp 源码完全拆解（二十七）：工具调用的反向解析——PEG 解析器、AST 映射与流式增量如何把 token 变回 tool_calls

节点类型

解析器节点用 std::variant 存在一个 arena 里，常见类型包括：

• literal：匹配一段固定字符串；
• sequence：按顺序匹配子节点；
• choice：有序尝试子节点，第一个成功者胜出；
• repetition：带上下界的重复；
• until / until_one_of：一直消费到某个分隔串出现；
• any：消费一个字节；
• negate / peek：负向/正向先行断言；
• atomic：禁止内部回溯泄漏到外部；
• tag：给匹配到的子树打标签，供后续 AST 映射使用；
• rule / ref：命名规则与递归引用；
• schema：按 JSON Schema 约束一段结构；
• gbnf：嵌入一段 GBNF 子语法。

组合子由 common_peg_parser_builder 提供，写法接近 EBNF：

1
auto value = choice({ p.json_string(), p.json_number(), p.json_object(), p.json_array(), p.json_bool(), p.json_null() });
2
auto member = p.json_string() + p.literal(":") + value;
3
auto object = p.literal("{") + p.optional(member + p.zero_or_more(p.literal(",") + member)) + p.literal("}");

这里的 + 是 sequence，| 是 choice，* 是 zero_or_more。所有节点最终被压进一个 common_peg_arena，规则通过 ref 解析成 id，解析时不需要再构造对象。

tag 是这层设计的关键。解析器不只回答“匹配成功没有”，还要告诉上层“这一段是工具名”“这一段是参数值”“这一段是思考内容”。标签随 AST 节点一起保存，映射器只需遍历 AST，按标签把文本填进 common_chat_msg，不需要再写一遍语法。

解析标志与部分匹配

common_peg_parse_flags 只有四个值：

• COMMON_PEG_PARSE_FLAG_LENIENT：允许输入在语法需要更多字符时提前结束；
• COMMON_PEG_PARSE_FLAG_COMPLETE：要求整段输入被完整消费；
• COMMON_PEG_PARSE_FLAG_DEBUG：打印 AST 和规则命中情况；
• COMMON_PEG_PARSE_FLAG_NONE：默认。

解析结果有三种状态：SUCCESS、FAIL、NEED_MORE_INPUT。NEED_MORE_INPUT 是流式解析的核心：当解析器走到输入末尾、而语法还期待更多字符时，它不回退成失败，而是返回“还差输入”，并把已经匹配到的 AST 节点带回来。

common_chat_peg_parse 只在 is_partial == false 时加上 COMPLETE 标志：

1
common_peg_parse_flags flags = COMMON_PEG_PARSE_FLAG_LENIENT;
2
if (!is_partial) {
3
    flags |= COMMON_PEG_PARSE_FLAG_COMPLETE;
4
}

这意味着流式中间帧允许“语法还没闭合”；最后一帧则必须闭合到根规则的 p.end()。如果最后一帧仍然有未消费的尾部，解析器会记录 result.end，并在日志里打印“unparsed output”，然后抛出异常——这是一条很实用的排障线索：看到这条日志，说明模型输出的格式和模板推断出的语法不一致。

为什么 until 比正则的 .*? 更可靠

until(delimiter) 的实现不是简单的字符串查找，而是在解析上下文里逐字节推进，并处理 UTF-8 边界。它只在当前层级寻找分隔串，不会跨越已经进入的子结构。这一点对工具参数非常重要：参数值里可能出现和结束标记相同的字符序列（例如字符串内容里写了 </tool_call>），until 在字符串规则内部不会把它当成分隔符，因为字符串规则会先消费掉引号内的内容。

tag_with_safe_content 进一步处理“内容里出现标记”的情况：

1
common_peg_parser common_chat_peg_builder::tag_with_safe_content(
2
        const std::string & tag_name, const std::string & marker, const common_peg_parser & p) {
3
    if (marker.empty()) {
4
        return zero_or_more(choice({ p, rule(tag_name, content(any())) }));
5
    }
6
    auto content_chunk = rule(tag_name, content(negate(literal(marker)) + any() + until(marker)));
7
    return zero_or_more(choice({ p, content_chunk }));
8
}

它的语义是：优先匹配结构化内容 p；如果匹配不上，就消费“不是结束标记的任意字节”，直到遇到标记。这样即使正文里出现了类似标记的片段，解析器也不会错位，而是把它归入内容。

路径一：专用模板处理器

有些模型的格式太特殊，差分分析难以稳定推断，llama.cpp 为它们保留了手写的 common_chat_params_init_*。模板初始化时会扫描模板源码，按特征字符串选择处理器：

1
// 文件：common/chat.cpp（简化）
2
static common_chat_params_init_fn common_chat_template_detect_params_init(const std::string & src) {
3
    if (src.find("[SYSTEM_PROMPT]") != std::string::npos &&
4
        src.find("[TOOL_CALLS]") != std::string::npos &&
5
        src.find("[ARGS]") != std::string::npos &&
6
        src.find("[CALL_ID]") == std::string::npos) {
7
        return common_chat_params_init_ministral_3;
8
    }
9
    if (src.find("<|channel|>") != std::string::npos) {
10
        return common_chat_params_init_gpt_oss;
11
    }
12
    if (src.find(">>>all") != std::string::npos &&
13
        src.find(">>>${recipient}") != std::string::npos) {
14
        return common_chat_params_init_functionary_v3_2;
15
    }
16
    ...
17
    return nullptr;   // 交给自动解析器
18
}

这条路径的存在说明一件事：模板生态并不整齐，自动推断不是万能的。专用处理器的价值在于把“已知的怪异格式”固化下来，避免每次请求都重新分析，也避免分析失败导致工具调用不可用。代价是新增模型时要维护代码。

路径二：差分自动解析器

没有专用处理器时，走 autoparser。它在模板初始化阶段只分析一次，结果缓存在 common_chat_template::analysis 里，后续每次请求直接复用。

分析的核心手法是“差分探测”：用同一套模板渲染两个只在某一个维度上不同的消息序列，比较两次渲染结果的差异，从差异里反推出标记。

1
// 文件：common/chat-auto-parser-helpers.cpp（简化）
2
std::optional<compare_variants_result> compare_variants(
3
    const common_chat_template & tmpl,
4
    const template_params & params_A,
5
    const std::function<void(template_params &)> & params_modifier) {
6
    template_params params_B = params_A;
7
    if (params_modifier) { params_modifier(params_B); }
8

9
    std::string output_A = apply_template(tmpl, params_A);
10
    std::string output_B = apply_template(tmpl, params_B);
11
    if (output_A == ERR_TMPL || output_B == ERR_TMPL) { return std::nullopt; }
12

13
    compare_variants_result result;
14
    result.diff = calculate_diff_split(output_A, output_B);
15
    result.output_A = output_A;
16
    result.output_B = output_B;
17
    return result;
18
}

calculate_diff_split 把两次输出切成公共前缀、公共后缀、左侧差异和右侧差异四段。公共前缀是模板的稳定外壳，右侧差异就是“新增内容引入了什么标记”。

分析分三个阶段进行。

阶段一：推理标记。 比较“带 reasoning_content 的 assistant 消息”和“不带的 assistant 消息”的渲染结果。如果差异里出现了思考内容，就在差异文本里找包裹它的标记：先用“标记 + 内容 + 标记”的严格模式匹配，失败再退化为“内容 + 后置标记”的分隔符模式。然后比较 enable_thinking = true/false 两次生成提示的差异，补充只有前置标记、没有后置标记的情况。

阶段二：正文标记。 比较“纯 content 消息”和“带 tool_calls 的消息”，再比较“纯 content 消息”和“带 reasoning 的消息”。如果 content 在差异里是裸文本，说明模板不包裹正文；如果被标记包住，就把前后标记记下来。这里有一个容易误判的点：有些模板在只有推理内容时也会输出正文标记，分析器必须把 reasoning.end 之后的片段排除，否则会把思考标记误当成正文标记。

阶段三：工具调用格式。 先渲染“一条带工具的 assistant 消息”，把差异段作为 haystack。然后判断函数名和参数名在 haystack 里是否处于 JSON 引号内：

• 函数名在引号内 → JSON_NATIVE，整个调用是一个 JSON 对象；
• 参数名在引号内、函数名不在 → TAG_WITH_JSON，函数名是标签，参数是 JSON；
• 两者都不在引号内 → TAG_WITH_TAGGED，函数名和参数都是标签。

1
// 文件：common/chat-diff-analyzer.cpp（简化）
2
auto fun_quote = in_json_haystack(fun_name_needle);
3
auto arg_quote = in_json_haystack(arg_name_needle);
4

5
if (fun_quote) {
6
    format.mode = tool_format::JSON_NATIVE;
7
} else if (arg_quote) {
8
    format.mode = tool_format::TAG_WITH_JSON;
9
} else {
10
    format.mode = tool_format::TAG_WITH_TAGGED;
11
}

确定大类之后，再逐项提取：section 的开始/结束标记、每个调用的开始/结束标记、函数名前缀/后缀/结束标记、参数容器标记、参数名前缀/后缀、参数值前缀/后缀、参数分隔符、调用 ID 的位置。对 JSON 原生格式，还要判断并行调用是数组包裹还是重复的 section；对非 JSON 格式，要判断是否有 per-call 标记。

最后，分析器把所有非空的标记收进 preserved_tokens。这一步决定了采样器会不会把 <tool_call> 拆成普通文本——如果拆了，解析器就永远等不到结束标记，表现为“工具调用一直不结束，直到 max_tokens”。

路径二点五：补丁

自动分析之后还有一层 workarounds。这是一组针对已知模板的定向补丁，只在模板源码命中特定字符串时生效。例如：

• 旧 Qwen 模板用 content.split('</think>') 拆分思考内容，但不读 reasoning_content，补丁手动补上 <think> / </think> 标记；
• Granite 3.3 用 <think> 包思考、<response> 包正文，补丁同时设置推理和正文的模式；
• Cohere Command R+ 的正文被 <|CHATBOT_TOKEN|> 包裹，补丁补上正文标记和用户消息起点；
• DeepSeek-R1-Distill-Qwen 的 <｜tool▁call▁begin｜> 系列标记无法从差分里稳定推断，补丁直接写死 section 标记、函数名分隔符和闭合的 ```。

这层补丁不是“绕过解析”，而是把分析器难以稳定推断的边角信息补全。它和专用处理器的区别是：专用处理器完全接管参数生成，补丁只修改分析结果中的某几个字段。

推理段和正文段

推理段的语法非常短：

1
common_peg_parser analyze_reasoning::build_parser(parser_build_context & ctx) const {
2
    auto & p = ctx.p;
3
    if (!ctx.extracting_reasoning) { return p.eps(); }
4
    if (mode == reasoning_mode::TAG_BASED || mode == reasoning_mode::TOOLS_ONLY) {
5
        if (!end.empty()) {
6
            if (!start.empty()) {
7
                return p.optional(p.optspace(start) + p.reasoning(p.until(trim_whitespace(end))) +
8
                                  p.optspace(end));
9
            }
10
            return p.optional(p.reasoning(p.until(trim_whitespace(end))) + p.optspace(end));
11
        }
12
    }
13
    return p.eps();
14
}

它假设思考段最多出现一次，且一定以结束标记收尾。optspace 允许标记两侧有空白——这是对真实模型的妥协：模板渲染时标记和内容之间通常没有空格，但模型生成时经常多打一个换行。

正文段分两种形态。如果模板总是包裹正文（例如 <response>...</response>），语法是“推理段 + 正文标记 + until(结束) + 结束标记 + end”；否则是“推理段 + rest + end”。前者必须在标记内找结束，后者直接把剩余全部归入正文。

三种工具格式的语法

JSON 原生格式 的语法由 standard_json_tools 生成。它先按工具定义里的参数 schema 为每个工具建一条规则，再把规则组成 choice：

1
// 文件：common/chat-peg-parser.cpp（简化，nested keys 模式）
2
for (size_t i = 0; i < tools.size(); i++) {
3
    const auto & function = tools[i].at("function");
4
    std::string name = function.at("name");
5
    ordered_json params = common_chat_tool_parameters(function);
6

7
    auto nested_name = literal("\"" + nested_name_field + "\"") + space() + literal(":") + space() +
8
                       atomic(literal("\"") + tool_name(literal(name)) + literal("\""));
9
    auto nested_args = literal("\"" + nested_args_field + "\"") + space() + literal(":") + space() +
10
                       tool_args(schema(json(), "tool-" + std::to_string(i) + "-schema", params));
11

12
    auto nested_object = literal("{") + space() + nested_name + space() + literal(",") + space() +
13
                         nested_args + space() + literal("}");
14
    auto tool_parser_body = tool_open(literal("{")) + space();
15
    // 可选的 id / tool_call_id 字段
16
    tool_parser_body = tool_parser_body + optional(id_parser + space() + literal(",") + space());
17
    tool_parser_body = tool_parser_body + nested_field + space() + tool_close(literal("}"));
18
    tool_choices |= rule("tool-" + std::to_string(i), tool(tool_parser_body));
19
}

这里每个工具都有独立的规则，函数名是字面量而不是 json_string()。这个选择看似限制了模型的自由度，实际上是把“函数名必须是已知工具之一”编码进语法：模型如果输出了不存在的工具名，解析器会在工具名分支全部失败后报错，而不是把它当成一个未知调用传给客户端。约束解码时，GBNF 也只允许这些字面量，从生成阶段就杜绝了幻觉工具名。

参数部分用 schema() 包住 json()。schema() 不是简单的“合法 JSON”检查，它把工具定义的 JSON Schema 编译成一棵带类型的 PEG 子树：字符串、数字、布尔、数组、对象、枚举、required 字段都会影响匹配。这样解析器可以在流式阶段就知道“这个参数应该是字符串”，从而在映射时决定是否给值加引号。

parallel_tool_calls 决定调用之间是否允许逗号分隔；array_wrapped 决定整个 section 是否被 [...] 包裹；function_is_key 处理 {"get_weather": {...}} 这种把函数名当键的格式；parameters_order 处理那些要求参数按固定顺序输出的模板。这些开关都来自前文的差分分析结果，不是写死的。

标签 + JSON 参数格式 的语法由 build_tool_parser_tag_json 生成。函数名是标签，参数段是 schema(json())。标签 + 标签参数格式 则由 standard_constructed_tools 生成：

1
// 文件：common/chat-peg-parser.cpp（简化）
2
auto arg_rule = tool_arg(
3
    tool_arg_open(literal(param_key_prefix)) +
4
    tool_arg_name(arg_name_parser) +
5
    literal(param_key_suffix) +
6
    tool_arg_value(until(param_closer)) +
7
    tool_arg_close(literal(param_closer)));
8
arg_choice |= arg_rule;
9
args = zero_or_more(arg_choice + space());

参数名在三种引号形态里选：裸名、双引号、单引号。参数值用 until(param_closer) 而不是 JSON 值，因为很多模板的参数值就是裸文本，不要求 JSON 转义。映射器在最后会把标签参数重新组装成 JSON 对象，这一过程需要处理引号、逗号和未闭合的大括号。

内容块的顺序：permute

有些模板把正文、推理、工具调用三块放在同一条消息里，但顺序不固定：有的先思考再正文再工具，有的先工具再正文。硬编码顺序会在另一种模板上失败。permute 用位掩码枚举所有排列：

1
common_peg_parser common_chat_peg_builder::permute(
2
        const std::string & rule_prefix, const std::vector<common_peg_parser> & parsers) {
3
    if (parsers.empty()) { return eps(); }
4
    if (parsers.size() == 1 || parsers.size() > COMMON_CHAT_MAX_PERMUTE) {
5
        return sequence(parsers);
6
    }
7
    std::map<uint32_t, common_peg_parser> rules;
8
    std::function<common_peg_parser(uint32_t)> remaining_of;
9
    remaining_of = [&](uint32_t remaining) -> common_peg_parser {
10
        if (remaining == 0) { return eps(); }
11
        auto alternatives = choice();
12
        for (size_t i = 0; i < parsers.size(); i++) {
13
            const uint32_t bit = 1u << i;
14
            if (remaining & bit) {
15
                alternatives |= parsers[i] + remaining_of(remaining & ~bit);
16
            }
17
        }
18
        return rules.emplace(remaining, rule(rule_prefix + "-" + std::to_string(remaining),
19
                                            alternatives)).first->second;
20
    };
21
    return remaining_of((1u << parsers.size()) - 1);
22
}

COMMON_CHAT_MAX_PERMUTE 是 6。超过 6 个块时退化为固定顺序，因为排列数按阶乘增长，6 个块已经有 720 种顺序，语法树规模会迅速膨胀。这个上限是一个典型的工程折中：真实模板的独立块很少超过 4 个，6 已经留足余量。

标签约定

映射器和语法树之间用一组固定的 tag 常量通信：

1
static constexpr const char * REASONING = "reasoning";
2
static constexpr const char * CONTENT   = "content";
3
static constexpr const char * TOOL      = "tool";
4
static constexpr const char * TOOL_OPEN = "tool-open";
5
static constexpr const char * TOOL_CLOSE= "tool-close";
6
static constexpr const char * TOOL_ID   = "tool-id";
7
static constexpr const char * TOOL_NAME = "tool-name";
8
static constexpr const char * TOOL_ARGS = "tool-args";
9
static constexpr const char * TOOL_ARG_OPEN  = "tool-arg-open";
10
static constexpr const char * TOOL_ARG_CLOSE = "tool-arg-close";
11
static constexpr const char * TOOL_ARG_NAME  = "tool-arg-name";
12
static constexpr const char * TOOL_ARG_VALUE = "tool-arg-value";
13
static constexpr const char * TOOL_ARG_STRING_VALUE = "tool-arg-string-value";

这些标签在语法树里出现的位置，就是映射器要读取的位置。TOOL_ARG_STRING_VALUE 和 TOOL_ARG_VALUE 的区别很重要：前者用于 schema 明确声明为字符串的参数，映射器会给值加引号并转义；后者用于 JSON 值或裸文本，映射器按原样处理，只在需要时做引号归一化。

工具调用的生命周期

一个工具调用在映射器里经历四个阶段：打开、命名、填参数、关闭。

打开时，TOOL_OPEN 创建一个 pending_tool_call，把参数缓冲 args_buffer 清空，参数计数归零，引号挂起标记复位。这个“挂起”状态是流式解析的关键：一个调用可能先出现参数、后出现函数名（有些模板把参数写在函数名之前），此时参数不能直接写进调用对象，因为还不知道它属于哪个函数。

命名时，TOOL_NAME 把节点文本填入 name，并把缓冲里的参数合并进来；如果缓冲为空，就给参数一个 { 作为起点。然后调用被推进 result.tool_calls，指针改为指向结果数组里的元素。这一步让流式增量可以立刻看到这个调用。

填参数时，映射器根据节点类型选择不同的写入方式：

1
if (is_arg_name && current_tool) {
2
    std::string arg_entry;
3
    if (arg_count > 0) { arg_entry = ","; }
4
    arg_entry += ordered_json(trim(node.text)).dump() + ":";
5
    ++arg_count;
6
    auto & target = args_target();
7
    if (target.empty()) { target = "{"; }
8
    target += arg_entry;
9
}
10

11
if ((is_arg_value || is_arg_string_value) && current_tool) {
12
    std::string value_content = std::string(node.text);
13
    std::string value_to_add;
14
    if (value_content.empty() && is_arg_string_value) {
15
        value_to_add = "\"";
16
        closing_quote_pending = true;
17
    } else if (!value_content.empty() && is_arg_string_value) {
18
        if (!closing_quote_pending) {
19
            value_to_add = "\"";
20
            closing_quote_pending = true;
21
        }
22
        value_to_add += escape_json_string_inner(value_content);
23
    } else if (!value_content.empty()) {
24
        value_to_add += normalize_container_value(value_content);
25
    }
26
    args_target() += value_to_add;
27
}

args_target() 返回的是“当前应该写到哪里”：如果函数名已经出现，就写进当前调用的 arguments；否则写进 args_buffer。这个间接层让“参数先于函数名”的模板也能工作。

关闭时，TOOL_CLOSE 做四件收尾工作：如果函数名始终没出现但有缓冲参数，把缓冲写进 arguments；如果还有挂起的引号，补一个 "；如果大括号没有闭合，按嵌套深度补 }；如果函数名非空，把调用推进结果数组。

这里最容易被忽略的是“补 }”的逻辑：

1
for (int d = json_brace_depth(current_tool->arguments); d > 0; d--) {
2
    current_tool->arguments += "}";
3
}

它只补大括号，不补中括号。原因是工具参数在 OpenAI 协议里必须是 JSON 对象，顶层永远是 {；数组只可能出现在对象内部，而对象的闭合会同时完成数组的语义。这个假设在 schema 允许“顶层参数就是数组”时不成立，但工具定义的顶层参数按规范就是对象，所以可以安全地简化。

部分结果与引号

流式解析最麻烦的是“值只到了一半”。以 {"city": "Bei 为例，AST 里会出现一个 TOOL_ARG_NAME 节点 city 和一个 TOOL_ARG_STRING_VALUE 节点 Bei，但引号还没闭合。映射器此时已经把 {"city": "Bei 写进 arguments，并设置 closing_quote_pending = true。下一帧到了 jing"，节点文本变成 Beijing，映射器发现引号已经挂起，就只追加 jing，不再补开引号；到 TOOL_ARG_CLOSE 时再补一个 "，得到 {"city": "Beijing"。

这个状态机保证了一个性质：任意时刻的 arguments 都是“如果现在强行结束，补全后能得到合法 JSON”的前缀。客户端可以安全地拼接这些片段，不必担心中间帧出现无法解析的结构。

调用 ID 的稳定性

有些模板不提供调用 ID，只提供函数名和参数。OpenAI 协议要求每个 tool_call 有唯一 id，客户端用它把工具结果和执行请求对应起来。llama.cpp 的解法是在消息层生成并缓存：

1
void common_chat_msg::set_tool_call_ids(std::vector<std::string> & ids_cache,
2
                                        const std::function<std::string()> & gen_tool_call_id) {
3
    for (auto i = 0u; i < tool_calls.size(); i++) {
4
        if (ids_cache.size() <= i) {
5
            auto id = tool_calls[i].id;
6
            if (id.empty()) { id = gen_tool_call_id(); }
7
            ids_cache.push_back(id);
8
        }
9
        tool_calls[i].id = ids_cache[i];
10
    }
11
}

ids_cache 按调用下标缓存。为什么不能每次解析都重新生成？因为流式帧是按调用下标增量发送的，如果第二帧的 id 和第一帧不同，客户端会把同一个调用当成两个。缓存把“第一次见到这个下标时生成”的 ID 固定下来，后续帧复用。

这里还有一个隐含约束：调用下标必须稳定。如果解析器在某一帧把两个调用合并成一个，或者改变了顺序，缓存就会错位。llama.cpp 的语法生成保证了调用按出现顺序追加、不重排，所以下标是单调的。

差量计算

common_chat_msg_diff::compute_diffs 比较前后两条消息，生成增量。正文和推理内容用 string_diff：

1
static std::string string_diff(const std::string & last, const std::string & current) {
2
    if (last.empty()) { return current; }
3
    if (!string_starts_with(current, last)) {
4
        if (string_starts_with(last, current)) { return ""; }
5
        throw std::runtime_error("Invalid diff: '" + last + "' not found at start of '" + current + "'");
6
    }
7
    return current.substr(last.size());
8
}

它假设新字符串一定以旧字符串为前缀。这符合“模型输出只增不减”的直觉，但解析器的部分结果可能违反它：例如某个标记先被识别成内容、后来又被识别成结构，导致前面的文本被重新归类。llama.cpp 对这种情况的处理是“允许旧串是新串的前缀时返回空增量”，否则抛异常。抛异常不是逃避，而是把“解析结果不单调”当成真正的 bug 暴露出来，避免把错误的增量发给客户端。

工具调用的差量更复杂。compute_diffs 只比较最后一个已有调用的参数增量，新增调用则整条发送：

1
if (!msg_prv.tool_calls.empty()) {
2
    const auto idx = msg_prv.tool_calls.size() - 1;
3
    const auto & pref = msg_prv.tool_calls[idx];
4
    const auto & newf = msg_new.tool_calls[idx];
5
    // 允许函数名在增量解析中从空变非空、从短变长
6
    if (pref.name != newf.name && !pref.name.empty() && !newf.name.empty()) {
7
        bool is_prefix = (newf.name.rfind(pref.name, 0) == 0);
8
        if (!is_prefix) { throw std::runtime_error("Invalid diff: tool call mismatch!"); }
9
    }
10
    const auto args_diff = string_diff(pref.arguments, newf.arguments);
11
    if (!args_diff.empty() || pref.id != newf.id || pref.name != newf.name) {
12
        auto & diff = diffs.emplace_back();
13
        diff.tool_call_index = idx;
14
        if (pref.id != newf.id || pref.name != newf.name) {
15
            diff.tool_call_delta.id = newf.id;
16
            diff.tool_call_delta.name = newf.name;
17
        }
18
        diff.tool_call_delta.arguments = args_diff;
19
    }
20
}

为什么只比较最后一个调用？因为前面的调用在语法上已经闭合，不会再变；只有最后一个调用可能还在增长。这个假设同样依赖“调用按顺序追加、不重排”的语法设计。

服务端为什么要重排增量

compute_diffs 产出的增量是“按消息结构变化”的，不是“按 OpenAI 流式协议”的。OpenAI 期望的顺序是：先发一个带 id、name、空 arguments 的调用头，再发参数片段。而解析器可能在函数名出现之前就已经积累了参数，导致第一帧同时带名字和一大段参数。

task_result_state::update_chat_msg 里的 filter_tool_calls 分支就是做这个重排：

1
for (size_t i = 0; i < chat_msg.tool_calls.size(); ++i) {
2
    if (sent_tool_call_names.count(i) || chat_msg.tool_calls[i].name.empty()) { continue; }
3
    if (d.tool_call_index != i || !d.tool_call_delta.arguments.empty()) {
4
        common_chat_msg_diff header;
5
        header.tool_call_index = i;
6
        header.tool_call_delta.id = chat_msg.tool_calls[i].id;
7
        header.tool_call_delta.name = chat_msg.tool_calls[i].name;
8
        diffs.push_back(std::move(header));
9
        sent_tool_call_names.insert(i);
10
    }
11
}

它维护一个“已经发过名字的调用下标”集合。当发现一个调用还没发过头、且当前增量不是“纯参数增量”时，先补一个只含 id 和 name 的 header，再把参数增量单独发。这样客户端收到的顺序就符合协议，不会出现“参数比函数名先到”的帧。

这个重排还处理了另一个边界：如果函数名在解析过程中从 get_ 长成 get_weather，sent_tool_call_names 已经记录了下标，后续帧只发参数，不再重复发名字。名字的最终形态以第一次发送时的完整值为准；如果解析器后来修正了名字，客户端不会收到修正，这是一个已知的取舍——函数名通常在一次解析内就完整出现，真正需要修正的情况很少。

特殊 token 与 UTF-8

流式解析还要处理两个字节级问题。

第一，特殊 token 的文本可能不是一个合法的 UTF-8 字符序列。llama.cpp 的 common_chat_input_tokenize 会把文本按词表切成 token，并记录每个 token 的字节范围；如果拼接后的文本和原始文本不一致（例如 tokenizer 的规范化改变了空格），它会退回纯文本模式，不携带 token 映射。这个回退保证了“解析器看到的文本”和“模型实际生成的文本”一致。

第二，AST 节点可能包含不完整的 UTF-8 序列。common_peg_ast_node 里有 invalid_utf8 字段，记录节点内无法解码的字节区间；sanitized_text() 会把这些区间替换成 U+FFFD。映射器在取文本时用 sanitized_text，避免把一个多字节字符的半个字节写进 JSON，导致客户端解码失败。

惰性语法与解析器的配合

惰性语法只约束生成，不改变解析。解析器仍然按完整语法解析整段输出，包括触发词之前的正文。这带来一个微妙的一致性要求：解析器的根规则必须允许“正文 + 工具段”，而 GBNF 的惰性版本只约束工具段。两者不是同一棵树，但共享同一套标记分析结果。

如果分析器把触发词识别错了，会出现两种症状：生成阶段语法一直不生效，模型自由发挥，输出格式飘逸；或者语法过早生效，模型刚写一个 < 就被约束成工具语法，正文被截断。排查时看 --verbose 日志里的 grammar_triggers 和分析出的 section_start 是否一致，是最快的路径。

模板漂移

模板是模型自带的，模型升级时模板可能改一个空格、换一个标记。差分分析对空格不敏感（optspace 会容忍），但对标记的变化敏感。一个标记改了，preserved_tokens 里还是旧的，采样器可能把新标记拆开，解析器等不到结束。

llama.cpp 的应对是“分析失败就报错，不静默降级”：

1
if (!tmpl.analysis) {
2
    throw std::invalid_argument("Unable to generate parser for this template. Automatic parser generation failed: " +
3
                                tmpl.analysis_error);
4
}

这个选择在服务场景里是对的：静默降级会让工具调用悄悄失效，客户端收到一堆正文而不是 tool_calls，排查成本更高。显式报错至少能在启动或首次请求时暴露问题。

函数名未知时的参数缓冲

前文讲过 args_buffer。这个设计的代价是：在函数名出现之前，解析器无法判断参数属于哪个工具，也就无法用该工具的 schema 校验参数。如果模型先写参数、后写函数名，且参数格式不符合任何工具的 schema，解析器只能先缓冲，等函数名出现后再决定。这个窗口期里，部分结果可能包含“看起来像参数但还没归属”的文本，映射器的处理是把它放进缓冲，不写进任何调用。

并行调用的交错

parallel_tool_calls 为 true 时，多个调用的参数可能交错出现。llama.cpp 的语法是“调用 A 完整、调用 B 完整、调用 C 完整”的序列，不允许交错；如果模型真的交错输出，解析器会在调用 A 的参数段遇到调用 B 的起始标记，匹配失败。

这不是解析器的缺陷，而是语法设计的取舍：交错输出在 JSON 原生格式里无法用简单的递归语法表达，除非把每个调用的参数都做成“可中断”的状态机。主流模型的训练格式本身也倾向顺序输出，所以 llama.cpp 选择不支持交错。工程上如果遇到交错输出的模型，正确做法是换模板或在服务端做缓冲重排，而不是改解析器。

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

前文提到协议层禁止“工具 + grammar”。这个限制的根源是：工具语法的根规则是“推理 + 工具段 + end”，而结构化输出的根规则是“一个 JSON 值 + end”。两者对“整段输出”的约束互斥。如果强行合并，只能做成语法的并集，模型可能输出一个 JSON 值而不是工具调用，客户端无法区分。

llama.cpp 在应用模板时直接抛错：

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

这是一个“早失败”的设计，比在解析阶段发现歧义要好。

思考内容与工具调用的先后

有些模型先思考、再调用工具；有些模型在工具调用前不允许思考。分析器用 reasoning_mode::TOOLS_ONLY 区分后者：只有当消息里带工具调用时才提取思考内容，普通正文不提取。这个模式来自“带推理内容 + 工具调用”和“带推理内容 + 纯正文”两次渲染的差异比较。

如果模式判断错了，表现是：模型明明写了 <think>，但服务端把它当正文发给客户端；或者普通正文里的 <think> 被误当成推理标记，正文被截断。排查时看 common_chat_templates_get_caps 返回的 supports_reasoning 和 reasoning_mode 是否符合预期。

语言模型输出的是 token，不是字符

所有解析都发生在文本层，但文本是由 token 拼出来的。一个 token 可能包含多个字符、一个字符可能跨多个 token。llama.cpp 的处理是把 token 展开成字节，再让 PEG 在字节层匹配。这带来两个后果：

• 语法里的字面量必须按 UTF-8 字节匹配，不能假设“一个字符一个节点”；
• 部分匹配可能停在一个字符的中间，NEED_MORE_INPUT 必须能处理这种边界。

common_peg_ast_node 的 invalid_utf8 和 sanitized_text 就是为这个边界准备的。映射器不会把半个字符写进 JSON。