自適應思考

自適應思考（adaptive thinking）是在 Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 5 和 Claude Sonnet 4.6 上使用擴展思考的建議方式，也是 Claude Fable 5 和 Claude Mythos 5 上唯一的思考模式。自適應思考不需要手動設定思考 token 預算，而是讓 Claude 根據每個請求的複雜度，動態決定何時以及使用多少擴展思考。各模型的預設值和限制列於支援的模型。



支援的模型

以下模型支援自適應思考：

• Claude Fable 5（claude-fable-5）和 Claude Mythos 5（claude-mythos-5），自適應思考始終開啟；不支援 thinking: {type: "disabled"}。這兩個模型都不適用於零資料保留。
• Claude Mythos Preview（claude-mythos-preview），自適應思考為預設值；不支援 thinking: {type: "disabled"}，手動的 {type: "enabled", budget_tokens: N} 仍然可以使用。
• 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），除非您明確設定 thinking: {type: "adaptive"}，否則自適應思考為關閉狀態；手動的 {type: "enabled", budget_tokens: N} 仍然可以使用但已被棄用。
• Claude Sonnet 5（claude-sonnet-5），自適應思考預設為開啟；傳入 thinking: {type: "disabled"} 可將其關閉。手動的 {type: "enabled"} 會被拒絕並回傳 400 錯誤。
• Claude Sonnet 4.6（claude-sonnet-4-6），除非您明確設定 thinking: {type: "adaptive"}，否則自適應思考為關閉狀態；手動的 {type: "enabled", budget_tokens: N} 仍然可以使用但已被棄用。



自適應思考的運作方式

在自適應模式下，思考對模型而言是可選的。Claude 會評估每個請求的複雜度，並決定是否以及使用多少擴展思考。在預設的 effort 等級（high）下，Claude 幾乎總是會思考。在較低的 effort 等級下，Claude 可能會對較簡單的問題跳過思考。

自適應思考也會自動啟用交錯思考。這表示 Claude 可以在工具呼叫之間進行思考，使其在代理式工作流程中特別有效。



如何使用自適應思考

在您的 API 請求中將 thinking.type 設定為 "adaptive"。範例中也將 thinking.display 設定為 "summarized" 以使思考文字可見：在最新的模型上，display 預設為 "omitted"，會回傳 thinking 欄位為空的思考區塊。詳情請參閱控制思考顯示。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    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}")

思考 token 會計入 max_tokens，因此請將其設定得足夠高，以便為思考和回應文字都留出空間。請參閱成本控制。



自適應思考與 effort 參數

您可以將自適應思考與 effort 參數結合使用，以引導 Claude 的思考量。effort 等級作為 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?"}],
)

for block in response.content:
    if block.type == "text":
        print(block.text)



使用自適應思考進行串流

自適應思考可與串流搭配使用。思考區塊透過 thinking_delta 事件進行串流，與手動思考模式相同。如同先前的範例，thinking.display: "summarized" 使串流的思考文字可見：

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    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)



自適應 vs 手動 vs 停用思考



重要注意事項



驗證變更

使用自適應思考時，先前的 assistant 回合不需要以思考區塊開頭。這比手動模式更有彈性，手動模式下 API 會強制要求啟用思考的回合以思考區塊開頭。

另外，Claude Fable 5、Claude Mythos 5、Claude Mythos Preview、Claude Opus 4.8、Claude Opus 4.7 和 Claude Sonnet 5 會拒絕非預設的 temperature、top_p 和 top_k 值並回傳 400 錯誤。這適用於這些模型上的每個請求，無論思考是否處於啟用狀態。



提示快取

使用 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 effort 等級下，Claude 可能會進行更廣泛的思考，也更有可能耗盡 max_tokens 預算。如果您在回應中觀察到 stop_reason: "max_tokens"，請考慮增加 max_tokens 以給模型更多空間，或降低 effort 等級。



使用思考區塊

以下概念適用於所有支援擴展思考的模型，無論您使用自適應模式還是手動模式。



摘要式思考

啟用「extended thinking」（擴展思考）後，Claude 4 模型的 Messages API 會回傳 Claude 完整思考過程的摘要。摘要式思考提供擴展思考的完整智慧優勢，同時防止濫用。當思考配置中的 display 欄位未設定或設定為 "summarized" 時，這是 Claude 4 模型的預設行為。在 Claude Fable 5、Claude Mythos 5、Claude Sonnet 5、Claude Opus 4.8、Claude Opus 4.7 和 Claude Mythos Preview 上，display 預設為 "omitted"，因此您必須明確設定 display: "summarized" 才能接收摘要式思考。

以下是關於摘要式思考的一些重要考量事項：

• 您需要為原始請求所產生的完整思考 token 付費，而非摘要 token。
• 計費的輸出 token 數量將不會符合您在回應中看到的 token 數量。
• 在 Claude 4 模型上，思考輸出的前幾行較為詳盡，提供詳細的推理過程，這對於提示工程特別有幫助。Claude Mythos Preview 從第一個 token 開始就進行摘要，因此其思考區塊不會顯示這種詳盡的前言。
• 由於 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 Sonnet 5、Claude Opus 4.8、Claude Opus 4.7 及 Claude Mythos Preview 的預設值。

當您的應用程式不向使用者顯示思考內容時，設定 display: "omitted" 會很有用。主要好處是**串流時更快取得首個文本 token：**伺服器會完全跳過串流思考 token，僅傳送簽章，因此最終文本回應能更快開始串流。

以下是關於省略思考的一些重要考量：

• 您仍需為完整的思考 token 付費。省略可降低延遲，但不會降低成本。
• 如果您在多輪對話中回傳思考區塊，請原封不動地傳回。伺服器會解密 signature 以重建原始思考內容用於提示建構（請參閱保留思考區塊）。您在往返傳遞的省略區塊中放入 thinking 欄位的任何文本都會被忽略。
• display 與 thinking.type: "disabled" 搭配使用時無效（因為沒有內容可顯示）。
• 當使用 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 和 Google Cloud）。在一個平台上生成的值可與另一個平台相容。



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 拒絕的是內容被修改過的區塊，而不是您讀取過的區塊。

當您切換模型時，例如在分類器拒絕回退之後，請從先前的 assistant 回合中移除 thinking 和 redacted_thinking 區塊。思考區塊與產生它們的模型綁定。其他模型會默默忽略它們而不是拒絕請求，但被忽略的區塊仍會增加 input tokens。

有兩個例外情況，詳見回退額度：

• 回退額度重試必須原封不動地回傳被拒絕的請求主體。
• 來自輸出中途回退的 fallback 區塊保留在它們出現的位置。

若要了解模型的推理過程，請讀取本節所述的 thinking 區塊，而不是在回應文字中提示要求推理。在 Claude Fable 5 上，試圖將模型的內部推理作為回應文字一部分引出的請求可能會被拒絕，並回傳 stop_details.category: "reasoning_extraction"。請參閱拒絕類別以了解欄位參考和處理指引。



定價

如需完整的定價資訊，包括基本費率、快取寫入、快取命中和輸出 token，請參閱定價頁面。

思考過程會產生以下費用：

• 思考期間使用的 token（輸出 token）
• 保留在上下文中的先前助手回合的思考區塊：在較早的 Opus/Sonnet 模型和所有 Haiku 模型上僅保留最後一個回合；在 Opus 4.5+ 和 Sonnet 4.6+ 上預設保留所有回合（輸入 token）
• 標準文字輸出 token

使用摘要式思考時：

• **輸入 token：**您原始請求中的 token（不包括先前回合的思考 token）
• **輸出 token（計費）：**Claude 內部生成的原始思考 token
• **輸出 token（可見）：**您在回應中看到的摘要式思考 token
• **不收費：**用於生成摘要的 token

使用 display: "omitted" 時：

• **輸入 token：**您原始請求中的 token（與摘要式相同）
• **輸出 token（計費）：**Claude 內部生成的原始思考 token（與摘要式相同）
• **輸出 token（可見）：**零個思考 token（thinking 欄位為空）

若要查看內部推理消耗了多少計費輸出 token，請讀取回應中的 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 的限制。
• **擴展思考與提示快取：**搭配思考區塊進行快取的程式碼範例。自適應模式特有的快取行為已在本頁稍早的提示快取中說明。
• **上下文視窗：**思考 token 如何與 max_tokens 和上下文視窗限制互動。



後續步驟