OpenAI API 推理模型 reasoning 参数详解:effort 档位、summary 思考摘要获取与 max_output_tokens 预留防截断

调用 OpenAI 推理模型常遇到输出为空或 status 为 incomplete?本文按官方文档详解 Responses API 的 reasoning.effort 档位、summary 思考摘要获取与 max_output_tokens 预算预留做法。

NNathaniel bigo··原创首发·AI 辅助撰写
9 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 其他 账号

结论先说

  1. Responses API 通过 reasoning 对象统一控制思考深度与摘要。核心字段为 effort(常用 low、medium、high,默认 medium)与 summary(可选 auto、concise、detailed)。
  2. 内部推理 Token 不直接暴露原文,但按输出 Token 单价计费。可在返回结果的 usage.output_tokens_details.reasoning_tokens 中精确查看本轮消耗的思考量。
  3. max_output_tokens 管的是「推理 + 可见回答」的总和。若上限设得太小,模型在内部思考阶段就会耗光配额,导致可见文本为空且 status 变为 incomplete。
  4. 获取 summary 思考摘要无需额外付费。但部分前沿推理模型要求先在 OpenAI Platform 后台完成组织身份验证(Organization Verification)才能开启摘要返回。
  5. 想免写代码直接交互体验高阶推理模型,国内无外币卡用户可在本站自助开通 ChatGPT Plus 或高配额 ChatGPT Pro,企业研发团队可了解 ChatGPT Business 团队定制。

OpenAI 推理模型 effort 档位与参数对比

图:本站根据 OpenAI 官方文档:Reasoning models 整理的示意图

本文根据 OpenAI API 官方文档《Reasoning models》《Responses API Reference》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。

适用于谁

  • 在代码里调用 OpenAI 推理模型,想按任务难度平衡延迟、准确度与 Token 账单的开发者;
  • 希望在前端界面展示模型「正在思考什么」,需要拉取 reasoning.summary 思考摘要的人;
  • 遇到 API 返回 HTTP 200 但正文为空、status 显示 incomplete 的排查者。

一、effort 思考强度档位与两套接口写法

OpenAI 新版开发首选 Responses API(与旧接口差异见 /guides/openai-responses-api)。effort 各档位定位如下:

档位取值思考深度与耗时适用任务场景
low简短推理,首字响应快、消耗少意图路由、结构化抽取、明确语法改写
medium(默认)速度与深度均衡常规业务代码编写、多步逻辑问答、文档审查
high深度多路径推演,推理 Token 占比高复杂算法证明、跨模块疑难排障、架构方案设计

注:部分新版 GPT 系列模型还支持更轻量的档位(以具体模型参考页为准);在交互终端 Codex CLI 里切换同款思考强度的做法见 /guides/codex-switch-model-reasoning-effort。若仍在维护旧版 Chat Completions 接口,对应顶层参数名为 reasoning_effort="medium"。

二、调用示例:同时读取思考摘要与正文并防截断

下面用官方 Python SDK 演示传入 reasoning 参数、预留 max_output_tokens 预算,并检查 incomplete 状态:

python
from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="o4-mini",
    input="请排查高并发下数据库连接池耗尽的三类常见根因,并给出连接超时配置建议。",
    reasoning=dict(effort="medium", summary="auto"),
    max_output_tokens=16000,
)

if resp.status == "incomplete":
    print("输出被截断,原因:", resp.incomplete_details.reason)

for item in resp.output:
    if item.type == "reasoning":
        for s in item.summary:
            print("[思考摘要]", s.text)

print("[正式回答]\n", resp.output_text)
print("推理消耗 Token:", resp.usage.output_tokens_details.reasoning_tokens)

流式传输(stream=True)时,同样可以监听摘要增量与正文增量事件,流式基础写法参考 /guides/openai-api-streaming。

订阅与账号准备提示:调试复杂推理提示词前,很多开发者会先在网页端或 Codex 里对比不同思考档位的效果。若缺少境外支付卡,可在本站自助选购 ChatGPT Plus 会员 或大额度的 ChatGPT Pro 充值,免交账号密码即可完成卡密兑换。

三、输出为空或半截中断的排错决策

推理模型输出为空或截断排查决策

图:本站根据 OpenAI 官方文档:Reasoning models 整理的示意图

  1. resp.output_text 为空字符串且 status == "incomplete":查看 resp.incomplete_details.reason,若为 max_output_tokens,说明你把上限(例如 1024)设得太低,全被内部推理吃掉了。官方建议调试期预留至少 16000 至 25000 的上限,没用完的额度不会扣费(计费标准见 /guides/openai-api-price-official-table)。
  2. 传了 temperature 或 top_p 报 400 错误:标准推理模型(或在非零推理档位下)固定不支持采样温度、presence_penalty 等传统采样参数,删掉即可恢复正常。
  3. 请求 summary="auto" 报权限错误或返回空数组:登录 OpenAI Platform 进入组织设置(Settings > Organization > General)核查是否已完成组织认证;极简问题未触发长链思考时,summary 数组也可能为空。
  4. 流式渲染时首字等待偏久:高档位(high)推理可能需要十余秒才开始吐出第一段正文。若产品界面对白屏敏感,建议开启 summary="auto" 并监听流式推理摘要增量事件,先把阶段性思考摘要实时呈现在折叠面板里,能明显改善用户等待体验。
  5. 批量离线任务优先搭配缓存与批处理:推理模型同样享受输入提示词缓存(Prompt Caching)与 Batch API 折扣,固定不变的系统规则与参考资料应放在输入最前端以提高缓存命中率。

常见问题

问:把 max_output_tokens 设成 25000 会不会每次都按两万五千个 Token 扣钱?

答:不会。max_output_tokens 只是安全上限刹车,实际账单只按本轮真实生成的「推理 Token + 可见输出 Token」数量结算。

问:多轮对话时要不要把上一轮的思考摘要拼回 input 传给下一轮?

答:不需要手动拼摘要文本。使用 Responses API 时直接传入 previous_response_id=resp.id,服务端会自动承接上下文与必要的推理状态。

问:国内没有外币卡,或者公司需要开增值税发票报销,怎么开通 ChatGPT 会员配合开发?

答:可通过本站 AI 会员充值总览 选购 ChatGPT Plus 或 ChatGPT Pro,支持支付宝、微信支付与 AlipayHK,支持卡密自助兑换与企业定制,并可开具增值税发票。实时价格以页面显示为准;售后遵循掉订阅按剩余天数折退、封号不在质保范围的规则。

相关教程

参考资料

  • OpenAI API 官方文档:Reasoning models — https://platform.openai.com/docs/guides/reasoning
  • OpenAI API 官方文档:Responses API Reference — https://platform.openai.com/docs/api-reference/responses

Nathaniel 的更多内容

  1. 01

    Anthropic Contextual Retrieval(上下文增强检索)是什么、怎么实现:给文档块自动补背景摘要结合缓存降失误率

    长文档切成小块后丢了公司名、年份和主语指代导致 RAG 频频搜错?本文按 Anthropic 官方技术文章详解 Contextual Retrieval 原理、官方公开评测失误率下降 49% 至 67% 的组合架构,以及用 Claude 提示词缓存低成本批量生成切片背景的完整 Python 代码。

    Claude其他 AI 工具0
  2. 02

    RAG 知识库回答不准怎么调优:切片大小(Chunking)、BM25 + 向量混合检索与 Rerank 重排序三步排查法

    搭好的 RAG 企业知识库一问具体型号、报错码或跨行表格就答非所问?本文按 OpenAI 与 Anthropic 官方检索文档,给出先隔离检索与生成故障、再按结构化切片(Chunking)、BM25 加向量混合召回(RRF)与 Rerank 重排序逐层调优的三步法。

    Claude其他 AI 工具0
  3. 03

    Langfuse 开源本地部署(Docker Compose)与提示词版本管理(Prompt Management)从零上手教程

    企业内网严禁业务日志出境,又想免费拥有大模型调用链追踪与不发版热更新提示词的能力?本文按 Langfuse 官方文档整理 Docker Compose 本地一键启动(含 ClickHouse 架构注意事项)、密钥配置与 Prompt Management 标签化版本管理全流程。

    Claude其他 AI 工具0
  4. 04

    LangSmith 入门教程:给 LangGraph 与原生 OpenAI / Claude 接口加调用链追踪、Token 成本统计与免费层限额

    智能体多步调用总是找不到哪一轮提示词跑偏、单次请求到底烧了多少 Token?本文按 LangSmith 官方文档讲清环境变量零侵入接入 LangGraph、用 wrap_openai / wrap_anthropic 与 @traceable 追踪原生接口,以及 Developer 免费层额度与留存规则。

    Claude其他 AI 工具0
  5. 05

    用 Google Takeout 单独备份导出 NotebookLM 笔记本与 Gemini 记录:只勾选指定服务不下载整个云端硬盘的步骤

    想把 NotebookLM 里的几十个研究笔记本、来源副本与音频概览,连同 Gemini 聊天记录一起备份到本地,又怕 Google Takeout 把整个云端硬盘和相册全打包?本文讲清先取消全选、精准勾选两项服务、解压目录查看与跨号迁移的做法。

    Gemini0
  6. 06

    Google Workspace 企业/教育版管理员怎么在后台给成员开启 Gemini 应用、NotebookLM 与设置年龄访问权限

    团队成员或学校师生登录 Google Workspace 账号时提示无权使用 Gemini 或打不开 NotebookLM?本文按 Google 管理控制台官方文档整理服务开关路径、组织部门(OU)与群组放行、18 岁年龄访问权限设置及对话保留合规配置。

    Gemini0

同模型

  1. 01

    OpenAI Cookbook 官方示例库怎么用:快速查找生产级 RAG、多模态解析与评测代码模板

    看完了基础 API 文档却不知道怎么把 RAG 检索、PDF 图表解析和自动化评测串成完整项目?本文整理 OpenAI Cookbook 官方网站与 GitHub 仓库的检索技巧、版本甄别方法及运行步骤。

    ChatGPT0
  2. 02

    OpenAI API 报 context_length_exceeded 与输出半截中断怎么防:服务端 truncation: "auto" 与窗口预算控制

    多轮对话越聊越长突然报 400 context_length_exceeded,或者 JSON 生成到一半断掉?本文按官方文档讲清 Responses API 的 truncation: auto 自动裁剪机制与输出预算控制做法。

    ChatGPT0
  3. 03

    OpenAI Agents SDK 接入本地与远程 MCP 服务器怎么写:MCPServerStdio、MCPServerStreamableHttp 与工具缓存

    怎么在 OpenAI Agents SDK 里挂载现成的本地与远程 MCP 工具服务器?本文按官方文档整理 MCPServerStdio、MCPServerStreamableHttp 连接与释放写法,以及 cacheToolsList 工具缓存优化。

    ChatGPT0
  4. 04

    OpenAI Agents SDK(TypeScript / Node.js 版 @openai/agents)入门:定义 Agent、Zod 工具、Handoffs 与流式输出

    想用 TypeScript 快速写多智能体协作应用却不想背负厚重框架?本文按官方文档整理 @openai/agents 的安装要求、Agent 定义、Zod 工具函数、Handoffs 路由交接与 stream 流式输出完整代码。

    ChatGPT0
  5. 05

    OpenAI API 图像编辑(images.edit 局部遮罩重绘、多参考图合成与透明背景)参数与代码示例

    怎么用 OpenAI API 给商品图换背景、按遮罩局部改字或把多张参考图合成一张海报?本文按官方文档详解 client.images.edit 的 mask 透明通道规则、多图输入、background 透明背景及 Python 代码。

    ChatGPT0
  6. 06

    OpenAI API 音频输入输出(gpt-audio 异步对话)怎么调:与 Realtime WebSocket 实时语音的选型对比

    想让应用直接听懂用户录音并用自然语音回复,该调 gpt-audio 还是上 Realtime API?本文按官方文档对比两套架构差异,并给出 Python 音频输入输出、音色参数与多轮对话代码示例。

    ChatGPT0

同产品的其他教程

  1. 01

    iPhone 操作按钮(Action Button)或锁屏小组件一键开启 ChatGPT / Gemini 实时语音对话配置教程

    每次在 iPhone 上练口语或语音提问都要解锁、找图标、再点耳机按钮太繁琐?本文整理利用 iPhone 操作按钮(Action Button)、iOS 18 锁屏底部控制项、控制中心与背面轻点一键直达 ChatGPT 实时语音或 Gemini Live 的完整步骤。

    ChatGPTGemini0
  2. 02

    沉浸式翻译(Immersive Translate)怎么配置 OpenAI、Claude、Gemini、DeepSeek API Key 与省钱模型选择

    不想一直用传统机翻,怎么给沉浸式翻译浏览器扩展绑定自己的大模型 API Key?本文整理接入 OpenAI、Claude、Gemini、DeepSeek 官方密钥的步骤、高性价比轻量模型选型与防 429 并发限流设置。

    ChatGPT其他 AI 工具0
  3. 03

    在公司或公共电脑登录过 ChatGPT / Claude 后怎么远程一键登出所有设备并清理本机授权残留

    下班或离职后想起公司电脑、酒店公共电脑还挂着 ChatGPT 或 Claude 账号?本文按两家官方帮助中心整理远程一键登出所有设备的菜单路径、生效时限,以及 Codex 与 Claude Code 本地令牌清理清单。

    ChatGPTClaude0
  4. 04

    OpenAI Platform 组织与多项目(Projects)权限怎么管:按业务线拆分 API 账单预算、模型白名单与密钥审计

    公司多条业务线共用一个 OpenAI API 账户怕测试脚本跑飞烧光余额?本文按官方文档整理 Projects 多项目创建、月度软硬预算上限、模型白名单收敛、受限密钥权限与账单拆分步骤。

    ChatGPT0
  5. 05

    OpenAI API Webhooks 事件回调怎么配:异步接收 Batch、后台长任务与微调完成通知及签名验签

    跑 OpenAI Batch 批量请求或后台长推理任务还在写死循环轮询状态?本文按官方文档讲清 Webhooks 端点配置、支持事件类型、whsec_ 密钥获取,以及用 SDK webhooks.unwrap 完成签名验签与防重放。

    ChatGPT0
  6. 06

    OpenAI API Predicted Outputs(预测输出)怎么用:改写大段代码或文档只动几行时显著降低响应延迟的做法

    让模型微调几百行代码文件却要干等全文逐字吐完?本文按 OpenAI 官方文档详解 Predicted Outputs(prediction 参数)的加速原理、Python 示例、被拒预测 Token 计费规则与不兼容参数限制。

    ChatGPT0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~