执行摘要

该PR修复了Gemma 4模型在流式工具调用中，因令牌边界切分字符串分隔符导致部分分隔符片段（如'<'、'|'）泄漏到JSON参数中，从而引发JSON解析错误的bug。通过扩展参数解析时剥离的字符集，并添加单元测试覆盖此边界情况，确保流式输出的JSON始终有效。影响范围限于Gemma 4工具调用，风险较低，是重要的可靠性修复。

功能与动机

修复Issue #38946中报告的问题：Gemma 4流式工具调用会生成无效JSON。问题根源在于，当流式输出中令牌边界切分了Gemma 4的字符串分隔符<|"|>时，残留的分隔符片段（如'<'、'|'）未被剥离，混入JSON参数值中，导致后续解析失败。PR body明确引用该issue，并指出“Partial <|"|> delimiter chars must not leak into streamed JSON”。

实现拆解

主要改动涉及两个文件：

1. 核心解析逻辑（vllm/tool_parsers/gemma4_tool_parser.py）：
   • 在_emit_argument_diff方法中，修改safe_json的生成逻辑，将剥离的字符从"}"、'"'、"]"扩展为还包括"<"、"|"、"\\"、">"。
   • 代码片段：
     

     while safe_json and safe_json[-1] in ("}", '"', "]", "<", "|", "\\", ">"):
         safe_json = safe_json[:-1]
     

   • 这确保了即使分隔符被部分流式输出，其片段也不会污染JSON。
2. 单元测试（tests/tool_parsers/test_gemma4_tool_parser.py）：
   • 新增test_streaming_split_delimiter_no_invalid_json测试，模拟分隔符被切分的流式chunks：
     

     chunks = [
         "<|tool_call>",
         "call:todowrite{",
         'content:<|"|>Buy milk<|",
         '"|>}',
         "<tool_call|>",
     ]
     

   • 验证参数文本可被json.loads解析，且不包含'<'等分隔符片段。

评论区精华

review讨论简洁，主要聚焦于修复验证：

• bbrowning：

  “I cloned this locally, verified the new unit test reproduces the failure without the parser change and then verified the parser change fixes the unit test. The change looks good to me and the additional withheld characters here match what the official Gemma 4 prompt formatting docs show as the string delimiters.”

  • 确认了修复的有效性，并指出剥离字符集与官方文档一致，支持了设计合理性。
  • 其他reviewer（robertgshaw2-redhat、tlrmchlsmth）无具体评论，直接批准。无争议或未解决疑虑。

风险与影响

• 风险：
  • 剥离字符集扩展可能过度剥离有效字符（如JSON字符串中合法出现的'<'、'>'），但Gemma 4的JSON参数通常不包含这些字符，风险可控；现有测试应覆盖常规场景。
  • 性能影响可忽略，仅增加少量字符检查。
• 影响：
  • 用户：修复后，Gemma 4流式工具调用用户不再遇到JSON解析错误，提升可靠性。
  • 系统：仅影响工具解析模块，不涉及核心推理路径或其他模型。
  • 团队：新增测试作为回归防护，变更简单易维护。

关联脉络

• 从近期历史PR看，本PR与工具调用（tool-calling）相关，但未发现直接关联的PR。
• 作为bugfix，它独立解决了Gemma 4模型在流式场景下的一个边界问题，体现了对模型特定格式处理的精细化改进。