使用扩展思考进行构建

有关更多信息，请参阅不同模型版本中思考的差异。

扩展思考的工作原理

启用扩展思考后，Claude 会创建 thinking 内容块，其中输出其内部推理。Claude 在制作最终响应之前会整合来自此推理的见解。

API 响应将包括 thinking 内容块，后跟 text 内容块。

以下是默认响应格式的示例：

有关扩展思考响应格式的更多信息，请参阅 Messages API 参考。

如何使用扩展思考

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

要启用扩展思考，请添加一个 thinking 对象，将 type 参数设置为 enabled，并将 budget_tokens 设置为扩展思考的指定令牌预算。

budget_tokens 参数确定 Claude 允许用于其内部推理过程的最大令牌数。在 Claude 4 模型中，此限制适用于完整思考令牌，而不是总结输出。较大的预算可以通过为复杂问题启用更彻底的分析来改进响应质量，尽管 Claude 可能不会使用整个分配的预算，特别是在 32k 以上的范围内。

budget_tokens 必须设置为小于 max_tokens 的值。但是，当使用交错思考与工具时，您可以超过此限制，因为令牌限制变成您的整个上下文窗口（200k 令牌）。

总结的思考

启用扩展思考后，Claude 4 模型的 Messages API 返回 Claude 完整思考过程的摘要。总结的思考提供了扩展思考的全部智能优势，同时防止了滥用。

以下是总结思考的一些重要考虑事项：

• 您需要为原始请求生成的完整思考令牌付费，而不是摘要令牌。
• 计费的输出令牌计数将不匹配您在响应中看到的令牌计数。
• 思考输出的前几行更详细，提供了详细的推理，这对提示工程目的特别有帮助。
• 随着 Anthropic 寻求改进扩展思考功能，总结行为可能会发生变化。
• 总结保留了 Claude 思考过程的关键思想，增加的延迟最少，实现了可流式传输的用户体验，并便于从 Claude Sonnet 3.7 迁移到 Claude 4 模型。
• 总结由与您在请求中指定的模型不同的模型处理。思考模型看不到总结的输出。

流式传输思考

您可以使用服务器发送事件 (SSE) 流式传输扩展思考响应。

启用扩展思考的流式传输后，您会通过 thinking_delta 事件接收思考内容。

有关通过 Messages API 进行流式传输的更多文档，请参阅流式传输消息。

以下是如何处理思考流式传输的方法：

示例流式传输输出：

扩展思考与工具使用

扩展思考可以与工具使用一起使用，允许 Claude 通过工具选择和结果处理进行推理。

使用扩展思考和工具使用时，请注意以下限制：

1. 工具选择限制：带有思考的工具使用仅支持 tool_choice: {"type": "auto"} (默认) 或 tool_choice: {"type": "none"}。使用 tool_choice: {"type": "any"} 或 tool_choice: {"type": "tool", "name": "..."} 将导致错误，因为这些选项强制工具使用，这与扩展思考不兼容。

2. 保留思考块：在工具使用期间，您必须将 thinking 块传回 API 以获取最后的助手消息。将完整的未修改块传回 API 以维持推理连续性。

在对话中切换思考模式

您不能在助手轮次中间切换思考，包括在工具使用循环期间。整个助手轮次必须在单一思考模式下运行：

• 如果启用了思考，最后的助手轮次必须以思考块开始。
• 如果禁用了思考，最后的助手轮次不能包含任何思考块

从模型的角度来看，工具使用循环是助手轮次的一部分。助手轮次直到 Claude 完成其完整响应（可能包括多个工具调用和结果）才完成。

例如，这个序列都是单个助手轮次的一部分：

尽管有多个 API 消息，但工具使用循环在概念上是一个连续助手响应的一部分。

常见错误场景

您可能会遇到此错误：

这通常发生在以下情况：

1. 您在工具使用序列期间禁用了思考
2. 您想再次启用思考
3. 您的最后一条助手消息包含工具使用块但没有思考块

实际指导

✗ 无效：在工具使用后立即切换思考

✓ 有效：首先完成助手轮次

最佳实践：在每个轮次开始时规划您的思考策略，而不是尝试在轮次中间切换。

保留思考块

在工具使用期间，您必须将 thinking 块传回 API，并且必须将完整的未修改块传回 API。这对于维持模型的推理流和对话完整性至关重要。

当 Claude 调用工具时，它暂停了响应的构建以等待外部信息。返回工具结果后，Claude 将继续构建该现有响应。这需要在工具使用期间保留思考块，原因有两个：

1. 推理连续性：思考块捕获了导致工具请求的 Claude 逐步推理。当您发布工具结果时，包括原始思考可确保 Claude 能够从中断的地方继续推理。

2. 上下文维护：虽然工具结果在 API 结构中显示为用户消息，但它们是连续推理流的一部分。保留思考块在多个 API 调用中维持这个概念流。有关上下文管理的更多信息，请参阅我们的上下文窗口指南。

重要：提供 thinking 块时，连续 thinking 块的整个序列必须与模型在原始请求期间生成的输出相匹配；您不能重新排列或修改这些块的序列。

交错思考

Claude 4 模型中的扩展思考与工具使用支持交错思考，这使 Claude 能够在工具调用之间进行思考，并在收到工具结果后进行更复杂的推理。

通过交错思考，Claude 可以：

• 在决定下一步操作之前，对工具调用的结果进行推理
• 在推理步骤之间链接多个工具调用
• 根据中间结果做出更细致的决策

要启用交错思考，请在 API 请求中添加 beta 标头 interleaved-thinking-2025-05-14。

以下是交错思考的一些重要注意事项：

• 使用交错思考时，budget_tokens 可以超过 max_tokens 参数，因为它代表一个助手轮次内所有思考块的总预算。
• 交错思考仅支持 通过 Messages API 使用的工具。
• 交错思考仅支持 Claude 4 模型，需要使用 beta 标头 interleaved-thinking-2025-05-14。
• 直接调用 Claude API 允许您在对任何模型的请求中传递 interleaved-thinking-2025-05-14，但不会产生任何效果。
• 在第三方平台上（例如 Amazon Bedrock 和 Vertex AI），如果您将 interleaved-thinking-2025-05-14 传递给除 Claude Opus 4.5、Claude Opus 4.1、Opus 4 或 Sonnet 4 之外的任何模型，您的请求将失败。

扩展思考与提示缓存

提示缓存 与思考有几个重要的注意事项：

思考块上下文移除

• 来自先前轮次的思考块从上下文中移除，这可能会影响缓存断点
• 继续使用工具的对话时，思考块被缓存并在从缓存读取时计为输入令牌
• 这造成了一个权衡：虽然思考块在视觉上不消耗上下文窗口空间，但在缓存时仍然计入您的输入令牌使用量
• 如果思考被禁用，如果您在当前工具使用轮次中传递思考内容，请求将失败。在其他情况下，传递给 API 的思考内容将被忽略

缓存失效模式

• 思考参数的更改（启用/禁用或预算分配）会使消息缓存断点失效
• 交错思考 放大了缓存失效，因为思考块可以在多个 工具调用 之间发生
• 系统提示和工具尽管思考参数更改或块移除，仍保持缓存

理解思考块缓存行为

使用扩展思考与工具使用时，思考块表现出特定的缓存行为，这会影响令牌计数：

工作原理：

1. 仅当您发出包含工具结果的后续请求时，才会发生缓存
2. 发出后续请求时，先前的对话历史记录（包括思考块）可以被缓存
3. 这些缓存的思考块在从缓存读取时计为您的使用指标中的输入令牌
4. 当包含非工具结果用户块时，所有先前的思考块都被忽略并从上下文中剥离

详细示例流程：

请求 1：

响应 1：

请求 2：

响应 2：

请求 2 写入请求内容的缓存（不是响应）。缓存包括原始用户消息、第一个思考块、工具使用块和工具结果。

请求 3：

对于 Claude Opus 4.5 及更高版本，默认情况下保留所有先前的思考块。对于较旧的模型，因为包含了非工具结果用户块，所有先前的思考块都被忽略。此请求将按以下方式处理：

关键点：

• 这种缓存行为会自动发生，即使没有显式的 cache_control 标记
• 无论使用常规思考还是交错思考，这种行为都是一致的

扩展思考中的最大令牌和上下文窗口大小

在较旧的 Claude 模型中（Claude Sonnet 3.7 之前），如果提示令牌和 max_tokens 的总和超过模型的上下文窗口，系统会自动调整 max_tokens 以适应上下文限制。这意味着您可以设置一个大的 max_tokens 值，系统会根据需要静默减少它。

使用 Claude 3.7 和 4 模型，max_tokens（启用思考时包括您的思考预算）被强制执行为严格限制。如果提示令牌 + max_tokens 超过上下文窗口大小，系统现在将返回验证错误。

扩展思考中的上下文窗口

使用启用思考的扩展思考计算上下文窗口使用时，需要注意一些事项：

• 来自先前轮次的思考块被剥离，不计入您的上下文窗口
• 当前轮次思考计入该轮次的 max_tokens 限制

下图演示了启用扩展思考时的专门令牌管理：

有效的上下文窗口计算为：

我们建议使用 令牌计数 API 为您的特定用例获取准确的令牌计数，特别是在处理包含思考的多轮对话时。

扩展思考和工具使用中的上下文窗口

使用扩展思考与工具使用时，思考块必须显式保留并与工具结果一起返回。

扩展思考与工具使用的有效上下文窗口计算变为：

下图说明了扩展思考与工具使用的令牌管理：

使用扩展思考管理令牌

鉴于 Claude 3.7 和 4 模型的上下文窗口和 max_tokens 行为与扩展思考，您可能需要：

• 更积极地监控和管理您的令牌使用
• 随着提示长度的变化调整 max_tokens 值
• 可能更频繁地使用 令牌计数端点
• 意识到先前的思考块不会在您的上下文窗口中累积

进行此更改是为了提供更可预测和透明的行为，特别是因为最大令牌限制已显著增加。

思考加密

完整的思考内容被加密并在 signature 字段中返回。此字段用于验证思考块是由 Claude 生成的，当传递回 API 时。

以下是关于思考加密的一些重要注意事项：

• 当 流式传输响应 时，签名通过 content_block_delta 事件中的 signature_delta 添加，就在 content_block_stop 事件之前。
• signature 值在 Claude 4 模型中的长度明显长于以前的模型。
• signature 字段是一个不透明字段，不应被解释或解析 - 它仅用于验证目的。
• signature 值在平台之间兼容（Claude API、Amazon Bedrock 和 Vertex AI）。在一个平台上生成的值将与另一个平台兼容。

思维过程编辑

偶尔，Claude 的内部推理会被我们的安全系统标记。当这种情况发生时，我们会加密 thinking 块的部分或全部内容，并将其作为 redacted_thinking 块返回给您。redacted_thinking 块在传回 API 时会被解密，允许 Claude 继续其响应而不会丢失上下文。

在构建使用扩展思维的面向客户的应用程序时：

• 请注意，编辑后的思维块包含不可读的加密内容
• 考虑提供简单的解释，例如："Claude 的某些内部推理已自动加密以确保安全。这不会影响响应的质量。"
• 如果向用户显示思维块，您可以过滤掉编辑后的块，同时保留正常的思维块
• 要透明地说明使用扩展思维功能可能偶尔会导致某些推理被加密
• 实施适当的错误处理，以优雅地管理编辑后的思维，而不会破坏您的 UI

以下是显示正常和编辑后思维块的示例：

在多轮对话中将 thinking 和 redacted_thinking 块传回 API 时，您必须将最后一个助手转向的完整未修改块传回 API。这对于维护模型的推理流程至关重要。我们建议始终将所有思维块传回 API。有关更多详情，请参阅上面的保留思维块部分。

不同模型版本中的思维差异

Messages API 在 Claude Sonnet 3.7 和 Claude 4 模型中处理思维的方式不同，主要在编辑和总结行为方面。

请参阅下表了解简明对比：

Claude Opus 4.5 中的思维块保留

Claude Opus 4.5 引入了一个新的默认行为：默认情况下，来自先前助手转向的思维块在模型上下文中被保留。这与早期模型不同，早期模型会从先前的转向中删除思维块。

思维块保留的好处：

• 缓存优化：使用工具使用时，保留的思维块可以启用缓存命中，因为它们与工具结果一起传回并在助手转向中增量缓存，从而在多步工作流中节省令牌
• 无智能影响：保留思维块对模型性能没有负面影响

重要注意事项：

• 上下文使用：长对话将消耗更多上下文空间，因为思维块保留在上下文中
• 自动行为：这是 Claude Opus 4.5 的默认行为——不需要代码更改或测试版标头
• 向后兼容性：要利用此功能，继续将完整的、未修改的思维块传回 API，就像您对工具使用所做的那样

定价

有关完整的定价信息，包括基本费率、缓存写入、缓存命中和输出令牌，请参阅定价页面。

思维过程产生的费用包括：

• 思维期间使用的令牌（输出令牌）
• 后续请求中包含的最后一个助手转向的思维块（输入令牌）
• 标准文本输出令牌

使用总结的思维时：

• 输入令牌：原始请求中的令牌（不包括先前转向的思维令牌）
• 输出令牌（计费）：Claude 内部生成的原始思维令牌
• 输出令牌（可见）：您在响应中看到的总结思维令牌
• 无费用：用于生成摘要的令牌

扩展思维的最佳实践和注意事项

使用思维预算

• 预算优化：最小预算为 1,024 个令牌。我们建议从最小值开始，逐步增加思维预算以找到您用例的最优范围。更高的令牌计数可以实现更全面的推理，但根据任务的不同会有递减的回报。增加预算可以改善响应质量，但代价是增加延迟。对于关键任务，测试不同的设置以找到最优平衡。请注意，思维预算是一个目标而不是严格限制——实际令牌使用可能因任务而异。
• 起点：对于复杂任务，从较大的思维预算（16k+ 令牌）开始，然后根据您的需求进行调整。
• 大预算：对于超过 32k 的思维预算，我们建议使用批处理以避免网络问题。推动模型思维超过 32k 令牌的请求会导致长时间运行的请求，可能会遇到系统超时和开放连接限制。
• 令牌使用跟踪：监控思维令牌使用情况以优化成本和性能。

性能考虑

• 响应时间：为推理过程所需的额外处理可能导致的更长响应时间做好准备。考虑生成思维块可能会增加总体响应时间。
• 流式传输要求：当 max_tokens 大于 21,333 时，需要流式传输。流式传输时，准备好处理思维和文本内容块的到达。

功能兼容性

• 思维与 temperature 或 top_k 修改以及强制工具使用不兼容。
• 启用思维时，您可以将 top_p 设置为 1 到 0.95 之间的值。
• 启用思维时，您无法预填充响应。
• 对思维预算的更改会使包含消息的缓存提示前缀失效。但是，当思维参数更改时，缓存的系统提示和工具定义将继续工作。

使用指南

• 任务选择：对于特别复杂的任务使用扩展思维，这些任务受益于逐步推理，如数学、编码和分析。
• 上下文处理：您不需要自己删除先前的思维块。Claude API 会自动忽略先前转向的思维块，它们在计算上下文使用时不包括在内。
• 提示工程：如果您想最大化 Claude 的思维能力，请查看我们的扩展思维提示技巧。

后续步骤