Codex 的 reasoning.effort 如何权衡推理质量、Token 成本与响应延迟？

Codex 的 reasoning.effort 会影响模型投入的推理量，从而改变任务质量、Token 消耗与响应延迟。正确的优化目标不是让单次请求最便宜，也不是让所有任务使用最高档位，而是降低“每个成功任务的总成本”：模型费用、失败重试、人工返工、等待时间和错误风险都要计算在内。

三个指标为什么互相制约

降低 Reasoning Effort 通常能减少推理开销并加快响应，但复杂任务可能因遗漏约束而失败。提高档位可能改善困难任务的正确率，却增加推理 Token 和端到端等待时间。

简单地比较单次 Token 数会产生误导。例如低档位一次调用便宜，但需要三次重试和人工修正；高档位虽然单次更贵，却一次完成。后者的实际成本可能更低。

先定义总成本

可以用以下结构评估每类任务：

单位成功任务成本 =
  模型输入成本
  模型输出与推理成本
  工具和基础设施成本
  重试成本
  人工审查与返工成本
  延迟造成的业务成本

这个公式不要求把每项都精确换算成货币，但必须至少记录，避免只优化最容易看到的 API 。

质量应如何测量

编码 Agent 的质量不能只靠主观评分。优先使用可重复证据：

• 公开测试和隐藏测试通过率。
• 类型检查、Lint 和安全扫描结果。
• 人工审查发现的严重问题数。
• 是否修改了任务范围外的文件。
• 首次输出即可合并的比例。
• 失败后能否正确诊断和恢复。

对于分析任务，可使用事实正确率、关键证据覆盖率和结论一致性。

Token 成本包含哪些部分

总用量可能包括系统指令、用户输入、会话历史、工具定义、工具输出、模型推理和最终回答。Reasoning Effort 主要调整模型的推理投入，但上下文冗余与工具日志也可能是更大的成本来源。

如果每轮都重复发送完整仓库说明或大段测试日志，仅下调 Reasoning Effort 不会根治浪费。应先精简上下文、截取相关日志并复用稳定提示前缀。

延迟应该拆开记录

指标	含义	用户影响
首响应时间	从请求到开始返回可见内容	影响交互感受
模型完成时间	模型生成和推理完成所需时间	受档位与任务复杂度影响
工具等待时间	搜索、测试、网络与文件操作耗时	可能与推理档位无关
端到端完成时间	从任务开始到获得可验证结果	最接近真实生产价值
返工完成时间	包含用户纠正和重试后的总时间	反映低质量的隐藏延迟

只测模型响应时间，可能把慢测试误认为高推理档位造成。

low 的成本优势

low 适合结构明确的执行型任务。它通常能以较低延迟完成搜索、常规编码、数据分析和多步工具调用。

适合的任务特征包括：

• 输入完整，目标文件已知。
• 完成条件可以由测试直接判断。
• 失败影响小，可以快速回滚。
• 流程重复，已有成熟提示和工具。
• 用户正在交互等待。

如果低档位质量与中档位近似，它往往是最优选择。

medium 的基线价值

medium 适合复杂度不确定的通用任务。它是建立基线的好起点：先测量质量、Token 与延迟，再判断某个任务族是否可以降到 low，或需要升到更高档位。

没有评测数据时直接使用最低档，可能产生大量隐性返工；直接使用最高档，则可能为简单任务支付不必要成本。

high 的使用条件

high 应用于确实需要复杂推理的 Agent 工作，例如跨服务故障、并发问题、迁移设计、安全分析或多约束架构决策。

采用 high 前应满足：

1. 任务质量在较低档位存在可重复缺口。
2. 缺口来自推理，而不是缺少数据或工具。
3. 质量提升足以抵消额外延迟和用量。
4. 任务有明确停止条件和工具预算。
5. 风险允许 Agent 获得相应上下文与权限。

xhigh 的经济性

xhigh 更适合最困难的异步任务或能力上限评测。它的价值不在于日常默认，而在于解决少数高价值、高复杂度问题。

如果任务可以由工程师在数小时内完成，而高档位 Agent 能显著减少人工调查，额外模型成本可能合理。反之，用它生成模板、改文案或执行固定命令，通常没有经济性。

更高档位不一定更可靠

OpenAI 官方提醒，冲突指令、薄弱停止标准和开放工具会让高推理档位过度思考、进行多余搜索，甚至引发质量回退。Reasoning Effort 无法修复错误上下文。

升档之前先检查：

• 目标是否具体。
• 约束是否互相冲突。
• 工具描述是否准确。
• 日志是否包含真正的错误信息。
• 成功和停止条件是否明确。

用单位成功率做比较

假设同一任务族执行一百次，可以计算：

一次通过率 = 首次满足验收条件的任务数 / 总任务数
平均成功成本 = 所有调用与返工成本 / 最终成功任务数
P95 完成时间 = 95% 成功任务能够完成的时间上限

生产决策应同时设质量门槛和成本目标。例如先要求隐藏测试通过率不下降，再在满足条件的档位中选择平均成功成本最低者。

不要只看平均值

平均延迟会掩盖少量极慢请求，平均质量也会掩盖某类严重失败。至少记录中位数、P90 或 P95、最大值和失败类型分布。

高风险任务还应单独统计越权修改、错误删除和虚假成功报告，不能用大量简单任务的高分稀释。

建立分层任务集

层级	示例	建议测试档位
简单	单文件修改、格式转换、已知错误修复	low、medium
中等	多文件功能、普通调试、测试补全	low、medium、high
困难	跨服务根因、并发与安全问题	medium、high、xhigh
极难	长时间研究、未知架构迁移	high、xhigh

每层都应使用真实生产分布，不能只挑模型擅长的样本。

设置延迟 SLO

不同交互需要不同目标：

• 编辑器补全和即时问答重视首响应时间。
• 交互式调试重视每轮反馈速度。
• 后台代码审查重视端到端完成时间。
• 夜间迁移分析可以接受更高延迟。

同一个任务在交互模式和异步模式下，合理档位可能不同。

自动路由如何设计

可以用任务风险和复杂度选择档位：

低风险 + 明确步骤 + 强验证 → low
普通复杂度或未知难度       → medium
跨模块 + 高推理 + 可等待   → high
极难 + 高价值 + 异步运行   → xhigh

路由器应记录选择原因，并允许用户覆盖。不要根据提示长度单独判断难度，短问题也可能需要复杂推理。

失败后自动升档

有限升档可以降低日常成本：先用 low 处理稳定任务，只有出现可归因于推理不足的失败才改用 medium 或 high。

但网络错误、权限拒绝、工具缺失和无效输入不会因升档改善。系统必须先分类失败，限制最多升档次数，并使用幂等键避免重复副作用。

上下文优化往往比降档更有效

• 只提供任务相关文件和日志片段。
• 稳定规则放在可缓存的提示前缀。
• 压缩重复历史，保留关键决定。
• 限制工具输出长度并提供继续读取方式。
• 用结构化结果减少反复澄清。

更干净的上下文可以同时提升质量、降低 Token 和缩短延迟。

流式输出能解决什么

流式输出可以改善感知延迟，让用户更早看到进展，但不会缩短模型完成全部推理和工具工作的真实时间。对于编码 Agent，更有价值的是展示当前阶段、工具状态和可取消入口，而不是输出大量占位文字。

批处理与异步执行

不需要即时结果的高档位任务可以转为后台执行。这样不会降低模型用量，但能减少对交互体验的影响，并允许使用队列、预算和并发控制。

后台任务必须有状态查询、超时、取消和结果持久化，不能让用户通过重复提交来确认是否完成。

评测流程

1. 固定模型版本、提示、工具和任务数据。
2. 在 medium 上建立基线。
3. 对简单与中等任务测试 low。
4. 对失败集测试 high，而不是测试全部流量。
5. 只在极难样本比较 high 与 xhigh。
6. 统计成功率、Token、P95 延迟与人工返工。
7. 按任务族配置路由并进行小流量上线。
8. 模型或提示变更后重新运行评测。

常见问题

Token 更少是否一定成本更低

不一定。失败重试和人工返工可能远高于节省的模型费用，应比较单位成功任务成本。

提高 Reasoning Effort 是否会增加输出长度

不一定。推理投入和最终输出详细程度是不同维度，输出格式应单独约束。

所有 Codex 任务都能使用相同档位吗

不适合。交互式修复、后台审查和复杂迁移的质量与延迟目标不同，应分层路由。

没有评测集时如何开始

先用 medium 收集真实任务和失败样本，再逐步测试降档或升档，不要凭单次体验决定。

总结

reasoning.effort 的权衡应围绕单位成功任务成本展开。以 medium 建立基线，让稳定、低风险任务使用 low，复杂高价值任务使用 high，仅把 xhigh 留给最困难的异步任务。同步记录质量、推理 Token、P95 延迟、重试和人工返工，并先优化上下文与工具，才能得到真实可持续的配置。