[RFC]: `reasoning_content` -> `reasoning`

[hmellor]

Motivation.

When GPT-OSS was released, OpenAI provided guidance that chain of thought content should be returned in the reasoning field of the response. They recommend this for Chat Completions API even though it does not officially support returning chain of thought in the official API. Since vLLM implements the OpenAI API, it makes sense to conform to their recommendations.

Before #27752, vLLM used reasoning_content as this is what DeepSeek originally used. That PR makes the change from reasoning_content to reasoning, maintaining backwards compatibility.

Proposed Change.

Remove reasoning_content completely to avoid confusion.

Feedback Period.

2 weeks

CC List.

No response

Any Other Things.

No response

Before submitting a new issue...

• Make sure you already searched for relevant issues, and asked the chatbot living at the bottom right corner of the documentation page, which can answer lots of frequently asked questions.

[alecsolder]

I think this strategy makes sense for keeping the completions endpoint up to date with OpenRouter for sure.

Especially as OpenAI themselves are migrating away from completions, I think this is likely a good time to ensure that the representation we use for reasoning is compatible with OpenAI Responses as well as the Anthropic Messages path.

[bbrowning]

Here's the guidance from OpenAI about how to handle reasoning content in the Chat Completions API, and the proposal here aligns with moving that guidance to use a reasoning property for both non-streaming and streaming cases.

There is some separate guidance there about how to pass this reasoning content back into subsequent requests. This RFC does not cover what to do there, and I assume aligning with the guidance for how to handle reasoning inputs on subsequent requests is something we will tackle later.

[Riatre]

There is some separate guidance there about how to pass this reasoning content back into subsequent requests.

The "separate guidance" shows a reasoning_details field in the response messages (i.e. outputs) instead of a reasoning field. If we take the advice to

We ask you to follow the following convention from OpenRouter instead.

Does this mean we have to migrate from the proposed reasoning to reasoning_details again when we want to support passing the reasoning content back?

[hmellor]

reasoning_details is part of OpenRouter's Responses API (similar to OpenAI's one), which is not applicable here.

i.e. see https://openrouter.ai/docs/use-cases/reasoning-tokens#examples where the reasoning text is extracted using:

msg = response.choices[0].message
print(getattr(msg, "reasoning", None))

[hmellor]

There is some separate guidance there about how to pass this reasoning content back into subsequent requests. This RFC does not cover what to do there, and I assume aligning with the guidance for how to handle reasoning inputs on subsequent requests is something we will tackle later.

I assume you are referring to point 4:

4. On subsequent turns you should be able to receive the previous reasoning (as reasoning) and handle it in accordance with the behavior specified in the chat template section above.

Yes this would be handled as a separate RFC.

[bbrowning]

I assume you are referring to point 4:
Yes this would be handled as a separate RFC.

Yes, that's what I was referring to and thanks for clarifying that.

[hmellor]

I don't think it'd be hard to copy the reasoning field from the first assistant message that has it into all subsequent assistant messages to achieve the behaviour in point 4.

Although I'm not sure how that would interact with a model which can perform additional reasoning in multi-turn conversations. It might be best to ignore that piece of guidance 😅 (or do an RFC to determine if we shouldn't)

[bbrowning]

The reasoning_details mentioned above is used by OpenRouter even for Chat Completions, but only for specific models. I believe this mostly comes into play for models that have different types of reasoning, like models that output reasoning summaries in addition to their raw chain of thought. Or, openai/gpt-5 models with encrypted reasoning content.

The reasoning_content field we have today should be semantically similar to OpenRouter's reasoning field, so renaming to align seems fairly straightforward.

@Riatre If I'm misinterpreting how OpenRouter handles reasoning vs reasoning_details please correct me. My general understanding is reasoning is populated for any reasoning model, while reasoning_details is only for specific Anthropic and OpenAI models that have this extra level of reasoning content.

I'd suggest to defer discussion of an additional field, like reasoning_details (which is an additional level of reasoning details over the base reasoning field) and the passing of reasoning or reasoning_details back into subsequent requests to a separate RFC. The nuance of how to ensure the model gets exactly the right input prompts with its reasoning content as needed on subsequent requests is important, but also not trivial. @alecsolder and others are working to ensure full reasoning content can be sent back via responses and passed back into requests via our Responses API, and we'd probably want to take those learnings and get their input into any these areas of the Chat Completion API.

[Riatre]

OpenRouter returns chunks like this in their Chat Completions API for gpt-5:

ChatCompletionChunk(id='gen-1761995428-tyxmR5sByxQYa4Y7a6ML', choices=[Choice(delta=ChoiceDelta(content='', function_call=None, refusal=None, role='assistant', tool_calls=None, reasoning='**Estim', reasoning_details=[{'type': 'reasoning.summary', 'summary': '**Estim', 'format': 'openai-responses-v1', 'index': 0}]), finish_reason=None, index=0, logprobs=None, native_finish_reason=None)], created=1761995428, model='openai/gpt-5', object='chat.completion.chunk', service_tier=None, system_fingerprint=None, usage=None, provider='OpenAI')
...
ChatCompletionChunk(id='gen-1761995428-tyxmR5sByxQYa4Y7a6ML', choices=[Choice(delta=ChoiceDelta(content='', function_call=None, refusal=None, role='assistant', tool_calls=None, reasoning='!', reasoning_details=[{'type': 'reasoning.summary', 'summary': '!', 'format': 'openai-responses-v1', 'index': 0}]), finish_reason=None, index=0, logprobs=None, native_finish_reason=None)], created=1761995428, model='openai/gpt-5', object='chat.completion.chunk', service_tier=None, system_fingerprint=None, usage=None, provider='OpenAI')
ChatCompletionChunk(id='gen-1761995428-tyxmR5sByxQYa4Y7a6ML', choices=[Choice(delta=ChoiceDelta(content='', function_call=None, refusal=None, role='assistant', tool_calls=None, reasoning=None, reasoning_details=[{'type': 'reasoning.encrypted', 'data': 'gAA<...sic...>', 'id': 'rs_001852f3b36d1d45016905eaa4e45c81938cc0ff5cdda03af9', 'format': 'openai-responses-v1', 'index': 0}]), finish_reason=None, index=0, logprobs=None, native_finish_reason=None)], created=1761995428, model='openai/gpt-5', object='chat.completion.chunk', service_tier=None, system_fingerprint=None, usage=None, provider='OpenAI')

And this for gpt-oss:

ChatCompletionChunk(id='gen-1761995526-ZFJZZOO8Aa7M3vC80izP', choices=[Choice(delta=ChoiceDelta(content='', function_call=None, refusal=None, role='assistant', tool_calls=None, reasoning='We', reasoning_details=[{'type': 'reasoning.text', 'text': 'We', 'format': 'unknown', 'index': 0}]), finish_reason=None, index=0, logprobs=None, native_finish_reason=None)], created=1761995526, model='openai/gpt-oss-120b', object='chat.completion.chunk', service_tier=None, system_fingerprint=None, usage=None, provider='GMICloud')
ChatCompletionChunk(id='gen-1761995526-ZFJZZOO8Aa7M3vC80izP', choices=[Choice(delta=ChoiceDelta(content='', function_call=None, refusal=None, role='assistant', tool_calls=None, reasoning=' need', reasoning_details=[{'type': 'reasoning.text', 'text': ' need', 'format': 'unknown', 'index': 0}]), finish_reason=None, index=0, logprobs=None, native_finish_reason=None)], created=1761995526, model='openai/gpt-oss-120b', object='chat.completion.chunk', service_tier=None, system_fingerprint=None, usage=None, provider='GMICloud')

i.e. they always return both a reasoning field and a reasoning_details field, with the latter being a strict superset of the former. For the older reasoning field, it looks like they put the raw reasoning tokens (reasoning.text) there if the underlying model make it available, otherwise they have reasoning.summary. I'm not sure whether OpenRouter wants to deprecate the old reasoning field or not, as it is redundant now.

I don't think we are ever going to implement redacted reasoning tokens in vLLM, so reasoning.summary and reasoning.encrypted in reasoning_details makes no sense for us and a simple reasoning field is enough.

I could be wrong, but it looks like, contrary to the OpenAI guide, OpenRouter does NOT support passing reasoning property back in the assistant message, and instead insist on using the new reasoning_details. I agree that we should ignore that piece of guidance that asks us to align with OpenRouter.

I assume you are referring to point 4:

Ah, thanks for the quote, I looked over this :/ and thought there's no words on how to pass reasoning tokens back in the OpenAI guidance.

[hmellor]

To summarise the above discussion. reasoning and reasoning_details are two different fields which can coexist.

For the purposes of this PR, we are simply aligning the naming with the reasoning field.