Claude Platform Docs
Messages思考

扩展思考

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

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

要了解思考本身的工作原理，包括思考块和响应结构、display 参数、"streaming"（流式传输）、结合 "tool use"（工具使用）的思考以及加密，请参阅思考概述。

支持的模型

各模型的扩展思考可用性（包括扩展思考是唯一模式的模型）列在各模型配置表中。

如何使用扩展思考

以下是在 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 模型上，请在 API 请求中添加 interleaved-thinking-2025-05-14 beta 标头。

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

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

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

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

各平台对 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 个令牌，可以直接展示失效情况：

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 4.7 或更高版本的模型，例如 Claude Opus 5.5、Claude Sonnet 5 或 Claude Fable 5.1，这些模型上的 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?