使用延伸思考進行構建

延伸思考為 Claude 提供了增強的推理能力，用於處理複雜任務，同時在提供最終答案之前提供不同程度的透明度，讓您了解其逐步思考過程。

支援的模型

延伸思考在以下模型中受支援：

• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Sonnet 3.7 (claude-3-7-sonnet-20250219) (已棄用)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)

延伸思考的工作原理

啟用延伸思考後，Claude 會建立 thinking 內容區塊，其中輸出其內部推理。Claude 在製作最終回應之前會納入此推理中的見解。

API 回應將包括 thinking 內容區塊，後面跟著 text 內容區塊。

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

{
  "content": [
    {
      "type": "thinking",
      "thinking": "讓我逐步分析這個...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "text",
      "text": "根據我的分析..."
    }
  ]
}

如需更多關於延伸思考回應格式的資訊，請參閱訊息 API 參考。

如何使用延伸思考

以下是在訊息 API 中使用延伸思考的範例：

若要啟用延伸思考，請新增 thinking 物件，將 type 參數設定為 enabled，並將 budget_tokens 設定為延伸思考的指定代幣預算。

budget_tokens 參數決定了 Claude 被允許用於其內部推理過程的最大代幣數。在 Claude 4 模型中，此限制適用於完整思考代幣，而不適用於摘要輸出。較大的預算可以透過為複雜問題啟用更徹底的分析來改善回應品質，儘管 Claude 可能不會使用整個分配的預算，特別是在 32k 以上的範圍內。

budget_tokens 必須設定為小於 max_tokens 的值。但是，當使用與工具交錯的思考時，您可以超過此限制，因為代幣限制變成您的整個上下文視窗（200k 代幣）。

摘要思考

啟用延伸思考後，Claude 4 模型的訊息 API 會傳回 Claude 完整思考過程的摘要。摘要思考提供了延伸思考的完整智能優勢，同時防止濫用。

以下是摘要思考的一些重要考慮事項：

• 您需要為原始請求產生的完整思考代幣付費，而不是摘要代幣。
• 計費的輸出代幣計數將不符合您在回應中看到的代幣計數。
• 思考輸出的前幾行更詳細，提供了詳細的推理，特別有助於提示工程目的。
• 隨著 Anthropic 尋求改進延伸思考功能，摘要行為可能會改變。
• 摘要化保留了 Claude 思考過程的關鍵思想，同時增加了最少的延遲，實現了可流式傳輸的使用者體驗和從 Claude Sonnet 3.7 到 Claude 4 模型的輕鬆遷移。
• 摘要化由與您在請求中指定的模型不同的模型處理。思考模型看不到摘要輸出。

流式傳輸思考

您可以使用伺服器發送事件 (SSE) 流式傳輸延伸思考回應。

啟用延伸思考的流式傳輸後，您會透過 thinking_delta 事件接收思考內容。

如需更多關於透過訊息 API 進行流式傳輸的文件，請參閱流式傳輸訊息。

以下是如何處理思考流式傳輸的方法：

範例流式傳輸輸出：

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

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

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "讓我逐步解決這個問題：\n\n1. 首先分解 27 * 453"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n2. 453 = 400 + 50 + 3"}}

// 其他思考 delta...

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": "27 * 453 = 12,231"}}

// 其他文字 delta...

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"}

延伸思考與工具使用

延伸思考可以與工具使用一起使用，允許 Claude 透過工具選擇和結果處理進行推理。

使用延伸思考與工具使用時，請注意以下限制：

1. 工具選擇限制：具有思考的工具使用僅支援 tool_choice: {"type": "auto"} (預設) 或 tool_choice: {"type": "none"}。使用 tool_choice: {"type": "any"} 或 tool_choice: {"type": "tool", "name": "..."} 將導致錯誤，因為這些選項強制工具使用，與延伸思考不相容。

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

在對話中切換思考模式

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

• 如果啟用思考，最終助手回合必須以思考區塊開始。
• 如果停用思考，最終助手回合不得包含任何思考區塊

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

例如，此序列全部是單一助手回合的一部分：

使用者："巴黎的天氣如何？"
助手：[思考] + [tool_use: get_weather]
使用者：[tool_result: "20°C，晴天"]
助手：[文字："巴黎的天氣是 20°C 和晴天"]

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

常見錯誤情景

您可能會遇到此錯誤：

預期 `thinking` 或 `redacted_thinking`，但找到 `tool_use`。
啟用 `thinking` 時，最終 `assistant` 訊息必須以思考區塊開始
（在最後一組 `tool_use` 和 `tool_result` 區塊之前）。

這通常發生在以下情況：

1. 您在工具使用序列期間停用思考
2. 您想再次啟用思考
3. 您的最後助手訊息包含工具使用區塊但沒有思考區塊

實用指南

✗ 無效：在工具使用後立即切換思考

使用者："天氣如何？"
助手：[tool_use] (思考已停用)
使用者：[tool_result]
// 無法在此啟用思考 - 仍在同一助手回合中

✓ 有效：先完成助手回合

使用者："天氣如何？"
助手：[tool_use] (思考已停用)
使用者：[tool_result]
助手：[文字："天氣晴朗"]
使用者："明天呢？" (思考已停用)
助手：[思考] + [文字："..."] (思考已啟用 - 新回合)

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

保留思考區塊

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

當 Claude 呼叫工具時，它會暫停其回應的構建以等待外部資訊。當工具結果返回時，Claude 將繼續構建該現有回應。這需要在工具使用期間保留思考區塊，原因有幾個：

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

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

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

交錯思考

Claude 4 模型中的擴展思考與工具使用支持交錯思考，這使 Claude 能夠在工具調用之間進行思考，並在接收工具結果後進行更複雜的推理。

通過交錯思考，Claude 可以：

• 在決定下一步操作之前，對工具調用的結果進行推理
• 在推理步驟之間鏈接多個工具調用
• 根據中間結果做出更細緻的決策

要啟用交錯思考，請將測試版標頭 interleaved-thinking-2025-05-14 添加到您的 API 請求中。

以下是交錯思考的一些重要考慮事項：

• 使用交錯思考時，budget_tokens 可以超過 max_tokens 參數，因為它代表一個助手轉向內所有思考塊的總預算。
• 交錯思考僅支持通過 Messages API 使用的工具。
• 交錯思考僅支持 Claude 4 模型，使用測試版標頭 interleaved-thinking-2025-05-14。
• 直接調用 Claude API 允許您在對任何模型的請求中傳遞 interleaved-thinking-2025-05-14，無任何效果。
• 在第三方平台上（例如，Amazon Bedrock 和 Vertex AI），如果您將 interleaved-thinking-2025-05-14 傳遞給除 Claude Opus 4.5、Claude Opus 4.1、Opus 4 或 Sonnet 4 之外的任何模型，您的請求將失敗。

使用提示詞快取的擴展思考

提示詞快取與思考有幾個重要的考慮事項：

思考塊上下文移除

• 來自先前轉向的思考塊從上下文中移除，這可能會影響快取斷點
• 在使用工具繼續對話時，思考塊被快取並在從快取讀取時計為輸入令牌
• 這造成了一個權衡：雖然思考塊在視覺上不消耗上下文窗口空間，但在快取時仍然計入您的輸入令牌使用量
• 如果思考被禁用，如果您在當前工具使用轉向中傳遞思考內容，請求將失敗。在其他上下文中，傳遞給 API 的思考內容只是被忽略

快取失效模式

• 對思考參數的更改（啟用/禁用或預算分配）會使消息快取斷點失效
• 交錯思考放大了快取失效，因為思考塊可以在多個工具調用之間發生
• 系統提示詞和工具儘管思考參數更改或塊移除仍保持快取

理解思考塊快取行為

使用擴展思考與工具使用時，思考塊表現出特定的快取行為，影響令牌計數：

工作原理：

1. 只有當您發出包含工具結果的後續請求時，才會進行快取
2. 發出後續請求時，先前的對話歷史記錄（包括思考塊）可以被快取
3. 這些快取的思考塊在從快取讀取時計為您的使用指標中的輸入令牌
4. 當包含非工具結果用戶塊時，所有先前的思考塊都被忽略並從上下文中移除

詳細示例流程：

請求 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]

對於 Claude Opus 4.5 及更高版本，默認情況下保留所有先前的思考塊。對於較舊的模型，因為包含了非工具結果用戶塊，所有先前的思考塊都被忽略。此請求將按以下方式處理：

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 標記
• 無論使用常規思考還是交錯思考，此行為都是一致的

使用擴展思考的最大令牌和上下文窗口大小

在較舊的 Claude 模型中（Claude Sonnet 3.7 之前），如果提示令牌和 max_tokens 的總和超過模型的上下文窗口，系統會自動調整 max_tokens 以適應上下文限制。這意味著您可以設置一個大的 max_tokens 值，系統會根據需要自動減少它。

使用 Claude 3.7 和 4 模型，max_tokens（啟用思考時包括您的思考預算）被強制執行為嚴格限制。如果提示令牌 + max_tokens 超過上下文窗口大小，系統現在將返回驗證錯誤。

使用擴展思考的上下文窗口

使用啟用思考的上下文窗口計算時，有一些需要注意的考慮事項：

• 來自先前轉向的思考塊被剝離，不計入您的上下文窗口
• 當前轉向思考計入該轉向的 max_tokens 限制

下圖演示了啟用擴展思考時的專門令牌管理：

有效的上下文窗口計算為：

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

我們建議使用令牌計數 API為您的特定用例獲得準確的令牌計數，特別是在使用包含思考的多轉對話時。

使用擴展思考和工具使用的上下文窗口

使用擴展思考與工具使用時，思考塊必須明確保留並與工具結果一起返回。

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

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

下圖說明了使用擴展思考和工具使用的令牌管理：

使用擴展思考管理令牌

鑑於 Claude 3.7 和 4 模型的上下文窗口和 max_tokens 行為使用擴展思考，您可能需要：

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

進行此更改是為了提供更可預測和透明的行為，特別是隨著最大令牌限制的顯著增加。

思考加密

完整的思考內容被加密並在 signature 字段中返回。此字段用於驗證思考塊是由 Claude 生成的，當傳遞回 API 時。

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

• 當流式傳輸回應時，簽名通過 content_block_delta 事件內的 signature_delta 添加，就在 content_block_stop 事件之前。
• signature 值在 Claude 4 模型中的長度明顯長於先前的模型。
• signature 字段是一個不透明字段，不應被解釋或解析 - 它僅用於驗證目的。
• signature 值在平台之間兼容（Claude API、Amazon Bedrock 和 Vertex AI）。在一個平台上生成的值將與另一個平台兼容。

思考內容編輯

偶爾 Claude 的內部推理會被我們的安全系統標記。當這種情況發生時，我們會加密 thinking 區塊的部分或全部內容，並將其作為 redacted_thinking 區塊返回給您。redacted_thinking 區塊在傳回 API 時會被解密，允許 Claude 繼續其回應而不會失去上下文。

在構建使用擴展思考的面向客戶的應用程式時：

• 請注意 redacted thinking 區塊包含不可人類閱讀的加密內容
• 考慮提供簡單的解釋，例如：「Claude 的某些內部推理已因安全原因自動加密。這不會影響回應的品質。」
• 如果向用戶顯示思考區塊，您可以過濾掉 redacted 區塊，同時保留正常的思考區塊
• 透明地說明使用擴展思考功能可能偶爾會導致某些推理被加密
• 實施適當的錯誤處理，以優雅地管理 redacted thinking，而不會破壞您的 UI

以下是顯示正常和 redacted thinking 區塊的範例：

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

在多輪對話中將 thinking 和 redacted_thinking 區塊傳回 API 時，您必須將最後一個助手回合的完整未修改區塊傳回 API。這對於維持模型的推理流程至關重要。我們建議始終將所有思考區塊傳回 API。如需更多詳細資訊，請參閱上面的保留思考區塊部分。

不同模型版本間的思考差異

Messages API 在 Claude Sonnet 3.7 和 Claude 4 模型之間以不同方式處理思考，主要在編輯和摘要行為方面。

請參閱下表以了解簡明比較：

Claude Opus 4.5 中的思考區塊保留

Claude Opus 4.5 引入了新的預設行為：來自先前助手回合的思考區塊預設在模型上下文中保留。這與早期模型不同，早期模型會移除先前回合的思考區塊。

思考區塊保留的優點：

• 快取最佳化：使用工具時，保留的思考區塊可啟用快取命中，因為它們會與工具結果一起傳回，並在助手回合中逐步快取，導致多步驟工作流程中的代幣節省
• 無智能影響：保留思考區塊對模型效能沒有負面影響

重要考慮事項：

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

定價

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

思考過程產生的費用包括：

• 思考期間使用的代幣（輸出代幣）
• 後續請求中包含的最後一個助手回合的思考區塊（輸入代幣）
• 標準文字輸出代幣

使用摘要思考時：

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

擴展思考的最佳實踐和考慮事項

使用思考預算

• **預算最佳化：**最小預算為 1,024 個代幣。我們建議從最小值開始，逐步增加思考預算以找到您用例的最佳範圍。更高的代幣計數可啟用更全面的推理，但根據任務會有遞減的回報。增加預算可以改善回應品質，但代價是增加延遲。對於關鍵任務，測試不同的設定以找到最佳平衡。請注意，思考預算是目標而非嚴格限制——實際代幣使用可能因任務而異。
• **起點：**對於複雜任務，從較大的思考預算（16k+ 代幣）開始，並根據您的需求進行調整。
• **大型預算：**對於超過 32k 的思考預算，我們建議使用批次處理以避免網路問題。推動模型思考超過 32k 代幣的請求會導致長時間執行的請求，可能會遇到系統逾時和開放連線限制。
• **代幣使用追蹤：**監控思考代幣使用情況以最佳化成本和效能。

效能考慮事項

• **回應時間：**為推理過程所需的額外處理可能導致的更長回應時間做好準備。考慮到生成思考區塊可能會增加整體回應時間。
• **串流要求：**當 max_tokens 大於 21,333 時，需要串流。串流時，請準備好在思考和文字內容區塊到達時處理它們。

功能相容性

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

使用指南

• **任務選擇：**對於受益於逐步推理的特別複雜任務（如數學、編碼和分析），使用擴展思考。
• **上下文處理：**您不需要自己移除先前的思考區塊。Claude API 會自動忽略先前回合的思考區塊，它們在計算上下文使用時不包括在內。
• **提示工程：**如果您想最大化 Claude 的思考能力，請查看我們的擴展思考提示提示。

後續步驟