reasoning.effort 调参实战：把推理深度变成可调参数

reasoning.effort 是 OpenAI API 的请求级参数，控制模型在回答前进行内部推理的深度：档位越低响应越快越便宜，档位越高模型"想"得越多、正确率越高。它让"同一个模型、不同深度的思考"成为一行配置——本教程讲清参数写法、各档位的适用场景、与 max_output_tokens 的配合，以及调错档位的双向代价。

说明：本文代码写法逐行对照官方 Reasoning 指南（文档核对版），lastTestedAt 为核对日期；档位体系以 GPT-5.6 家族为准。

1. 参数写法：三种语言

请求里加 reasoning 参数即可，官方指南给出多语言同构示例：

from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-5.6-terra",
    reasoning={"effort": "medium"},
    input=[
        {"role": "user", "content": "把这段日志按错误级别分类并汇总"},
    ],
)

print(resp.output_text)

JavaScript 写法同构（reasoning: { effort: "low" }），官方指南还给出了 curl 与 Ruby 的等价示例——参数名与取值跨语言一致。

2. 档位选择表

GPT-5.6 家族的 effort 从 none 到 max 连续可调：

两个选型原则：第一，档位错配是双向浪费——该高不高会答错返工，该低不高会为固定模式的任务支付推理溢价；第二，档位是请求级的，同一个产品里可以按任务难度混用多档。

3. 与 max_output_tokens 的配合：留够推理预算

effort 高时，模型内部推理会消耗输出预算。预算不足的响应不会报错，而是返回 incomplete 状态——官方指南的示例明确演示了这个处理：

const response = await client.responses.create({
  model: "gpt-5.6-terra",
  reasoning: { effort: "medium" },
  input: [{ role: "user", content: prompt }],
  max_output_tokens: 300,
});

if (response.status === "incomplete" && response.incomplete_details) {
  // 预算不足：提高 max_output_tokens 或降低 effort
  console.log(response.incomplete_details);
}

生产代码里这个检查应该是标配：incomplete 的响应看起来"正常返回"，内容却是被截断的——不做状态检查，错误会静默流向下游。

4. 成本联动：effort 是账单旋钮

effort 越高，推理消耗的输出 token 越多，而输出单价是输入的数倍。以 Sol 为例（2026-08-21 起促销价 $4/$20，官方 changelog）：输出是输入的 5 倍价，推理 token 每多一倍，账单输出项就多一倍。

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.6-sol",
    "reasoning": {"effort": "high"},
    "input": "逐步推导这道约束满足问题的解"
  }'

没有跨任务通用的倍数——最准的度量是用同一批任务在相邻两档各跑一次，对比真实 token 消耗与正确率：正确率持平就降档，这是免费的优化。

5. 动态路由：最大的成本杠杆

比"选对一档"更有效的，是"按请求调档"：

1. 打难度标签：规则（任务类型、输入长度）或轻量分类模型。
2. 分流：简单流量走 none/low，不确定的走 medium，标记为难的走 high 以上。
3. 校准：定期抽样对比高低档的正确率与成本，调整阈值。

GPT-5.6 家族三档共享 1.05M 上下文与原生多模态，升降档不需要改提示词结构——这是把 effort 用成"账单旋钮"的前提。极端难题的正确率焦虑交给 o-series（effort 固定 max 的专用线），日常流量留在 GPT-5.6 家族按需调档。

常见问题

1. effort 各档位分别适合什么任务？

none / low：分类、抽取、格式转换、简单改写——要快、要便宜、答案模式固定。medium：日常产品主力——常规问答、摘要、代码补全。high / xhigh：多步推理、数学、复杂调试、Agent 规划。max：必须答对的场景——竞赛级数学、关键代码正确性。用错误档位的代价是双向的：该高不高会答错，该低不高会烧钱。

2. 为什么我的响应被截断了？

大概率是 max_output_tokens 给的预算没算上推理消耗——effort 高时推理本身会消耗输出预算。官方示例的做法是显式检查 response.status：状态为 incomplete 时说明预算不足，提高 max_output_tokens 或降低 effort。

3. effort 调高，成本会涨多少？

effort 越高，模型内部推理消耗的输出 token 越多，按输出单价计费。以 Sol 促销价 $4/$20（2026-08-21 起）为例：输出是输入的 5 倍价，推理 token 每多一倍，账单里输出项就多一倍。没有统一倍数——用同一任务在两档下各跑一次，对比真实 token 消耗最准。

4. effort 应该在系统提示里说还是用参数？

用参数。effort 是 API 级配置，写在提示词里的"请深入思考"不改变模型分配的推理预算。参数化还有个好处：可以在路由层按任务难度动态设置，而提示词是静态的。

5. 动态路由怎么落地？

三步：给请求打难度标签（规则或轻量分类模型）；低难度流量走 low/none，不确定的走 medium，标签为"难"的走 high 以上；定期抽样对比高低档的正确率，校准阈值。GPT-5.6 家族共享上下文与多模态能力，升降档不需要改提示词结构。

6. o-series 和 effort 有什么关系？

o-series 是"固定最深推理"的专用线——effort 固定 max、慢且贵，为必须答对的场景设计。GPT-5.6 家族的 effort 参数把"思考多深"变成连续可调。日常产品默认用 GPT-5.6 家族调 effort；只有把 effort 拉满仍不够的极难任务才切 o-series。

下一步

• 模型家族整体选型（价格已按 8-21 促销价更新）？读 《GPT 模型完全指南（2026-07）：GPT-5.6 Sol / Terra / Luna 选型》。
• 想要结构化输出配合高 effort？读 《OpenAI 结构化输出完全指南：json_schema、strict 模式与常见报错》。
• 按请求选档的进阶玩法（structured outputs / 流式 / Batch）？读 《Responses API 高级实战：structured outputs / 流式 SSE / Batch / prompt caching》。