You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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.
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.
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:
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.
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)
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.
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.
Activity
alecsolder commentedon Oct 29, 2025
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 commentedon Oct 30, 2025
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
reasoningproperty 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 commentedon Oct 31, 2025
The "separate guidance" shows a
reasoning_detailsfield in the response messages (i.e. outputs) instead of areasoningfield. If we take the advice toDoes this mean we have to migrate from the proposed
reasoningtoreasoning_detailsagain when we want to support passing the reasoning content back?hmellor commentedon Oct 31, 2025
reasoning_detailsis 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:
hmellor commentedon Oct 31, 2025
I assume you are referring to point 4:
Yes this would be handled as a separate RFC.
bbrowning commentedon Oct 31, 2025
Yes, that's what I was referring to and thanks for clarifying that.
hmellor commentedon Oct 31, 2025
I don't think it'd be hard to copy the
reasoningfield from the firstassistantmessage that has it into all subsequentassistantmessages 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 commentedon Oct 31, 2025
The
reasoning_detailsmentioned 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_contentfield we have today should be semantically similar to OpenRouter'sreasoningfield, so renaming to align seems fairly straightforward.@Riatre If I'm misinterpreting how OpenRouter handles
reasoningvsreasoning_detailsplease correct me. My general understanding isreasoningis populated for any reasoning model, whilereasoning_detailsis 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 basereasoningfield) and the passing ofreasoningorreasoning_detailsback 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 commentedon Nov 1, 2025
OpenRouter returns chunks like this in their Chat Completions API for gpt-5:
And this for gpt-oss:
i.e. they always return both a
reasoningfield and areasoning_detailsfield, with the latter being a strict superset of the former. For the olderreasoningfield, it looks like they put the raw reasoning tokens (reasoning.text) there if the underlying model make it available, otherwise they havereasoning.summary. I'm not sure whether OpenRouter wants to deprecate the oldreasoningfield or not, as it is redundant now.I don't think we are ever going to implement redacted reasoning tokens in vLLM, so
reasoning.summaryandreasoning.encryptedinreasoning_detailsmakes no sense for us and a simplereasoningfield is enough.I could be wrong, but it looks like, contrary to the OpenAI guide, OpenRouter does NOT support passing
reasoningproperty back in the assistant message, and instead insist on using the newreasoning_details. I agree that we should ignore that piece of guidance that asks us to align with OpenRouter.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 commentedon Nov 5, 2025
To summarise the above discussion.
reasoningandreasoning_detailsare two different fields which can coexist.For the purposes of this PR, we are simply aligning the naming with the
reasoningfield.Enhance reasoning handling in openaiApi.ts
fix(providers/openai): accept streaming chunks with both reasoning fi…
fix: parse "reasoning" as an alias for "reasoning_content" in OpenAI …
docs: document reasoning_content output removal as a breaking client …