Claude Platform Docs
Messages思考

擴展思考

在支援的 Claude 模型上以固定的 budget_tokens 預算設定手動擴展思考，並遷移至自適應思考。

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

若要了解思考本身的運作方式，包括思考區塊與回應結構、display 參數、「streaming」（串流）、搭配「tool use」（工具使用）的思考，以及加密，請參閱思考概覽。

支援的模型

各模型的擴展思考可用性，包括擴展思考為唯一模式的模型，列於各模型設定表中。

如何使用擴展思考

以下是在 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 模型上，請在您的 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 標頭會被接受但忽略。

手動模式下交錯思考的另外兩項注意事項：

各平台處理 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，可直接觀察到失效情形：

Output
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 4.7 或更新的模型，例如 Claude Opus 5.5、Claude Sonnet 5 或 Claude Fable 5.1，這些模型上的 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 以及模型遷移指南。

後續步驟

思考

了解思考的運作方式：區塊、顯示、串流與工具使用。

引導思考

讓 Claude 在每個請求上決定何時思考以及思考多少。

工具與多輪工作流程中的思考

保留思考區塊，並在工具呼叫與輪次之間管理思考。

Was this page helpful?