使用扩展思考构建
扩展思考为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
内容块。
以下是默认响应格式的示例:
有关扩展思考响应格式的更多信息,请参阅消息API参考。
如何使用扩展思考
以下是在消息API中使用扩展思考的示例:
要启用扩展思考,请添加一个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进行流式传输的更多文档,请参阅流式传输消息。
以下是如何处理带有思考的流式传输:
流式传输输出示例:
在使用启用思考的流式传输时,您可能会注意到文本有时以较大的块交替出现,有时则是逐个令牌传递。这是预期的行为,特别是对于思考内容。
流式传输系统需要批量处理内容以获得最佳性能,这可能导致这种”块状”传递模式,流式传输事件之间可能会有延迟。我们正在不断努力改善这种体验,未来的更新将专注于使思考内容流式传输更加流畅。
扩展思考与工具使用
扩展思考可以与工具使用一起使用,允许Claude推理工具选择和结果处理。
在使用带有工具使用的扩展思考时,请注意以下限制:
-
工具选择限制:带有思考的工具使用仅支持
tool_choice: any
(不支持specific
、auto
或其他值)。 -
保留思考块:在工具使用期间,您必须将最后一条助手消息的
thinking
块传回API。将完整的未修改块传回API以维持推理连续性。
保留思考块
在工具使用期间,您必须将thinking
块传回API,并且必须将完整的未修改块传回API。这对于维护模型的推理流程和对话完整性至关重要。
虽然您可以省略先前assistant
角色回合中的thinking
块,但我们建议始终将所有思考块传回API,用于任何多轮对话。API将:
- 自动过滤提供的思考块
- 使用保留模型推理所需的相关思考块
- 只对显示给Claude的块的输入令牌计费
当Claude调用工具时,它会暂停构建响应以等待外部信息。当工具结果返回时,Claude将继续构建现有响应。这需要在工具使用期间保留思考块,原因有几个:
-
推理连续性:思考块捕获了Claude导致工具请求的逐步推理。当您发布工具结果时,包含原始思考确保Claude可以从中断的地方继续其推理。
-
上下文维护:虽然工具结果在API结构中显示为用户消息,但它们是连续推理流程的一部分。保留思考块在多个API调用中维护这种概念流程。有关上下文管理的更多信息,请参阅我们的上下文窗口指南。
重要提示:在提供thinking
块时,连续thinking
块的整个序列必须与模型在原始请求期间生成的输出匹配;您不能重新排列或修改这些块的序列。
交错思考
Claude 4模型中带有工具使用的扩展思考支持交错思考,这使Claude能够在工具调用之间进行思考,并在接收工具结果后进行更复杂的推理。
通过交错思考,Claude可以:
- 在决定下一步操作之前,对工具调用的结果进行推理
- 在多个工具调用之间链接思考步骤
- 基于中间结果做出更细微的决策
要启用交错思考,请在API请求中添加beta标头 interleaved-thinking-2025-05-14
。
交错思考仅支持通过消息API使用的工具。
使用交错思考时,budget_tokens
可以超过max_tokens
参数,因为它代表一个助手回合内所有思考块的总预算。
扩展思考与提示缓存
提示缓存与思考一起使用有几个重要的考虑因素:
思考块上下文移除
- 先前回合的思考块会从上下文中移除,这可能会影响缓存断点
- 在继续使用工具的对话时,思考块会被缓存,并在从缓存读取时计为输入令牌
- 这创造了一个权衡:虽然思考块在视觉上不消耗上下文窗口空间,但它们在缓存时仍然计入您的输入令牌使用量
- 如果思考被禁用,当您在当前工具使用回合中传递思考内容时,请求将失败。在其他上下文中,传递给API的思考内容会被简单地忽略
缓存失效模式
理解思考块缓存行为
在使用带有工具使用的扩展思考时,思考块表现出特定的缓存行为,这会影响令牌计数:
工作原理:
- 缓存仅在您发出包含工具结果的后续请求时发生
- 当发出后续请求时,先前的对话历史(包括思考块)可以被缓存
- 这些缓存的思考块在从缓存读取时计入您的使用指标中的输入令牌
- 当包含非工具结果用户块时,所有先前的思考块都会被忽略并从上下文中剥离
详细示例流程:
请求1:
响应1:
请求2:
响应2:
请求2写入请求内容的缓存(而不是响应)。缓存包括原始用户消息、第一个思考块、工具使用块和工具结果。
请求3:
因为包含了非工具结果用户块,所有先前的思考块都会被忽略。此请求将以与以下相同的方式处理:
要点:
- 这种缓存行为会自动发生,即使没有明确的
cache_control
标记 - 无论使用常规思考还是交错思考,这种行为都是一致的
扩展思考的最大令牌数和上下文窗口大小
在较旧的Claude模型(Claude Sonnet 3.7之前),如果提示令牌和max_tokens
的总和超过了模型的上下文窗口,系统会自动调整max_tokens
以适应上下文限制。这意味着您可以设置一个较大的max_tokens
值,系统会静默地根据需要减少它。
对于Claude 3.7和4模型,max_tokens
(当启用思考时包括您的思考预算)被强制执行为严格限制。如果提示令牌+max_tokens
超过上下文窗口大小,系统现在会返回验证错误。
您可以阅读我们的上下文窗口指南,获取更全面的深入了解。
扩展思考的上下文窗口
在计算启用思考的上下文窗口使用情况时,有一些需要注意的考虑因素:
- 先前回合的思考块会被剥离,不计入您的上下文窗口
- 当前回合的思考计入该回合的
max_tokens
限制
下图展示了启用扩展思考时的专门令牌管理:
有效上下文窗口计算为:
我们建议使用令牌计数API获取您特定用例的准确令牌计数,特别是在处理包含思考的多回合对话时。
扩展思考和工具使用的上下文窗口
在使用带有工具使用的扩展思考时,必须明确保留思考块并与工具结果一起返回。
带有工具使用的扩展思考的有效上下文窗口计算变为:
下图说明了带有工具使用的扩展思考的令牌管理:
管理扩展思考的令牌
鉴于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
以下是显示正常和编辑后思考块的示例:
在您的输出中看到编辑后的思考块是预期的行为。模型仍然可以使用这种编辑后的推理来为其响应提供信息,同时维护安全护栏。
如果您需要在应用程序中测试编辑后的思考处理,可以使用这个特殊的测试字符串作为您的提示:ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB
在多轮对话中将thinking
和redacted_thinking
块传回API时,您必须将完整的未修改块传回API,用于最后一个助手回合。这对于维护模型的推理流程至关重要。我们建议始终将所有思考块传回API。有关更多详细信息,请参阅上面的保留思考块部分。
不同模型版本间的思考差异
消息API在Claude Sonnet 3.7和Claude 4模型之间对思考的处理方式不同,主要在编辑和摘要行为方面。
请参阅下表获取简明比较:
功能 | Claude Sonnet 3.7 | Claude 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时,需要流式传输。在流式传输时,请准备好处理思考和文本内容块的到达。
功能兼容性
- 思考与
temperature
或top_k
修改以及强制工具使用不兼容。 - 启用思考时,您可以将
top_p
设置为1到0.95之间的值。 - 启用思考时,您不能预填充响应。
- 思考预算的更改会使包含消息的缓存提示前缀失效。但是,当思考参数更改时,缓存的系统提示和工具定义将继续工作。
使用指南
- 任务选择: 将扩展思考用于特别复杂的任务,这些任务受益于逐步推理,如数学、编码和分析。
- 上下文处理: 您不需要自己移除先前的思考块。Anthropic API会自动忽略先前回合的思考块,它们在计算上下文使用时不会被包括在内。
- 提示工程: 如果您想最大化Claude的思考能力,请查看我们的扩展思考提示技巧。