使用扩展思考进行构建

扩展思考赋予 Claude 增强的推理能力，用于处理复杂任务，同时在提供最终答案之前，提供不同程度的逐步思考过程透明度。

支持的模型

以下模型支持扩展思考：

• Claude Opus 4.6 (claude-opus-4-6) — 推荐使用自适应思考；手动模式（type: "enabled"）已弃用
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)（已弃用）
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)

扩展思考的工作原理

当扩展思考开启时，Claude 会创建 thinking 内容块，在其中输出其内部推理过程。Claude 会在制定最终回复之前整合这些推理中的洞察。

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

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

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me analyze this step by step...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

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

如何使用扩展思考

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

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-sonnet-4-5",
    "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?"
        }
    ]
}'

要开启扩展思考，请添加一个 thinking 对象，将 type 参数设置为 enabled，并将 budget_tokens 设置为扩展思考的指定 token 预算。对于 Claude Opus 4.6，我们建议改用 type: "adaptive" — 详情请参阅自适应思考。虽然 Opus 4.6 仍然支持带 budget_tokens 的 type: "enabled"，但它已被弃用，将在未来版本中移除。

budget_tokens 参数决定了 Claude 在其内部推理过程中允许使用的最大 token 数量。在 Claude 4 及更高版本的模型中，此限制适用于完整的思考 token，而不是摘要输出。更大的预算可以通过对复杂问题进行更彻底的分析来提高响应质量，尽管 Claude 可能不会使用分配的全部预算，特别是在超过 32k 的范围内。

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

摘要思考

With extended thinking enabled, the Messages API for Claude 4 models returns a summary of Claude's full thinking process. Summarized thinking provides the full intelligence benefits of extended thinking, while preventing misuse.

Here are some important considerations for summarized thinking:

• You're charged for the full thinking tokens generated by the original request, not the summary tokens.
• The billed output token count will not match the count of tokens you see in the response.
• The first few lines of thinking output are more verbose, providing detailed reasoning that's particularly helpful for prompt engineering purposes.
• As Anthropic seeks to improve the extended thinking feature, summarization behavior is subject to change.
• Summarization preserves the key ideas of Claude's thinking process with minimal added latency, enabling a streamable user experience and easy migration from Claude Sonnet 3.7 to Claude 4 and later models.
• Summarization is processed by a different model than the one you target in your requests. The thinking model does not see the summarized output.

流式思考

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

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

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

以下是如何处理带有思考的流式传输：

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-sonnet-4-5",
    "max_tokens": 16000,
    "stream": true,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?"
        }
    ]
}'

流式输出示例：

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-sonnet-4-5", "stop_reason": null, "stop_sequence": null}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n462 = 3 × 147 + 21\n147 = 7 × 21 + 0\n\nSo GCD(1071, 462) = 21"}}

// Additional thinking deltas...

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "The greatest common divisor of 1071 and 462 is **21**."}}

// Additional text deltas...

event: content_block_stop
data: {"type": "content_block_stop", "index": 1}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}

event: message_stop
data: {"type": "message_stop"}

扩展思考与工具使用

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

在将扩展思考与工具使用结合时，请注意以下限制：

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

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

在对话中切换思考模式

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

• 如果思考已启用，最后的助手回合应以思考块开始。
• 如果思考已禁用，最后的助手回合不应包含任何思考块。

从模型的角度来看，工具使用循环是助手回合的一部分。助手回合在 Claude 完成其完整响应之前不会结束，这可能包括多次工具调用和结果。

例如，以下序列都是单个助手回合的一部分：

User: "What's the weather in Paris?"
Assistant: [thinking] + [tool_use: get_weather]
User: [tool_result: "20°C, sunny"]
Assistant: [text: "The weather in Paris is 20°C and sunny"]

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

思考优雅降级

当发生回合中途思考冲突时（例如在工具使用循环期间开启或关闭思考），API 会自动为该请求禁用思考。为了保持模型质量并保持在分布范围内，API 可能会：

• 当思考块会创建无效的回合结构时，从对话中剥离思考块
• 当对话历史与启用思考不兼容时，为当前请求禁用思考

这意味着尝试在回合中途切换思考不会导致错误，但思考将在该请求中被静默禁用。要确认思考是否处于活动状态，请检查响应中是否存在 thinking 块。

实践指导

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

示例：在完成回合后切换思考

User: "What's the weather?"
Assistant: [tool_use] (thinking disabled)
User: [tool_result]
Assistant: [text: "It's sunny"]
User: "What about tomorrow?"
Assistant: [thinking] + [text: "..."] (thinking enabled - new turn)

通过在切换思考之前完成助手回合，您可以确保思考在新请求中确实被启用。

保留思考块

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

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

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

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

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

交错思考

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

通过交错思考，Claude 可以：

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

对于 Claude Opus 4.6，使用自适应思考时会自动启用交错思考 — 无需 beta 头。

对于 Claude 4 模型，在 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.6、Claude Opus 4.5、Claude Opus 4.1、Opus 4 或 Sonnet 4 以外的任何模型，您的请求将失败。

扩展思考与提示缓存

提示缓存与思考结合使用有几个重要注意事项：

思考块上下文移除

• 先前回合的思考块会从上下文中移除，这可能会影响缓存断点
• 在使用工具继续对话时，思考块会被缓存，并在从缓存读取时计为输入 token
• 这产生了一个权衡：虽然思考块在视觉上不占用上下文窗口空间，但在缓存时它们仍然计入您的输入 token 使用量
• 如果思考被禁用且您在当前工具使用回合中传递了思考内容，思考内容将被剥离，思考将在该请求中保持禁用状态

缓存失效模式

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

理解思维块缓存行为

在将扩展思维与工具使用结合时，思维块表现出特定的缓存行为，会影响 token 计数：

工作原理：

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

详细示例流程：

请求 1：

User: "What's the weather in Paris?"

响应 1：

[thinking_block_1] + [tool_use block 1]

请求 2：

User: ["What's the weather in Paris?"], 
Assistant: [thinking_block_1] + [tool_use block 1], 
User: [tool_result_1, cache=True]

响应 2：

[thinking_block_2] + [text block 2]

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

请求 3：

User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]

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

User: ["What's the weather in Paris?"],
Assistant: [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [text block 2],
User: [Text response, cache=True]

关键要点：

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

扩展思维中的最大 token 数和上下文窗口大小

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

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

扩展思维中的上下文窗口

在启用思维的情况下计算上下文窗口使用量时，需要注意以下几点：

• 之前轮次的思维块会被剥离，不计入您的上下文窗口
• 当前轮次的思维计入该轮次的 max_tokens 限制

下图演示了启用扩展思维时的专门 token 管理：

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

context window =
  (current input tokens - previous thinking tokens) +
  (thinking tokens + encrypted thinking tokens + text output tokens)

我们建议使用 token 计数 API 来获取特定用例的准确 token 计数，尤其是在处理包含思维的多轮对话时。

扩展思维与工具使用中的上下文窗口

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

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

context window =
  (current input tokens + previous thinking tokens + tool use tokens) +
  (thinking tokens + encrypted thinking tokens + text output tokens)

下图说明了扩展思维与工具使用的 token 管理：

管理扩展思维中的 token

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

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

此更改旨在提供更可预测和透明的行为，尤其是在最大 token 限制已显著增加的情况下。

思维加密

Full thinking content is encrypted and returned in the signature field. This field is used to verify that thinking blocks were generated by Claude when passed back to the API.

Here are some important considerations on thinking encryption:

• When streaming responses, the signature is added via a signature_delta inside a content_block_delta event just before the content_block_stop event.
• signature values are significantly longer in Claude 4 models than in previous models.
• The signature field is an opaque field and should not be interpreted or parsed - it exists solely for verification purposes.
• signature values are compatible across platforms (Claude APIs, Amazon Bedrock, and Vertex AI). Values generated on one platform will be compatible with another.

思维编辑

Occasionally Claude's internal reasoning will be flagged by our safety systems. When this occurs, we encrypt some or all of the thinking block and return it to you as a redacted_thinking block. redacted_thinking blocks are decrypted when passed back to the API, allowing Claude to continue its response without losing context.

When building customer-facing applications that use extended thinking:

• Be aware that redacted thinking blocks contain encrypted content that isn't human-readable
• Consider providing a simple explanation like: "Some of Claude's internal reasoning has been automatically encrypted for safety reasons. This doesn't affect the quality of responses."
• If showing thinking blocks to users, you can filter out redacted blocks while preserving normal thinking blocks
• Be transparent that using extended thinking features may occasionally result in some reasoning being encrypted
• Implement appropriate error handling to gracefully manage redacted thinking without breaking your UI

Here's an example showing both normal and redacted thinking blocks:

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me analyze this step by step...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "redacted_thinking",
      "data": "EmwKAhgBEgy3va3pzix/LafPsn4aDFIT2Xlxh0L5L8rLVyIwxtE3rAFBa8cr3qpPkNRj2YfWXGmKDxH4mPnZ5sQ7vB9URj2pLmN3kF8/dW5hR7xJ0aP1oLs9yTcMnKVf2wRpEGjH9XZaBt4UvDcPrQ..."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

When passing thinking and redacted_thinking blocks back to the API in a multi-turn conversation, you must include the complete unmodified block back to the API for the last assistant turn. This is critical for maintaining the model's reasoning flow. We suggest always passing back all thinking blocks to the API. For more details, see the Preserving thinking blocks section.

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

Messages API 在 Claude Sonnet 3.7 和 Claude 4 模型之间对思维的处理方式不同，主要体现在编辑和摘要行为上。

请参阅下表进行简要比较：

Claude Opus 4.5 及更高版本中的思维块保留

从 Claude Opus 4.5 开始（并延续到 Claude Opus 4.6），默认情况下，之前助手轮次的思维块会保留在模型上下文中。这与较早的模型不同，较早的模型会从先前轮次中移除思维块。

思维块保留的优势：

• 缓存优化：使用工具时，保留的思维块能够实现缓存命中，因为它们会与工具结果一起传回，并在助手轮次中增量缓存，从而在多步骤工作流中节省 token
• 不影响智能：保留思维块不会对模型性能产生负面影响

重要注意事项：

• 上下文使用：长对话将消耗更多上下文空间，因为思维块保留在上下文中
• 自动行为：这是 Claude Opus 4.5 及更高版本模型（包括 Opus 4.6）的默认行为——无需代码更改或 beta 头
• 向后兼容：要利用此功能，请继续像工具使用时一样将完整、未修改的思维块传回 API

定价

For complete pricing information including base rates, cache writes, cache hits, and output tokens, see the pricing page.

The thinking process incurs charges for:

• Tokens used during thinking (output tokens)
• Thinking blocks from the last assistant turn included in subsequent requests (input tokens)
• Standard text output tokens

When using summarized thinking:

• Input tokens: Tokens in your original request (excludes thinking tokens from previous turns)
• Output tokens (billed): The original thinking tokens that Claude generated internally
• Output tokens (visible): The summarized thinking tokens you see in the response
• No charge: Tokens used to generate the summary

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

使用思维预算

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

性能注意事项

• 响应时间： 由于推理过程需要额外处理，请准备好可能更长的响应时间。考虑到生成思维块可能会增加整体响应时间。
• 流式传输要求： 当 max_tokens 大于 21,333 时，SDK 要求使用流式传输以避免长时间运行请求的 HTTP 超时。这是客户端验证，而非 API 限制。如果您不需要增量处理事件，请使用 .stream() 配合 .get_final_message()（Python）或 .finalMessage()（TypeScript）来获取完整的 Message 对象，而无需处理单个事件——详见流式消息。使用流式传输时，请准备好在事件到达时处理思维和文本内容块。

功能兼容性

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

使用指南

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

后续步骤