使用扩展思维进行构建
扩展思维使 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
。
API 响应将包含思维和文本内容块:
理解思维块
思维块代表了 Claude 的内部思考过程。为了让 Claude 能够在保持我们的安全标准和无状态 API 的同时以最小的内部限制解决问题,我们实现了以下功能:
- 思维块包含一个
signature
字段。该字段包含一个加密令牌,用于验证思维块是由 Claude 生成的,并在思维块传回 API 时进行验证。在流式响应时,签名通过content_block_delta
事件中的signature_delta
添加,就在content_block_stop
事件之前。只有在使用工具和扩展思维时才需要严格传回思维块。否则,您可以省略之前轮次的思维块,或者让 API 在您传回它们时将其剥离。 - 有时 Claude 的内部推理会被我们的安全系统标记。当这种情况发生时,我们会加密部分或全部
thinking
块,并将其作为redacted_thinking
块返回给您。这些被编辑的思维块在传回 API 时会被解密,使 Claude 能够在不失去上下文的情况下继续其响应。
以下是显示正常和被编辑的思维块的示例:
在输出中看到被编辑的思维块是预期的行为。模型仍然可以使用这种被编辑的推理来为其响应提供信息,同时保持安全防护。
如果您需要在应用程序中测试被编辑思维的处理,可以使用这个特殊的测试字符串作为您的提示:ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB
在多轮对话中将 thinking
和 redacted_thinking
块传回 API 时,您必须将最后一个助手轮次的完整未修改块传回 API。
这对于维持模型的推理流程至关重要。我们建议始终将所有思维块传回 API。有关更多详细信息,请参阅保留思维块部分。
在生产环境中处理被编辑思维的建议
在构建使用扩展思维的面向客户的应用程序时:
- 请注意,被编辑的思维块包含不可人工阅读的加密内容
- 考虑提供简单的解释,如:“Claude 的部分内部推理已出于安全原因自动加密。这不会影响响应的质量。”
- 如果向用户显示思维块,您可以过滤掉被编辑的块,同时保留正常的思维块
- 要透明地说明使用扩展思维功能可能偶尔会导致某些推理被加密
- 实现适当的错误处理,以优雅地管理被编辑的思维,而不会破坏您的 UI
流式传输扩展思维
当启用流式传输时,您将通过 thinking_delta
事件接收思维内容。以下是如何处理带有思维的流式传输:
流式输出示例:
关于带思维的流式传输行为
当使用带有思维功能的流式传输时,您可能会注意到文本有时会以较大的块交替出现,有时则是逐个令牌传递。这是预期的行为,特别是对于思维内容。
流式系统需要批量处理内容以获得最佳性能,这可能会导致这种”块状”传递模式。我们正在不断努力改善这种体验,未来的更新将着重于使思维内容流式传输更加流畅。
redacted_thinking
块不会有任何增量相关联,将作为单个事件发送。
使用扩展思维的重要考虑因素
使用思维预算: 最小预算是 1,024 个令牌。我们建议从最小值开始,逐步增加思维预算,以找到适合您的用例的最佳范围。更高的令牌数可能允许您实现更全面和细致的推理,但根据任务的不同,可能也会有收益递减的情况。
- 思维预算是一个目标而不是严格的限制 - 实际令牌使用可能会根据任务而变化。
- 由于推理过程需要额外的处理,要准备可能会有较长的响应时间。
- 当
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
限制
下图演示了启用扩展思维时的专门令牌管理:
有效的上下文窗口计算如下:
我们建议使用令牌计数 API来获取您特定用例的准确令牌计数,特别是在处理包含思维的多轮对话时。
您可以阅读我们的上下文窗口指南以获得更深入的了解。
管理带扩展思维的令牌
鉴于带扩展思维的模型(如 Claude 3.7 Sonnet)的新上下文窗口和 max_tokens
行为,您可能需要:
- 更主动地监控和管理您的令牌使用
- 随着提示长度的变化调整
max_tokens
值 - 可能更频繁地使用令牌计数端点
- 注意之前的思维块不会在您的上下文窗口中累积
这种改变是为了提供更可预测和透明的行为,特别是在最大令牌限制显著增加的情况下。
带工具使用的扩展思维
在使用带工具使用的扩展思维时,请注意以下行为模式:
-
第一个助手轮次:当您发送初始用户消息时,助手响应将包含思维块,然后是工具使用请求。
-
工具结果轮次:当您传递带有工具结果块的用户消息时,后续的助手消息将不包含任何额外的思维块。
在这里展开,带思维的工具使用对话的正常顺序遵循以下步骤:
- 用户发送初始消息
- 助手以思维块和工具请求响应
- 用户发送带有工具结果的消息
- 助手以更多工具调用或仅文本响应(此响应中没有思维块)
- 如果请求更多工具,重复步骤 3-4,直到对话完成
这种设计允许 Claude 在发出工具请求之前显示其推理过程,但在接收工具结果后不重复思维过程。Claude 在下一个非 tool_result
的 user
轮次之前不会输出另一个思维块。
下图说明了在结合扩展思维和工具使用时的上下文窗口令牌管理:
保留思维块
在工具使用期间,您必须将 thinking
和 redacted_thinking
块传回 API,并且必须将完整的未修改块传回 API。这对于维护模型的推理流程和对话完整性至关重要。
虽然您可以省略之前 assistant
角色轮次的 thinking
和 redacted_thinking
块,但我们建议在任何多轮对话中始终将所有思维块传回 API。API 将:
- 自动过滤提供的思维块
- 使用必要的思维块来保持模型的推理
- 仅对显示给 Claude 的块的输入令牌计费
为什么必须保留思维块
当 Claude 调用工具时,它会暂停其响应构建以等待外部信息。当工具结果返回时,Claude 将继续构建该现有响应。这需要在工具使用期间保留思维块,原因有几个:
-
推理连续性:思维块捕获了导致工具请求的 Claude 逐步推理。当您发布工具结果时,包含原始思维确保 Claude 可以从它停止的地方继续其推理。
-
上下文维护:虽然工具结果在 API 结构中显示为用户消息,但它们是连续推理流程的一部分。保留思维块在多个 API 调用中维护这种概念流程。
重要提示:在提供 thinking
或 redacted_thinking
块时,连续 thinking
或 redacted_thinking
块的整个序列必须与模型在原始请求期间生成的输出相匹配;您不能重新排列或修改这些块的序列。
充分利用扩展思维模式的提示
要充分利用扩展思维:
-
设置适当的预算:对于复杂任务,从较大的思维预算(16,000+ 令牌)开始,并根据您的需求进行调整。
-
实验思维令牌预算:模型在不同的最大思维预算设置下可能表现不同。增加最大思维预算可以使模型思考得更好/更努力,但会增加延迟。对于关键任务,考虑测试不同的预算设置,以找到质量和性能之间的最佳平衡。
-
您不需要自己移除之前的思维块:Anthropic API 会自动忽略之前轮次的思维块,它们在计算上下文使用时不会被包含。
-
监控令牌使用:跟踪思维令牌使用情况以优化成本和性能。
-
将扩展思维用于特别复杂的任务:为受益于逐步推理的任务启用思维,如数学、编码和分析。
-
考虑延长响应时间:考虑到生成思维块可能会增加整体响应时间。
-
适当处理流式传输:在流式传输时,准备好处理思维和文本内容块的到来。
-
提示工程:如果您想最大化 Claude 的思维能力,请查看我们的扩展思维提示技巧。