[Bug]: Gemma 4 (31B / 26B-A4B) generates infinite repetition loops, especially with structured output (JSON schema)

快速结论：当使用 vLLM 服务 Gemma 4 模型并启用 JSON Schema 结构化输出时，模型可能在生成一段有效前缀后陷入无限重复循环，持续输出无意义的重复 token 直到达到 max_tokens。

问题场景

该问题在 vLLM 中通过 OpenAI 兼容 API 或直接使用 response_format=json_schema 参数调用 Gemma 4 系列模型（包括 31B 和 26B-A4B 指令版）时触发。受结构化输出的语法约束编码（xgrammar）限制影响，模型 token 空间受限，容易陷入重复循环。

报错原文

Gemma 4 models (31B-it and 26B-A4B-it) produce infinite repetition loops when generating structured output via JSON schema. The model generates a valid prefix, then enters a degenerate loop repeating a phrase with minor variations until max_tokens is hit — consuming GPU resources for thousands of garbage tokens.

原因分析

这不是 vLLM 代码层的单一 Bug，而是 模型层面的重复倾向，在多平台（google-deepmind/gemma#622、google-deepmind/gemma#610、Vertex AI）均有确认。vLLM 的采样流水线放大了该问题：

语法约束位掩码在采样惩罚之前应用（vllm/v1/worker/gpu/model_runner.py:841-848），被禁止的 token 被设为 -inf logits，惩罚无法恢复它们。
在 JSON 字符串值内部，xgrammar 允许成千上万 token，但模型概率分布严重偏向重复短语。
默认 repetition_penalty=1.0（无惩罚）无法抑制此倾向。
已有的 RepetitionDetectionParams（N-gram 循环检测）是 opt-in 的，默认关闭。

环境排查

vLLM 版本：确认是否为 0.19.1rc1.dev355 或更高版本（该版本可能已包含修复）。
模型：注意 Gemma 4 的 BOS token 传递是否正确——缺乏 chat_template 可能导致特殊 token（如 <bos>）未正确传入，从而引发模型异常行为。
PyTorch 版本：2.11.0 或兼容版本。
CUDA 版本：12.9 或以上（取决于驱动）。
GPU：Blackwell 或 Hopper 架构，多卡时需要检查显存分配。

解决步骤

升级 vLLM 至包含修复的版本：社区已提出 PR #40099，自动在结构化输出激活且用户未设置显式重复检测时启用 RepetitionDetectionParams。默认阈值：max_pattern_size=20, min_pattern_size=3, min_count=4，仅在约 60+ 纯 N-gram 重复 token 后触发。
手动启用重复检测：作为临时方案，启动 vLLM 服务器时设置 --repetition-detection 参数，或通过 API 参数显式配置 repetition_detection。
检查 chat_template 使用：确保使用方法调用中正确传递了 chat_template，以便模型接收到 BOS 等特殊 token。例如，使用 client.chat.completions.create 而不是单纯文本补全。
调整采样参数：尝试非默认的 repetition_penalty（如 1.05-1.2），并考虑设置 top_p 或 temperature 来降低重复倾向。

验证方法

启动 vLLM 并调用带有 JSON Schema 的结构化输出请求，观察生成的响应是否在合理长度内完成，而不是无限重复。通过监控 GPU 利用率是否异常持续高企，以及 finish_reason 是否为正常 "stop" 而非 "length" 或 "repetition_detected" 来判定。