Effort

effort 参数让您可以控制 Claude 在响应请求时消耗令牌的积极程度。您可以通过单个模型在响应完整性和令牌效率之间进行权衡。effort 参数在所有受支持的模型上均可使用，无需 beta 标头。



effort 的工作原理

默认情况下，Claude 使用 high effort，根据需要消耗尽可能多的令牌以获得出色的结果。您可以将 effort 级别提高到 max 以获得绝对最高的能力，或降低级别以更保守地使用令牌，在接受一定能力降低的同时优化速度和成本。

effort 参数影响响应中的所有令牌，包括：

• 文本响应和解释
• 工具调用和函数参数
• 扩展思考（启用时）

这种方法有两个主要优势：

1. 它不需要启用思考功能。
2. 它可以影响所有令牌消耗，包括工具调用。例如，较低的 effort 意味着 Claude 会进行更少的工具调用。这为效率控制提供了更大的灵活度。



Effort 级别



Claude Sonnet 5 的推荐 effort 级别

Claude Sonnet 5 默认使用 high effort。

• High effort（默认）： 适用于复杂推理、编码和智能体任务，这些任务中质量比速度或成本更重要。
• Xhigh effort： 适用于最困难的编码和智能体任务。请参阅 Claude Sonnet 5 提示指南。
• Medium effort： 从默认级别降级以节省成本。与 high effort 下的 Claude Sonnet 4.6 相当。
• Low effort： 适用于高吞吐量或对延迟敏感的工作负载。适用于优先考虑更快周转时间的聊天和非编码用例。
• Max effort： 适用于需要绝对最高能力且对令牌消耗没有限制的任务。



Sonnet 4.6 的推荐 effort 级别

Sonnet 4.6 默认使用 high effort。使用 Sonnet 4.6 时请显式设置 effort，以避免意外的延迟：

• Medium effort（推荐默认值）：对大多数应用而言，在速度、成本和性能之间达到最佳平衡。适用于智能体编码、工具密集型工作流和代码生成。
• Low effort： 适用于高吞吐量或对延迟敏感的工作负载。适用于优先考虑更快周转时间的聊天和非编码用例。
• High effort： 适用于复杂推理以及质量比速度或成本更重要的任务。
• Max effort： 适用于需要绝对最高能力且对令牌消耗没有限制的任务。



Claude Opus 4.7 的推荐 effort 级别

对于编码和智能体用例，从 xhigh 开始，对于大多数对智能要求较高的工作负载，使用 high 作为最低级别。对于成本敏感的工作负载，降级到 medium；仅当您的评估显示在 xhigh 级别仍有可衡量的提升空间时，才升级到 max。

API 默认值为 high。要使用 xhigh，请显式设置 effort；您传递的值会覆盖默认值。

Claude Opus 4.7 对 effort 级别的遵循也比 Claude Opus 4.6 更严格，尤其是在 low 和 medium 级别。在较低的 effort 级别下，模型会将其工作范围限定在所要求的内容上，而不会超额完成。如果您在使用 Claude Opus 4.7 处理复杂问题时观察到推理较浅，请提高 effort 级别，而不是通过提示来规避。如果您必须为了延迟而保持较低的 effort，请添加针对性的指导，例如"此任务涉及多步推理。请在响应前仔细思考。"

在 xhigh 或 max effort 级别下运行 Claude Opus 4.7 时，请设置较大的 max_tokens，以便模型有足够空间在子智能体和工具调用之间进行思考和行动。从 64k 令牌开始并据此调整是一个合理的默认值。



Claude Opus 4.8 的推荐 effort 级别

Claude Opus 4.7 的指南同样适用于 Claude Opus 4.8。对于编码和智能体用例，从 xhigh 开始，对于大多数其他对智能要求较高的工作负载使用 high，仅当您通过评估确认较低级别能够保持质量时，才降级到 medium 或 low。

API 默认值为 high。显式设置 effort 以使用不同的级别；您传递的值会覆盖默认值。

在 xhigh 或 max effort 级别下运行 Claude Opus 4.8 时，请设置较大的 max_tokens，以便模型有足够空间在子智能体和工具调用之间进行思考和行动。从 64k 令牌开始并据此调整是一个合理的默认值。



Claude Fable 5 的推荐 effort 级别

Effort 是在 Claude Fable 5 上权衡智能、延迟和成本的主要控制手段。对于大多数任务，从默认的 high 开始，对于对能力最敏感的工作负载使用 xhigh，对于常规工作降级到 medium 或 low。Claude Fable 5 上较低的 effort 设置仍然表现良好，通常超过先前模型在 xhigh 级别下的性能。在 high 和 xhigh 级别下，请设置较大的 max_tokens：它是总输出（思考加响应文本）的硬性限制。请参阅成本控制。

如果任务完成但耗时超过必要时间，或者您希望获得更快、更具交互性的工作方式，请降低 effort。相同的建议也适用于 Claude Mythos 5。有关更完整的指南，请参阅 Claude Fable 5 提示指南。



基本用法

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between microservices and monolithic architectures",
        }
    ],
    output_config={"effort": "medium"},
)

print(response.content[0].text)



何时调整 effort 参数

• 当您需要绝对最高能力且没有任何限制时，使用 max effort：最全面的推理和最深入的分析。适用于 Claude Fable 5、Claude Mythos 5、Claude Opus 4.8、Claude Mythos Preview、Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 5 和 Claude Sonnet 4.6。
• 对于需要扩展探索的高级编码和复杂智能体工作（如重复工具调用和详细搜索），使用 xhigh effort。适用于 Claude Fable 5、Claude Mythos 5、Claude Opus 4.8、Claude Opus 4.7 和 Claude Sonnet 5。
• 对于复杂推理、细致分析、困难的编码问题，或任何质量比速度或成本更重要的任务，使用 high effort（默认值）。
• 当您希望获得稳定的性能而不需要 high effort 的全部令牌消耗时，使用 medium effort 作为平衡选项。
• 当您优化速度（因为 Claude 用更少的令牌回答）或成本时，使用 low effort。例如，简单的分类任务、快速查询，或边际质量改进不足以证明额外延迟或支出合理性的高吞吐量用例。



Effort 与工具使用

使用工具时，effort 参数会同时影响工具调用周围的解释和工具调用本身。较低的 effort 级别倾向于：

• 将多个操作合并为更少的工具调用
• 进行更少的工具调用
• 直接采取行动而无需前言
• 完成后使用简洁的确认消息

较高的 effort 级别可能会：

• 进行更多的工具调用
• 在采取行动前解释计划
• 提供详细的变更摘要
• 包含更全面的代码注释



Effort 与扩展思考

effort 参数与扩展思考协同工作。其行为取决于模型：

• Claude Fable 5 和 Claude Mythos 5 使用自适应思考，该功能始终开启（无需 thinking 配置）。thinking: {type: "disabled"} 会被拒绝。Effort 控制思考深度的方式与 Opus 4.8 和 Opus 4.7 相同。
• Claude Opus 4.8 使用自适应思考（thinking: {type: "adaptive"}），其中 effort 是控制思考深度的推荐方式。不支持手动扩展思考（thinking: {type: "enabled", budget_tokens: N}），会返回 400 错误。模型根据每个请求决定何时以及思考多少，因此仅在需要时触发思考。在 high、xhigh 和 max effort 级别下，Claude 几乎总是会深入思考。在较低级别下，对于较简单的问题，它可能会跳过思考。设置 thinking: {type: "adaptive"} 以启用思考；如果不设置，请求将在不思考的情况下运行。
• Claude Mythos Preview 默认使用自适应思考（无需 thinking 配置）。thinking: {type: "disabled"} 会被拒绝。Effort 控制思考深度的方式与 Opus 4.7 和 Opus 4.6 相同。
• Claude Opus 4.7 使用自适应思考（thinking: {type: "adaptive"}），其中 effort 是控制思考深度的推荐方式。Opus 4.7 不再支持手动扩展思考（thinking: {type: "enabled", budget_tokens: N}）；请改用带 effort 的自适应思考。在 high、xhigh 和 max effort 级别下，Claude 几乎总是会深入思考。在较低级别下，对于较简单的问题，它可能会跳过思考。
• Claude Opus 4.6 使用自适应思考（thinking: {type: "adaptive"}），其中 effort 是控制思考深度的推荐方式。虽然 Opus 4.6 仍接受 budget_tokens，但它已被弃用，并将在未来版本中移除。在 high 和 max effort 级别下，Claude 几乎总是会深入思考。在较低级别下，对于较简单的问题，它可能会跳过思考。
• Claude Sonnet 5 使用自适应思考，该功能默认开启（无需 thinking 配置），effort 是控制思考深度的推荐方式。不支持手动扩展思考（thinking: {type: "enabled", budget_tokens: N}），会返回 400 错误。传递 thinking: {type: "disabled"} 可关闭思考。在 high（默认）、xhigh 和 max effort 级别下，Claude 几乎总是会深入思考。在较低级别下，对于较简单的问题，它可能会跳过思考。
• Claude Sonnet 4.6 使用自适应思考（其中 effort 控制思考深度）。带交错模式的手动思考（thinking: {type: "enabled", budget_tokens: N}）仍然可用，但已被弃用。
• Claude Opus 4.5 使用手动思考（thinking: {type: "enabled", budget_tokens: N}），其中 effort 与思考令牌预算协同工作。为您的任务设置 effort 级别，然后根据任务复杂度设置思考令牌预算。

effort 参数可以在启用或不启用扩展思考的情况下使用。在不启用思考的情况下使用时，它仍然控制文本响应和工具调用的总体令牌消耗。



最佳实践

1. 显式设置 effort： API 默认为 high，但正确的起点取决于您的模型和工作负载。
2. 对速度敏感或简单的任务使用 low： 当延迟很重要或任务较为简单时，low effort 可以显著减少响应时间和成本。
3. 测试您的用例： effort 级别的影响因任务类型而异。在部署之前，请在您的特定用例上评估性能。
4. 考虑动态 effort： 根据任务复杂度调整 effort。简单查询可能适合 low effort，而智能体编码和复杂推理则受益于 high effort。



后续步骤