执行摘要

• 一句话：Gemma4 解析器迁移至统一引擎框架
• 推荐动作：值得精读，特别是 _parse_gemma4_args 的流式部分和状态机配置。展示了如何将复杂手写解析器迁移到统一引擎框架的设计模式。

功能与动机

Gemma4 模型原有的 reasoning 和 tool 解析器是独立编写的，处理 spec decoding、流式推理/工具调用边界时有诸多 bug。PR 将其迁移到统一的 ParserEngine 框架（最初为 Qwen3 设计），以解决这些问题并清理代码。PR 描述提到：'This cleans up a multitude of issues with Gemma4 models (including DiffusionGemma) when used with spec decoding, stream_interval > 1, and general handling of reasoning / tool call boundaries, especially in streaming scenarios.'

实现拆解

1. 创建 vllm/parser/gemma4.py，基于 ParserEngineConfig 定义状态机和配置。包括 _GEMMA4_MODEL_DROP_TOKENS、channel/tool 常量、_parse_gemma4_args 函数解析自定义参数格式，以及 Gemma4Parser 类继承 ParserEngine。
2. 删除旧的 vllm/tool_parsers/gemma4_tool_parser.py（896行）和 vllm/reasoning/gemma4_reasoning_parser.py（225行），不再使用。
3. 新增 vllm/tool_parsers/gemma4_engine_tool_parser.py 和 vllm/reasoning/gemma4_engine_reasoning_parser.py，作为注册适配器，指向新的 gemma4 配置。
4. 在 vllm/parser/engine/parser_engine.py 中添加 _preprocess_feed 逻辑以支持新的 hold-back 恢复。
5. 修改 vllm/parser/qwen3.py 中的 CONTENT→TOOL_START 转换，增加 REASONING_END 事件，防止工具调用紧跟工具响应时缺少推理结束信号。
6. 增加/修改大量测试：tests/parser/engine/test_gemma4_streaming_reasoning.py（1201行新增）、test_token_id_scanner.py（652行修改）、trace_builder.py（113行新增 Gemma4 段构建）、test_replay.py、test_gemma4_tool_parser.py 等，覆盖各类流式边界情况。

关键文件：

• vllm/parser/gemma4.py（模块 解析器；类别 source；类型 core-logic；符号 _strip_partial_delim, _parse_gemma4_args, _parse_gemma4_array, _gemma4_arg_converter）: 新的单一状态机解析器，取代旧的两个解析器，是核心变更。
• vllm/tool_parsers/gemma4_tool_parser.py（模块 工具解析器；类别 source；类型 deletion；符号 _parse_gemma4_value, _parse_gemma4_args, _parse_gemma4_array, Gemma4ToolParser）: 删除旧的工具解析器，被引擎框架替代。
• vllm/reasoning/gemma4_reasoning_parser.py（模块 推理解析器；类别 source；类型 deletion；符号 Gemma4ReasoningParser, init, adjust_request, start_token）: 删除旧的推理解析器，被引擎框架替代。
• tests/parser/engine/test_gemma4_streaming_reasoning.py（模块 测试；类别 test；类型 test-coverage；符号 _make_tokenizer, decode, _stream_tokens_batched, _collect_fields）: 新增全面的流式推理+工具调用测试，覆盖边缘场景。
• vllm/parser/engine/parser_engine.py（模块 引擎核心；类别 source；类型 core-logic；符号 _preprocess_feed, _feed）: 引擎核心增加 hold-back 恢复支持，使 Gemma4 流式解析更健壮。
• vllm/tool_parsers/gemma4_engine_tool_parser.py（模块 工具解析器；类别 source；类型 core-logic；符号 Gemma4EngineToolParser）: 注册适配器，确保旧配置名仍能正确加载新解析器。
• vllm/reasoning/gemma4_engine_reasoning_parser.py（模块 推理解析器；类别 source；类型 dependency-wiring）: 注册适配器，确保旧推理解析器名能加载新引擎实现。

关键符号：_strip_partial_delim, _parse_gemma4_args, _parse_gemma4_array, _gemma4_arg_converter, Gemma4Parser, Gemma4ToolParser, Gemma4ReasoningParser

关键源码片段

vllm/parser/gemma4.py

新的单一状态机解析器，取代旧的两个解析器，是核心变更。

# 常量定义
CHANNEL_START = "<|channel>"
CHANNEL_END = "<channel|>"
TOOL_CALL_START = "<|tool_call>"
TOOL_CALL_END = "<tool_call|>"
STRING_DELIM = '<|"|>'
_DELIM_LEN = len(STRING_DELIM)
​
# 部分定界符后缀列表，用于流式截断
_PARTIAL_DELIM_SUFFIXES = tuple(
    STRING_DELIM[:k] for k in range(len(STRING_DELIM), 0, -1)
)
​
​
def _strip_partial_delim(value: str) -> str:
    """Strip a trailing partial ``STRING_DELIM`` prefix from *value*.
    Prevents partial delimiters from leaking into the streamed JSON diff.
    """
    for suffix in _PARTIAL_DELIM_SUFFIXES:
        if value.endswith(suffix):
            return value[: -len(suffix)]
    return value
​
​
def _parse_gemma4_args(args_str: str, *, partial: bool = False) -> dict:
    """Parse Gemma4's custom key:value format into a Python dict.
    Format examples::
        location:<|"|>Tokyo<|"|>
        count:42,flag:true
    Args:
        args_str: The raw Gemma4 argument string.
        partial: When True (streaming), bare values at end are omitted.
    """
    if not args_str or not args_str.strip():
        return {}
​
    result: dict = {}
    i = 0
    n = len(args_str)
​
    while i < n:
        # 跳过空白和逗号
        while i < n and args_str[i] in (" ", ",", "\n", "\t"):
            i += 1
        if i >= n:
            break
​
        # 解析键（无引号，遇到 ':' 结束）
        key_start = i
        while i < n and args_str[i] != ":":
            i += 1
        if i >= n:
            break
        key = args_str[key_start:i].strip()
        # 修复 #44715：如果键被 <|"|> 包围，去除定界符
        if key.startswith(STRING_DELIM) and key.endswith(STRING_DELIM):
            key = key[_DELIM_LEN:-_DELIM_LEN]
        i += 1 # 跳过 ':'
​
        # 值解析继续（字符串、嵌套对象、数组等）
        # ... 完整实现见头文件

评论区精华

仅在 qwen3.py 中一行变更触发讨论：sfeng33 询问 (ParserState.CONTENT, "TOOL_START") 增加 EventType.REASONING_END 是否 intended。bbrowning 确认是该 PR 对 Qwen3 的修复，处理模型在工具响应后立即输出工具调用而无推理时的边缘情况，并指出测试由新的 tool-after-tool-response Scenario 覆盖。

• qwen3.py transition 变更意图 (correctness): bbrowning 确认是修复工具调用紧跟工具响应时缺少推理结束信号的边缘情况，测试由新的 tool-after-tool-response Scenario 覆盖。

风险与影响

• 风险：
  1) 旧解析器完全删除，若出现回归无法快速切换回旧路径，需要依赖测试覆盖。
  2) qwen3.py 的 transition 变更影响所有使用 Qwen3 引擎的模型，虽然修复了边缘情况，但可能引入新的顺序问题。
  3) Gemma4 自定义参数格式解析器重新实现，流式部分兼容性需充分验证。
  4) 测试虽多但模拟 tokenizer 可能遗漏真实 tokenizer 行为差异。
  • 影响：对用户透明（无需配置变更），但显著改善 Gemma4 在流式、spec decoding 和 MTP 下的解析正确性，特别是工具调用密集场景。内部架构统一到引擎框架，方便未来扩展。对开发团队，后续模型解析器可参考此模式。影响范围为 Gemma4 用户，特别是使用 spec decoding 和流式工具调用的用户。
  • 风险标记：旧解析器删除后回滚困难, 核心引擎变更影响其他模型, 复杂流式状态机潜在边缘情况, 模拟 tokenizer 测试覆盖不足

关联脉络

• PR #45832 [Bugfix][Gemma4] Fix parsing when thinking is disabled: 同一 Gemma4 解析器修复系列，本 PR 是更彻底的引擎化替代。