支持的模型
以下模型支持扩展思考:- Claude Sonnet 4.5 (
claude-sonnet-4-5-20250929) - Claude Sonnet 4 (
claude-sonnet-4-20250514) - Claude Sonnet 3.7 (
claude-3-7-sonnet-20250219) - Claude Haiku 4.5 (
claude-haiku-4-5-20251001) - Claude Opus 4.1 (
claude-opus-4-1-20250805) - Claude Opus 4 (
claude-opus-4-20250514)
API行为在Claude Sonnet 3.7和Claude 4模型之间有所不同,但API结构保持完全相同。更多信息,请参阅不同模型版本中思考的差异。
扩展思考的工作原理
当扩展思考开启时,Claude会创建thinking内容块,在其中输出内部推理。Claude在制作最终回应之前会融入这种推理的见解。
API响应将包含thinking内容块,然后是text内容块。
以下是默认响应格式的示例:
如何使用扩展思考
以下是在Messages API中使用扩展思考的示例:thinking对象,将type参数设置为enabled,并将budget_tokens设置为扩展思考的指定token预算。
budget_tokens参数决定了Claude在内部推理过程中允许使用的最大token数量。在Claude 4模型中,此限制适用于完整的思考token,而不是总结的输出。更大的预算可以通过为复杂问题启用更彻底的分析来提高响应质量,尽管Claude可能不会使用分配的全部预算,特别是在超过32k的范围内。
budget_tokens必须设置为小于max_tokens的值。但是,当使用交错思考与工具时,您可以超过此限制,因为token限制变成您的整个上下文窗口(200k token)。
总结思考
启用扩展思考后,Claude 4模型的Messages API返回Claude完整思考过程的总结。总结思考提供扩展思考的全部智能优势,同时防止滥用。 以下是总结思考的一些重要考虑因素:- 您需要为原始请求生成的完整思考token付费,而不是总结token。
- 计费的输出token计数将不匹配您在响应中看到的token计数。
- 思考输出的前几行更加详细,提供特别有助于提示工程目的的详细推理。
- 随着Anthropic寻求改进扩展思考功能,总结行为可能会发生变化。
- 总结保留了Claude思考过程的关键思想,延迟最小,实现了可流式传输的用户体验,并便于从Claude Sonnet 3.7迁移到Claude 4模型。
- 总结由与您在请求中目标模型不同的模型处理。思考模型看不到总结的输出。
Claude Sonnet 3.7继续返回完整的思考输出。在需要访问Claude 4模型完整思考输出的罕见情况下,联系我们的销售团队。
流式思考
您可以使用服务器发送事件(SSE)流式传输扩展思考响应。 当为扩展思考启用流式传输时,您通过thinking_delta事件接收思考内容。
有关通过Messages API进行流式传输的更多文档,请参阅流式消息。
以下是如何处理带有思考的流式传输:
当使用启用思考的流式传输时,您可能会注意到文本有时以较大的块到达,与较小的逐token传递交替。这是预期的行为,特别是对于思考内容。流式系统需要批量处理内容以获得最佳性能,这可能导致这种”块状”传递模式,流式事件之间可能有延迟。我们正在持续改进这种体验,未来的更新将专注于使思考内容流式传输更加流畅。
扩展思考与工具使用
扩展思考可以与工具使用一起使用,允许Claude推理工具选择和结果处理。 当使用扩展思考与工具使用时,请注意以下限制:-
工具选择限制:带有思考的工具使用仅支持
tool_choice: {"type": "auto"}(默认)或tool_choice: {"type": "none"}。使用tool_choice: {"type": "any"}或tool_choice: {"type": "tool", "name": "..."}将导致错误,因为这些选项强制使用工具,这与扩展思考不兼容。 -
保留思考块:在工具使用期间,您必须将最后一条助手消息的
thinking块传回API。将完整的未修改块包含回API以维持推理连续性。
示例:使用工具结果传递思考块
示例:使用工具结果传递思考块
以下是一个实际示例,展示了在提供工具结果时如何保留思考块:API响应将包含思考、文本和tool_use块:现在让我们继续对话并使用工具API响应现在将仅包含文本
保留思考块
在工具使用期间,您必须将thinking块传回API,并且必须将完整的未修改块包含回API。这对于维持模型的推理流程和对话完整性至关重要。
虽然您可以省略先前
assistant角色轮次的thinking块,但我们建议在任何多轮对话中始终将所有思考块传回API。API将:- 自动过滤提供的思考块
- 使用保持模型推理所需的相关思考块
- 仅对显示给Claude的块的输入token计费
- 推理连续性:思考块捕获了Claude导致工具请求的逐步推理。当您发布工具结果时,包含原始思考确保Claude可以从中断的地方继续其推理。
- 上下文维护:虽然工具结果在API结构中显示为用户消息,但它们是连续推理流程的一部分。保留思考块在多个API调用中维持这种概念流程。有关上下文管理的更多信息,请参阅我们的上下文窗口指南。
thinking块时,连续thinking块的整个序列必须与模型在原始请求期间生成的输出匹配;您不能重新排列或修改这些块的序列。
交错思考
Claude 4模型中的扩展思考与工具使用支持交错思考,这使Claude能够在工具调用之间思考,并在接收工具结果后进行更复杂的推理。 通过交错思考,Claude可以:- 在决定下一步做什么之前推理工具调用的结果
- 在推理步骤之间链接多个工具调用
- 基于中间结果做出更细致的决策
interleaved-thinking-2025-05-14。
以下是交错思考的一些重要考虑因素:
- 使用交错思考时,
budget_tokens可以超过max_tokens参数,因为它代表一个助手轮次内所有思考块的总预算。 - 交错思考仅支持通过Messages API使用的工具。
- 交错思考仅支持Claude 4模型,使用beta头
interleaved-thinking-2025-05-14。 - 直接调用Claude API允许您在对任何模型的请求中传递
interleaved-thinking-2025-05-14,没有效果。 - 在第三方平台上(例如,Amazon Bedrock和Vertex AI),如果您将
interleaved-thinking-2025-05-14传递给除Claude Opus 4.1、Opus 4或Sonnet 4之外的任何模型,您的请求将失败。
不使用交错思考的工具使用
不使用交错思考的工具使用
- Claude在开始时思考一次以理解任务
- 预先做出所有工具使用决策
- 当工具结果返回时,Claude立即提供响应而不进行额外思考
使用交错思考的工具使用
使用交错思考的工具使用
- Claude最初思考任务
- 收到计算器结果后,Claude可以再次思考该结果的含义
- 然后Claude根据第一个结果决定如何查询数据库
- 收到数据库结果后,Claude在制定最终响应之前再次思考两个结果
- 思考预算分布在轮次内的所有思考块中
扩展思考与提示缓存
带有思考的提示缓存有几个重要考虑因素:扩展思考任务通常需要超过5分钟才能完成。考虑使用1小时缓存持续时间来维持跨越更长思考会话和多步骤工作流程的缓存命中。
- 来自先前轮次的思考块被移除,这可能影响缓存断点
- 当继续使用工具使用的对话时,思考块被缓存并在从缓存读取时计为输入token
- 这创建了一个权衡:虽然思考块在视觉上不消耗上下文窗口空间,但在缓存时仍计入您的输入token使用量
- 如果思考被禁用,如果您在当前工具使用轮次中传递思考内容,请求将失败。在其他上下文中,传递给API的思考内容被简单忽略
理解思考块缓存行为
当使用扩展思考与工具使用时,思考块表现出影响token计数的特定缓存行为: 工作原理:- 缓存仅在您进行包含工具结果的后续请求时发生
- 当进行后续请求时,先前的对话历史(包括思考块)可以被缓存
- 这些缓存的思考块在从缓存读取时在您的使用指标中计为输入token
- 当包含非工具结果用户块时,所有先前的思考块被忽略并从上下文中剥离
- 这种缓存行为自动发生,即使没有显式的
cache_control标记 - 无论使用常规思考还是交错思考,此行为都是一致的
系统提示缓存(思考更改时保留)
系统提示缓存(思考更改时保留)
消息缓存(思考更改时失效)
消息缓存(思考更改时失效)
cache_creation_input_tokens=1370和cache_read_input_tokens=0,证明当思考参数更改时基于消息的缓存失效。扩展思考的最大token和上下文窗口大小
在较旧的Claude模型(Claude Sonnet 3.7之前)中,如果提示token和max_tokens的总和超过了模型的上下文窗口,系统会自动调整max_tokens以适应上下文限制。这意味着您可以设置一个大的max_tokens值,系统会根据需要静默减少它。
对于Claude 3.7和4模型,max_tokens(当启用思考时包括您的思考预算)被强制执行为严格限制。如果提示token + max_tokens超过上下文窗口大小,系统现在将返回验证错误。
您可以阅读我们的上下文窗口指南以获得更彻底的深入了解。
扩展思考的上下文窗口
当计算启用思考的上下文窗口使用量时,有一些需要注意的考虑因素:- 来自先前轮次的思考块被剥离,不计入您的上下文窗口
- 当前轮次思考计入该轮次的
max_tokens限制
扩展思考与工具使用的上下文窗口
当使用扩展思考与工具使用时,思考块必须明确保留并与工具结果一起返回。 扩展思考与工具使用的有效上下文窗口计算变为:管理扩展思考的token
鉴于扩展思考Claude 3.7和4模型的上下文窗口和max_tokens行为,您可能需要:
- 更积极地监控和管理您的token使用
- 随着提示长度的变化调整
max_tokens值 - 可能更频繁地使用token计数端点
- 注意先前的思考块不会在您的上下文窗口中累积
思考加密
完整的思考内容被加密并在signature字段中返回。此字段用于验证思考块是由Claude生成的,当传回API时。
只有在使用扩展思考的工具时才严格需要发送回思考块。否则,您可以省略先前轮次的思考块,或者如果您传回它们,让API为您剥离它们。如果发送回思考块,我们建议按照您收到的方式传回所有内容,以保持一致性并避免潜在问题。
- 当流式响应时,签名通过
content_block_delta事件内的signature_delta添加,就在content_block_stop事件之前。 - Claude 4模型中的
signature值比先前模型中的显著更长。 signature字段是一个不透明字段,不应被解释或解析 - 它仅用于验证目的。signature值在平台间兼容(Claude API、Amazon Bedrock和Vertex AI)。在一个平台上生成的值将与另一个平台兼容。
思考编辑
偶尔Claude的内部推理会被我们的安全系统标记。当这种情况发生时,我们加密部分或全部thinking块并将其作为redacted_thinking块返回给您。redacted_thinking块在传回API时被解密,允许Claude继续其响应而不失去上下文。
当构建使用扩展思考的面向客户的应用程序时:
- 注意编辑的思考块包含不可读的加密内容
- 考虑提供简单的解释,如:“Claude的一些内部推理已因安全原因自动加密。这不会影响响应的质量。”
- 如果向用户显示思考块,您可以过滤掉编辑的块,同时保留正常的思考块
- 透明地说明使用扩展思考功能可能偶尔导致一些推理被加密
- 实施适当的错误处理,以优雅地管理编辑的思考而不破坏您的UI
在您的输出中看到编辑的思考块是预期行为。模型仍然可以使用这种编辑的推理来告知其响应,同时维持安全护栏。如果您需要在应用程序中测试编辑思考处理,您可以使用这个特殊测试字符串作为您的提示:
ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CBthinking和redacted_thinking块传回API时,您必须为最后一个助手轮次将完整的未修改块包含回API。这对于维持模型的推理流程至关重要。我们建议始终将所有思考块传回API。有关更多详细信息,请参阅上面的保留思考块部分。
示例:处理编辑的思考块
示例:处理编辑的思考块
不同模型版本中思考的差异
Messages API在Claude Sonnet 3.7和Claude 4模型中处理思考的方式不同,主要在编辑和总结行为方面。 请参阅下表进行简要比较:| 功能 | Claude Sonnet 3.7 | Claude 4模型 |
|---|---|---|
| 思考输出 | 返回完整思考输出 | 返回总结思考 |
| 交错思考 | 不支持 | 支持interleaved-thinking-2025-05-14 beta头 |
定价
扩展思考使用标准token定价方案:| 模型 | 基础输入Token | 缓存写入 | 缓存命中 | 输出Token |
|---|---|---|---|---|
| Claude Opus 4.1 | $15 / MTok | $18.75 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Opus 4 | $15 / MTok | $18.75 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Sonnet 4.5 | $3 / MTok | $3.75 / MTok | $0.30 / MTok | $15 / 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 |
- 思考期间使用的token(输出token)
- 来自最后一个助手轮次的思考块包含在后续请求中(输入token)
- 标准文本输出token
当启用扩展思考时,会自动包含专门的系统提示以支持此功能。
- 输入token:您原始请求中的token(不包括先前轮次的思考token)
- 输出token(计费):Claude内部生成的原始思考token
- 输出token(可见):您在响应中看到的总结思考token
- 无费用:用于生成总结的token
计费的输出token计数将不匹配响应中可见的token计数。您为完整的思考过程付费,而不是您看到的总结。
扩展思考的最佳实践和考虑因素
使用思考预算
- 预算优化:最小预算是1,024个token。我们建议从最小值开始,逐步增加思考预算以找到您用例的最佳范围。更高的token计数能够进行更全面的推理,但根据任务的不同,收益递减。增加预算可以以增加延迟为代价提高响应质量。对于关键任务,测试不同设置以找到最佳平衡。请注意,思考预算是目标而不是严格限制——实际token使用可能根据任务而变化。
- 起点:对于复杂任务,从较大的思考预算(16k+ token)开始,并根据您的需要进行调整。
- 大预算:对于超过32k的思考预算,我们建议使用批处理以避免网络问题。推动模型思考超过32k token的请求会导致长时间运行的请求,可能遇到系统超时和开放连接限制。
- Token使用跟踪:监控思考token使用以优化成本和性能。
性能考虑
- 响应时间:由于推理过程需要额外处理,准备好可能更长的响应时间。考虑到生成思考块可能增加整体响应时间。
- 流式要求:当
max_tokens大于21,333时需要流式传输。流式传输时,准备好处理到达的思考和文本内容块。
功能兼容性
- 思考与
temperature或top_k修改以及强制工具使用不兼容。 - 当启用思考时,您可以将
top_p设置为1到0.95之间的值。 - 当启用思考时,您不能预填充响应。
- 思考预算的更改会使包含消息的缓存提示前缀失效。但是,当思考参数更改时,缓存的系统提示和工具定义将继续工作。
使用指南
- 任务选择:对特别复杂的任务使用扩展思考,这些任务受益于逐步推理,如数学、编码和分析。
- 上下文处理:您不需要自己移除先前的思考块。Claude API自动忽略先前轮次的思考块,它们在计算上下文使用时不包括在内。
- 提示工程:如果您想最大化Claude的思考能力,请查看我们的扩展思考提示技巧。