擴展思考

手動模式下的「extended thinking」（擴展思考）讓您可以直接控制 Claude 思考的程度。您在每個請求上使用 thinking: {type: "enabled", budget_tokens: N} 設定思考 token 預算，Claude 會根據該預算進行思考，然後才開始其最終答案。當您的工作負載需要可預測的延遲或對思考成本的精確控制時，手動模式仍然很有用。本頁涵蓋如何設定和調整預算、手動模式如何與交錯思考和提示快取互動，以及如何遷移至自適應思考。

關於思考本身的運作方式，包括思考區塊和回應結構、display 參數、串流、搭配工具使用的思考以及加密，請參閱思考概覽。



支援的模型

每個模型的擴展思考可用性，包括擴展思考是唯一模式的模型，都列在各模型設定表中。



如何使用擴展思考

以下是在 Messages API 中使用擴展思考的範例：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        }
    ],
)

# 回應包含摘要化的思考區塊與文字區塊
for block in response.content:
    match block.type:
        case "thinking":
            print(f"\nThinking summary: {block.thinking}")
        case "text":
            print(f"\nResponse: {block.text}")

要開啟手動擴展思考，請新增一個 thinking 物件，將 type 設為 enabled 並提供 budget_tokens 值。

budget_tokens 參數設定 Claude 可用於其內部推理過程的 token 數量目標。較大的預算可以透過對複雜問題進行更徹底的分析來提高回應品質。



預算規則與調整

budget_tokens 必須滿足以下限制：

• 最少 1,024 個 token。 API 會拒絕更小的值。
• 小於 max_tokens。 思考 token 計入該輪次的 max_tokens 限制，因此預算必須為最終回應留出空間。唯一的例外是交錯思考，其中 budget_tokens 可以超過 max_tokens，因為預算涵蓋一個助手輪次內的所有思考區塊。
• 不支援快取預熱。 由於 budget_tokens 必須小於 max_tokens，擴展思考無法與 max_tokens: 0（快取預熱）結合使用。

預算是一個目標，而非嚴格的上限。實際的 token 使用量會因任務而異，Claude 可能在預算用盡之前就停止推理；max_tokens 仍然是總輸出的硬性上限。

在 Claude Opus 4.5（唯一支援 effort 的僅限擴展思考模型）上，effort 塑造整體回應，而 budget_tokens 設定思考深度；兩者都要設定。

調整預算的方法：

• 根據任務選擇起始點。對於簡單任務，從接近 1,024 個 token 的最小值開始，逐步增加以找到適合您使用案例的最佳範圍。對於複雜任務，從 16,000 個 token 或更多的較大預算開始，並根據您的延遲和品質需求進行調整。較高的預算可以實現更全面的推理，但報酬遞減的程度取決於任務，且代價是延遲增加。對於關鍵任務，請測試不同的設定以找到適當的平衡。
• 對於超過 32k 的思考預算，請使用批次處理以避免網路問題。推動模型思考超過 32k 個 token 會產生長時間執行的請求，可能會觸及系統逾時和開放連線限制。

要追蹤預算實際花費多少，請監控回應中的 usage.output_tokens_details.thinking_tokens 欄位，該欄位報告計費的輸出 token 中有多少是內部推理。在串流時，此明細僅出現在最後的 message_delta 事件上。

當您準備好放棄手動預算時，請參閱遷移至自適應思考。



手動模式下的交錯思考

「Interleaved thinking」（交錯思考）讓 Claude 在單一助手輪次內的工具呼叫之間進行思考，在決定下一步之前對每個工具結果進行推理。關於此概念、輪次結構以及它在自適應思考模型上的行為，請參閱思考概覽中的交錯思考。本節涵蓋當您使用手動 type: "enabled" 思考時如何啟用它。

在 Claude Opus 4.5、Claude Sonnet 4.5 和較早的 Claude 4 模型（Claude Opus 4.1（已棄用）、Claude Opus 4 和 Claude Sonnet 4）上，請將 interleaved-thinking-2025-05-14 beta 標頭新增至您的 API 請求。

4.6 世代在手動模式下有所區分：

• Claude Sonnet 4.6：搭配手動 type: "enabled" 的 beta 標頭仍然有效但已棄用。建議使用自適應思考，它會自動交錯，無需標頭。
• Claude Opus 4.6：手動模式完全沒有交錯思考。只有其自適應模式會交錯，因此如果您需要在此模型上的工具呼叫之間進行推理，請切換至 thinking: {type: "adaptive"}。

Claude Haiku 4.5 不支援交錯思考。在 Claude API 上，beta 標頭會被接受但被忽略。

手動模式下交錯思考的另外兩個考量：

• budget_tokens 在此可以超過 max_tokens；預算規則解釋了此例外。
• 交錯思考僅支援透過 Messages API 使用的工具。

各平台對 beta 標頭的處理方式不同。Claude API 和 Claude Platform on AWS 在任何模型上都接受 interleaved-thinking-2025-05-14，並在不支援的地方忽略它。接受不等於生效：在拒絕 type: "enabled" 的模型（4.7 及更高版本）或缺少手動模式交錯的模型（Claude Opus 4.6）上，該標頭在手動模式下沒有效果；自適應思考在那裡會自動交錯。

合作夥伴營運的平台（Amazon Bedrock 和 Google Cloud）同樣在任何模型上接受該標頭而不會回傳錯誤，並在不支援交錯思考的模型上忽略它。



手動模式下的輪次結構

一般的輪次結構規則，包括單輪工具使用迴圈、輪次中途的衝突處理，以及在輪次之間切換思考，都在搭配工具使用的思考中。

手動模式增加了一項要求：啟用思考的請求的最終助手輪次必須以思考區塊開頭（自適應思考取消了該要求）。在輪次之間變更思考設定也會使提示快取失效；請參閱下一節。



手動模式下的提示快取

手動模式在思考與提示快取中描述的與模式無關的快取行為之上增加了一條規則：在請求之間變更 budget_tokens 會使快取斷點失效，就像切換思考模式一樣，因為預算值會被渲染到提示中。預算變更後，訊息層級的斷點總是會未命中；工具和系統提示斷點是否也會未命中，取決於模型在何處渲染該設定。

實務上，請選擇一個預算並在快取對話的整個生命週期中保持穩定。在 Claude Sonnet 4.6 上執行具有訊息層級快取的多輪對話，並在第三個請求上將預算從 4,000 變更為 8,000 個 token，可以直接顯示失效情況：

First request - establishing cache
First response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 17, output_tokens: 700 }

Second request - same thinking parameters (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 1370, input_tokens: 303, output_tokens: 874 }

Third request - different thinking budget (cache miss expected)
Third response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 747, output_tokens: 619 }

第三個請求重新建立了快取（cache_creation_input_tokens=1370、cache_read_input_tokens=0），因為預算在請求之間發生了變更。關於自適應模式下相同實驗的可執行版本（其中 effort 層級扮演了 budget_tokens 在此處扮演的快取角色），請參閱引導頁面上的提示快取。



共通機制

大多數思考行為與模式無關，並在思考頁面上統一記錄。那裡的所有內容也適用於手動模式：

• 控制思考顯示
• 串流思考
• 搭配工具使用的思考，包括保留思考區塊
• 思考與提示快取
• 思考與上下文視窗
• 思考加密
• 定價（在引導思考頁面上）



遷移至自適應思考

如果您的模型僅支援擴展思考（Claude Sonnet 4.5、Claude Opus 4.5、Claude Haiku 4.5 和較早的 Claude 4 模型），目前無需採取任何行動：自適應思考在那裡不可用，且 type: "adaptive" 會回傳 400 錯誤。請保留 budget_tokens，直到您移至支援自適應思考的模型，然後套用以下的對應方式。

在以下情況下，您需要從 type: "enabled" 遷移：

• 您使用 Claude Opus 4.6 或 Claude Sonnet 4.6，其中 budget_tokens 已棄用。
• 您正在移至 Claude Opus 4.7、Claude Opus 4.8、Claude Opus 5、Claude Sonnet 5、Claude Fable 5 或 Claude Mythos 5，其中 type: "enabled" 會回傳 400 錯誤。

對應方式很簡單：移除 budget_tokens，設定 thinking: {type: "adaptive"}，並使用 output_config: {effort: ...} 而非 token 預算來控制推理深度。

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  }
}

變成：

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "adaptive"
  },
  "output_config": {
    "effort": "high"
  }
}

effort: "high" 與 API 預設值相符；它出現在這裡只是為了顯示深度控制現在的位置，省略它會產生相同的行為。

請預期行為上的差異，而不僅僅是語法變更。使用固定預算時，Claude 在每個請求上都會思考。使用自適應思考時，Claude 會在每個請求上決定是否思考以及思考多少，並且在較低的 effort 設定下，它可能會在簡單的輸入上完全跳過思考。遷移後您也可以移除 interleaved-thinking-2025-05-14 beta 標頭：自適應思考會自動交錯，且 Claude API 在這些模型上會忽略該標頭。思考區塊的保留也會改變：Claude Opus 4.5 和編號 4.6 及更高的模型會將先前輪次的思考區塊保留在上下文中並作為輸入計費，而 Claude Sonnet 4.5、Claude Haiku 4.5 和較早的模型會將它們移除；請參閱各模型的思考區塊保留。

切換模式是一種思考設定變更，因此切換後的第一個請求會使快取斷點失效，如手動模式下的提示快取中所述。

如需完整指引，請參閱自適應思考、effort 和模型遷移指南。



後續步驟