# Effort 通过 effort 参数控制 Claude 在响应时使用多少 token，在响应彻底性和 token 效率之间进行权衡。 --- 此功能符合[零数据保留（ZDR）](/docs/en/build-with-claude/api-and-data-retention)条件。当您的组织拥有 ZDR 协议时，通过此功能发送的数据在 API 响应返回后不会被存储。 effort 参数允许您控制 Claude 在响应请求时花费 token 的积极性。这使您能够在响应彻底性和 token 效率之间进行权衡，全部通过单个模型实现。effort 参数在所有支持的模型上可用，无需 beta 头。 effort 参数由 [Claude Mythos Preview](https://anthropic.com/glasswing)、Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 4.6 和 Claude Opus 4.5 支持。 对于 Claude Opus 4.6 和 Sonnet 4.6，effort 取代了 `budget_tokens` 成为控制思考深度的推荐方式。将 effort 与[自适应思考](/docs/en/build-with-claude/adaptive-thinking)（`thinking: {type: "adaptive"}`）结合使用可获得最佳体验。虽然 `budget_tokens` 在 Opus 4.6 和 Sonnet 4.6 上仍被接受，但它已被弃用，并将在未来的模型版本中移除。在 `high`（默认）和 `max` effort 下，Claude 几乎总是会思考。在较低的 effort 级别，它可能会跳过对较简单问题的思考。 ## effort 的工作原理 默认情况下，Claude 使用高 effort，花费所需的 token 以获得优秀的结果。您可以将 effort 级别提高到 `max` 以获得绝对最高的能力，或者降低它以更保守地使用 token，优化速度和成本，同时接受一定程度的能力降低。 将 `effort` 设置为 `"high"` 产生的行为与省略 `effort` 参数完全相同。 effort 参数影响响应中的**所有 token**，包括： - 文本响应和解释 - 工具调用和函数参数 - 扩展思考（启用时） 这种方法有两个主要优势： 1. 不需要启用思考即可使用。 2. 它可以影响所有 token 支出，包括工具调用。例如，较低的 effort 意味着 Claude 进行更少的工具调用。这提供了更大程度的效率控制。 ### Effort 级别 | 级别 | 描述 | 典型用例 | | --- | --- | --- | | `max` | 绝对最高能力，对 token 支出没有限制。在 Claude Mythos Preview、Claude Opus 4.7、Claude Opus 4.6 和 Claude Sonnet 4.6 上可用。 | 需要最深度推理和最彻底分析的任务 | | `xhigh` | 扩展能力，适用于长时间工作。在 Claude Opus 4.7 上可用。 | 长时间运行的智能体和编码任务（超过 30 分钟），token 预算达数百万 | | `high` | 高能力。等同于不设置参数。 | 复杂推理、困难编码问题、智能体任务 | | `medium` | 平衡方法，适度节省 token。 | 需要平衡速度、成本和性能的智能体任务 | | `low` | 最高效。显著节省 token，但能力有所降低。 | 需要最快速度和最低成本的较简单任务，如子智能体 | Effort 是行为信号，而非严格的 token 预算。在较低的 effort 级别，Claude 仍然会在足够困难的问题上思考，但与较高级别相比，思考量会减少。 ### Sonnet 4.6 推荐的 effort 级别 Sonnet 4.6 默认为 `high` effort。使用 Sonnet 4.6 时请显式设置 effort 以避免意外延迟： - **Medium effort**（推荐默认）：大多数应用中速度、成本和性能的最佳平衡。适用于智能体编码、工具密集型工作流和代码生成。 - **Low effort：** 适用于高吞吐量或延迟敏感的工作负载。适用于聊天和非编码用例，优先考虑更快的响应。 - **High effort：** 适用于复杂推理和质量比速度或成本更重要的任务。 - **Max effort：** 适用于需要绝对最高能力且对 token 支出没有限制的任务。 ### Claude Opus 4.7 推荐的 effort 级别 **从 `xhigh` 开始用于编码和智能体用例**，对大多数智能体敏感的工作负载使用 `high` 作为最低值。对成本敏感的工作负载降低到 `medium`，或仅在您的评估显示 `xhigh` 有可衡量的提升空间时才提高到 `max`。 API 默认为 `high`。要使用 `xhigh`，请显式设置 `effort`；您传递的值会覆盖默认值。 | Effort | Claude Opus 4.7 指导 | |--------|------| | `low` | 高效，但最适合短小、范围明确的任务。如果任务有多个部分，请将 `low` 与显式检查清单配对使用。 | | `medium` | 平均工作流的替代方案，您希望在降低成本的同时获得良好结果。 | | `high` | 仍需要智能和 token 消耗平衡的高级用例。这通常是平衡质量和 token 效率的最佳选择。 | | `xhigh` | 编码和智能体工作的推荐起点，以及探索性任务，如重复工具调用、详细网络搜索和知识库搜索。预计 token 使用量明显高于 `high`。 | | `max` | 保留给真正前沿的问题。在大多数工作负载上，`max` 会显著增加成本但质量提升相对较小，在一些结构化输出或不太需要智能的任务上可能导致过度思考。 | Claude Opus 4.7 也比 Claude Opus 4.6 更严格地遵守 effort 级别，特别是在 `low` 和 `medium` 时。在较低的 effort 级别，模型会将工作范围限定在被要求的内容，而不是超出预期。如果您在 Claude Opus 4.7 上观察到复杂问题的推理较浅，请提高 effort 而不是通过提示来绕过。如果您必须保持低 effort 以降低延迟，请添加有针对性的指导，如"此任务涉及多步推理。请仔细思考后再回答。" 在 `xhigh` 或 `max` effort 下运行 Claude Opus 4.7 时，设置较大的 `max_tokens` 以便模型有空间在子智能体和工具调用之间进行思考和行动。从 64k token 开始并从中调整是合理的默认值。 ## 基本用法 ```bash cURL curl https://api.anthropic.com/v1/messages \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" \ --header "content-type: application/json" \ --data '{ "model": "claude-opus-4-7", "max_tokens": 4096, "messages": [{ "role": "user", "content": "Analyze the trade-offs between microservices and monolithic architectures" }], "output_config": { "effort": "medium" } }' ``` ```bash CLI ant messages create --transform 'content.0.text' --raw-output <<'YAML' model: claude-opus-4-7 max_tokens: 4096 messages: - role: user content: Analyze the trade-offs between microservices and monolithic architectures output_config: effort: medium YAML ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-4-7", 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) ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const response = await client.messages.create({ model: "claude-opus-4-7", max_tokens: 4096, messages: [ { role: "user", content: "Analyze the trade-offs between microservices and monolithic architectures" } ], output_config: { effort: "medium" } }); const textBlock = response.content.find( (block): block is Anthropic.TextBlock => block.type === "text" ); console.log(textBlock?.text); ``` ```csharp C# using System; using System.Threading.Tasks; using Anthropic; using Anthropic.Models.Messages; class Program { static async Task Main(string[] args) { AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 4096, Messages = [new() { Role = Role.User, Content = "Analyze the trade-offs between microservices and monolithic architectures" }], OutputConfig = new OutputConfig { Effort = Effort.Medium } }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); } } ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the trade-offs between microservices and monolithic architectures")), }, OutputConfig: anthropic.OutputConfigParam{ Effort: anthropic.OutputConfigEffortMedium, }, }) if err != nil { log.Fatal(err) } fmt.Println(response.Content[0].Text) } ``` ```java Java hidelines={1..5,7..9,-2..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.Model; import com.anthropic.models.messages.OutputConfig; public class Main { public static void main(String[] args) { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(4096L) .addUserMessage("Analyze the trade-offs between microservices and monolithic architectures") .outputConfig(OutputConfig.builder() .effort(OutputConfig.Effort.MEDIUM) .build()) .build(); Message response = client.messages().create(params); response.content().stream() .flatMap(block -> block.text().stream()) .forEach(textBlock -> System.out.println(textBlock.text())); } } ``` ```php PHP hidelines={1..4} messages->create( maxTokens: 4096, messages: [ ['role' => 'user', 'content' => 'Analyze the trade-offs between microservices and monolithic architectures'] ], model: 'claude-opus-4-7', outputConfig: ['effort' => 'medium'], ); echo $message->content[0]->text; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-4-7", max_tokens: 4096, messages: [ { role: "user", content: "Analyze the trade-offs between microservices and monolithic architectures" } ], output_config: { effort: "medium" } ) puts message.content.first.text ``` ## 何时调整 effort 参数 - 使用 **max effort** 当您需要绝对最高能力且没有约束时：最彻底的推理和最深入的分析。在 Claude Mythos Preview、Claude Opus 4.7、Claude Opus 4.6 和 Claude Sonnet 4.6 上可用。 - 使用 **xhigh effort** 用于高级编码和需要扩展探索的复杂智能体工作，如重复工具调用和详细搜索。在 Claude Opus 4.7 上可用。 - 使用 **high effort**（默认）用于复杂推理、细致分析、困难编码问题，或任何质量比速度或成本更重要的任务。 - 使用 **medium effort** 作为平衡选项，当您希望在不完全消耗 high effort token 的情况下获得可靠性能时。 - 使用 **low effort** 当您在优化速度（因为 Claude 用更少的 token 回答）或成本时。例如，简单的分类任务、快速查找或边际质量改进不值得额外延迟或支出的高吞吐量用例。 ## Effort 与工具使用 使用工具时，effort 参数同时影响工具调用周围的解释和工具调用本身。较低的 effort 级别倾向于： - 将多个操作合并为更少的工具调用 - 进行更少的工具调用 - 直接采取行动而不做铺垫 - 完成后使用简短的确认消息 较高的 effort 级别可能： - 进行更多工具调用 - 在采取行动之前解释计划 - 提供详细的变更摘要 - 包含更全面的代码注释 ## Effort 与扩展思考 effort 参数与扩展思考配合使用。其行为取决于模型： - **Claude Mythos Preview** 默认使用[自适应思考](/docs/en/build-with-claude/adaptive-thinking)（无需 `thinking` 配置）。`thinking: {type: "disabled"}` 会被拒绝。Effort 以与 Opus 4.7 和 Opus 4.6 相同的方式控制思考深度。 - **Claude Opus 4.7** 使用[自适应思考](/docs/en/build-with-claude/adaptive-thinking)（`thinking: {type: "adaptive"}`），其中 effort 是控制思考深度的推荐方式。Opus 4.7 不再支持手动扩展思考（`thinking: {type: "enabled", budget_tokens: N}`）；请改用自适应思考配合 effort。在 `high`、`xhigh` 和 `max` effort 下，Claude 几乎总是深入思考。在较低级别，它可能会跳过对较简单问题的思考。 - **Claude Opus 4.6** 使用[自适应思考](/docs/en/build-with-claude/adaptive-thinking)（`thinking: {type: "adaptive"}`），其中 effort 是控制思考深度的推荐方式。虽然 `budget_tokens` 在 Opus 4.6 上仍被接受，但它已被弃用，并将在未来版本中移除。在 `high` 和 `max` effort 下，Claude 几乎总是深入思考。在较低级别，它可能会跳过对较简单问题的思考。 - **Claude Sonnet 4.6** 使用[自适应思考](/docs/en/build-with-claude/adaptive-thinking)（其中 effort 控制思考深度）。使用[交错模式](/docs/en/build-with-claude/extended-thinking#interleaved-thinking)的手动思考（`thinking: {type: "enabled", budget_tokens: N}`）仍可用但已弃用。 - **Claude Opus 4.5** 使用手动思考（`thinking: {type: "enabled", budget_tokens: N}`），其中 effort 与思考 token 预算配合使用。为您的任务设置 effort 级别，然后根据任务复杂性设置思考 token 预算。 effort 参数可以在启用或不启用扩展思考的情况下使用。在不使用思考时，它仍然控制文本响应和工具调用的总体 token 支出。 ## 最佳实践 1. **显式设置 effort：** API 默认为 `high`，但正确的起点取决于您的模型和工作负载。 2. **对速度敏感或简单任务使用 low：** 当延迟很重要或任务简单时，low effort 可以显著减少响应时间和成本。 3. **测试您的用例：** effort 级别对不同任务类型的影响各不相同。在部署前评估您特定用例的性能。 4. **考虑动态 effort：** 根据任务复杂性调整 effort。简单查询可能适合 low effort，而智能体编码和复杂推理则受益于 high effort。