接入教程

OpenAI 兼容 API 如何开启 thinking:enable_thinking 写法与验证(2026)

ROIBest AI

「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}
  }'

有两点要马上记住:

  1. 这些服务器文档里的写法,不是顶层的 "enable_thinking": true,而是放在 chat_template_kwargs 里。
  2. 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,但结果没变」通常落在下面几类:

  1. 字段放错位置。 官方 OpenAI 要的是 reasoning_effort 或 reasoning.effort。vLLM / Qwen 要的是 chat_template_kwargs.enable_thinking,在 SDK 里通常走 extra_body。把 enable_thinking 放在 JSON 顶层最好写,也最容易被严格的服务器忽略或拒绝。
  2. 实际打到了官方 API。 客户端看起来像兼容调用,base_url 却仍是默认的 OpenAI 地址。官方 API 不会处理 enable_thinking。
  3. 没有开 reasoning parser。 模型可能已经在思考,但文本混在 content 里、包在模型自己的标签中,或在到达客户端前被丢掉。按模型启用对应 parser,再读 reasoning 字段。
  4. 该模型的 chat template 并不声明 enable_thinking。 vLLM 写过:模板不接受的 kwarg 会被过滤。DeepSeek R1 风格的模型,解析器和开关可能都与 Qwen3 不同。
  5. 厂商用了另一套方言。 有的 API 文档写的是 thinking 对象,例如 { "type": "enabled" },而不是 enable_thinking。这类「可选字段不保证一致」,正是兼容性会在哪里失效要解决的问题。以你正在调用的服务器文档为准。
  6. 静默丢弃。 有的兼容端点接受未知字段然后丢掉,比直接 400 更难查。开关请求返回 200、输出却不变时,把实际发出的 JSON 和该服务器的文档对照,而不是和 OpenAI 官方 schema 对照。

搜索建议里也常出现 LM Studio 这类带 OpenAI 兼容服务的本地应用。规则相同:产品可能既有界面开关,也有请求级参数。用该产品文档里的名称,不要把 enable_thinking 复制到从未记载这个字段的服务器上。

该传哪一种控制项

你正在调用的对象

真正起作用的控制项

官方 OpenAI Chat Completions

reasoning_effort

官方 OpenAI Responses API

reasoning.effort

vLLM / Qwen3 风格的兼容服务器

chat_template_kwargs.enable_thinking(SDK 里多用 extra_body)

文档写了 thinking 对象的厂商 API

以该厂商文档中的对象为准,不要猜测一个 enable_thinking

前两行是官方约定,后两行是扩展。混用是最常见的失败方式。

常见问题

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 或方言,再假设模型不会思考。