[Bug]: Vllm + Gemma 4 + claude code: tool calling problems

快速结论：该 bug 出现在使用 vLLM 部署 Gemma 4 模型（如 google/gemma-4-26B-A4B-it 或 Gemma-4-31B-it）并通过 Claude Code 等 agent 工具进行多轮 tool calling 时。症状包括工具调用参数中出现未闭合的 <|"|> 标记，或者整个 <|tool_call> 序列作为纯文本泄露到输出中。优先排查：使用 #39027 中的 chat template 配置，并确保开启 thinking 模式。

问题场景

用户使用 vLLM 部署 Gemma 4 系列模型，通过 OpenAI 兼容 API 提供给 Claude Code 等工具进行多轮 agentic 工作流。在持续 20–30 次工具调用后，出现以下两类失败模式：

工具调用的参数（如文件路径）中出现未闭合的 <|"|> 标记，导致解析失败。
整个 <|tool_call>...<tool_call|> 序列被模型以纯文本形式返回，而非解析为结构化工具调用。

报错原文

<|tool_call>call:Read{file_path:<|"|>src/paude/cli/domains.py<|"|>}<tool_call|>

此外，在流式模式下，工具调用可能以 finish_reason=stop 和 tools=0 返回，而相同请求在非流式模式下能正常返回 finish_reason=tool_calls 和有效工具调用。

原因分析

根据 Issue 中的多轮调试，根本原因是一个复合问题：

模型本身的行为： 在多轮长上下文中，Gemma 4 模型会间歇性地返回 <|tool_call>...<tool_call|> 序列作为普通文本（纯模型输出问题），而非作为可解析的工具调用。
流式与非流式不一致： 存在一个可以稳定复现的现象：相同请求在非流式模式下返回正确的 tool_calls，而在流式模式下返回 finish_reason=stop 且工具数量为 0。
早期猜测（已排除）： 社区曾怀疑 Gemma4ToolParser 跨请求复用导致 current_tool_id 累积，但经确认 parser 是 per-request 实例化的，该假设不成立。
可能原因： vLLM 的 Messages API 到 Chat Completions 的翻译、Gemma 4 的 reasoning parser 以及 tool parser 之间存在多个需要修复的边界情况。社区正在将修复拆分为多个针对性 PR。

环境排查

Python 版本：3.13.6（用户环境）
PyTorch 版本：2.10.0+cu130
CUDA 版本：13.2.51（runtime）/ 13.0（编译）
GPU 型号：NVIDIA RTX PRO 4000 Blackwell（3x）
驱动版本：595.45.04
vLLM 版本：0.18.2rc1.dev73+gdb7a17ecc（用户测试版本）
模型：google/gemma-4-26B-A4B-it 或 Gemma-4-31B-it
确认是否启用 thinking 模式（推荐开启）
确认使用的 chat template 是否来自 #39027

解决步骤

优先尝试 #39027 中的完整修复集。 该 PR 汇集了 chat template 和 reasoning parser 的修复。即使该 PR 不会直接合入，也会作为暂存区保持更新。阅读其中的 vllm serve 示例命令，确保正确配置 thinking 模式：
vllm serve google/gemma-4-26B-A4B-it --chat-template /path/to/gemma4_chat_template.jinja --enable-thinking
同时应用 #38909 和 #39114 中的修复（这些是分拆后有针对性的 PR）。
如果仍需修复工具解析问题，关注 #39027 的后续拆分 PR（社区正在将 Gemma 4 的 Messages API 翻译、reasoning parser 和 tool parser 的修复拆分成多个可合入的 PR）。
在部署命令中显式指定 --chat-template，使用 Gemma 4 专用的 chat template。这是目前社区确认有效的修复路径。
如果问题出现在流式模式下，可尝试改用非流式请求作为临时规避方案。非流式模式在用户测试中表现更稳定。

验证方法

在应用上述修复后，通过 Claude Code（或同类 agent 工具）进行多轮工具调用测试：

验证连续 30 次以上的工具调用不会出现 <|"|> 标记尚未闭合的参数。
验证长时间运行的对话中，<|tool_call> 序列不会被作为纯文本泄露。
验证流式与非流式模式下，相同请求的 tool calling 行为一致。

参考来源

vllm-project/vllm #39043 — [Bug]: Vllm + Gemma 4 + claude code: tool calling problems

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

[Bug]: Vllm + Gemma 4 + claude code: tool calling problems