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

支持的模型

扩展思考在以下模型中受支持:

  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)

API行为在Claude 3.7和Claude 4模型之间有所不同,但API结构保持完全相同。

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

扩展思考的工作原理

当启用扩展思考时,Claude会创建thinking内容块,在其中输出其内部推理过程。Claude在制定最终回应之前,会整合这些推理中的见解。

API响应将包含thinking内容块,随后是text内容块。

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

{
  "content": [
    {
      "type": "thinking",
      "thinking": "让我逐步分析一下...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "text",
      "text": "基于我的分析..."
    }
  ]
}

有关扩展思考响应格式的更多信息,请参阅消息API参考

如何使用扩展思考

以下是在消息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-20250514",
    "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对象,将thinking参数设置为enabled,并将budget_tokens设置为指定的扩展思考令牌预算。

budget_tokens参数确定了Claude在内部推理过程中允许使用的最大令牌数量。在Claude 4模型中,此限制适用于完整思考令牌,而不是摘要输出。更大的预算可以通过为复杂问题启用更全面的分析来提高响应质量,尽管Claude可能不会使用分配的整个预算,特别是在超过32k的范围内。

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

摘要思考

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

以下是摘要思考的一些重要考虑因素:

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

Claude Sonnet 3.7继续返回完整的思考输出。

在极少数情况下,如果您需要访问Claude 4模型的完整思考输出,请联系我们的销售团队

流式传输思考

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

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

有关通过消息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-20250514",
    "max_tokens": 16000,
    "stream": true,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {
            "role": "user",
            "content": "What is 27 * 453?"
        }
    ]
}'

流式传输输出示例:

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-sonnet-4-20250514", "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": "Let me solve this step by step:\n\n1. First break down 27 * 453"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n2. 453 = 400 + 50 + 3"}}

// 额外的思考增量...

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": "27 * 453 = 12,231"}}

// 额外的文本增量...

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: any(不支持specificauto或其他值)。

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

保留思考块

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

虽然您可以省略先前assistant角色回合中的thinking块,但我们建议始终将所有思考块传回API,用于任何多轮对话。API将:

  • 自动过滤提供的思考块
  • 使用保留模型推理所需的相关思考块
  • 只对显示给Claude的块的输入令牌计费

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

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

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

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

交错思考

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

通过交错思考,Claude可以:

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

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

交错思考仅支持通过消息API使用的工具

使用交错思考时,budget_tokens可以超过max_tokens参数,因为它代表一个助手回合内所有思考块的总预算。

扩展思考与提示缓存

提示缓存与思考一起使用有几个重要的考虑因素:

思考块上下文移除

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

缓存失效模式

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

虽然思考块会被移除以进行缓存和上下文计算,但在继续使用工具使用的对话时,必须保留它们,特别是使用交错思考时。

理解思考块缓存行为

在使用带有工具使用的扩展思考时,思考块表现出特定的缓存行为,这会影响令牌计数:

工作原理:

  1. 缓存仅在您发出包含工具结果的后续请求时发生
  2. 当发出后续请求时,先前的对话历史(包括思考块)可以被缓存
  3. 这些缓存的思考块在从缓存读取时计入您的使用指标中的输入令牌
  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]

因为包含了非工具结果用户块,所有先前的思考块都会被忽略。此请求将以与以下相同的方式处理:

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

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

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

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

您可以阅读我们的上下文窗口指南,获取更全面的深入了解。

扩展思考的上下文窗口

在计算启用思考的上下文窗口使用情况时,有一些需要注意的考虑因素:

  • 先前回合的思考块会被剥离,不计入您的上下文窗口
  • 当前回合的思考计入该回合的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)

下图说明了带有工具使用的扩展思考的令牌管理:

管理扩展思考的令牌

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

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

这一变化旨在提供更可预测和透明的行为,特别是随着最大令牌限制的显著增加。

思考加密

完整的思考内容会被加密并在signature字段中返回。该字段用于在传回API时验证思考块是由Claude生成的。当流式传输响应时,签名通过content_block_stop事件之前的content_block_delta事件中的signature_delta添加。

请注意,签名字段将比以前的模型明显更长。这是一个不透明的字段,不应该被解释或解析 - 它仅用于验证目的。

只有在使用带有扩展思考的工具时,才有必要发送回思考块。否则,您可以省略先前回合的思考块,或者如果您将它们传回,让API为您剥离它们。

如果发送回思考块,我们建议按照您收到的方式传回所有内容,以保持一致性并避免潜在问题。

思考编辑

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

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

  • 请注意,编辑后的思考块包含不可人类阅读的加密内容
  • 考虑提供简单的解释,如:“Claude的一些内部推理已出于安全原因自动加密。这不会影响响应的质量。”
  • 如果向用户显示思考块,您可以过滤掉编辑后的块,同时保留正常的思考块
  • 透明地表明使用扩展思考功能可能偶尔会导致一些推理被加密
  • 实现适当的错误处理,以优雅地管理编辑后的思考,而不破坏您的UI

以下是显示正常和编辑后思考块的示例:

{
  "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..."
    }
  ]
}

在您的输出中看到编辑后的思考块是预期的行为。模型仍然可以使用这种编辑后的推理来为其响应提供信息,同时维护安全护栏。

如果您需要在应用程序中测试编辑后的思考处理,可以使用这个特殊的测试字符串作为您的提示:ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB

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

不同模型版本间的思考差异

消息API在Claude Sonnet 3.7和Claude 4模型之间对思考的处理方式不同,主要在编辑和摘要行为方面。

请参阅下表获取简明比较:

功能Claude Sonnet 3.7Claude 4模型
思考输出返回完整思考输出返回摘要思考
交错思考不支持使用interleaved-thinking-2025-05-14 beta标头支持

定价

扩展思考使用标准令牌定价方案:

模型基本输入令牌缓存写入缓存命中输出令牌
Claude Opus 4$15 / MTok$18.75 / MTok$1.50 / MTok$75 / MTok
Claude Sonnet 4$3 / MTok$3.75 / MTok$0.30 / MTok$15 / MTok
Claude Sonnet 3.7$3 / MTok$3.75 / MTok$0.30 / MTok$15 / MTok

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

  • 思考期间使用的令牌(输出令牌)
  • 后续请求中包含的最后一个助手回合的思考块(输入令牌)
  • 标准文本输出令牌

启用扩展思考时,会自动包含一个专门的系统提示来支持此功能。

使用摘要思考时:

  • 输入令牌:原始请求中的令牌(不包括先前回合的思考令牌)
  • 输出令牌(计费):Claude内部生成的原始思考令牌
  • 输出令牌(可见):您在响应中看到的摘要思考令牌
  • 不收费:用于生成摘要的令牌

计费的输出令牌数量将不会与响应中可见的令牌数量匹配。您需要为完整的思考过程付费,而不是您看到的摘要。

扩展思考的最佳实践和考虑因素

使用思考预算

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

性能考虑

  • 响应时间: 由于推理过程需要额外的处理,请准备好可能较长的响应时间。考虑到生成思考块可能会增加整体响应时间。
  • 流式传输要求:max_tokens大于21,333时,需要流式传输。在流式传输时,请准备好处理思考和文本内容块的到达。

功能兼容性

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

使用指南

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

下一步