擴展思考

手動模式下的「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）上，請在您的 API 請求中新增 interleaved-thinking-2025-05-14 beta 標頭。

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 和 AWS 上的 Claude Platform 在任何模型上都接受 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 和模型遷移指南。



後續步驟