使用扩展思维进行构建

扩展思维让 Claude 3.7 Sonnet 在处理复杂任务时具有增强的推理能力,同时在提供最终答案之前,还能透明地展示其逐步思考过程。

扩展思维的工作原理

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

API 响应将包含 thinking 和 text 内容块。

在多轮对话中,只有与工具使用会话或最后一条消息位置的 assistant 轮次相关的思维块对 Claude 可见,并作为输入令牌计费;与早期 assistant 消息相关的思维块对 Claude 在采样时不可见,也不会作为输入令牌计费。

实现扩展思维

在 API 请求中添加 thinking 参数和指定用于扩展思维的令牌预算。

budget_tokens 参数决定了允许 Claude 用于内部推理过程的最大令牌数。更大的预算可以通过为复杂问题启用更全面的分析来提高响应质量,尽管在超过 32K 的范围内,Claude 可能不会使用全部分配的预算。

您的 budget_tokens 必须始终小于指定的 max_tokens。

bash

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-3-7-sonnet-20250219",
"max_tokens": 20000,
"thinking": {
"type": "enabled",
"budget_tokens": 16000
},
"messages": [
{
"role": "user",
"content": "Are there an infinite number of prime numbers such that n mod 4 == 3?"
}
]
}'

理解思维块

思维块代表了 Claude 的内部思考过程。为了让 Claude 能够以最小的内部限制来处理问题,同时保持我们的安全标准和无状态 API,我们实现了以下功能:

思维块包含一个 signature 字段。该字段包含一个加密令牌,用于验证思维块是由 Claude 生成的,并在思维块传回 API 时进行验证。在流式响应时,签名通过 content_block_delta 事件中的 signature_delta 添加,就在 content_block_stop 事件之前。只有在使用工具和扩展思维时,才需要严格地将思维块传回。否则,您可以省略之前轮次的思维块,或者让 API 为您删除它们。
有时 Claude 的内部推理会被我们的安全系统标记。当这种情况发生时,我们会加密部分或全部 thinking 块,并将其作为 redacted_thinking 块返回给您。这些被编辑的思维块在传回 API 时会被解密,允许 Claude 在不丢失上下文的情况下继续其响应。
thinking 和 redacted_thinking 块在响应中会在 text 块之前返回。

以下是一个同时显示正常和被编辑的思维块的示例:

json

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

TIP

在输出中看到被编辑的思维块是预期的行为。模型仍然可以使用这种被编辑的推理来为其响应提供信息,同时保持安全护栏。如果您需要在应用程序中测试被编辑思维的处理,可以使用这个特殊的测试字符串作为您的提示: ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB

当在多轮对话中将 thinking 和 redacted_thinking 块传回 API 时,您必须将最后一个助手轮次的完整未修改块传回 API。

这对于维持模型的推理流程至关重要。我们建议始终将所有思维块传回 API。有关更多详细信息,请参阅保留思维块部分。

在生产环境中处理被编辑思维的建议

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

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

流式传输扩展思维

当启用流式传输时,您将通过 thinking_delta 事件接收思维内容

示例流式输出:

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-3-7-sonnet-20250219", "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: message_stop
data: {"type": "message_stop"}

[TIP] 关于带思维的流式传输行为当使用带有思维功能的流式传输时,您可能会注意到文本有时会以较大的块交替出现,有时则是逐个令牌传递。这是预期的行为,尤其是对于思维内容。流式传输系统需要批量处理内容以获得最佳性能,这可能会导致这种”块状”传递模式。我们正在不断努力改善这种体验,未来的更新将着重于使思维内容流式传输更加流畅。 redacted_thinking 块不会有任何增量关联,将作为单个事件发送。

使用扩展思维时的重要考虑因素

使用思维预算: 最小预算是 1,024 个令牌。我们建议从最小值开始,逐步增加思维预算,以找到 Claude 在您的用例中表现良好的最佳范围。更高的令牌数可能允许您获得更全面和细致的推理,但根据任务的不同,可能也会有收益递减的情况。

思维预算是一个目标而不是严格的限制 - 实际令牌使用量可能会根据任务而变化。
由于推理过程需要额外的处理,要准备可能会有较长的响应时间。
当 max_tokens 大于 21,333 时,需要流式传输。

对于超过 32K 的思维预算: 我们建议对思维预算设置在 32K 以上的工作负载使用批处理,以避免网络问题。要求模型在 32K 令牌以上进行思考的请求会导致长时间运行的请求,可能会遇到系统超时和开放连接限制。

思维与其他功能的兼容性:

思维与 temperature、top_p 或 top_k 修改以及强制工具使用不兼容。
启用思维时不能预填响应。
对思维预算的更改会使包含消息的缓存提示前缀失效。但是,当思维参数改变时,缓存的系统提示和工具定义将继续工作。

扩展思维的定价和令牌使用

扩展思维令牌计入上下文窗口,并作为输出令牌计费。由于思维令牌被视为普通输出令牌,它们也计入您的速率限制。在规划 API 使用时,请务必考虑这种增加的令牌使用量。

对于 Claude 3.7 Sonnet,定价如下:

令牌使用	成本
输入令牌	$3 / MTok
输出令牌(包括思维令牌)	$15 / MTok
提示缓存写入	$3.75 / MTok
提示缓存读取	$0.30 / MTok

扩展思维的批处理价格为这些价格的 50%,通常在不到 1 小时内完成。

所有扩展思维令牌(包括被编辑的思维令牌)都作为输出令牌计费,并计入您的速率限制。在多轮对话中,与早期助手消息相关的思维块不会作为输入令牌计费。当启用扩展思维时,会自动包含一个专门的 28 或 29 个令牌的系统提示来支持此功能。

扩展输出功能(测试版)

Claude 3.7 Sonnet 可以产生比以前的模型长得多的响应,支持高达 128K 输出令牌(测试版)—比其他 Claude 模型长 15 倍以上。这种扩展的能力对于涉及复杂推理、丰富代码生成和全面内容创建的扩展思维用例特别有效。

通过传递 anthropic-beta 头部值 output-128k-2025-02-19 可以启用此功能。

在使用较长输出的扩展思维时,您可以分配更大的思维预算来支持更全面的推理,同时仍然有足够的令牌用于最终响应。

我们建议对这种扩展输出功能使用流式传输或批处理模式;有关更多详细信息,请参阅我们关于长请求的网络可靠性考虑指南。

将扩展思维与提示缓存一起使用

带思维的提示缓存有几个重要的考虑因素:

缓存提示中的思维块包含

思维仅在生成助手轮次时包含,不打算被缓存。
忽略前几轮的思维块。
如果思维被禁用,传递给 API 的任何思维内容都会被简单地忽略。

缓存失效规则

对思维参数的更改(启用/禁用或预算更改)会使消息中设置的缓存断点失效。
系统提示和工具在思维参数更改时保持缓存。

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

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

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

### 如何计算带扩展思维的上下文窗口

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

前几轮的思维块会被删除,不计入您的上下文窗口
当前轮次的思维计入该轮次的 max_tokens 限制

有效的上下文窗口计算如下:

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

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

管理带扩展思维的令牌

鉴于带扩展思维的模型(如 Claude 3.7 Sonnet)的新上下文窗口和 max_tokens 行为,您可能需要:

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

这种改变是为了提供更可预测和透明的行为,特别是在最大令牌限制显著增加的情况下。

带工具使用的扩展思维

在将扩展思维与工具使用结合时,请注意以下行为模式:

第一个助手轮次: 当您发送初始用户消息时,助手响应将包含思维块,然后是工具使用请求。
工具结果轮次: 当您传递带有工具结果块的用户消息时,后续的助手消息将不包含任何额外的思维块。

在这里展开,带思维的工具使用对话的正常顺序遵循以下步骤:

用户发送初始消息
助手响应包含思维块和工具请求
用户发送带有工具结果的消息
助手响应要么包含更多工具调用,要么只包含文本(此响应中没有思维块)
如果请求更多工具,重复步骤 3-4,直到对话完成

这种设计允许 Claude 在发出工具请求之前显示其推理过程,但在收到工具结果后不重复思维过程。Claude 在下一个非 tool_result 的 user 轮次之前不会输出另一个思维块。

保留思维块

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

TIP

虽然您可以省略来自先前 assistant 角色轮次的 thinking 和 redacted_thinking 块,但我们建议在任何多轮对话中始终将所有思维块传回 API。API 将:

自动过滤提供的思维块
使用必要的思维块来保持模型的推理
只对显示给 Claude 的块的输入令牌计费

为什么必须保留思维块

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

推理连续性: 思维块捕获了导致工具请求的 Claude 逐步推理。当您发布工具结果时,包含原始思维确保 Claude 可以从它停止的地方继续推理。
上下文维护: 虽然工具结果在 API 结构中显示为用户消息,但它们是连续推理流程的一部分。保留思维块在多个 API 调用中维护这种概念流程。

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

充分利用扩展思维模式的提示

要充分利用扩展思维:

设置适当的预算: 对于复杂任务,从较大的思维预算(16,000+ 令牌)开始,并根据您的需求进行调整。
实验思维令牌预算: 模型在不同的最大思维预算设置下可能表现不同。增加最大思维预算可以使模型思考得更好/更努力,但会增加延迟。对于关键任务,考虑测试不同的预算设置,以找到质量和性能之间的最佳平衡。
您不需要自己删除前几轮的思维块: Anthropic API 会自动忽略前几轮的思维块,它们在计算上下文使用量时不会被包含。
监控令牌使用: 跟踪思维令牌使用情况以优化成本和性能。
将扩展思维用于特别复杂的任务: 为需要逐步推理的任务启用思维,如数学、编码和分析。
考虑延长响应时间: 考虑到生成思维块可能会增加整体响应时间。
适当处理流式传输: 在流式传输时,要准备好处理思维和文本内容块的到来。
提示工程: 如果您想最大化 Claude 的思维能力,请查看我们的扩展思维提示技巧。

使用扩展思维进行构建 ​

扩展思维的工作原理 ​

实现扩展思维 ​

理解思维块 ​

在生产环境中处理被编辑思维的建议 ​

流式传输扩展思维 ​

使用扩展思维时的重要考虑因素 ​

扩展思维的定价和令牌使用 ​

扩展输出功能(测试版) ​

将扩展思维与提示缓存一起使用 ​

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

管理带扩展思维的令牌 ​

带工具使用的扩展思维 ​

保留思维块 ​

为什么必须保留思维块 ​

充分利用扩展思维模式的提示 ​