扩展思考

"Extended thinking"（扩展思考）为 Claude 提供了处理复杂任务的增强推理能力，同时在给出最终答案之前，以不同程度的透明度展示其逐步思考过程。



支持的模型

所有当前的 Claude 模型均支持扩展思考。启用方式取决于具体模型：

使用自适应思考时，模型会在每次请求中自行决定是否思考以及思考的程度。在 Claude Mythos Preview、Claude Fable 5 和 Claude Mythos 5 上，不支持 thinking: {type: "disabled"}。有关各模型的行为差异（思考输出、交错思考和块保留），请参阅不同模型版本的思考差异。



扩展思考的工作原理

当扩展思考开启时，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 中使用扩展思考的示例：

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:
    if block.type == "thinking":
        print(f"\nThinking summary: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

要开启扩展思考，请添加一个 thinking 对象，将 type 设置为 enabled 并指定 budget_tokens 值。在手动扩展思考已弃用或不受支持的模型上（参见支持的模型），请改用 type: "adaptive"，如自适应思考中所述。

budget_tokens 参数设置 Claude 可用于其内部推理过程的最大令牌数。此限制适用于完整的思考令牌，而非摘要输出。更大的预算可以通过对复杂问题进行更深入的分析来提高响应质量，但 Claude 可能不会用完分配的全部预算，尤其是在超过 32k 的范围内。

budget_tokens 必须设置为小于 max_tokens 的值。但是，当使用工具的交错思考时，您可以超过此限制，因为令牌限制变为您的整个上下文窗口。由于 budget_tokens 必须小于 max_tokens，扩展思考不能与 max_tokens: 0（缓存预热）结合使用。



控制思考显示

思考配置中的 display 字段用于控制 API 响应中思考内容的返回方式。它接受两个值：

• "summarized"：思考块包含摘要化的思考文本。详情请参阅摘要化思考。这是 Claude Opus 4.6、Claude Sonnet 4.6 以及更早的 Claude 4 模型的默认值。
• "omitted"：返回的思考块中 thinking 字段为空。signature 字段仍然携带加密的完整思考内容，以支持多轮对话的连续性（请参阅思考加密）。这是 Claude Fable 5、Claude Mythos 5、Claude Opus 4.8、Claude Opus 4.7 以及 Claude Mythos Preview 的默认值。

当您的应用程序不向用户展示思考内容时，设置 display: "omitted" 会非常有用。其主要优势在于**流式传输时更快获得首个文本令牌：**服务器会完全跳过思考令牌的流式传输，仅传递签名，因此最终的文本响应能够更早开始流式传输。

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

• 您仍需为完整的思考令牌付费。省略思考可降低延迟，但不会降低成本。
• 如果您在多轮对话中回传思考块，请原样传递。服务器会解密 signature 以重建原始思考内容，用于构建提示（请参阅保留思考块）。您在回传的省略块的 thinking 字段中放置的任何文本都将被忽略。
• 当 thinking.type: "disabled" 时，display 无效（因为没有内容可显示）。
• 当使用 thinking.type: "adaptive" 且模型针对简单请求跳过思考时，无论 display 设置为何值，都不会生成思考块。

从不向最终用户展示思考内容的自动化管道可以省去通过网络接收思考令牌的开销。对延迟敏感的应用程序可以获得相同的推理质量，而无需在最终响应开始之前等待思考文本的流式传输。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000,
        "display": "omitted",
    },
    messages=[
        {"role": "user", "content": "What is 27 * 453?"},
    ],
)

for block in response.content:
    if block.type == "thinking":
        if block.thinking:
            print(f"Thinking: {block.thinking}")
        else:
            print("Thinking: [omitted]")
    elif block.type == "text":
        print(f"Response: {block.text}")

当设置 display: "omitted" 时，响应包含 thinking 字段为空的 thinking 块：

{
  "content": [
    {
      "type": "thinking",
      "thinking": "",
      "signature": "EosnCkYICxIMMb3LzNrMu..."
    },
    {
      "type": "text",
      "text": "The answer is 12,231."
    }
  ]
}

当使用 display: "omitted" 进行流式传输时，不会发出 thinking_delta 事件；有关事件序列，请参阅流式传输思考。



摘要思考

启用扩展思考后，Claude 4 模型的 Messages API 会返回 Claude 完整思考过程的摘要。摘要式思考在提供扩展思考全部智能优势的同时，可防止滥用。当思考配置中的 display 字段未设置或设置为 "summarized" 时，这是 Claude 4 模型的默认行为。在 Claude Fable 5、Claude Mythos 5、Claude Opus 4.8、Claude Opus 4.7 和 Claude Mythos Preview 上，display 默认为 "omitted"，因此您必须显式设置 display: "summarized" 才能接收摘要式思考。

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

• 您需要为原始请求生成的完整思考令牌付费，而非摘要令牌。
• 计费的输出令牌数量将不会匹配您在响应中看到的令牌数量。
• 在 Claude 4 模型上，思考输出的前几行更为详尽，提供了详细的推理过程，这对提示工程尤其有帮助。Claude Mythos Preview 从第一个令牌开始就进行摘要，因此其思考块不会显示这种详尽的前导内容。
• 随着 Anthropic 不断改进扩展思考功能，摘要行为可能会发生变化。
• 摘要以最小的额外延迟保留了 Claude 思考过程的关键思路，从而实现可流式传输的用户体验。
• 摘要由与您在请求中指定的模型不同的另一个模型处理。思考模型不会看到摘要后的输出。



流式传输思考

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

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

当设置 display: "omitted" 时，不会发出 thinking_delta 事件。请参阅控制思考显示。

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

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

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
) as stream:
    thinking_started = False
    response_started = False

    for event in stream:
        if event.type == "content_block_start":
            print(f"\nStarting {event.content_block.type} block...")
            # 为每个新块重置标志
            thinking_started = False
            response_started = False
        elif event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                if not thinking_started:
                    print("Thinking: ", end="", flush=True)
                    thinking_started = True
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                if not response_started:
                    print("Response: ", end="", flush=True)
                    response_started = True
                print(event.delta.text, end="", flush=True)
        elif event.type == "content_block_stop":
            print("\nBlock complete.")

流式传输输出示例：

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

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

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"}

当设置 display: "omitted" 时，思考块打开，单个 signature_delta 到达，然后块关闭，不会有任何 thinking_delta 事件。文本流式传输随即开始：

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

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

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":""}}



扩展思考与工具使用

扩展思考可以与工具使用一起使用，使 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 模型中带有工具使用的扩展思考支持"interleaved thinking"（交错思考），这使 Claude 能够在工具调用之间进行思考，并在收到工具结果后进行更复杂的推理。

通过交错思考，Claude 可以：

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

启用交错思考的方式取决于模型：

此处的"更早的 Claude 4 模型"指 Claude Sonnet 4.5、Claude Opus 4.1（已弃用）、Claude Opus 4（已停用，Vertex AI 除外）和 Claude Sonnet 4（已停用，Bedrock 和 Vertex AI 除外）。

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

• 使用交错思考时，budget_tokens 可以超过 max_tokens 参数，因为它代表一个助手回合内所有思考块的总预算。
• 交错思考仅支持通过 Messages API 使用的工具。
• Claude API 和 AWS 上的 Claude Platform 在对任何模型的请求中接受 interleaved-thinking-2025-05-14 而不返回错误。在不支持交错思考的模型上，该标头会被忽略。在 Claude Opus 4.8、Claude Opus 4.7 和 Claude Opus 4.6 上，它已弃用并被安全忽略。在 Claude Mythos Preview 上，不需要该标头且会被安全忽略。
• 在合作伙伴运营的平台上（例如 Amazon Bedrock 和 Vertex AI），如果您将 interleaved-thinking-2025-05-14 传递给 Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 4.6、Claude Opus 4.5、Claude Opus 4.1（已弃用）、Opus 4（已停用，Vertex AI 除外）、Sonnet 4.5 或 Sonnet 4（已停用，Bedrock 和 Vertex AI 除外）以外的任何模型，您的请求将失败。



扩展思考与提示缓存

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

思考块上下文移除

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

缓存失效模式

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



理解思考块缓存行为

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

工作原理：

1. 只有当您发出包含工具结果的后续请求时才会发生缓存
2. 发出后续请求时，先前的对话历史（包括思考块）可以被缓存
3. 这些缓存的思考块在从缓存读取时会在您的使用指标中计为输入令牌
4. 当包含非工具结果的用户块时：在 Opus 4.5+ 和 Sonnet 4.6+ 上，先前的思考块会被保留；在更早的 Opus/Sonnet 模型和所有 Haiku 模型上，所有先前的思考块都会被忽略并从上下文中剥离

详细示例流程：

请求 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]

对于 Opus 4.5+ 和 Sonnet 4.6+，所有先前的思考块默认被保留。对于更早的 Opus/Sonnet 模型和所有 Haiku 模型，由于包含了非工具结果的用户块，所有先前的思考块都会被忽略并从上下文中剥离。此请求的处理方式与以下相同：

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 标记
• 无论使用常规思考还是交错思考，此行为都是一致的



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

max_tokens（启用思考时包括您的思考预算）作为严格限制强制执行。在 Claude 4.5 及更新的模型上，如果输入令牌加上 max_tokens 超过上下文窗口大小，API 会接受该请求。如果生成随后达到上下文窗口限制，则会以 stop_reason: "model_context_window_exceeded" 停止。在更早的模型上，API 会返回验证错误。请参阅处理停止原因。



扩展思考的上下文窗口

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

• 在 Opus 4.5+ 和 Sonnet 4.6+ 上，先前回合的思考块会被保留并计入您的上下文窗口；在更早的 Opus/Sonnet 模型和所有 Haiku 模型上，它们会被剥离且不计入
• 当前回合的思考计入该回合的 max_tokens 限制

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

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

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

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



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

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

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

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

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



使用扩展思考管理令牌

鉴于扩展思考的上下文窗口和 max_tokens 行为，您可能需要：

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



思考加密

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

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

• 当使用流式传输响应时，签名会通过 content_block_delta 事件内的 signature_delta 添加，该事件紧接在 content_block_stop 事件之前。
• Claude 4 模型中的 signature 值比之前的模型长得多。
• signature 字段是一个不透明字段，不应对其进行解释或解析。
• signature 值在各平台之间兼容（Claude API、Amazon Bedrock 和 Vertex AI）。在一个平台上生成的值可以在另一个平台上兼容使用。



已编辑的思考块

除了常规的 thinking 块之外，API 还可能返回 redacted_thinking 块。redacted_thinking 块在 data 字段中包含加密的思考内容，没有可读的摘要：

{
  "type": "redacted_thinking",
  "data": "..."
}

data 字段是不透明且加密的。与常规思考块上的 signature 字段一样，在使用工具继续多轮对话时，您应将 redacted_thinking 块原样传回 API。



不同模型版本的思考差异

Messages API 在不同 Claude 模型版本中对思考的处理方式不同。下表给出了简要对比：

¹ 设置 display: "summarized" 以接收摘要思考。在 Claude Fable 5、Claude Mythos 5 和 Claude Mythos Preview 上，永远不会返回原始思考令牌。
² 通过自适应思考。这些模型不需要 interleaved-thinking-2025-05-14 beta 标头，如包含则会被安全忽略。
³ 在不支持 Mythos 思考格式的模型上继续对话时，块会被剥离。



按模型划分的思考块保留

先前助手回合的思考块是否默认保留在上下文中取决于模型类别。Opus：Claude Opus 4.5 及更高版本的 Opus 模型保留所有先前的思考块；Claude Opus 4.1（已弃用）及更早的 Opus 模型仅保留最后一个助手回合的思考。Sonnet：Claude Sonnet 4.6 及更高版本的 Sonnet 模型保留全部；Claude Sonnet 4.5 及更早的 Sonnet 模型仅保留最后回合。Haiku：截至 Claude Haiku 4.5 的所有 Haiku 模型仅保留最后回合。Claude Mythos Preview 也保留所有先前的思考块。

思考块保留的好处：

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

重要注意事项：

• 上下文使用：由于思考块保留在上下文中，长对话将消耗更多上下文空间
• 自动行为：这是上述每个模型的默认行为。无需代码更改或 beta 标头
• 向后兼容性：要利用此功能，请像处理工具使用一样，继续将完整且未修改的思考块传回 API



定价

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

思考过程会产生以下费用：

• 思考期间使用的令牌（输出令牌）
• 保留在上下文中的先前助手轮次的思考块：在早期 Opus/Sonnet 模型和所有 Haiku 模型上仅保留最后一轮；在 Opus 4.5+ 和 Sonnet 4.6+ 上默认保留所有轮次（输入令牌）
• 标准文本输出令牌

使用摘要式思考时：

• **输入令牌：**您原始请求中的令牌（不包括先前轮次的思考令牌）
• **输出令牌（计费）：**Claude 内部生成的原始思考令牌
• **输出令牌（可见）：**您在响应中看到的摘要式思考令牌
• **不收费：**用于生成摘要的令牌

使用 display: "omitted" 时：

• **输入令牌：**您原始请求中的令牌（与摘要式相同）
• **输出令牌（计费）：**Claude 内部生成的原始思考令牌（与摘要式相同）
• **输出令牌（可见）：**零思考令牌（thinking 字段为空）

要查看内部推理消耗了多少计费输出令牌，请读取响应中的 usage.output_tokens_details.thinking_tokens。该值反映模型生成的原始推理（而非响应正文中返回的摘要文本），并且始终小于或等于 output_tokens。从 output_tokens 中减去该值即可估算输出中非推理部分的令牌数。

{
  "usage": {
    "input_tokens": 25,
    "output_tokens": 348,
    "output_tokens_details": {
      "thinking_tokens": 312
    }
  }
}

output_tokens 仍然是用于计费的包含性权威总数。output_tokens_details 是用于可观测性的只读明细。



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



使用思考预算

• **预算优化：**最小预算为 1,024 个令牌。从最小值开始，逐步增加思考预算，以找到适合您用例的最佳范围。更高的令牌数量可以实现更全面的推理，但根据任务的不同，收益会逐渐递减。增加预算可以提高响应质量，但代价是增加延迟。对于关键任务，请测试不同的设置以找到最佳平衡点。请注意，思考预算是一个目标值，而非严格限制。实际令牌使用量可能因任务而异。
• **起始点：**对于复杂任务，从较大的思考预算（16k+ 令牌）开始，然后根据您的需求进行调整。
• **大预算：**对于超过 32k 的思考预算，请使用批处理以避免网络问题。促使模型思考超过 32k 令牌的请求会导致长时间运行的请求，可能会遇到系统超时和开放连接限制的问题。
• **令牌使用跟踪：**监控思考令牌的使用情况，以优化成本和性能。响应中的 usage.output_tokens_details.thinking_tokens 字段报告了计费输出令牌中有多少是内部推理令牌。在流式传输时，此细分信息仅出现在最终的 message_delta 事件中。



性能考量

• **响应时间：**由于需要额外的处理，请做好响应时间更长的准备。生成思考块会增加整体响应时间。
• **流式传输要求：**当 max_tokens 大于 21,333 时，SDK 要求使用流式传输，以避免长时间运行的请求出现 HTTP 超时。这是客户端验证，而非 API 限制。如果您不需要增量处理事件，请使用 .stream() 配合 .get_final_message()（Python）或 .finalMessage()（TypeScript）来获取完整的 Message 对象，而无需处理单个事件。详情请参阅流式传输消息。在流式传输时，请做好在思考内容块和文本内容块到达时分别处理它们的准备。
• **省略思考以降低延迟：**如果您的应用程序不显示思考内容，请在思考配置中设置 display: "omitted"，以减少首个文本令牌的生成时间。请参阅控制思考显示。



功能兼容性

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



使用指南

• **任务选择：**对于受益于逐步推理的特别复杂的任务（如数学、编程和分析），请使用扩展思考。
• **上下文处理：**您无需自行删除之前的思考块。在 Opus 4.5+ 和 Sonnet 4.6+ 上，Claude API 默认保留之前轮次的思考块；在更早的 Opus/Sonnet 模型以及所有 Haiku 模型上，API 会自动忽略它们，并且在计算上下文使用量时不会将其包含在内。
• **提示工程：**如果您想最大限度地发挥 Claude 的思考能力，请查阅扩展思考提示技巧。



后续步骤