使用延伸思考功能進行開發
延伸思考功能讓 Claude 3.7 Sonnet 在處理複雜任務時具有增強的推理能力,同時也能讓您看到它在提供最終答案前的逐步思考過程。
延伸思考的運作方式
當啟用延伸思考時,Claude 會創建 thinking
內容區塊來輸出其內部推理過程。Claude 會在形成最終回應前整合這些推理的見解。
API 回應會同時包含 thinking
和 text
內容區塊。
在多輪對話中,只有與工具使用階段或最後一條訊息位置的 assistant
回合相關的思考區塊對 Claude 可見並計入輸入標記;與較早的 assistant
訊息相關的思考區塊對 Claude 在採樣時不可見,也不會計入輸入標記。
實作延伸思考
在您的 API 請求中加入 thinking
參數和指定用於延伸思考的標記預算。
budget_tokens
參數決定了允許 Claude 用於內部推理過程的最大標記數。較大的預算可以通過為複雜問題啟用更全面的分析來改善回應品質,不過在超過 32K 的範圍時,Claude 可能不會使用全部分配的預算。
您的 budget_tokens
必須始終小於指定的 max_tokens
。
API 回應將包含思考和文字內容區塊:
理解思考區塊
思考區塊代表 Claude 的內部思考過程。為了讓 Claude 能夠在維持我們的安全標準和無狀態 API 的同時以最少的內部限制來解決問題,我們實施了以下措施:
- 思考區塊包含一個
signature
欄位。此欄位包含一個加密令牌,用於驗證思考區塊是由 Claude 生成的,並在思考區塊傳回 API 時進行驗證。在串流回應時,簽名會通過content_block_delta
事件中的signature_delta
在content_block_stop
事件之前添加。只有在使用工具與延伸思考時才需要傳回思考區塊。否則您可以省略之前回合的思考區塊,或讓 API 為您過濾掉這些區塊。 - 有時 Claude 的內部推理會被我們的安全系統標記。當這種情況發生時,我們會加密部分或全部
thinking
區塊,並以redacted_thinking
區塊的形式返回給您。這些被編輯的思考區塊在傳回 API 時會被解密,讓 Claude 能夠在不失去上下文的情況下繼續其回應。
以下是顯示正常和被編輯的思考區塊的示例:
在您的輸出中看到被編輯的思考區塊是預期的行為。模型仍然可以使用這種被編輯的推理來形成其回應,同時維持安全防護。
如果您需要在應用程式中測試被編輯思考的處理,可以使用這個特殊的測試字串作為您的提示: ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB
當在多輪對話中將 thinking
和 redacted_thinking
區塊傳回 API 時,您必須將最後一個助理回合的完整未修改區塊包含在內。
這對於維持模型的推理流程至關重要。我們建議始終將所有思考區塊傳回 API。有關更多詳細信息,請參閱保留思考區塊部分。
在生產環境中處理被編輯思考的建議
在構建使用延伸思考的面向客戶的應用程式時:
- 請注意被編輯的思考區塊包含不可人工閱讀的加密內容
- 考慮提供簡單的解釋,例如:“Claude 的部分內部推理已出於安全原因自動加密。這不會影響回應的品質。”
- 如果要向用戶展示思考區塊,您可以過濾掉被編輯的區塊,同時保留正常的思考區塊
- 明確說明使用延伸思考功能可能偶爾會導致某些推理被加密
- 實施適當的錯誤處理,以優雅地管理被編輯的思考而不破壞您的 UI
串流延伸思考
當啟用串流時,您將通過 thinking_delta
事件接收思考內容。以下是如何處理帶有思考的串流:
串流輸出示例:
關於帶有思考的串流行為
當使用帶有思考功能的串流時,您可能會注意到文字有時會以較大的塊狀形式到達,與較小的、逐標記傳遞交替出現。這是預期的行為,特別是對於思考內容。
串流系統需要批量處理內容以獲得最佳性能,這可能會導致這種”塊狀”傳遞模式。我們正在持續努力改善這種體驗,未來的更新將著重於使思考內容更流暢地串流。
redacted_thinking
區塊不會有任何增量相關聯,並且會作為單個事件發送。
使用延伸思考時的重要考慮事項
使用思考預算: 最小預算是 1,024 個標記。我們建議從最小值開始,逐步增加思考預算,以找到適合您使用案例的最佳範圍。較高的標記數可能讓您獲得更全面和細緻的推理,但根據任務的不同,可能也會有收益遞減的情況。
- 思考預算是一個目標而不是嚴格的限制 - 實際標記使用量可能會根據任務而變化。
- 由於推理過程需要額外的處理時間,請做好可能會有較長回應時間的準備。
- 當
max_tokens
大於 21,333 時,需要啟用串流。
對於超過 32K 的思考預算: 我們建議對思考預算設定在 32K 以上的工作負載使用批次處理,以避免網路問題。要求模型進行超過 32K 標記的思考會導致長時間運行的請求,可能會遇到系統超時和開放連接限制。
思考與其他功能的相容性:
- 思考與
temperature
、top_p
或top_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
值 - 可能需要更頻繁地使用標記計數端點
- 注意之前的思考區塊不會在您的上下文視窗中累積
這種改變是為了提供更可預測和透明的行為,特別是在最大標記限制顯著增加的情況下。
延伸思考與工具使用
在將延伸思考與工具使用結合時,請注意以下行為模式:
-
第一個助理回合: 當您發送初始用戶訊息時,助理回應將包含思考區塊,然後是工具使用請求。
-
工具結果回合: 當您傳遞帶有工具結果區塊的用戶訊息時,後續的助理訊息將不包含任何額外的思考區塊。
具體來說,帶有思考的工具使用對話的正常順序遵循以下步驟:
- 用戶發送初始訊息
- 助理回應包含思考區塊和工具請求
- 用戶發送帶有工具結果的訊息
- 助理回應要麼包含更多工具調用,要麼只包含文字(此回應中沒有思考區塊)
- 如果請求更多工具,重複步驟 3-4 直到對話完成
這種設計允許 Claude 在發出工具請求之前展示其推理過程,但在接收工具結果後不重複思考過程。Claude 在下一個非 tool_result
的 user
回合之前不會輸出另一個思考區塊。
下圖說明了在將延伸思考與工具使用結合時的上下文視窗標記管理:
保留思考區塊
在工具使用期間,您必須將 thinking
和 redacted_thinking
區塊傳回 API,並且必須包含完整的未修改區塊。這對於維持模型的推理流程和對話完整性至關重要。
雖然您可以省略之前 assistant
角色回合的 thinking
和 redacted_thinking
區塊,但我們建議在任何多輪對話中始終將所有思考區塊傳回 API。API 將:
- 自動過濾提供的思考區塊
- 使用必要的思考區塊來保持模型的推理
- 只對顯示給 Claude 的區塊的輸入標記計費
為什麼必須保留思考區塊
當 Claude 調用工具時,它會暫停其回應構建以等待外部信息。當工具結果返回時,Claude 將繼續構建該現有回應。這需要在工具使用期間保留思考區塊,原因有二:
-
推理連續性: 思考區塊捕獲了導致工具請求的 Claude 逐步推理。當您發布工具結果時,包含原始思考確保 Claude 可以從它停止的地方繼續其推理。
-
上下文維護: 雖然工具結果在 API 結構中顯示為用戶訊息,但它們是連續推理流程的一部分。保留思考區塊在多個 API 調用中維持這種概念流程。
重要: 在提供 thinking
或 redacted_thinking
區塊時,連續的 thinking
或 redacted_thinking
區塊的整個序列必須與模型在原始請求期間生成的輸出相匹配;您不能重新排列或修改這些區塊的序列。
充分利用延伸思考模式的提示
要充分利用延伸思考:
-
設置適當的預算: 對於複雜任務,從較大的思考預算(16,000+ 標記)開始,並根據您的需求調整。
-
實驗思考標記預算: 模型在不同的最大思考預算設置下可能表現不同。增加最大思考預算可以讓模型思考得更好/更努力,但會增加延遲。對於關鍵任務,考慮測試不同的預算設置以找到品質和性能之間的最佳平衡。
-
您不需要自己移除之前的思考區塊: Anthropic API 會自動忽略之前回合的思考區塊,它們在計算上下文使用量時不會被包含。
-
監控標記使用: 跟踪思考標記使用情況以優化成本和性能。
-
將延伸思考用於特別複雜的任務: 為需要逐步推理的任務啟用思考,如數學、編碼和分析。
-
考慮延長回應時間: 考慮到生成思考區塊可能會增加整體回應時間。
-
適當處理串流: 在串流時,準備好處理思考和文字內容區塊的到來。
-
提示工程: 如果您想最大化 Claude 的思考能力,請查看我們的延伸思考提示技巧。