扩展思考

在支持扩展思考的 Claude 模型上，使用固定的 budget_tokens 预算配置手动扩展思考，并迁移到自适应思考。

手动模式下的扩展思考让您可以直接控制 Claude 的思考量。您通过 thinking: {type: "enabled", budget_tokens: N} 在每个请求上设置思考令牌预算，Claude 会在开始生成最终答案之前依据该预算进行思考。当您的工作负载需要可预测的延迟或对思考成本进行精确控制时，手动模式仍然很有用。本页面介绍如何设置和调整预算、手动模式如何与交错思考和提示缓存交互，以及如何迁移到自适应思考。

有关思考本身的工作原理，包括思考块和响应结构、display 参数、流式传输、结合工具使用的思考以及加密，请参阅思考概述。

支持的模型

各模型的扩展思考可用性，包括仅支持扩展思考模式的模型，列于各模型配置表中。

如何使用扩展思考

以下是在 Messages API 中使用扩展思考的示例：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        }
    ],
)

# 响应包含摘要化的思考块和文本块
for block in response.content:
    match block.type:
        case "thinking":
            print(f"\nThinking summary: {block.thinking}")
        case "text":
            print(f"\nResponse: {block.text}")

要开启手动扩展思考，请添加一个 thinking 对象，将 type 设置为 enabled，并提供 budget_tokens 值。

budget_tokens 参数为 Claude 的内部推理过程可使用的令牌数量设定目标。更大的预算可以通过对复杂问题进行更深入的分析来提高响应质量。

预算规则与调优

budget_tokens 必须满足以下约束：

最小值为 1,024 个令牌。 API 会拒绝更小的值。
小于 max_tokens。 思考令牌计入该轮次的 max_tokens 限制，因此预算必须为最终响应留出空间。唯一的例外是交错思考，在该模式下 budget_tokens 可以超过 max_tokens，因为预算涵盖单个助手轮次内的所有思考块。
不支持缓存预热。 由于 budget_tokens 必须小于 max_tokens，扩展思考无法与 max_tokens: 0（缓存预热）结合使用。

预算是一个目标值，而非严格上限。实际令牌使用量因任务而异，Claude 可能在预算耗尽之前就停止推理；max_tokens 仍然是总输出的硬性上限。

在 Claude Opus 4.5（唯一支持 effort 的仅限扩展思考的模型）上，effort 决定整体响应，而 budget_tokens 设置思考深度；请同时设置两者。

调整预算的方法：

根据任务匹配起始值。对于简单任务，从接近 1,024 令牌的最小值开始，逐步增加以找到适合您用例的最佳范围。对于复杂任务，从 16,000 令牌或更大的预算开始，并根据您的延迟和质量需求进行调整。更高的预算可以实现更全面的推理，但收益递减程度取决于任务，且会增加延迟。对于关键任务，请测试不同的设置以找到合适的平衡点。
对于超过 32k 的思考预算，请使用批处理以避免网络问题。让模型思考超过 32k 令牌会产生长时间运行的请求，可能触发系统超时和开放连接数限制。

要跟踪预算的实际成本，请监控响应中的 usage.output_tokens_details.thinking_tokens 字段，该字段报告计费输出令牌中有多少用于内部推理。在流式传输时，此明细仅出现在最终的 message_delta 事件中。

当您准备好不再使用手动预算时，请参阅迁移到自适应思考。

手动模式下的交错思考

交错思考允许 Claude 在单个助手轮次内的工具调用之间进行思考，在决定下一步操作之前对每个工具结果进行推理。有关该概念、轮次结构以及在自适应思考模型上的行为，请参阅思考概述中的交错思考。本节介绍在使用手动 type: "enabled" 思考时如何启用它。

在 Claude Opus 4.5、Claude Sonnet 4.5 以及更早的 Claude 4 模型（Claude Opus 4.1、Claude Opus 4 和 Claude Sonnet 4）上，请在 API 请求中添加 interleaved-thinking-2025-05-14 beta 标头。

4.6 代模型在手动模式下有所区分：

Claude Sonnet 4.6：带有手动 type: "enabled" 的 beta 标头仍然有效，但已弃用。建议使用自适应思考，它会自动交错，无需标头。
Claude Opus 4.6：手动模式完全不支持交错思考。只有其自适应模式支持交错，因此如果您需要在此模型上的工具调用之间进行推理，请切换到 thinking: {type: "adaptive"}。

Claude Haiku 4.5 不支持交错思考。在 Claude API 上，该 beta 标头会被接受但被忽略。

手动模式下交错思考的另外两个注意事项：

此处 budget_tokens 可以超过 max_tokens；预算规则解释了这一例外情况。
交错思考仅支持通过 Messages API 使用的工具。

各平台对 beta 标头的处理方式不同。Claude API 和 AWS 上的 Claude Platform 在任何模型上都接受 interleaved-thinking-2025-05-14，并在不支持的情况下忽略它。接受并不等同于生效：在拒绝 type: "enabled" 的模型（4.7 及更高版本）或缺少手动模式交错功能的模型（Claude Opus 4.6）上，该标头在手动模式下无效；在这些模型上，自适应思考会自动交错。

合作伙伴运营的平台（Amazon Bedrock 和 Google Cloud）同样在任何模型上接受该标头而不返回错误，并在不支持交错思考的模型上忽略它。

手动模式下的轮次结构

通用的轮次结构规则，包括单轮次工具使用循环、轮次中途冲突处理以及在轮次之间切换思考，请参阅结合工具使用的思考。

手动模式增加了一项要求：启用思考的请求的最后一个助手轮次必须以思考块开始（自适应思考取消了该要求）。在轮次之间更改思考配置也会使提示缓存失效；请参阅下一节。

手动模式下的提示缓存

在思考与提示缓存中描述的与模式无关的缓存行为基础上，手动模式增加了一条规则：在请求之间更改 budget_tokens 会使缓存断点失效，就像切换思考模式一样，因为预算值会被渲染到提示中。预算更改后，消息级断点总是会未命中；工具和系统提示断点是否也会未命中，取决于模型在何处渲染该配置。

在实践中，请选择一个预算并在缓存对话的整个生命周期内保持稳定。在 Claude Sonnet 4.6 上运行带有消息级缓存的多轮对话，并在第三个请求中将预算从 4,000 更改为 8,000 令牌，可以直接观察到失效情况：

Output

First request - establishing cache
First response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 17, output_tokens: 700 }

Second request - same thinking parameters (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 1370, input_tokens: 303, output_tokens: 874 }

Third request - different thinking budget (cache miss expected)
Third response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 747, output_tokens: 619 }

第三个请求重新创建了缓存（cache_creation_input_tokens=1370，cache_read_input_tokens=0），因为请求之间的预算发生了变化。有关在自适应模式下相同实验的可运行版本（其中 effort 级别扮演了此处 budget_tokens 的缓存角色），请参阅引导页面上的提示缓存。

共享机制

大多数思考行为与模式无关，并在思考页面上统一记录。那里的所有内容同样适用于手动模式：

迁移到自适应思考

如果您的模型仅支持扩展思考（Claude Sonnet 4.5、Claude Opus 4.5、Claude Haiku 4.5 以及更早的 Claude 4 模型），目前无需采取任何行动：这些模型不提供自适应思考，且 type: "adaptive" 会返回 400 错误。请继续使用 budget_tokens，直到您迁移到支持自适应思考的模型，然后应用下面的映射。

在以下情况下，您需要从 type: "enabled" 迁移：

您使用 Claude Opus 4.6 或 Claude Sonnet 4.6，其中 budget_tokens 已弃用。
您正在迁移到 Claude Opus 4.7、Claude Opus 4.8、Claude Opus 5、Claude Sonnet 5、Claude Fable 5 或 Claude Mythos 5，在这些模型上 type: "enabled" 会返回 400 错误。

映射很简单：移除 budget_tokens，设置 thinking: {type: "adaptive"}，并使用 output_config: {effort: ...} 而非令牌预算来控制推理深度。

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  }
}

变为：

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "adaptive"
  },
  "output_config": {
    "effort": "high"
  }
}

effort: "high" 与 API 默认值一致；此处列出它只是为了展示深度控制现在所在的位置，省略它会产生相同的行为。

请预期这是行为上的差异，而不仅仅是语法变化。使用固定预算时，Claude 在每个请求上都会思考。使用自适应思考时，Claude 会在每个请求上自行决定是否思考以及思考多少，在较低的 effort 设置下，它可能会在简单输入上完全跳过思考。迁移后，您还可以移除 interleaved-thinking-2025-05-14 beta 标头：自适应思考会自动交错，且 Claude API 在这些模型上会忽略该标头。思考块保留行为也有所变化：Claude Opus 4.5 以及版本号为 4.6 及更高的模型会在上下文中保留先前轮次的思考块并将其作为输入计费，而 Claude Sonnet 4.5、Claude Haiku 4.5 及更早的模型会将其剥离；请参阅各模型的思考块保留。

切换模式属于思考配置更改，因此切换后的第一个请求会使缓存断点失效，如手动模式下的提示缓存中所述。

有关完整指南，请参阅自适应思考、effort 以及模型迁移指南。

后续步骤

思考

了解思考的工作原理：思考块、显示、流式传输和工具使用。

引导思考

让 Claude 在每个请求上自行决定何时思考以及思考多少。

工具和多轮工作流中的思考

在工具调用和轮次之间保留思考块并管理思考。

Was this page helpful?

消息思考

扩展思考

在支持扩展思考的 Claude 模型上，使用固定的 budget_tokens 预算配置手动扩展思考，并迁移到自适应思考。

有关思考本身的工作原理，包括思考块和响应结构、display 参数、流式传输、结合工具使用的思考以及加密，请参阅思考概述。

支持的模型

各模型的扩展思考可用性，包括仅支持扩展思考模式的模型，列于各模型配置表中。

如何使用扩展思考

以下是在 Messages API 中使用扩展思考的示例：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        }
    ],
)

# 响应包含摘要化的思考块和文本块
for block in response.content:
    match block.type:
        case "thinking":
            print(f"\nThinking summary: {block.thinking}")
        case "text":
            print(f"\nResponse: {block.text}")

要开启手动扩展思考，请添加一个 thinking 对象，将 type 设置为 enabled，并提供 budget_tokens 值。

budget_tokens 参数为 Claude 的内部推理过程可使用的令牌数量设定目标。更大的预算可以通过对复杂问题进行更深入的分析来提高响应质量。

预算规则与调优

budget_tokens 必须满足以下约束：

最小值为 1,024 个令牌。 API 会拒绝更小的值。
小于 max_tokens。 思考令牌计入该轮次的 max_tokens 限制，因此预算必须为最终响应留出空间。唯一的例外是交错思考，在该模式下 budget_tokens 可以超过 max_tokens，因为预算涵盖单个助手轮次内的所有思考块。
不支持缓存预热。 由于 budget_tokens 必须小于 max_tokens，扩展思考无法与 max_tokens: 0（缓存预热）结合使用。

预算是一个目标值，而非严格上限。实际令牌使用量因任务而异，Claude 可能在预算耗尽之前就停止推理；max_tokens 仍然是总输出的硬性上限。

在 Claude Opus 4.5（唯一支持 effort 的仅限扩展思考的模型）上，effort 决定整体响应，而 budget_tokens 设置思考深度；请同时设置两者。

调整预算的方法：

根据任务匹配起始值。对于简单任务，从接近 1,024 令牌的最小值开始，逐步增加以找到适合您用例的最佳范围。对于复杂任务，从 16,000 令牌或更大的预算开始，并根据您的延迟和质量需求进行调整。更高的预算可以实现更全面的推理，但收益递减程度取决于任务，且会增加延迟。对于关键任务，请测试不同的设置以找到合适的平衡点。
对于超过 32k 的思考预算，请使用批处理以避免网络问题。让模型思考超过 32k 令牌会产生长时间运行的请求，可能触发系统超时和开放连接数限制。

当您准备好不再使用手动预算时，请参阅迁移到自适应思考。

手动模式下的交错思考

4.6 代模型在手动模式下有所区分：

Claude Sonnet 4.6：带有手动 type: "enabled" 的 beta 标头仍然有效，但已弃用。建议使用自适应思考，它会自动交错，无需标头。
Claude Opus 4.6：手动模式完全不支持交错思考。只有其自适应模式支持交错，因此如果您需要在此模型上的工具调用之间进行推理，请切换到 thinking: {type: "adaptive"}。

Claude Haiku 4.5 不支持交错思考。在 Claude API 上，该 beta 标头会被接受但被忽略。

手动模式下交错思考的另外两个注意事项：

此处 budget_tokens 可以超过 max_tokens；预算规则解释了这一例外情况。
交错思考仅支持通过 Messages API 使用的工具。

合作伙伴运营的平台（Amazon Bedrock 和 Google Cloud）同样在任何模型上接受该标头而不返回错误，并在不支持交错思考的模型上忽略它。

手动模式下的轮次结构

通用的轮次结构规则，包括单轮次工具使用循环、轮次中途冲突处理以及在轮次之间切换思考，请参阅结合工具使用的思考。

手动模式下的提示缓存

Output

First request - establishing cache
First response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 17, output_tokens: 700 }

Second request - same thinking parameters (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 1370, input_tokens: 303, output_tokens: 874 }

Third request - different thinking budget (cache miss expected)
Third response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 747, output_tokens: 619 }

共享机制

大多数思考行为与模式无关，并在思考页面上统一记录。那里的所有内容同样适用于手动模式：

迁移到自适应思考

在以下情况下，您需要从 type: "enabled" 迁移：

您使用 Claude Opus 4.6 或 Claude Sonnet 4.6，其中 budget_tokens 已弃用。
您正在迁移到 Claude Opus 4.7、Claude Opus 4.8、Claude Opus 5、Claude Sonnet 5、Claude Fable 5 或 Claude Mythos 5，在这些模型上 type: "enabled" 会返回 400 错误。

映射很简单：移除 budget_tokens，设置 thinking: {type: "adaptive"}，并使用 output_config: {effort: ...} 而非令牌预算来控制推理深度。

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  }
}

变为：

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "adaptive"
  },
  "output_config": {
    "effort": "high"
  }
}

effort: "high" 与 API 默认值一致；此处列出它只是为了展示深度控制现在所在的位置，省略它会产生相同的行为。

切换模式属于思考配置更改，因此切换后的第一个请求会使缓存断点失效，如手动模式下的提示缓存中所述。

有关完整指南，请参阅自适应思考、effort 以及模型迁移指南。

后续步骤

思考

了解思考的工作原理：思考块、显示、流式传输和工具使用。

引导思考

让 Claude 在每个请求上自行决定何时思考以及思考多少。

工具和多轮工作流中的思考

在工具调用和轮次之间保留思考块并管理思考。

Was this page helpful?

支持的模型

如何使用扩展思考

预算规则与调优

手动模式下的交错思考

手动模式下的轮次结构

手动模式下的提示缓存

共享机制

迁移到自适应思考

后续步骤

支持的模型

如何使用扩展思考

预算规则与调优

手动模式下的交错思考

手动模式下的轮次结构

手动模式下的提示缓存

共享机制

迁移到自适应思考

后续步骤

支持的模型

如何使用扩展思考

预算规则与调优

手动模式下的交错思考

手动模式下的轮次结构

手动模式下的提示缓存

共享机制

迁移到自适应思考

后续步骤

支持的模型

如何使用扩展思考

预算规则与调优

手动模式下的交错思考

手动模式下的轮次结构

手动模式下的提示缓存

共享机制

迁移到自适应思考

后续步骤