[Bugfix] Fix Gemma4 non-streaming reasoning parsing

[jacobzhang22]

Purpose

Fixes #38855, where Gemma4 non-streaming chat completions fail to populate reasoning_content and instead return the thought trace in content.

The issue report suggested a parser-side token ID fix, but after inspecting the merged Gemma4 implementation from #38826, the Gemma4 parser already inherits start_token_id / end_token_id support from BaseThinkingReasoningParser. The actual failure is in the non-streaming OpenAI chat serving path: it passes output.text to the parser after special tokens have already been stripped, so Gemma4 never sees <|channel> / <channel|> boundaries.

This PR fixes that handoff in vllm/entrypoints/openai/chat_completion/serving.py by reconstructing parser input from output.token_ids with skip_special_tokens=False when the reasoning parser's boundary token IDs are present. This keeps the fix narrow, preserves the existing parser contract, and avoids adding parser-side logic that would need to infer reasoning boundaries from text after the delimiter tokens have already been removed.

Test Plan

.venv/bin/python -m pytest tests/entrypoints/openai/chat_completion/test_serving_chat.py -k gemma4_non_streaming_reasoning_uses_token_ids -v
.venv/bin/pre-commit run --files vllm/entrypoints/openai/chat_completion/serving.py tests/entrypoints/openai/chat_completion/test_serving_chat.py

Test Result

Passed:

• Targeted regression test for the new non-streaming Gemma4 behavior in tests/entrypoints/openai/chat_completion/test_serving_chat.py
• pre-commit on all changed files

The focused regression covers the before/after behavior for this bug:

• Before: reasoning_content was null and content contained the thought trace
• After: reasoning and final content are separated correctly

[gemini-code-assist]

Code Review

This pull request introduces the _get_reasoning_parser_input_text helper function to preserve reasoning markers during non-streaming chat completions by re-decoding token IDs when special tokens are detected. It also includes unit tests for the Gemma4ReasoningParser. Feedback suggests relaxing the condition in the helper function to allow for reasoning parsers that define only a start or an end token, rather than requiring both.

[lucianommartins]

Hi @jacobzhang22 - it is not a bug, it is working as expected.

when you start a server with the reasoning parser,it is reasoning capable but depends on the inference request instructions.

if you request without reasoning, everything comes as a single structure with skip_special_tokens on the default True.

if you ensble thinking for a request, you must tell the server to keep the special tokens then the thoughts can be parsed.

it is a design/UX decision and it is in sync with the Transformers implementation too (some code samples at fhe official docs: https://ai.google.dev/gemma/docs/capabilities/thinking

[jacobzhang22]

lucianommartins

Thanks @lucianommartins, this is helpful context. Looking at the Gemma thinking docs, I see that the intended parsing flow depends on preserving the special tokens during decode (skip_special_tokens=False) before parsing the response. I was treating this as a vLLM bug in the non-streaming path, but it sounds like this is an intentional behavior/design choice rather than a regression.

I’m going to close this PR. Thanks for clarifying.

[bbrowning]

Hi @jacobzhang22 - it is not a bug, it is working as expected.

when you start a server with the reasoning parser,it is reasoning capable but depends on the inference request instructions.

if you request without reasoning, everything comes as a single structure with skip_special_tokens on the default True.

if you ensble thinking for a request, you must tell the server to keep the special tokens then the thoughts can be parsed.

it is a design/UX decision and it is in sync with the Transformers implementation too (some code samples at fhe official docs: https://ai.google.dev/gemma/docs/capabilities/thinking

I don't think these semantics are quite right from a user's point-of-view. In vLLM, enable_thinking=True (either via setting it as a default chat template kwarg that applies to every request or sending it per-request) should be enough to get reasoning working as expected, including reasoning content parsed by vLLM into the reasoning property on Chat Completion message responses. We wouldn't want users to also have to set skip_special_tokens=False on their request, as that's leaking vLLM internals of how we handle reasoning to the user.

[lucianommartins]

@bbrowning - I understand... I'm baking one PR to submit in the next minutes with a proposal to address that... but it requires on some vLLM core engine changes that I will need @ywang96 and the other vLLM folks to evaluate the idea.

[lucianommartins]

fyi @bbrowning - trying to fix that here #39081