OpenAI 兼容 API 如何开启 thinking:enable_thinking 写法与验证(2026)
「OpenAI 兼容 API 如何开启 thinking」到底在问什么
搜 openai compatible api enable thinking,或「OpenAI 兼容 API 开启 thinking」,多半不是在问模型本身会不会推理,而是在问:已经有一个接受 POST /v1/chat/completions 的兼容端点时,怎样把思考过程打开,或为了速度和费用把它关掉。
这和「如何把客户端指到兼容端点」不是同一篇文章。端点形态、/v1 路径和客户端切换,见什么是 OpenAI 兼容 API。本文只写思考开关:真正生效的字段叫什么、为什么官方 OpenAI API 没有 enable_thinking,以及怎样判断服务器有没有理会你的参数。
这里的 thinking,指模型在可见答案之前(或之间)多生成的推理 token。兼容服务器常常把这段文本放在单独字段里;官方 OpenAI 的推理模型也会「想」,但用的是另一套参数,返回方式也不一样。
官方 OpenAI 没有 enable_thinking 字段
如果 base_url 指向官方 OpenAI API,不要发送 enable_thinking。它不是 Chat Completions 的正式字段。
OpenAI 的 Chat Completions 参考 为推理模型提供的是 reasoning_effort。可选值视模型而定,包括 none、minimal、low、medium、high、xhigh、max;在字段被接受时,默认通常是 medium。更低的 effort 更偏向速度、少用推理 token;更高的 effort 则让模型想得更完整。推理指南 里,Responses API 对应的是 reasoning.effort——同一件事,请求形状不同。
部分官方模型会拒绝 none(有时也包括 minimal),直接返回 HTTP 400。不要假设每个取值都能用,以该模型在推理指南中的说明为准。
推理 token 会计入上下文窗口,并按输出 token 计费。官方用量里可以看 usage.completion_tokens_details.reasoning_tokens 一类字段。这是官方侧最直接的验证信号:你改了 effort,推理 token 数量随之变化。
from openai import OpenAI
client = OpenAI() # 官方 API,不要填兼容 base_url
resp = client.chat.completions.create(
model="gpt-5.5",
messages=[{"role": "user", "content": "9.11 和 9.8 哪个更大?简要说明。"}],
reasoning_effort="high",
)
print(resp.choices[0].message.content)
print(getattr(resp.usage, "completion_tokens_details", None))示例里的模型 ID 只是占位。请换成你项目里实际可用的推理模型,并核对它接受哪些 effort 值。
兼容服务器上的开关是 enable_thinking
许多 OpenAI 兼容服务器,尤其是用 vLLM 部署 Qwen3 系列时,用 chat_template_kwargs.enable_thinking 控制思考模式。Qwen 自己的 vLLM 部署说明 写得很清楚:传入 enable_thinking 并不是 OpenAI API 兼容写法,而且不同框架的方法可能不一样。
官方 OpenAI Python SDK 里,非标准字段要放进 extra_body。Qwen 文档中关闭思考的例子如下:
from openai import OpenAI
client = OpenAI(
api_key="EMPTY",
base_url="http://localhost:8000/v1",
)
resp = client.chat.completions.create(
model="Qwen/Qwen3-8B",
messages=[
{"role": "user", "content": "请用几句话介绍大语言模型。"},
],
max_tokens=8192,
extra_body={
"chat_template_kwargs": {"enable_thinking": False},
},
)
print(resp.choices[0].message.content)curl 可以直接把同一段 JSON 交给服务器:
curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "Qwen/Qwen3-8B",
"messages": [
{"role": "user", "content": "请用几句话介绍大语言模型。"}
],
"chat_template_kwargs": {"enable_thinking": true}
}'有两点要马上记住:
- 这些服务器文档里的写法,不是顶层的
"enable_thinking": true,而是放在chat_template_kwargs里。 - Qwen3 类模型常常默认开启思考。若你要的是短而直接的回答,需要显式传
enable_thinking: false(或改服务器默认值)。也有模型相反:vLLM 的推理输出说明提到,Gemma 4 这类模板必须先把enable_thinking设为true,才会生成推理 token。
vLLM 也可以在启动时设定全局默认:
vllm serve Qwen/Qwen3-8B \
--reasoning-parser qwen3 \
--default-chat-template-kwargs '{"enable_thinking": false}'请求级的 chat_template_kwargs 仍然优先于这个默认值。
当前 vLLM 文档还写了一个自动桥接:如果你传官方风格的 reasoning_effort(low / medium / high),服务器可能自动注入 enable_thinking: true;reasoning_effort: "none" 则注入 false。你自己显式设置了 enable_thinking 时,以你的值为准。这只是部分服务器的便利映射,不能当成所有兼容端点都如此实现。
怎样判断 thinking 真的跑起来了
传了开关,不等于你已经看到推理过程。
在 vLLM 上,要把思考内容拆到单独字段,通常需要启动时加上 --reasoning-parser(Qwen3 用 --reasoning-parser qwen3)。推理输出说明里读取的是 message 对象——当前文档写的是 message.reasoning。也有服务器或旧客户端用 reasoning_content。先检查实际返回,不要假定字段名只有一种。
msg = resp.choices[0].message
reasoning = getattr(msg, "reasoning", None) or getattr(msg, "reasoning_content", None)
print("reasoning:", reasoning)
print("content:", msg.content)用一道在开启思考时应该出现简短推理链的题目,例如比较大小或多步计算;再用同一道题关闭思考,对照两次结果。
有效的开关大致是这样:
- 开启: reasoning 字段非空(若服务器不做解析,也可能在
content里看到推理标签),完成长度更长。 - 关闭: reasoning 为空或不存在,答案更直接。
如果两次请求几乎一模一样,多半是标志没进 chat template、模型根本不认这个 kwarg,或你没有打到以为的那台服务器。后一种经常是 base URL 配错——多写了 /v1,或客户端其实还在访问 api.openai.com。
开关看起来「没效果」的常见原因
「我已经 enable thinking,但结果没变」通常落在下面几类:
- 字段放错位置。 官方 OpenAI 要的是
reasoning_effort或reasoning.effort。vLLM / Qwen 要的是chat_template_kwargs.enable_thinking,在 SDK 里通常走extra_body。把enable_thinking放在 JSON 顶层最好写,也最容易被严格的服务器忽略或拒绝。 - 实际打到了官方 API。 客户端看起来像兼容调用,
base_url却仍是默认的 OpenAI 地址。官方 API 不会处理enable_thinking。 - 没有开 reasoning parser。 模型可能已经在思考,但文本混在
content里、包在模型自己的标签中,或在到达客户端前被丢掉。按模型启用对应 parser,再读 reasoning 字段。 - 该模型的 chat template 并不声明
enable_thinking。 vLLM 写过:模板不接受的 kwarg 会被过滤。DeepSeek R1 风格的模型,解析器和开关可能都与 Qwen3 不同。 - 厂商用了另一套方言。 有的 API 文档写的是
thinking对象,例如{ "type": "enabled" },而不是enable_thinking。这类「可选字段不保证一致」,正是兼容性会在哪里失效要解决的问题。以你正在调用的服务器文档为准。 - 静默丢弃。 有的兼容端点接受未知字段然后丢掉,比直接 400 更难查。开关请求返回 200、输出却不变时,把实际发出的 JSON 和该服务器的文档对照,而不是和 OpenAI 官方 schema 对照。
搜索建议里也常出现 LM Studio 这类带 OpenAI 兼容服务的本地应用。规则相同:产品可能既有界面开关,也有请求级参数。用该产品文档里的名称,不要把 enable_thinking 复制到从未记载这个字段的服务器上。
该传哪一种控制项
|
你正在调用的对象 |
真正起作用的控制项 |
|---|---|
|
官方 OpenAI Chat Completions |
|
|
官方 OpenAI Responses API |
|
|
vLLM / Qwen3 风格的兼容服务器 |
|
|
文档写了 |
以该厂商文档中的对象为准,不要猜测一个 |
前两行是官方约定,后两行是扩展。混用是最常见的失败方式。
常见问题
enable_thinking 是官方 OpenAI API 参数吗?
不是。官方 Chat Completions 用 reasoning_effort,Responses API 用 reasoning.effort。enable_thinking 是部分 OpenAI 兼容服务器的扩展,尤其常见于用 vLLM 部署、且 chat template 声明了该 kwarg 的模型。
用 Python SDK 怎么在 OpenAI 兼容 API 上开启 thinking?
把官方 OpenAI 客户端的 base_url 指到兼容端点,再把该服务器的标志放进 extra_body。Qwen3 + vLLM 的写法是 extra_body={"chat_template_kwargs": {"enable_thinking": True}}。先用 GET /v1/models 确认模型 ID。
怎样在兼容端点上关闭 Qwen3 的 thinking?
把 chat_template_kwargs.enable_thinking 设为 false,或在启动 vLLM 时加上 --default-chat-template-kwargs '{"enable_thinking": false}'。若需要硬关闭,连 /think 这类提示也不生效,Qwen 还提供了非思考 chat template。
我已经打开 thinking,为什么 message.reasoning 仍是空的?
可能服务器没有解析推理内容,字段实际叫 reasoning_content,模板忽略了该 kwarg,或思考文本仍在 content 里。检查 parser、打印原始 message,并用同一道题做开/关对照。
切回官方 OpenAI API 时,还能用同一个标志吗?
不能。去掉 enable_thinking,改用 reasoning_effort(Responses 上则是 reasoning.effort)。本地 vLLM 上有效的字段并不属于官方 schema,这正是OpenAI 兼容性问题里会反复出现的缺口。
先按服务器文档传参,再验证结果
OpenAI 兼容 API 让你可以复用客户端,并不表示思考控制也可以原样搬运。官方 API 用 reasoning_effort 或 reasoning.effort,并核对推理 token 用量;vLLM 和 Qwen 风格的服务器传 chat_template_kwargs.enable_thinking,若要单独的推理字段就打开 reasoning parser,再确认输出确实变了。开关没有效果时,先修正字段位置、base URL 或方言,再假设模型不会思考。