支援的模型
延伸思考在以下模型中受支援:- 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.1 (
claude-opus-4-1-20250805) - Claude Opus 4 (
claude-opus-4-20250514)
API 行為在 Claude Sonnet 3.7 和 Claude 4 模型之間有所不同,但 API 形狀保持完全相同。如需更多資訊,請參閱不同模型版本間的思考差異。
延伸思考的工作原理
當延伸思考開啟時,Claude 會建立thinking 內容區塊,其中輸出其內部推理。Claude 在製作最終回應之前會納入此推理中的見解。
API 回應將包括 thinking 內容區塊,後面跟著 text 內容區塊。
以下是預設回應格式的範例:
如何使用延伸思考
以下是在訊息 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 模型的輕鬆遷移。
- 摘要化由與您在請求中指定的模型不同的模型處理。思考模型看不到摘要輸出。
Claude Sonnet 3.7 繼續傳回完整思考輸出。在罕見情況下,如果您需要存取 Claude 4 模型的完整思考輸出,請聯絡我們的銷售團隊。
串流思考
您可以使用伺服器傳送事件 (SSE) 串流延伸思考回應。 當為延伸思考啟用串流時,您會透過thinking_delta 事件接收思考內容。
如需更多關於透過訊息 API 進行串流的文件,請參閱串流訊息。
以下是如何處理思考串流的方法:
當使用啟用思考的串流時,您可能會注意到文字有時以較大的塊到達,交替進行較小的逐代幣傳遞。這是預期的行為,特別是對於思考內容。串流系統需要以批次方式處理內容以獲得最佳效能,這可能導致這種「分塊」傳遞模式,串流事件之間可能有延遲。我們正在持續努力改進這種體驗,未來的更新將專注於使思考內容流式傳輸更順暢。
延伸思考與工具使用
延伸思考可以與工具使用一起使用,允許 Claude 推理工具選擇和結果處理。 當使用延伸思考與工具使用時,請注意以下限制:-
工具選擇限制:思考工具使用僅支援
tool_choice: {"type": "auto"}(預設) 或tool_choice: {"type": "none"}。使用tool_choice: {"type": "any"}或tool_choice: {"type": "tool", "name": "..."}將導致錯誤,因為這些選項強制工具使用,與延伸思考不相容。 -
保留思考區塊:在工具使用期間,您必須將
thinking區塊傳回 API 以用於最後的助手訊息。將完整的未修改區塊傳回 API 以維持推理連續性。
在對話中切換思考模式
您無法在助手轉向中間切換思考,包括在工具使用迴圈期間。整個助手轉向必須在單一思考模式中運作:- 如果啟用思考,最終助手轉向必須以思考區塊開始。
- 如果停用思考,最終助手轉向不得包含任何思考區塊
常見錯誤情景
您可能會遇到此錯誤:- 您在工具使用序列期間停用了思考
- 您想再次啟用思考
- 您的最後助手訊息包含工具使用區塊但沒有思考區塊
實用指南
✗ 無效:在工具使用後立即切換思考切換思考模式也會使提示快取對訊息歷史記錄無效。如需更多詳細資訊,請參閱延伸思考與提示快取部分。
範例:使用工具結果傳遞思考區塊
範例:使用工具結果傳遞思考區塊
以下是一個實際範例,展示在提供工具結果時如何保留思考區塊:API 回應將包括思考、文字和 tool_use 區塊:現在讓我們繼續對話並使用工具API 回應現在僅包括文字
保留思考區塊
在工具使用期間,您必須將thinking 區塊傳回 API,並且必須將完整的未修改區塊傳回 API。這對於維持模型的推理流和對話完整性至關重要。
雖然您可以從先前的
assistant 角色轉向中省略 thinking 區塊,但我們建議始終將所有思考區塊傳回 API 以進行任何多轉向對話。API 將:- 自動篩選提供的思考區塊
- 使用必要的相關思考區塊來保留模型的推理
- 僅對顯示給 Claude 的區塊計費輸入代幣
在對話期間切換思考模式時,請記住整個助手轉向(包括工具使用迴圈)必須在單一思考模式中運作。如需更多詳細資訊,請參閱在對話中切換思考模式。
- 推理連續性:思考區塊捕捉了導致工具請求的 Claude 逐步推理。當您發佈工具結果時,包括原始思考可確保 Claude 可以從中斷的地方繼續推理。
- 上下文維護:雖然工具結果在 API 結構中顯示為使用者訊息,但它們是連續推理流的一部分。保留思考區塊在多個 API 呼叫中維持這個概念流。如需更多關於上下文管理的資訊,請參閱我們的上下文視窗指南。
thinking 區塊時,連續 thinking 區塊的整個序列必須符合模型在原始請求期間生成的輸出;您無法重新排列或修改這些區塊的序列。
交錯思考
Claude 4 模型中的延伸思考與工具使用支援交錯思考,這使 Claude 能夠在工具呼叫之間進行思考,並在接收工具結果後進行更複雜的推理。 透過交錯思考,Claude 可以:- 在決定下一步之前推理工具呼叫的結果
- 在推理步驟之間鏈接多個工具呼叫
- 根據中間結果做出更細緻的決定
interleaved-thinking-2025-05-14 新增至您的 API 請求。
以下是交錯思考的一些重要考慮事項:
- 使用交錯思考時,
budget_tokens可以超過max_tokens參數,因為它代表一個助手轉向內所有思考區塊的總預算。 - 交錯思考僅支援透過訊息 API 使用的工具。
- 交錯思考僅支援 Claude 4 模型,使用 beta 標頭
interleaved-thinking-2025-05-14。 - 直接呼叫 Claude API 允許您將
interleaved-thinking-2025-05-14傳遞到任何模型的請求中,沒有任何效果。 - 在第三方平台上(例如 Amazon Bedrock 和 Vertex AI),如果您將
interleaved-thinking-2025-05-14傳遞到除 Claude Opus 4.1、Opus 4 或 Sonnet 4 之外的任何模型,您的請求將失敗。
不使用交錯思考的工具使用
不使用交錯思考的工具使用
- Claude 在開始時思考一次以理解任務
- 預先做出所有工具使用決定
- 當工具結果返回時,Claude 立即提供回應而不進行額外思考
使用交錯思考的工具使用
使用交錯思考的工具使用
- Claude 最初思考任務
- 收到計算機結果後,Claude 可以再次思考該結果的含義
- Claude 然後根據第一個結果決定如何查詢資料庫
- 收到資料庫結果後,Claude 再思考一次兩個結果,然後制定最終回應
- 思考預算分佈在轉向內的所有思考區塊中
延伸思考與提示快取
提示快取與思考有幾個重要考慮事項:延伸思考任務通常需要超過 5 分鐘才能完成。考慮使用1 小時快取期限來維持跨越較長思考會話和多步驟工作流的快取命中。
- 來自先前轉向的思考區塊會從上下文中移除,這可能會影響快取斷點
- 在使用工具繼續對話時,思考區塊會被快取並在從快取讀取時計為輸入代幣
- 這造成了權衡:雖然思考區塊在視覺上不消耗上下文視窗空間,但在快取時仍計入您的輸入代幣使用量
- 如果思考被停用,如果您在目前工具使用轉向中傳遞思考內容,請求將失敗。在其他情況下,傳遞給 API 的思考內容會被忽略
理解思考區塊快取行為
當使用延伸思考與工具使用時,思考區塊表現出特定的快取行為,影響代幣計數: 工作原理:- 快取僅在您進行包含工具結果的後續請求時發生
- 進行後續請求時,先前的對話歷史記錄(包括思考區塊)可以被快取
- 這些快取的思考區塊在從快取讀取時計為您的使用指標中的輸入代幣
- 當包含非工具結果使用者區塊時,所有先前的思考區塊都會被忽略並從上下文中移除
- 即使沒有明確的
cache_control標記,此快取行為也會自動發生 - 無論使用常規思考還是交錯思考,此行為都是一致的
系統提示快取(在思考變化時保留)
系統提示快取(在思考變化時保留)
訊息快取(在思考變化時失效)
訊息快取(在思考變化時失效)
cache_creation_input_tokens=1370 和 cache_read_input_tokens=0,證明當思考參數變化時訊息快取無效。延伸思考的最大代幣和上下文視窗大小
在較舊的 Claude 模型(Claude Sonnet 3.7 之前)中,如果提示代幣和max_tokens 的總和超過模型的上下文視窗,系統會自動調整 max_tokens 以適應上下文限制。這意味著您可以設定一個大的 max_tokens 值,系統會根據需要自動減少它。
使用 Claude 3.7 和 4 模型,max_tokens(啟用思考時包括您的思考預算)被強制執行為嚴格限制。如果提示代幣 + max_tokens 超過上下文視窗大小,系統現在將傳回驗證錯誤。
您可以閱讀我們的上下文視窗指南以進行更徹底的深入探討。
延伸思考的上下文視窗
計算啟用思考時的上下文視窗使用量時,需要注意一些事項:- 來自先前轉向的思考區塊被移除,不計入您的上下文視窗
- 目前轉向思考計入該轉向的
max_tokens限制
延伸思考與工具使用的上下文視窗
當使用延伸思考與工具使用時,思考區塊必須明確保留並與工具結果一起返回。 延伸思考與工具使用的有效上下文視窗計算變為:使用延伸思考管理代幣
鑑於 Claude 3.7 和 4 模型的上下文視窗和max_tokens 行為,您可能需要:
- 更積極地監控和管理您的代幣使用
- 隨著提示長度的變化調整
max_tokens值 - 可能更頻繁地使用代幣計數端點
- 意識到先前的思考區塊不會在您的上下文視窗中累積
思考加密
完整思考內容被加密並在signature 欄位中返回。此欄位用於驗證思考區塊是否由 Claude 生成,當傳回 API 時。
僅當使用帶延伸思考的工具時才嚴格必要傳回思考區塊。否則您可以從先前的轉向中省略思考區塊,或讓 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 區塊是預期的行為。模型仍然可以使用此 redacted 推理來通知其回應,同時維持安全護欄。如果您需要在應用程式中測試 redacted thinking 處理,可以使用此特殊測試字串作為提示:
ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CBthinking 和 redacted_thinking 區塊傳回 API 時,您必須將完整的未修改區塊傳回 API 以用於最後的助手轉向。這對於維持模型的推理流至關重要。我們建議始終將所有思考區塊傳回 API。如需更多詳細資訊,請參閱上面的保留思考區塊部分。
範例:使用 redacted thinking 區塊
範例:使用 redacted thinking 區塊
不同模型版本間的思考差異
訊息 API 在 Claude Sonnet 3.7 和 Claude 4 模型之間以不同方式處理思考,主要是在編輯和摘要行為方面。 請參閱下表以進行簡明比較:| 功能 | Claude Sonnet 3.7 | Claude 4 模型 |
|---|---|---|
| 思考輸出 | 傳回完整思考輸出 | 傳回摘要思考 |
| 交錯思考 | 不支援 | 使用 interleaved-thinking-2025-05-14 beta 標頭支援 |
定價
延伸思考使用標準代幣定價方案:| 模型 | 基本輸入代幣 | 快取寫入 | 快取命中 | 輸出代幣 |
|---|---|---|---|---|
| Claude Opus 4.1 | $15 / MTok | $18.75 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Opus 4 | $15 / MTok | $18.75 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Sonnet 4.5 | $3 / MTok | $3.75 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 4 | $3 / MTok | $3.75 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 3.7 | $3 / MTok | $3.75 / MTok | $0.30 / MTok | $15 / MTok |
- 思考期間使用的代幣(輸出代幣)
- 後續請求中包含的最後助手轉向的思考區塊(輸入代幣)
- 標準文字輸出代幣
啟用延伸思考時,會自動包含專門的系統提示以支援此功能。
- 輸入代幣:原始請求中的代幣(不包括先前轉向的思考代幣)
- 輸出代幣(計費):Claude 內部生成的原始思考代幣
- 輸出代幣(可見):您在回應中看到的摘要思考代幣
- 無費用:用於生成摘要的代幣
計費的輸出代幣計數將不符合回應中的可見代幣計數。您需要為完整思考過程付費,而不是您看到的摘要。
延伸思考的最佳實踐和考慮事項
使用思考預算
- 預算最佳化:最小預算為 1,024 代幣。我們建議從最小值開始,逐步增加思考預算以找到您的用例的最佳範圍。較高的代幣計數可實現更全面的推理,但根據任務的不同會有遞減的回報。增加預算可以改善回應品質,但代價是增加延遲。對於關鍵任務,測試不同的設定以找到最佳平衡。請注意,思考預算是目標而不是嚴格限制 - 實際代幣使用可能因任務而異。
- 起點:為複雜任務從較大的思考預算(16k+ 代幣)開始,並根據您的需求進行調整。
- 大型預算:對於超過 32k 的思考預算,我們建議使用批次處理以避免網路問題。推動模型思考超過 32k 代幣的請求會導致長時間運行的請求,可能會遇到系統超時和開放連接限制。
- 代幣使用追蹤:監控思考代幣使用以最佳化成本和效能。
效能考慮
- 回應時間:為推理過程所需的額外處理做好準備,可能導致更長的回應時間。考慮生成思考區塊可能會增加整體回應時間。
- 串流要求:當
max_tokens大於 21,333 時需要串流。串流時,準備好處理思考和文字內容區塊,因為它們到達。
功能相容性
- 思考與
temperature或top_k修改以及強制工具使用不相容。 - 啟用思考時,您可以將
top_p設定為 1 到 0.95 之間的值。 - 啟用思考時無法預填充回應。
- 思考預算的變化會使包含訊息的快取提示前綴無效。但是,快取系統提示和工具定義在思考參數變化時將繼續工作。
使用指南
- 任務選擇:對特別複雜的任務使用延伸思考,這些任務受益於逐步推理,如數學、編碼和分析。
- 上下文處理:您不需要自己移除先前的思考區塊。Claude API 自動忽略先前轉向的思考區塊,在計算上下文使用時不包括它們。
- 提示工程:如果您想最大化 Claude 的思考能力,請查看我們的延伸思考提示提示。