docs(google/gemma-4-31b-it): document compact JSON workaround

[Mujae]

Summary

• document the grammar-valid whitespace-loop symptom for Gemma 4 31B JSON Schema output

• add the existing compact-xgrammar mitigation to the canonical model recipe

• clarify that the setting removes optional whitespace between JSON tokens, not whitespace inside string values

Related to vllm-project/vllm#40080.

Why

The current Gemma 4 31B recipe mentions structured outputs but does not document a known failure mode where the model produces a valid JSON prefix and then emits optional whitespace until max_tokens.

I revalidated the behavior with the same request body across both server configurations:

• Model: google/gemma-4-31B-it

• Revision: 842da3794eaa0b77d5f08bae87a17459d91ff475

• vLLM: 0.25.1

• Transformers: 5.13.1

• xgrammar: 0.2.3

• CUDA / GPU: CUDA 13.0 / NVIDIA B200

• Precision: BF16, TP=1

Server structured-output configuration | Runs | Result -- | -- | -- default (backend=auto, whitespace allowed) | 3/3 | finish_reason=length, 8,000 completion tokens, invalid/incomplete JSON, 93.6555% whitespace backend=xgrammar, disable_any_whitespace=true | 3/3 | finish_reason=stop, 368 completion tokens, valid JSON Schema output

The prompt, JSON Schema, request body, sampling parameters, model snapshot, and runtime were held constant. The mitigation is documented conditionally rather than changing the recipe's default server arguments.

Validation

• YAML parses successfully with js-yaml

• Markdown fences in the rendered guide are balanced

• git diff --check passes

• the repository API validator was also attempted; current main fails first on an unrelated pre-existing models/zai-org/GLM-5.2.yaml feature-mode validation error

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
vllm-recipes	Error		Jul 24, 2026 9:55am

[gemini-code-assist]

Code Review

This pull request updates the metadata date for the Gemma 4 31B model and adds documentation under the "Structured Outputs" section to address a whitespace loop issue by configuring vLLM with xgrammar. The reviewer suggested presenting only the --structured-outputs-config flag instead of a standalone vllm serve command to prevent out-of-memory errors, as the model typically requires tensor parallelism parameters to run.