扩展思考

手动模式下的 "extended thinking"（扩展思考）让您可以直接控制 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 事件上。

当您准备好放弃手动预算时，请参阅迁移到自适应思考。



手动模式下的交错思考

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

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

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

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

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

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

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

各平台对 beta 标头的处理方式不同。Claude API 和 Claude Platform on AWS 在任何模型上都接受 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 令牌，可以直接显示失效情况：

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 和模型迁移指南。



后续步骤