Effort
通过 effort 参数控制 Claude 在响应时使用多少 token,在响应彻底性和 token 效率之间进行权衡。
此功能符合零数据保留(ZDR)条件。当您的组织拥有 ZDR 协议时,通过此功能发送的数据在 API 响应返回后不会被存储。
effort 参数允许您控制 Claude 在响应请求时花费 token 的积极性。这使您能够在响应彻底性和 token 效率之间进行权衡,全部通过单个模型实现。effort 参数在所有支持的模型上可用,无需 beta 头。
effort 参数由 Claude Mythos Preview、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 与自适应思考(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,包括:
- 文本响应和解释
- 工具调用和函数参数
- 扩展思考(启用时)
这种方法有两个主要优势:
- 不需要启用思考即可使用。
- 它可以影响所有 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 开始并从中调整是合理的默认值。
基本用法
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"
}
}'
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
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)
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);
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);
}
}
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)
}
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
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->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;
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 默认使用自适应思考(无需
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和maxeffort 下,Claude 几乎总是深入思考。在较低级别,它可能会跳过对较简单问题的思考。 - Claude Opus 4.6 使用自适应思考(
thinking: {type: "adaptive"}),其中 effort 是控制思考深度的推荐方式。虽然budget_tokens在 Opus 4.6 上仍被接受,但它已被弃用,并将在未来版本中移除。在high和maxeffort 下,Claude 几乎总是深入思考。在较低级别,它可能会跳过对较简单问题的思考。 - Claude Sonnet 4.6 使用自适应思考(其中 effort 控制思考深度)。使用交错模式的手动思考(
thinking: {type: "enabled", budget_tokens: N})仍可用但已弃用。 - Claude Opus 4.5 使用手动思考(
thinking: {type: "enabled", budget_tokens: N}),其中 effort 与思考 token 预算配合使用。为您的任务设置 effort 级别,然后根据任务复杂性设置思考 token 预算。
effort 参数可以在启用或不启用扩展思考的情况下使用。在不使用思考时,它仍然控制文本响应和工具调用的总体 token 支出。
最佳实践
- 显式设置 effort: API 默认为
high,但正确的起点取决于您的模型和工作负载。 - 对速度敏感或简单任务使用 low: 当延迟很重要或任务简单时,low effort 可以显著减少响应时间和成本。
- 测试您的用例: effort 级别对不同任务类型的影响各不相同。在部署前评估您特定用例的性能。
- 考虑动态 effort: 根据任务复杂性调整 effort。简单查询可能适合 low effort,而智能体编码和复杂推理则受益于 high effort。