延伸思考功能讓 Claude 3.7 Sonnet 在處理複雜任務時具有增強的推理能力,同時也能讓您看到它在提供最終答案前的逐步思考過程。

延伸思考的運作方式

當啟用延伸思考時,Claude 會創建 thinking 內容區塊來輸出其內部推理過程。Claude 會在形成最終回應前整合這些推理的見解。

API 回應會同時包含 thinkingtext 內容區塊。

在多輪對話中,只有與工具使用階段或最後一條訊息位置的 assistant 回合相關的思考區塊對 Claude 可見並計入輸入標記;與較早的 assistant 訊息相關的思考區塊對 Claude 在採樣時不可見,也不會計入輸入標記。

實作延伸思考

在您的 API 請求中加入 thinking 參數和指定用於延伸思考的標記預算。

budget_tokens 參數決定了允許 Claude 用於內部推理過程的最大標記數。較大的預算可以通過為複雜問題啟用更全面的分析來改善回應品質,不過在超過 32K 的範圍時,Claude 可能不會使用全部分配的預算。

您的 budget_tokens 必須始終小於指定的 max_tokens

API 回應將包含思考和文字內容區塊:

{
    "content": [
        {
            "type": "thinking",
            "thinking": "To approach this, let's think about what we know about prime numbers...",
            "signature": "zbbJhbGciOiJFU8zI1NiIsImtakcjsu38219c0.eyJoYXNoIjoiYWJjMTIzIiwiaWFxxxjoxNjE0NTM0NTY3fQ...."
        },
        {
            "type": "text",
            "text": "Yes, there are infinitely many prime numbers such that..."
        }
    ]
}

理解思考區塊

思考區塊代表 Claude 的內部思考過程。為了讓 Claude 能夠在維持我們的安全標準和無狀態 API 的同時以最少的內部限制來解決問題,我們實施了以下措施:

  • 思考區塊包含一個 signature 欄位。此欄位包含一個加密令牌,用於驗證思考區塊是由 Claude 生成的,並在思考區塊傳回 API 時進行驗證。在串流回應時,簽名會通過 content_block_delta 事件中的 signature_deltacontent_block_stop 事件之前添加。只有在使用工具與延伸思考時才需要傳回思考區塊。否則您可以省略之前回合的思考區塊,或讓 API 為您過濾掉這些區塊。
  • 有時 Claude 的內部推理會被我們的安全系統標記。當這種情況發生時,我們會加密部分或全部 thinking 區塊,並以 redacted_thinking 區塊的形式返回給您。這些被編輯的思考區塊在傳回 API 時會被解密,讓 Claude 能夠在不失去上下文的情況下繼續其回應。

以下是顯示正常和被編輯的思考區塊的示例:

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

在您的輸出中看到被編輯的思考區塊是預期的行為。模型仍然可以使用這種被編輯的推理來形成其回應,同時維持安全防護。

如果您需要在應用程式中測試被編輯思考的處理,可以使用這個特殊的測試字串作為您的提示: ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB

當在多輪對話中將 thinkingredacted_thinking 區塊傳回 API 時,您必須將最後一個助理回合的完整未修改區塊包含在內。

這對於維持模型的推理流程至關重要。我們建議始終將所有思考區塊傳回 API。有關更多詳細信息,請參閱保留思考區塊部分。

在生產環境中處理被編輯思考的建議

在構建使用延伸思考的面向客戶的應用程式時:

  • 請注意被編輯的思考區塊包含不可人工閱讀的加密內容
  • 考慮提供簡單的解釋,例如:“Claude 的部分內部推理已出於安全原因自動加密。這不會影響回應的品質。”
  • 如果要向用戶展示思考區塊,您可以過濾掉被編輯的區塊,同時保留正常的思考區塊
  • 明確說明使用延伸思考功能可能偶爾會導致某些推理被加密
  • 實施適當的錯誤處理,以優雅地管理被編輯的思考而不破壞您的 UI

串流延伸思考

當啟用串流時,您將通過 thinking_delta 事件接收思考內容。以下是如何處理帶有思考的串流:

串流輸出示例:

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-3-7-sonnet-20250219", "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": "Let me solve this step by step:\n\n1. First break down 27 * 453"}}

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

// 額外的思考增量...

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

// 額外的文字增量...

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

關於帶有思考的串流行為

當使用帶有思考功能的串流時,您可能會注意到文字有時會以較大的塊狀形式到達,與較小的、逐標記傳遞交替出現。這是預期的行為,特別是對於思考內容。

串流系統需要批量處理內容以獲得最佳性能,這可能會導致這種”塊狀”傳遞模式。我們正在持續努力改善這種體驗,未來的更新將著重於使思考內容更流暢地串流。

redacted_thinking 區塊不會有任何增量相關聯,並且會作為單個事件發送。

使用延伸思考時的重要考慮事項

使用思考預算: 最小預算是 1,024 個標記。我們建議從最小值開始,逐步增加思考預算,以找到適合您使用案例的最佳範圍。較高的標記數可能讓您獲得更全面和細緻的推理,但根據任務的不同,可能也會有收益遞減的情況。

  • 思考預算是一個目標而不是嚴格的限制 - 實際標記使用量可能會根據任務而變化。
  • 由於推理過程需要額外的處理時間,請做好可能會有較長回應時間的準備。
  • max_tokens 大於 21,333 時,需要啟用串流。

對於超過 32K 的思考預算: 我們建議對思考預算設定在 32K 以上的工作負載使用批次處理,以避免網路問題。要求模型進行超過 32K 標記的思考會導致長時間運行的請求,可能會遇到系統超時和開放連接限制。

思考與其他功能的相容性:

  • 思考與 temperaturetop_ptop_k 修改以及強制工具使用不相容。
  • 當啟用思考時,您不能預填回應。
  • 對思考預算的更改會使包含訊息的快取提示前綴失效。但是,當思考參數改變時,快取的系統提示和工具定義仍然有效。

延伸思考的定價和標記使用

延伸思考標記計入上下文視窗並作為輸出標記計費。由於思考標記被視為正常的輸出標記,它們也計入您的速率限制。在規劃 API 使用時,請務必考慮到這種增加的標記使用量。

對於 Claude 3.7 Sonnet,定價如下:

標記使用成本
輸入標記$3 / MTok
輸出標記(包括思考標記)$15 / MTok
提示快取寫入$3.75 / MTok
提示快取讀取$0.30 / MTok

延伸思考的批次處理價格為這些價格的 50%,通常在不到 1 小時內完成。

所有延伸思考標記(包括被編輯的思考標記)都作為輸出標記計費,並計入您的速率限制。

在多輪對話中,與較早的助理訊息相關的思考區塊不會作為輸入標記計費。

當啟用延伸思考時,會自動包含一個專門的 28 或 29 個標記的系統提示以支援此功能。

延伸輸出功能(測試版)

Claude 3.7 Sonnet 可以產生比之前的模型長得多的回應,支援最多 128K 輸出標記(測試版)—比其他 Claude 模型長 15 倍以上。這種擴展的功能對於涉及複雜推理、豐富代碼生成和全面內容創建的延伸思考用例特別有效。

通過傳遞 anthropic-beta 標頭值 output-128k-2025-02-19 可以啟用此功能。

在使用較長輸出的延伸思考時,您可以分配較大的思考預算以支援更徹底的推理,同時仍有充足的標記可用於最終回應。

我們建議在使用這種延伸輸出功能時使用串流或批次模式;有關更多詳細信息,請參閱我們關於長請求的網路可靠性考慮指南。

將延伸思考與提示快取一起使用

帶有思考的提示快取有幾個重要的考慮事項:

快取提示中包含思考區塊

  • 思考只在生成助理回合時包含,不適合快取。
  • 忽略之前回合的思考區塊。
  • 如果思考被禁用,傳遞給 API 的任何思考內容都會被簡單地忽略。

快取失效規則

  • 對思考參數的更改(啟用/禁用或預算變更)會使訊息中設置的快取斷點失效。
  • 系統提示和工具即使在思考參數改變時也保持快取。

帶有延伸思考的提示快取示例

使用延伸思考時的最大標記數和上下文視窗大小

在較舊的 Claude 模型(在 Claude 3.7 Sonnet 之前),如果提示標記和 max_tokens 的總和超過了模型的上下文視窗,系統會自動調整 max_tokens 以適應上下文限制。這意味著您可以設置一個較大的 max_tokens 值,系統會根據需要靜默地減少它。

在 Claude 3.7 Sonnet 中,max_tokens(當啟用思考時包括您的思考預算)被強制執行為嚴格限制。如果提示標記 + max_tokens 超過上下文視窗大小,系統現在會返回驗證錯誤。

啟用延伸思考時如何計算上下文視窗

在啟用思考時計算上下文視窗使用量時,需要注意一些事項:

  • 之前回合的思考區塊會被剝離,不計入您的上下文視窗
  • 當前回合的思考計入該回合的 max_tokens 限制

下圖演示了啟用延伸思考時的專門標記管理:

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

上下文視窗 =
  (當前輸入標記 - 之前的思考標記) +
  (思考標記 + 被編輯的思考標記 + 文字輸出標記)

我們建議使用標記計數 API來獲取您特定使用案例的準確標記計數,特別是在處理包含思考的多輪對話時。

您可以閱讀我們的上下文視窗指南以獲得更深入的了解。

管理延伸思考的標記

鑑於像 Claude 3.7 Sonnet 這樣的延伸思考模型的新上下文視窗和 max_tokens 行為,您可能需要:

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

這種改變是為了提供更可預測和透明的行為,特別是在最大標記限制顯著增加的情況下。

延伸思考與工具使用

在將延伸思考與工具使用結合時,請注意以下行為模式:

  1. 第一個助理回合: 當您發送初始用戶訊息時,助理回應將包含思考區塊,然後是工具使用請求。

  2. 工具結果回合: 當您傳遞帶有工具結果區塊的用戶訊息時,後續的助理訊息將不包含任何額外的思考區塊。

具體來說,帶有思考的工具使用對話的正常順序遵循以下步驟:

  1. 用戶發送初始訊息
  2. 助理回應包含思考區塊和工具請求
  3. 用戶發送帶有工具結果的訊息
  4. 助理回應要麼包含更多工具調用,要麼只包含文字(此回應中沒有思考區塊)
  5. 如果請求更多工具,重複步驟 3-4 直到對話完成

這種設計允許 Claude 在發出工具請求之前展示其推理過程,但在接收工具結果後不重複思考過程。Claude 在下一個非 tool_resultuser 回合之前不會輸出另一個思考區塊。

下圖說明了在將延伸思考與工具使用結合時的上下文視窗標記管理:

保留思考區塊

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

雖然您可以省略之前 assistant 角色回合的 thinkingredacted_thinking 區塊,但我們建議在任何多輪對話中始終將所有思考區塊傳回 API。API 將:

  • 自動過濾提供的思考區塊
  • 使用必要的思考區塊來保持模型的推理
  • 只對顯示給 Claude 的區塊的輸入標記計費

為什麼必須保留思考區塊

當 Claude 調用工具時,它會暫停其回應構建以等待外部信息。當工具結果返回時,Claude 將繼續構建該現有回應。這需要在工具使用期間保留思考區塊,原因有二:

  1. 推理連續性: 思考區塊捕獲了導致工具請求的 Claude 逐步推理。當您發布工具結果時,包含原始思考確保 Claude 可以從它停止的地方繼續其推理。

  2. 上下文維護: 雖然工具結果在 API 結構中顯示為用戶訊息,但它們是連續推理流程的一部分。保留思考區塊在多個 API 調用中維持這種概念流程。

重要: 在提供 thinkingredacted_thinking 區塊時,連續的 thinkingredacted_thinking 區塊的整個序列必須與模型在原始請求期間生成的輸出相匹配;您不能重新排列或修改這些區塊的序列。

充分利用延伸思考模式的提示

要充分利用延伸思考:

  1. 設置適當的預算: 對於複雜任務,從較大的思考預算(16,000+ 標記)開始,並根據您的需求調整。

  2. 實驗思考標記預算: 模型在不同的最大思考預算設置下可能表現不同。增加最大思考預算可以讓模型思考得更好/更努力,但會增加延遲。對於關鍵任務,考慮測試不同的預算設置以找到品質和性能之間的最佳平衡。

  3. 您不需要自己移除之前的思考區塊: Anthropic API 會自動忽略之前回合的思考區塊,它們在計算上下文使用量時不會被包含。

  4. 監控標記使用: 跟踪思考標記使用情況以優化成本和性能。

  5. 將延伸思考用於特別複雜的任務: 為需要逐步推理的任務啟用思考,如數學、編碼和分析。

  6. 考慮延長回應時間: 考慮到生成思考區塊可能會增加整體回應時間。

  7. 適當處理串流: 在串流時,準備好處理思考和文字內容區塊的到來。

  8. 提示工程: 如果您想最大化 Claude 的思考能力,請查看我們的延伸思考提示技巧

下一步