Prhub

#39114 [Bugfix] Fix Gemma4 streaming tool call corruption for split boolean/number values

原始 PR 作者 sfeng33 合并时间 2026-04-09 00:46 文件变更 2 提交数 2 评论 0 代码增减 +78 / -8

bugfix tool-calling v1 frontend

执行摘要

修复 Gemma4 流式工具调用中布尔 / 数值跨 token 分割导致的类型损坏

修复Issue #39089 'gemma4 tool-call-parser corrupts boolean values in tool call arguments during streaming mode'。根本原因：_parse_gemma4_value()在流式模式下将部分布尔/数值字面值（如'tru'、'fals'、'4'）误识别为裸字符串，导致后续类型转换错误（字符串→布尔值），从而损坏流式JSON输出。PR body中提供了手动复现步骤和修复前后的对比示例。

该PR值得精读，特别是_parse_gemma4_args和_parse_gemma4_array中partial参数的设计，展示了如何处理流式解析中的不完整输入以避免类型损坏。对于从事工具解析或流式处理的工程师，这是一个实用的模式。

讨论亮点

review讨论较少，但所有评论均为正面。gemini-code-assist[bot]指出'implementation is sound and well-tested'，认可引入partial参数防止类型不稳定的设计。bbrowning表示已在本地进行广泛测试，'things are working well'，并批准合并。robertgshaw2-redhat也批准。无争议点或未解决疑虑。

实现拆解

核心改动在vllm/tool_parsers/gemma4_tool_parser.py：1. 为_parse_gemma4_args()和_parse_gemma4_array()函数添加partial参数（默认False），用于标识流式解析中的不完整输入。2. 在解析裸值时，若partial=True且已到字符串末尾，则跳过该值（break），避免将部分字面值（如'tru'）误解析为字符串。3. 递归解析嵌套对象和数组时，根据depth>0判断是否传递partial=True，确保嵌套结构中的不完整值也被正确处理。测试文件tests/tool_parsers/test_gemma4_tool_parser.py新增三个测试：test_streaming_boolean_split_across_chunks、test_streaming_false_split_across_chunks、test_streaming_number_split_across_chunks，分别验证布尔true、false和数值跨chunk分割的场景。

文件 模块 状态 重要度
vllm/tool_parsers/gemma4_tool_parser.py tool_parsers modified 8.0
tests/tool_parsers/test_gemma4_tool_parser.py tests modified 6.0

分析完成后，这里会展示 LLM 生成的相对完整源码片段和详细注释。

关键符号

_parse_gemma4_args _parse_gemma4_array _parse_gemma4_value test_streaming_boolean_split_across_chunks test_streaming_false_split_across_chunks test_streaming_number_split_across_chunks

评论区精华

partial 参数设计用于处理流式解析中的不完整值 设计

gemini-code-assist[bot] 认可引入 partial 参数来防止类型不稳定，避免将部分布尔 / 数值字面值误解析为字符串

结论：设计合理，测试充分，无争议 · 已解决

风险与影响

  1. 回归风险：修改了核心解析函数_parse_gemma4_args和_parse_gemma4_array，可能影响非流式模式下的解析行为，但partial参数默认False，且测试覆盖了流式场景，风险较低。2. 性能风险：添加了partial参数检查和递归传递，可能轻微增加解析开销，但影响可忽略。3. 兼容性风险：仅针对Gemma4工具解析器，不影响其他模型或解析器。4. 测试覆盖：新增测试针对特定跨chunk场景，但未覆盖所有可能的边界情况（如嵌套结构中更复杂的分割）。
  1. 对用户：修复了Gemma4模型在流式工具调用中布尔/数值参数损坏的问题，提升工具调用的可靠性和用户体验。2. 对系统：仅影响Gemma4工具解析器的流式解析逻辑，不改变其他组件。3. 对团队：提供了处理流式解析中部分值类型不稳定的通用模式（partial参数），可供其他解析器参考。影响范围局限于使用Gemma4工具解析器的流式请求。
核心路径变更 测试覆盖有限

关联 Issue

#39089 [Bug]: gemma4 tool-call-parser corrupts boolean values in tool call arguments during streaming mode

完整报告

Markdown PDF

执行摘要

  • 一句话：修复Gemma4流式工具调用中布尔/数值跨token分割导致的类型损坏
  • 推荐动作：该PR值得精读，特别是_parse_gemma4_args和_parse_gemma4_array中partial参数的设计，展示了如何处理流式解析中的不完整输入以避免类型损坏。对于从事工具解析或流式处理的工程师，这是一个实用的模式。

功能与动机

修复Issue #39089 'gemma4 tool-call-parser corrupts boolean values in tool call arguments during streaming mode'。根本原因：_parse_gemma4_value()在流式模式下将部分布尔/数值字面值（如'tru'、'fals'、'4'）误识别为裸字符串，导致后续类型转换错误（字符串→布尔值），从而损坏流式JSON输出。PR body中提供了手动复现步骤和修复前后的对比示例。

实现拆解

核心改动在vllm/tool_parsers/gemma4_tool_parser.py：1. 为_parse_gemma4_args()和_parse_gemma4_array()函数添加partial参数（默认False），用于标识流式解析中的不完整输入。2. 在解析裸值时，若partial=True且已到字符串末尾，则跳过该值（break），避免将部分字面值（如'tru'）误解析为字符串。3. 递归解析嵌套对象和数组时，根据depth>0判断是否传递partial=True，确保嵌套结构中的不完整值也被正确处理。测试文件tests/tool_parsers/test_gemma4_tool_parser.py新增三个测试：test_streaming_boolean_split_across_chunks、test_streaming_false_split_across_chunks、test_streaming_number_split_across_chunks，分别验证布尔true、false和数值跨chunk分割的场景。

关键文件：

  • vllm/tool_parsers/gemma4_tool_parser.py（模块 tool_parsers）: 核心修复文件，修改了参数解析逻辑以处理流式模式下的部分值
  • tests/tool_parsers/test_gemma4_tool_parser.py（模块 tests）: 新增测试验证布尔和数值跨chunk分割场景，确保修复正确性

关键符号：_parse_gemma4_args, _parse_gemma4_array, _parse_gemma4_value, test_streaming_boolean_split_across_chunks, test_streaming_false_split_across_chunks, test_streaming_number_split_across_chunks

评论区精华

review讨论较少，但所有评论均为正面。gemini-code-assist[bot]指出'implementation is sound and well-tested'，认可引入partial参数防止类型不稳定的设计。bbrowning表示已在本地进行广泛测试，'things are working well'，并批准合并。robertgshaw2-redhat也批准。无争议点或未解决疑虑。

  • partial参数设计用于处理流式解析中的不完整值 (design): 设计合理，测试充分，无争议

风险与影响

  • 风险：1. 回归风险：修改了核心解析函数_parse_gemma4_args和_parse_gemma4_array，可能影响非流式模式下的解析行为，但partial参数默认False，且测试覆盖了流式场景，风险较低。2. 性能风险：添加了partial参数检查和递归传递，可能轻微增加解析开销，但影响可忽略。3. 兼容性风险：仅针对Gemma4工具解析器，不影响其他模型或解析器。4. 测试覆盖：新增测试针对特定跨chunk场景，但未覆盖所有可能的边界情况（如嵌套结构中更复杂的分割）。
  • 影响：1. 对用户：修复了Gemma4模型在流式工具调用中布尔/数值参数损坏的问题，提升工具调用的可靠性和用户体验。2. 对系统：仅影响Gemma4工具解析器的流式解析逻辑，不改变其他组件。3. 对团队：提供了处理流式解析中部分值类型不稳定的通用模式（partial参数），可供其他解析器参考。影响范围局限于使用Gemma4工具解析器的流式请求。
  • 风险标记：核心路径变更, 测试覆盖有限

关联脉络

  • PR #38909 [Bugfix][Frontend] Fix Gemma4 streaming HTML duplication after tool calls: 同为Gemma4工具解析器的bugfix，涉及流式处理和前端问题，可能共享类似上下文
  • PR #38848 [Bugfix] Fix Qwen3 tool parser for Responses API tools: 同为工具解析器的bugfix，涉及Responses API和工具调用，反映工具解析模块的持续改进
  • PR #38755 [Parser] Migrate response api streaming to unified parser: 涉及流式解析和统一解析器，与本PR的流式处理场景相关

参与讨论