执行摘要

Gemma4 工具解析的流式性能优化：通过引入状态机（Text/Header/ToolCall）和增量扫描取代全缓冲区重复解析，长工具参数场景下延迟降低约 600 倍。核心设计是保持框架扫描与完整语法分离，在遇到结束标记前只做轻量扫描。

功能与动机

Gemma4 模型使用特殊标记 <|tool_call|> 和 <tool_call|> 表示工具调用，原实现每次流 chunk 到达时都在缓冲区上重新运行 gemma4_args 完整解析器，导致 O(n²) 复杂度。PR 提出只增量扫描原始参数直到结束标记，再触发一次完整解析，从而将热路径复杂度降至 O(n)。

实现拆解

1. 状态机引入：将 Gemma4Event 拆解为三个子事件（ToolCallStart、ToolCallHeader、ToolCall），并新增 Gemma4Mode 枚举跟踪当前状态。
2. 模式化分发：parse_next_gemma4_event 根据 mode 调用不同的子解析器，避免全局混合处理。
3. 增量扫描函数：gemma4_raw_args_until_tool_call_end 在 ToolCall 模式下逐字节扫描，通过跟踪 <|"|> 字符串分隔符的奇偶性忽略字符串内部标记，遇到外界 <tool_call|> 时停止。
4. 完成解析：扫描到结束标记后，将累积的原始参数字符串交由原 gemma4_args 解析器做一次完整语法解析，生成最终的 ToolCall 事件。
5. 复位保护：reset 方法根据当前模式保留必要的前缀（如 call: 和函数名），确保中断后重建缓冲区正确。
6. 基准覆盖：新增 long_tool_argument_fixture 模拟长工具参数流式输入，注册到 criterion 基准组。

rust/src/tool-parser/src/gemma4.rs

核心逻辑变更：引入 Gemma4Mode 状态机、增量扫描函数 gemma4_raw_args_until_tool_call_end，以及对应的事件分发和复位逻辑。

/// 增量扫描 Gemma4 工具调用原始参数，直到遇到字符串外部的 `<tool_call|>` 结束标记。
/// 返回本次扫描消耗的字节数（不含结束标记本身）。
/// 通过跟踪 `<|\"|>` 字符串分隔符的奇偶性，避免将字符串内部的标记误判。
fn gemma4_raw_args_until_tool_call_end<'i>(
    input: &mut Gemma4Input<'i>,
    state: &mut Gemma4ArgsScanState,
) -> ModalResult<usize> {
    // 从上次扫描结束的位置继续
    let start = state.scanned_len;
    let mut offset = 0;
    let data = &input.as_ref()[start..];
​
    // 逐个字节扫描，注意偏移量与实际字符串位置的转换
    // 标准写法使用 winnow 的 `take_until` 和 `literal` 组合，
    // 但为了跟踪 in_string 状态，这里手动推进
    while offset < data.len() {
        // 检查是否遇到字符串分隔符
        if data[offset..].starts_with(STRING_DELIM) {
            state.in_string = !state.in_string;
            offset += STRING_DELIM.len();
            continue;
        }
        // 仅在字符串外检查结束标记
        if !state.in_string && data[offset..].starts_with(TOOL_CALL_END) {
            // 消耗掉所有原始参数（结束标记之前的部分），更新扫描长度
            state.scanned_len += offset;
            return Ok(offset);
        }
        offset += 1;
    }
    // 未找到结束标记，消耗所有内容并报告不完全
    state.scanned_len += offset;
    Err(ErrMode::Incomplete(Needed::Unknown))
}
​
/// 主分发函数：根据当前模式调用不同的事件解析逻辑
fn parse_next_gemma4_event<'i>(
    input: &mut Gemma4Input<'i>,
    parser: &mut Gemma4ToolParser,
) -> ModalResult<Gemma4Event> {
    match &parser.mode {
        Gemma4Mode::Text => {
            // Text 模式：解析普通文本，直到遇到 `<|tool_call>` 或 EOI
            let event = parse_text_event(input)?;
            Ok(event)
        }
        Gemma4Mode::Header => {
            // Header 模式：解析函数调用头，如 `call:func_name{`
            let event = tool_call_header_event(input)?;
            Ok(event)
        }
        Gemma4Mode::ToolCall { name: _, args_scan: state } => {
            // ToolCall 模式：增量扫描原始参数，直到结束标记
            // 如果找到标记，则取出完整参数并用 gemma4_args 解析
            let consumed = gemma4_raw_args_until_tool_call_end(input, state)?;
            // 如果成功（返回 Ok），表示找到了结束标记
            // 消耗掉输入中对应的内容（包括结束标记，但结束标记由上层处理）
            … // 后续 : 使用已消耗的原始参数字符串调用 gemma4_args 解析器
        }
    }
}

评论区精华

无实质性 Review 讨论。作者在 PR body 中阐述了与 #43513 的对比：更简单的合约——只将 <tool_call|> 作为框架定界符，除非出现在 Gemma 字符串中；完整语法验证保留在 gemma4_args 解析器中，避免在流式层重复实现。对于模型格式中极少数 marker 形状文本被误分割为结束符的歧义，作者认为是可以接受的权衡。

风险与影响

• 标记误识别风险：未引用的 <tool_call|> 裸值将被误判为结束标记。作者已知并在 PR body 中说明这是设计权衡，实际模型输出中极罕见。
• 状态复位边界：reset 方法仅在当前模式已知时重建缓冲区；若异常中断（如 panic）可能丢失状态，但 Rust 类型系统确保正常路径下状态一致。
• 短内容微退化：状态机切换和扫描器开销在短参数场景有微小增加（基准显示仍为微秒级），可忽略。
• 测试覆盖：当前只添加了基准测试，缺少针对边界状态的单元测试（如 reset 在 Header 模式、字符串分隔符嵌套等）。

关联脉络

关联 PR #43513，该 PR 尝试构建语法感知的流式扫描器，但复杂度更高。本 PR 选择更小的设计合约，以轻微误判风险换取极大的实现简化和性能提升。整体上属于持续优化 Gemma4 模型工具解析能力的一条工作流。