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

延伸思考的運作方式

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

API 回應將包含 thinkingtext 內容區塊。

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

實作延伸思考

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

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

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

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 20000,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 16000
    },
    "messages": [
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?"
        }
    ]
}'

理解思考區塊

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

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

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

{
  "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。

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

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

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

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

串流延伸思考

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

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 20000,
    "stream": true,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 16000
    },
    "messages": [
        {
            "role": "user",
            "content": "What is 27 * 453?"
        }
    ]
}'

串流輸出範例:

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

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

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

關於思考的串流行為

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

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

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

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

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

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

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

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

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

延伸思考的定價和 token 使用

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

ModelBase Input TokensCache WritesCache HitsOutput Tokens
Claude Opus 3.8$15 / MTok$18.75 / MTok$1.50 / MTok$75 / MTok
Claude Sonnet 3.8$3 / MTok$3.75 / MTok$0.30 / MTok$15 / MTok
Claude 3.7 Sonnet$3 / MTok$3.75 / MTok$0.30 / MTok$15 / MTok

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

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

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

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

延伸輸出功能(測試版)

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

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

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: output-128k-2025-02-19" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 128000,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 32000
    },
    "messages": [
        {
            "role": "user",
            "content": "Generate a comprehensive analysis of..."
        }
    ],
    "stream": true
}'

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

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

使用延伸思考與提示快取

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

快取提示中包含思考區塊

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

快取失效規則

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

延伸思考與提示快取的範例