自适应思考

自适应思考是在 Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6 和 Claude Sonnet 4.6 上使用扩展思考的推荐方式。在 Claude Fable 5 和 Claude Mythos 5 上，思考始终处于启用状态且无法禁用；自适应思考是唯一的思考模式。在 Claude Mythos Preview 上，自适应思考是默认模式，当 thinking 未设置时会自动应用。自适应思考无需手动设置思考令牌预算，而是让 Claude 根据每个请求的复杂程度动态决定何时以及在多大程度上使用扩展思考。在 Claude Opus 4.8 和 Claude Opus 4.7 上，自适应思考是唯一支持的思考模式；手动设置 thinking: {type: "enabled", budget_tokens: N} 不再被接受。



支持的模型

以下模型支持自适应思考：

• Claude Fable 5（claude-fable-5）和 Claude Mythos 5（claude-mythos-5），自适应思考始终开启；不支持 thinking: {type: "disabled"}
• Claude Mythos Preview（claude-mythos-preview），自适应思考为默认模式；不支持 thinking: {type: "disabled"}
• Claude Opus 4.8（claude-opus-4-8），自适应思考是唯一支持的思考模式。除非您在请求中显式设置 thinking: {type: "adaptive"}，否则思考处于关闭状态；手动设置 thinking: {type: "enabled"} 会被拒绝并返回 400 错误。
• Claude Opus 4.7（claude-opus-4-7），自适应思考是唯一支持的思考模式。除非您在请求中显式设置 thinking: {type: "adaptive"}，否则思考处于关闭状态；手动设置 thinking: {type: "enabled"} 会被拒绝并返回 400 错误。
• Claude Opus 4.6（claude-opus-4-6）
• Claude Sonnet 4.6（claude-sonnet-4-6）



自适应思考的工作原理

在自适应模式下，思考对模型而言是可选的。Claude 会评估每个请求的复杂程度，并决定是否以及在多大程度上使用扩展思考。在默认的努力级别（high）下，Claude 几乎总是会进行思考。在较低的努力级别下，Claude 可能会对较简单的问题跳过思考。

自适应思考还会自动启用交错思考。这意味着 Claude 可以在工具调用之间进行思考，使其在智能体工作流中尤为有效。



如何使用自适应思考

在您的 API 请求中将 thinking.type 设置为 "adaptive"：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=[
        {
            "role": "user",
            "content": "Explain why the sum of two even numbers is always even.",
        }
    ],
)

for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")



自适应思考与 effort 参数

您可以将自适应思考与 effort 参数结合使用，以引导 Claude 的思考程度。努力级别作为 Claude 思考分配的软性指导：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "What is the capital of France?"}],
)

print(response.content[0].text)



自适应思考与流式传输

自适应思考可与流式传输无缝配合。思考块通过 thinking_delta 事件进行流式传输，与手动思考模式相同：

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
) as stream:
    for event in stream:
        if event.type == "content_block_start":
            print(f"\nStarting {event.content_block.type} block...")
        elif event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)



自适应、手动与禁用思考的对比



重要注意事项



验证变更

使用自适应思考时，之前的助手轮次不需要以思考块开头。这比手动模式更灵活，在手动模式下，API 会强制要求启用思考的轮次以思考块开头。



提示缓存

连续使用 adaptive 思考的请求会保留提示缓存断点。但是，在 adaptive 和 enabled/disabled 思考模式之间切换会破坏消息的缓存断点。无论模式如何变化，系统提示和工具定义仍会被缓存。



调整思考行为

自适应思考的触发行为可以通过提示进行调整。如果 Claude 思考的频率高于或低于您的预期，您可以在系统提示中添加指导：

Extended thinking adds latency and should only be used when it
will meaningfully improve answer quality — typically for problems
that require multi-step reasoning. When in doubt, respond directly.

如需鼓励思考，可使用类似以下的表述：

This task involves multi-step reasoning. Think carefully before responding.

引导效果可能对具体措辞较为敏感——如果某种表述未能产生您想要的行为，请尝试更直接的变体。

您还可以在用户轮次中按消息逐条引导思考。在用户消息末尾附加 "Please think hard before responding." 可鼓励 Claude 在该轮次进行思考；"Answer directly without deliberating." 则会抑制思考。这与系统提示相互独立，当对话中只有部分请求需要扩展推理时非常有用。



成本控制

使用 max_tokens 作为总输出（思考 + 响应文本）的硬性限制。effort 参数为 Claude 分配的思考量提供额外的软性指导。两者结合使用，可让您有效控制成本。

在 high 和 max 努力级别下，Claude 可能会进行更广泛的思考，更有可能耗尽 max_tokens 预算。如果您在响应中观察到 stop_reason: "max_tokens"，请考虑增加 max_tokens 以给模型更多空间，或降低努力级别。



使用思考块

以下概念适用于所有支持扩展思考的模型，无论您使用自适应模式还是手动模式。



摘要式思考

启用扩展思考后，Claude 4 模型的 Messages API 会返回 Claude 完整思考过程的摘要。摘要式思考在提供扩展思考全部智能优势的同时，可防止滥用。当思考配置中的 display 字段未设置或设置为 "summarized" 时，这是 Claude 4 模型的默认行为。在 Claude Fable 5、Claude Mythos 5、Claude Opus 4.8、Claude Opus 4.7 和 Claude Mythos Preview 上，display 默认为 "omitted"，因此您必须显式设置 display: "summarized" 才能接收摘要式思考。

以下是关于摘要式思考的一些重要注意事项：

• 您需要为原始请求生成的完整思考令牌付费，而非摘要令牌。
• 计费的输出令牌数量将不会匹配您在响应中看到的令牌数量。
• 在 Claude 4 模型上，思考输出的前几行更为详尽，提供了详细的推理过程，这对提示工程尤其有帮助。Claude Mythos Preview 从第一个令牌开始就进行摘要，因此其思考块不会显示这种详尽的前导内容。
• 随着 Anthropic 不断改进扩展思考功能，摘要行为可能会发生变化。
• 摘要以最小的额外延迟保留了 Claude 思考过程的关键思路，从而实现可流式传输的用户体验。
• 摘要由与您在请求中指定的模型不同的另一个模型处理。思考模型不会看到摘要后的输出。



控制思考显示

思考配置中的 display 字段用于控制 API 响应中思考内容的返回方式。它接受两个值：

• "summarized"：思考块包含摘要化的思考文本。详情请参阅摘要化思考。这是 Claude Opus 4.6、Claude Sonnet 4.6 以及更早的 Claude 4 模型的默认值。
• "omitted"：返回的思考块中 thinking 字段为空。signature 字段仍然携带加密的完整思考内容，以支持多轮对话的连续性（请参阅思考加密）。这是 Claude Fable 5、Claude Mythos 5、Claude Opus 4.8、Claude Opus 4.7 以及 Claude Mythos Preview 的默认值。

当您的应用程序不向用户展示思考内容时，设置 display: "omitted" 会非常有用。其主要优势在于**流式传输时更快获得首个文本令牌：**服务器会完全跳过思考令牌的流式传输，仅传递签名，因此最终的文本响应能够更早开始流式传输。

以下是关于省略思考的一些重要注意事项：

• 您仍需为完整的思考令牌付费。省略思考可降低延迟，但不会降低成本。
• 如果您在多轮对话中回传思考块，请原样传递。服务器会解密 signature 以重建原始思考内容，用于构建提示（请参阅保留思考块）。您在回传的省略块的 thinking 字段中放置的任何文本都将被忽略。
• 当 thinking.type: "disabled" 时，display 无效（因为没有内容可显示）。
• 当使用 thinking.type: "adaptive" 且模型针对简单请求跳过思考时，无论 display 设置为何值，都不会生成思考块。

thinking = {
    "type": "adaptive",
    "display": "summarized",
}

有关 display: "omitted" 的代码示例和流式传输行为，请参阅扩展思考页面上的控制思考显示。那里的示例使用 type: "enabled"；使用自适应思考时，请改用：

thinking = {"type": "adaptive", "display": "omitted"}



思考加密

完整的思考内容会被加密并在 signature 字段中返回。当思考块被传回 API 时，该字段用于验证这些思考块确实是由 Claude 生成的。

以下是关于思考加密的一些重要注意事项：

• 当使用流式传输响应时，签名会通过 content_block_delta 事件内的 signature_delta 添加，该事件紧接在 content_block_stop 事件之前。
• Claude 4 模型中的 signature 值比之前的模型长得多。
• signature 字段是一个不透明字段，不应对其进行解释或解析。
• signature 值在各平台之间兼容（Claude API、Amazon Bedrock 和 Vertex AI）。在一个平台上生成的值可以在另一个平台上兼容使用。



Claude Fable 5 和 Claude Mythos 5 上的思考输出

在 Claude Fable 5 和 Claude Mythos 5 上，原始思维链永远不会被返回。您收到的思考块是常规的 thinking 块，而非 redacted_thinking。thinking.display 设置的工作方式与其他模型相同：

• "summarized" 返回推理的可读摘要。
• "omitted"（这些模型上的默认值）仍会在响应中包含 thinking 块，但其 thinking 字段为空字符串。

有关思考块的响应结构，请参阅 Messages API 参考。

在同一模型上继续对话时，请将每个思考块按原样传回 API，包括 thinking 字段为空的块。请勿编辑或重构它们。读取摘要文本用于显示是可以的：API 拒绝的是内容被修改过的块，而不是您读取过的块。

当您切换模型时，例如在分类器拒绝回退之后，请从之前的助手轮次中剥离 thinking 和 redacted_thinking 块。思考块与生成它们的模型绑定。其他模型会静默忽略它们而不是拒绝请求，但被忽略的块仍会增加输入令牌。

有两个例外情况，详见回退额度：

• 回退额度重试必须原封不动地回传被拒绝的请求体。
• 来自输出中途回退的 fallback 块应保留在其出现的位置。

要了解模型的推理过程，请读取本节所述的 thinking 块，而不是通过提示让模型在响应文本中输出推理。在 Claude Fable 5 上，试图将模型的内部推理作为响应文本一部分引出的请求可能会被拒绝，并返回 stop_details.category: "reasoning_extraction"。有关字段参考和处理指南，请参阅拒绝类别。



定价

有关基础费率、缓存写入、缓存命中和输出令牌的完整定价信息，请参阅定价页面。

思考过程会产生以下费用：

• 思考期间使用的令牌（输出令牌）
• 保留在上下文中的先前助手轮次的思考块：在早期 Opus/Sonnet 模型和所有 Haiku 模型上仅保留最后一轮；在 Opus 4.5+ 和 Sonnet 4.6+ 上默认保留所有轮次（输入令牌）
• 标准文本输出令牌

使用摘要式思考时：

• **输入令牌：**您原始请求中的令牌（不包括先前轮次的思考令牌）
• **输出令牌（计费）：**Claude 内部生成的原始思考令牌
• **输出令牌（可见）：**您在响应中看到的摘要式思考令牌
• **不收费：**用于生成摘要的令牌

使用 display: "omitted" 时：

• **输入令牌：**您原始请求中的令牌（与摘要式相同）
• **输出令牌（计费）：**Claude 内部生成的原始思考令牌（与摘要式相同）
• **输出令牌（可见）：**零思考令牌（thinking 字段为空）

要查看内部推理消耗了多少计费输出令牌，请读取响应中的 usage.output_tokens_details.thinking_tokens。该值反映模型生成的原始推理（而非响应正文中返回的摘要文本），并且始终小于或等于 output_tokens。从 output_tokens 中减去该值即可估算输出中非推理部分的令牌数。

{
  "usage": {
    "input_tokens": 25,
    "output_tokens": 348,
    "output_tokens_details": {
      "thinking_tokens": 312
    }
  }
}

output_tokens 仍然是用于计费的包含性权威总数。output_tokens_details 是用于可观测性的只读明细。



其他主题

扩展思考页面通过特定模式的代码示例更详细地介绍了以下几个主题：

• 思考与工具使用：自适应思考适用相同的规则：在工具调用之间保留思考块，并注意思考激活时 tool_choice 的限制。
• 提示缓存：使用自适应思考时，连续使用相同思考模式的请求会保留缓存断点。在 adaptive 和 enabled/disabled 模式之间切换会破坏消息的缓存断点（系统提示和工具定义仍会被缓存）。
• 上下文窗口：思考令牌如何与 max_tokens 和上下文窗口限制交互。



后续步骤