使用擴展思考進行建構

「Extended thinking」（擴展思考）為 Claude 提供增強的推理能力以處理複雜任務，同時在提供最終答案之前，以不同程度的透明度呈現其逐步思考過程。

支援的模型

所有目前的 Claude 模型都支援手動擴展思考（thinking: {type: "enabled", budget_tokens: N}），但 Claude Fable 5、Claude Mythos 5、Claude Opus 4.8 和 Claude Opus 4.7 除外，這些模型不接受此設定並會回傳 400 錯誤。少數模型具有特定模式的行為：

• Claude Fable 5（claude-fable-5）和 Claude Mythos 5（claude-mythos-5）： 不支援手動擴展思考，會回傳 400 錯誤。自適應思考始終開啟；請使用 effort 參數來控制思考深度。
• Claude Opus 4.8（claude-opus-4-8）： 不支援手動擴展思考，會回傳 400 錯誤。請改用自適應思考（thinking: {type: "adaptive"}）搭配 effort 參數。模型會根據每個請求決定是否使用擴展思考以及使用多少。
• Claude Opus 4.7（claude-opus-4-7）： 不再支援手動擴展思考。請改用自適應思考（thinking: {type: "adaptive"}）搭配 effort 參數。
• Claude Mythos Preview： 自適應思考為預設值；也接受 thinking: {type: "enabled", budget_tokens: N}。不支援 thinking: {type: "disabled"}，且 display 預設為 "omitted" 而非回傳思考內容。傳遞 display: "summarized" 以接收摘要。
• Claude Opus 4.6（claude-opus-4-6）： 建議使用自適應思考；手動模式（type: "enabled"）已棄用但仍可運作。
• Claude Sonnet 4.6（claude-sonnet-4-6）： 建議使用自適應思考；搭配交錯模式的手動模式（type: "enabled"）已棄用但仍可運作。

擴展思考的運作方式

當擴展思考開啟時，Claude 會建立 thinking 內容區塊，在其中輸出其內部推理。Claude 會在產生最終回應之前，整合此推理的見解。

API 回應包含 thinking 內容區塊，後接 text 內容區塊。

以下是預設回應格式的範例：

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me analyze this step by step...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

如需擴展思考回應格式的更多資訊，請參閱 Messages API 參考文件。

如何使用擴展思考

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

若要開啟擴展思考，請新增一個 thinking 物件，將 type 參數設為 enabled，並將 budget_tokens 設為擴展思考的指定 token 預算。對於 Claude Opus 4.6 和 Claude Sonnet 4.6，請改用 type: "adaptive"。詳情請參閱自適應思考。雖然 type: "enabled" 搭配 budget_tokens 在這些模型上仍可運作，但已被棄用，並將在未來版本中移除。

budget_tokens 參數決定 Claude 可用於其內部推理過程的最大 token 數量。此限制適用於完整的思考 token，而非摘要輸出。較大的預算可透過對複雜問題進行更徹底的分析來提升回應品質，但 Claude 可能不會使用全部分配的預算，尤其是在超過 32k 的範圍內。

budget_tokens 必須設為小於 max_tokens 的值。但是，當使用搭配工具的交錯思考時，您可以超過此限制，因為 token 限制會變成您的整個上下文視窗。由於 budget_tokens 必須小於 max_tokens，擴展思考無法與 max_tokens: 0（快取預熱）結合使用。

摘要思考

啟用擴展思考後，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" 才能接收摘要式思考。

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

• 您需要為原始請求所產生的完整思考 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 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 設定為何，都不會產生思考區塊。

從不向終端使用者顯示思考內容的自動化管線，可以省去透過網路接收思考 token 的開銷。對延遲敏感的應用程式可獲得相同的推理品質，而無需等待思考文字串流完成後才開始最終回應。

當設定 display: "omitted" 時，回應包含 thinking 欄位為空的 thinking 區塊：

{
  "content": [
    {
      "type": "thinking",
      "thinking": "",
      "signature": "EosnCkYICxIMMb3LzNrMu..."
    },
    {
      "type": "text",
      "text": "The answer is 12,231."
    }
  ]
}

當使用 display: "omitted" 進行串流時，不會發出 thinking_delta 事件；請參閱下方的串流思考以了解事件順序。

串流思考

您可以使用伺服器傳送事件（SSE）來串流擴展思考回應。

當擴展思考啟用串流時，您會透過 thinking_delta 事件接收思考內容。

當設定 display: "omitted" 時，不會發出 thinking_delta 事件。請參閱控制思考顯示。

如需透過 Messages API 進行串流的更多文件，請參閱串流訊息。

以下是如何處理搭配思考的串流：

串流輸出範例：

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-sonnet-4-6", "stop_reason": null, "stop_sequence": null}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": "", "signature": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n462 = 3 × 147 + 21\n147 = 7 × 21 + 0\n\nSo GCD(1071, 462) = 21"}}

// Additional thinking deltas...

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "The greatest common divisor of 1071 and 462 is **21**."}}

// Additional text deltas...

event: content_block_stop
data: {"type": "content_block_stop", "index": 1}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}

event: message_stop
data: {"type": "message_stop"}

當設定 display: "omitted" 時，思考區塊會開啟，接著收到單一 signature_delta，然後區塊關閉，不會有任何 thinking_delta 事件。文字串流會在此之後立即開始：

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"thinking","thinking":"","signature":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"signature_delta","signature":"EosnCkYICxIMMb3LzNrMu..."}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"text","text":""}}

搭配工具使用的擴展思考

擴展思考可與工具使用一起使用，讓 Claude 能夠推理工具選擇和結果處理。

當搭配工具使用擴展思考時，請注意以下限制：

1. 工具選擇限制：搭配思考的工具使用僅支援 tool_choice: {"type": "auto"}（預設值）或 tool_choice: {"type": "none"}。使用 tool_choice: {"type": "any"} 或 tool_choice: {"type": "tool", "name": "..."} 會導致錯誤，因為這些選項會強制使用工具，這與擴展思考不相容。

2. 保留思考區塊：在工具使用期間，您必須將最後一則助理訊息的 thinking 區塊傳回 API。將完整未修改的區塊傳回 API 以維持推理連續性。

在對話中切換思考模式

您無法在助理回合中途切換思考，包括在工具使用迴圈期間。整個助理回合應在單一思考模式下運作：

• 如果思考已啟用，最後的助理回合應以思考區塊開始。
• 如果思考已停用，最後的助理回合不應包含任何思考區塊。

從模型的角度來看，工具使用迴圈是助理回合的一部分。助理回合在 Claude 完成其完整回應之前不會結束，這可能包括多次工具呼叫和結果。

例如，以下序列全部屬於單一助理回合：

User: "What's the weather in Paris?"
Assistant: [thinking] + [tool_use: get_weather]
User: [tool_result: "20°C, sunny"]
Assistant: [text: "The weather in Paris is 20°C and sunny"]

即使有多個 API 訊息，工具使用迴圈在概念上是一個連續助理回應的一部分。

思考的優雅降級

當發生回合中途的思考衝突時（例如在工具使用迴圈期間開啟或關閉思考），API 會自動停用該請求的思考。為了保持模型品質並維持在分佈範圍內，API 可能會：

• 當思考區塊會造成無效的回合結構時，從對話中移除思考區塊
• 當對話歷史與啟用思考不相容時，停用目前請求的思考

這表示嘗試在回合中途切換思考不會導致錯誤，但該請求的思考會被靜默停用。若要確認思考是否處於啟用狀態，請檢查回應中是否存在 thinking 區塊。

實務指引

最佳實務：在每個回合開始時規劃您的思考策略，而不是嘗試在回合中途切換。

範例：完成回合後切換思考

User: "What's the weather?"
Assistant: [tool_use] (thinking disabled)
User: [tool_result]
Assistant: [text: "It's sunny"]
User: "What about tomorrow?"
Assistant: [thinking] + [text: "..."] (thinking enabled - new turn)

透過在切換思考之前完成助理回合，您可以確保新請求確實啟用了思考。

保留思考區塊

在工具使用期間，您必須將 thinking 區塊傳回 API，且必須將完整未修改的區塊傳回 API。這對於維持模型的推理流程和對話完整性至關重要。

當 Claude 呼叫工具時，它會暫停建構回應以等待外部資訊。當工具結果回傳時，Claude 會繼續建構該現有回應。這使得在工具使用期間保留思考區塊成為必要，原因如下：

1. 推理連續性：思考區塊捕捉了 Claude 導致工具請求的逐步推理。當您發布工具結果時，包含原始思考可確保 Claude 能從中斷處繼續其推理。

2. 上下文維護：雖然工具結果在 API 結構中顯示為使用者訊息，但它們是連續推理流程的一部分。保留思考區塊可在多次 API 呼叫中維持此概念流程。如需上下文管理的更多資訊，請參閱上下文視窗指南。

重要：提供 thinking 區塊時，連續 thinking 區塊的整個序列必須與模型在原始請求期間產生的輸出相符；您不能重新排列或修改這些區塊的序列。

交錯思考

Claude 4 模型中搭配工具使用的擴展思考支援「interleaved thinking」（交錯思考），這使 Claude 能夠在工具呼叫之間進行思考，並在收到工具結果後進行更複雜的推理。

透過交錯思考，Claude 可以：

• 在決定下一步之前推理工具呼叫的結果
• 在多個工具呼叫之間串聯推理步驟
• 根據中間結果做出更細緻的決策

模型支援：

• Claude Opus 4.8：使用自適應思考（Claude Opus 4.8 上唯一支援的思考模式）時，交錯思考會自動啟用。不需要 beta 標頭。
• Claude Mythos Preview：交錯思考會自動發生。每個工具間的推理步驟都會移入思考區塊而非純文字，且思考區塊預設會跨回合保留。不需要也不支援 beta 標頭。
• Claude Opus 4.7：使用自適應思考（Opus 4.7 上唯一支援的思考模式）時，交錯思考會自動啟用。不需要 beta 標頭。
• Claude Opus 4.6：使用自適應思考時，交錯思考會自動啟用。不需要 beta 標頭。interleaved-thinking-2025-05-14 beta 標頭在 Opus 4.6 上已棄用，若包含則會被安全地忽略。
• Claude Sonnet 4.6：使用自適應思考（建議）時，交錯思考會自動啟用。搭配手動擴展思考（thinking: {type: "enabled"}）的 interleaved-thinking-2025-05-14 beta 標頭仍可運作但已棄用。
• 其他 Claude 4 模型（Opus 4.5、Opus 4.1（已棄用）、Opus 4（已棄用）、Sonnet 4.5、Sonnet 4（已棄用））：在您的 API 請求中新增 beta 標頭 interleaved-thinking-2025-05-14 以啟用交錯思考。

以下是交錯思考的一些重要考量：

• 使用交錯思考時，budget_tokens 可以超過 max_tokens 參數，因為它代表一個助理回合內所有思考區塊的總預算。
• 交錯思考僅支援透過 Messages API 使用的工具。
• Claude API 和 AWS 上的 Claude Platform 接受對任何模型的請求中包含 interleaved-thinking-2025-05-14，而不會回傳錯誤。在不支援交錯思考的模型上，該標頭會被忽略。在 Claude Opus 4.8、Claude Opus 4.7 和 Claude Opus 4.6 上，它已棄用並會被安全地忽略。在 Claude Mythos Preview 上，不需要此標頭且會被安全地忽略。
• 在合作夥伴營運的平台上（例如 Amazon Bedrock 和 Vertex AI），如果您將 interleaved-thinking-2025-05-14 傳遞給 Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 4.6、Claude Opus 4.5、Claude Opus 4.1（已棄用）、Opus 4（已棄用）、Sonnet 4.5 或 Sonnet 4（已棄用）以外的任何模型，您的請求將會失敗。

搭配提示快取的擴展思考

搭配思考的提示快取有幾個重要考量：

思考區塊上下文移除

• 在較早的 Opus/Sonnet 模型和所有 Haiku 模型上，先前回合的思考區塊會從上下文中移除，這可能會影響快取斷點。在 Opus 4.5+ 和 Sonnet 4.6+ 上，它們預設會被保留。
• 當繼續使用工具的對話時，思考區塊會被快取，並在從快取讀取時計為輸入 token
• 這會產生權衡：雖然思考區塊在視覺上不會消耗上下文視窗空間，但在快取時仍會計入您的輸入 token 使用量
• 如果思考變為停用狀態，且您在目前的工具使用回合中傳遞思考內容，則思考內容將被移除，且該請求的思考將保持停用狀態

快取失效模式

• 變更思考參數（啟用/停用或預算分配）會使訊息快取斷點失效
• 交錯思考會放大快取失效，因為思考區塊可能出現在多個工具呼叫之間
• 儘管思考參數變更或區塊移除，系統提示和工具仍會保持快取

了解思考區塊快取行為

當搭配工具使用擴展思考時，思考區塊會表現出特定的快取行為，這會影響 token 計數：

運作方式：

1. 快取僅在您發出包含工具結果的後續請求時發生
2. 當發出後續請求時，先前的對話歷史（包括思考區塊）可以被快取
3. 這些快取的思考區塊在從快取讀取時，會在您的使用量指標中計為輸入 token
4. 當包含非工具結果的使用者區塊時：在 Opus 4.5+ 和 Sonnet 4.6+ 上，先前的思考區塊會被保留；在較早的 Opus/Sonnet 模型和所有 Haiku 模型上，所有先前的思考區塊會被忽略並從上下文中移除

詳細範例流程：

請求 1：

User: "What's the weather in Paris?"

回應 1：

[thinking_block_1] + [tool_use block 1]

請求 2：

User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]

回應 2：

[thinking_block_2] + [text block 2]

請求 2 會寫入請求內容的快取（而非回應）。快取包含原始使用者訊息、第一個思考區塊、工具使用區塊和工具結果。

請求 3：

User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]

對於 Opus 4.5+ 和 Sonnet 4.6+，所有先前的思考區塊預設會被保留。對於較早的 Opus/Sonnet 模型和所有 Haiku 模型，由於包含了非工具結果的使用者區塊，所有先前的思考區塊會被忽略並從上下文中移除。此請求的處理方式將與以下相同：

User: ["What's the weather in Paris?"],
Assistant: [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [text block 2],
User: [Text response, cache=True]

重點：

• 此快取行為會自動發生，即使沒有明確的 cache_control 標記
• 無論使用一般思考或交錯思考，此行為都是一致的

擴展思考的最大 token 數和上下文視窗大小

max_tokens（當思考啟用時包含您的思考預算）會作為嚴格限制強制執行。在 Claude 4.5 模型及更新版本上，如果輸入 token 加上 max_tokens 超過上下文視窗大小，API 會接受該請求。如果生成隨後達到上下文視窗限制，則會以 stop_reason: "model_context_window_exceeded" 停止。在較早的模型上，API 會改為回傳驗證錯誤。請參閱處理停止原因。

擴展思考的上下文視窗

在啟用思考的情況下計算上下文視窗使用量時，有一些需要注意的考量：

• 在 Opus 4.5+ 和 Sonnet 4.6+ 上，先前回合的思考區塊會被保留並計入您的上下文視窗；在較早的 Opus/Sonnet 模型和所有 Haiku 模型上，它們會被移除且不計入
• 目前回合的思考會計入該回合的 max_tokens 限制

下圖展示了啟用擴展思考時的專用 token 管理：

有效的上下文視窗計算如下：

context window =
  (current input tokens - previous thinking tokens) +
  (thinking tokens + encrypted thinking tokens + text output tokens)

使用 token 計數 API 來取得您特定使用案例的準確 token 計數，尤其是在處理包含思考的多回合對話時。

擴展思考與工具使用的上下文視窗

當搭配工具使用擴展思考時，思考區塊必須明確保留並隨工具結果一起回傳。

搭配工具使用的擴展思考的有效上下文視窗計算變為：

context window =
  (current input tokens + previous thinking tokens + tool use tokens) +
  (thinking tokens + encrypted thinking tokens + text output tokens)

下圖說明了搭配工具使用的擴展思考的 token 管理：

使用擴展思考管理 token

鑑於擴展思考的上下文視窗和 max_tokens 行為，您可能需要：

• 更積極地監控和管理您的 token 使用量
• 隨著提示長度變化調整 max_tokens 值
• 可能更頻繁地使用 token 計數端點
• 注意先前的思考區塊不會在您的上下文視窗中累積

思考加密

完整的思考內容會被加密並在 signature 欄位中回傳。此欄位用於驗證思考區塊在傳回 API 時確實是由 Claude 所生成。

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

• 當串流回應時，簽章會透過 content_block_delta 事件內的 signature_delta 加入，且發生在 content_block_stop 事件之前。
• Claude 4 模型中的 signature 值比先前的模型長得多。
• signature 欄位是一個不透明的欄位，不應被解讀或解析。
• signature 值可跨平台相容（Claude API、Amazon Bedrock 和 Vertex AI）。在一個平台上生成的值可與另一個平台相容。

遮蔽的思考區塊

除了一般的 thinking 區塊外，API 可能會回傳 redacted_thinking 區塊。redacted_thinking 區塊在 data 欄位中包含加密的思考內容，沒有可讀的摘要：

{
  "type": "redacted_thinking",
  "data": "..."
}

data 欄位是不透明且加密的。與一般思考區塊上的 signature 欄位一樣，當繼續使用工具的多回合對話時，您應將 redacted_thinking 區塊原封不動地傳回 API。

不同模型版本的思考差異

Messages API 在不同 Claude 模型版本中處理思考的方式有所不同。下表提供了簡要比較：

各模型的思考區塊保留

先前助理回合的思考區塊是否預設保留在上下文中，取決於模型類別。Opus：Claude Opus 4.5 及更新的 Opus 模型會保留所有先前的思考區塊；Claude Opus 4.1（已棄用）及更早的 Opus 模型僅保留最後一個助理回合的思考。Sonnet：Claude Sonnet 4.6 及更新的 Sonnet 模型會保留全部；Claude Sonnet 4.5 及更早的 Sonnet 模型僅保留最後一個回合。Haiku：截至 Claude Haiku 4.5 的所有 Haiku 模型僅保留最後一個回合。Claude Mythos Preview 也會保留所有先前的思考區塊。

思考區塊保留的優點：

• 快取最佳化：使用工具使用時，保留的思考區塊可實現快取命中，因為它們會隨工具結果傳回並在助理回合中逐步快取，從而在多步驟工作流程中節省 token
• 無智慧影響：保留思考區塊對模型效能沒有負面影響

重要考量：

• 上下文使用量：由於思考區塊保留在上下文中，長對話將消耗更多上下文空間
• 自動行為：這是上述每個模型的預設值。不需要程式碼變更或 beta 標頭
• 向後相容性：若要利用此功能，請繼續將完整、未修改的思考區塊傳回 API，就像您在工具使用時所做的那樣

定價

如需完整的定價資訊，包括基本費率、快取寫入、快取命中和輸出 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 是僅供觀察用途的唯讀明細。

擴展思考的最佳實務與考量

使用思考預算

• **預算最佳化：**最低預算為 1,024 個 token。從最低值開始，逐步增加思考預算，以找到適合您使用案例的最佳範圍。較高的 token 數量可實現更全面的推理，但根據任務不同，效益會遞減。增加預算可以提升回應品質，但代價是延遲增加。對於關鍵任務，請測試不同的設定以找到最佳平衡點。請注意，思考預算是一個目標值，而非嚴格限制。實際的 token 使用量可能會因任務而異。
• **起始點：**對於複雜任務，從較大的思考預算（16k+ token）開始，並根據您的需求進行調整。
• **大型預算：**對於超過 32k 的思考預算，請使用批次處理以避免網路問題。將模型推向超過 32k token 思考的請求會導致長時間執行的請求，可能會遇到系統逾時和開放連線限制的問題。
• **Token 使用量追蹤：**監控思考 token 的使用量，以最佳化成本和效能。回應中的 usage.output_tokens_details.thinking_tokens 欄位會報告計費的輸出 token 中有多少用於內部推理。使用串流時，此細分資訊僅會出現在最後的 message_delta 事件中。

效能考量

• **回應時間：**由於需要額外處理，請預期較長的回應時間。生成思考區塊會增加整體回應時間。
• **串流需求：**當 max_tokens 大於 21,333 時，SDK 會要求使用串流，以避免長時間執行的請求發生 HTTP 逾時。這是用戶端驗證，而非 API 限制。如果您不需要逐步處理事件，請使用 .stream() 搭配 .get_final_message()（Python）或 .finalMessage()（TypeScript）來取得完整的 Message 物件，而無需處理個別事件。詳情請參閱串流訊息。使用串流時，請準備好在思考和文字內容區塊到達時分別處理它們。
• **省略思考以降低延遲：**如果您的應用程式不顯示思考內容，請在思考設定中設定 display: "omitted"，以縮短首個文字 token 的回應時間。請參閱控制思考顯示。

功能相容性

• 思考功能與 temperature 或 top_k 的修改以及強制工具使用不相容。
• 啟用思考功能時，您可以將 top_p 設定為 1 到 0.95 之間的值。
• 啟用思考功能時，您無法預先填入回應。
• 變更思考預算會使包含訊息的快取提示前綴失效。然而，當思考參數變更時，快取的系統提示和工具定義仍會繼續運作。

使用指南

• **任務選擇：**對於受益於逐步推理的特別複雜任務（如數學、程式設計和分析），請使用擴展思考。
• **上下文處理：**您不需要自行移除先前的思考區塊。在 Opus 4.5+ 和 Sonnet 4.6+ 上，Claude API 預設會保留先前回合的思考區塊；在較早的 Opus/Sonnet 模型和所有 Haiku 模型上，API 會自動忽略它們，且在計算上下文使用量時不會將其納入。
• **提示工程：**如果您想最大化 Claude 的思考能力，請查閱擴展思考提示技巧。

後續步驟