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

扩展思维的工作原理

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

API 响应将包含 thinkingtext 内容块。

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

实现扩展思维

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

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

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

API 响应将包含思维和文本内容块:

{
    "content": [
        {
            "type": "thinking",
            "thinking": "To approach this, let's think about what we know about prime numbers...",
            "signature": "zbbJhbGciOiJFU8zI1NiIsImtakcjsu38219c0.eyJoYXNoIjoiYWJjMTIzIiwiaWFxxxjoxNjE0NTM0NTY3fQ...."
        },
        {
            "type": "text",
            "text": "Yes, there are infinitely many prime numbers such that..."
        }
    ]
}

理解思维块

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

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

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

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

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

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

在多轮对话中将 thinkingredacted_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: 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"}

关于带思维的流式传输行为

当使用带有思维功能的流式传输时,您可能会注意到文本有时会以较大的块交替出现,有时则是逐个令牌传递。这是预期的行为,特别是对于思维内容。

流式系统需要批量处理内容以获得最佳性能,这可能会导致这种”块状”传递模式。我们正在不断努力改善这种体验,未来的更新将着重于使思维内容流式传输更加流畅。

redacted_thinking 块不会有任何增量相关联,将作为单个事件发送。

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

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

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

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

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

  • 思维与 temperaturetop_ptop_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 限制

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

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

上下文窗口 =
  (当前输入令牌 - 之前的思维令牌) +
  (思维令牌 + 被编辑的思维令牌 + 文本输出令牌)

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

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

管理带扩展思维的令牌

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

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

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

带工具使用的扩展思维

在使用带工具使用的扩展思维时,请注意以下行为模式:

  1. 第一个助手轮次:当您发送初始用户消息时,助手响应将包含思维块,然后是工具使用请求。

  2. 工具结果轮次:当您传递带有工具结果块的用户消息时,后续的助手消息将不包含任何额外的思维块。

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

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

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

下图说明了在结合扩展思维和工具使用时的上下文窗口令牌管理:

保留思维块

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

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

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

为什么必须保留思维块

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

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

  2. 上下文维护:虽然工具结果在 API 结构中显示为用户消息,但它们是连续推理流程的一部分。保留思维块在多个 API 调用中维护这种概念流程。

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

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

要充分利用扩展思维:

  1. 设置适当的预算:对于复杂任务,从较大的思维预算(16,000+ 令牌)开始,并根据您的需求进行调整。

  2. 实验思维令牌预算:模型在不同的最大思维预算设置下可能表现不同。增加最大思维预算可以使模型思考得更好/更努力,但会增加延迟。对于关键任务,考虑测试不同的预算设置,以找到质量和性能之间的最佳平衡。

  3. 您不需要自己移除之前的思维块:Anthropic API 会自动忽略之前轮次的思维块,它们在计算上下文使用时不会被包含。

  4. 监控令牌使用:跟踪思维令牌使用情况以优化成本和性能。

  5. 将扩展思维用于特别复杂的任务:为受益于逐步推理的任务启用思维,如数学、编码和分析。

  6. 考虑延长响应时间:考虑到生成思维块可能会增加整体响应时间。

  7. 适当处理流式传输:在流式传输时,准备好处理思维和文本内容块的到来。

  8. 提示工程:如果您想最大化 Claude 的思维能力,请查看我们的扩展思维提示技巧

下一步