--- title: 擴展思考 url: https://platform.claude.com/docs/zh-TW/build-with-claude/extended-thinking description: 在支援的 Claude 模型上以固定的 budget_tokens 預算設定手動擴展思考，並遷移至自適應思考。 --- 若要了解「zero data retention」（零資料保留），即 ZDR 如何適用於此功能，請參閱 [API 與資料保留](https://platform.claude.com/docs/zh-TW/manage-claude/api-and-data-retention)。「Extended thinking」（擴展思考）（`thinking.type: "enabled"` 搭配 `budget_tokens`）在 Claude 4.6 模型上已被棄用（使用它的請求仍會成功）。Claude 4.7 及更新的模型不支援它，並會拒絕使用它的請求，回傳 400 錯誤。在支援思考功能的 Claude 4.5 及更早的模型上，擴展思考是唯一可用的思考模式。Claude Mythos Preview 同時支援兩種模式。在兩種模式皆可用的情況下，請改用[「adaptive thinking」（自適應思考）](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking)。請參閱[遷移至自適應思考](https://platform.claude.com/docs/zh-TW/build-with-claude/extended-thinking#migrating-to-adaptive-thinking)以改用自適應思考。如果您的模型僅支援擴展思考，本頁說明了所支援的設定；在您改用較新的模型之前，無需進行任何變更。如果請求失敗並回傳 400 錯誤，且其訊息以 `"thinking.type.enabled" is not supported` 開頭，表示您的模型改用自適應思考。請參閱[思考疑難排解](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking-troubleshooting#error-thinking-type-enabled)，或直接跳至[遷移至自適應思考](https://platform.claude.com/docs/zh-TW/build-with-claude/extended-thinking#migrating-to-adaptive-thinking)。手動模式下的「extended thinking」（擴展思考）讓您能直接控制 Claude 思考的程度。您可以在每個請求上透過 `thinking: {type: "enabled", budget_tokens: N}` 設定思考 token 預算，Claude 會在開始產生最終答案之前依據該預算進行思考。當您的工作負載需要可預測的延遲或對思考成本的精確控制時，手動模式仍然很有用。本頁涵蓋如何設定與調整預算、手動模式如何與交錯思考及「prompt caching」（提示快取）互動，以及如何遷移至自適應思考。若要了解思考本身的運作方式，包括思考區塊與回應結構、`display` 參數、「streaming」（串流）、搭配「tool use」（工具使用）的思考，以及加密，請參閱[思考概覽](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking)。 ## 支援的模型各模型的擴展思考可用性，包括擴展思考為唯一模式的模型，列於[各模型設定表](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking-troubleshooting#supported-models)中。 ## 如何使用擴展思考以下是在 Messages API 中使用擴展思考的範例： ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-4-6", "max_tokens": 16000, "thinking": { "type": "enabled", "budget_tokens": 10000 }, "messages": [ { "role": "user", "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?" } ] }' ``` ```bash CLI ant messages create \ --format yaml <<'YAML' model: claude-sonnet-4-6 max_tokens: 16000 thinking: type: enabled budget_tokens: 10000 messages: - role: user content: Are there an infinite number of prime numbers such that n mod 4 == 3? YAML ``` ```python Python client = anthropic.Anthropic() response = client.messages.create( model="claude-sonnet-4-6", max_tokens=16000, thinking={"type": "enabled", "budget_tokens": 10000}, messages=[ { "role": "user", "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?", } ], ) # 回應包含摘要化的思考區塊與文字區塊 for block in response.content: match block.type: case "thinking": print(f"\nThinking summary: {block.thinking}") case "text": print(f"\nResponse: {block.text}") ``` ```typescript TypeScript const client = new Anthropic(); const response = await client.messages.create({ model: "claude-sonnet-4-6", max_tokens: 16000, thinking: { type: "enabled", budget_tokens: 10000 }, messages: [ { role: "user", content: "Are there an infinite number of prime numbers such that n mod 4 == 3?" } ] }); // 回應包含摘要化的思考區塊與文字區塊 for (const block of response.content) { switch (block.type) { case "thinking": console.log(`\nThinking summary: ${block.thinking}`); break; case "text": console.log(`\nResponse: ${block.text}`); break; } } ``` ```csharp C# AnthropicClient client = new(); var response = await client.Messages.Create(new() { Model = Model.ClaudeSonnet4_6, MaxTokens = 16000, Thinking = new ThinkingConfigEnabled(budgetTokens: 10000), Messages = [ new() { Role = Role.User, Content = "Are there an infinite number of prime numbers such that n mod 4 == 3?", }, ], }); // 回應包含摘要化的思考區塊與文字區塊 foreach (var block in response.Content) { if (block.TryPickThinking(out var thinking)) { Console.WriteLine($"\nThinking summary: {thinking.Thinking}"); } else if (block.TryPickText(out var text)) { Console.WriteLine($"\nResponse: {text.Text}"); } } ``` ```go Go client := anthropic.NewClient() response, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeSonnet4_6, MaxTokens: 16000, Thinking: anthropic.ThinkingConfigParamOfEnabled(10000), Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Are there an infinite number of prime numbers such that n mod 4 == 3?")), }, }) if err != nil { log.Fatal(err) } // 回應包含摘要化的思考區塊與文字區塊 for _, block := range response.Content { switch block := block.AsAny().(type) { case anthropic.ThinkingBlock: fmt.Printf("\nThinking summary: %s", block.Thinking) case anthropic.TextBlock: fmt.Printf("\nResponse: %s", block.Text) } } ``` ```java Java import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; void main() { var client = AnthropicOkHttpClient.fromEnv(); var params = MessageCreateParams.builder() .model(Model.CLAUDE_SONNET_4_6) .maxTokens(16_000) .enabledThinking(10_000) .addUserMessage("Are there an infinite number of prime numbers such that n mod 4 == 3?") .build(); var response = client.messages().create(params); // 回應包含摘要化的思考區塊與文字區塊 for (var block : response.content()) { block.thinking().ifPresent(thinkingBlock -> IO.println("\nThinking summary: " + thinkingBlock.thinking()) ); block.text().ifPresent(textBlock -> IO.println("\nResponse: " + textBlock.text()) ); } } ``` ```php PHP $client = new Client(); $response = $client->messages->create( model: 'claude-sonnet-4-6', maxTokens: 16000, thinking: ['type' => 'enabled', 'budget_tokens' => 10000], messages: [ [ 'role' => 'user', 'content' => 'Are there an infinite number of prime numbers such that n mod 4 == 3?', ], ], ); // 回應包含摘要化的思考區塊與文字區塊 foreach ($response->content as $block) { echo match (true) { $block instanceof \Anthropic\Messages\ThinkingBlock => "\nThinking summary: {$block->thinking}", $block instanceof \Anthropic\Messages\TextBlock => "\nResponse: {$block->text}", default => '', }; } ``` ```ruby Ruby client = Anthropic::Client.new response = client.messages.create( model: "claude-sonnet-4-6", max_tokens: 16_000, thinking: { type: :enabled, budget_tokens: 10_000 }, messages: [ { role: :user, content: "Are there an infinite number of prime numbers such that n mod 4 == 3?" } ] ) # 回應包含摘要化的思考區塊與文字區塊 response.content.each do |block| case block when Anthropic::Models::ThinkingBlock puts "\nThinking summary: #{block.thinking}" when Anthropic::Models::TextBlock puts "\nResponse: #{block.text}" end end ``` 若要開啟手動擴展思考，請新增一個 `thinking` 物件，將 `type` 設為 `enabled`，並提供 `budget_tokens` 值。 `budget_tokens` 參數設定了 Claude 可用於其內部推理過程的 token 數量目標。較大的預算可透過對複雜問題進行更徹底的分析來提升回應品質。 ## 預算規則與調整 `budget_tokens` 必須滿足以下限制： * **最少 1,024 個 token。** API 會拒絕較小的值。 * **小於 `max_tokens`。** 思考 token 會計入該輪次的 `max_tokens` 限制，因此預算必須為最終回應保留空間。唯一的例外是[交錯思考](https://platform.claude.com/docs/zh-TW/build-with-claude/extended-thinking#interleaved-thinking)，在該情況下 `budget_tokens` 可以超過 `max_tokens`，因為預算涵蓋單一助手輪次內的所有思考區塊。 * **不支援快取預熱。** 由於 `budget_tokens` 必須小於 `max_tokens`，擴展思考無法與 `max_tokens: 0`（[快取預熱](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching#pre-warming-the-cache)）結合使用。預算是一個目標，而非嚴格的上限。實際的 token 使用量會因任務而異，Claude 可能在預算耗盡之前就停止推理；`max_tokens` 仍是總輸出的硬性上限。在 Claude Opus 4.5 上（這是唯一支援 [effort](https://platform.claude.com/docs/zh-TW/build-with-claude/effort) 的僅限擴展思考模型），effort 會塑造整體回應，而 `budget_tokens` 則設定思考深度；請同時設定兩者。若要調整預算： * 讓起始點與任務相符。對於簡單任務，從接近 1,024 個 token 的最小值開始，並逐步增加以找出適合您使用情境的最佳範圍。對於複雜任務，從 16,000 個 token 或更多的較大預算開始，並依您的延遲與品質需求進行調整。較高的預算可實現更全面的推理，但其邊際效益遞減的程度取決於任務，且代價是延遲增加。對於關鍵任務，請測試不同的設定以找出適當的平衡。 * 對於超過 32k 的思考預算，請使用[批次處理](https://platform.claude.com/docs/zh-TW/build-with-claude/batch-processing)以避免網路問題。促使模型思考超過 32k 個 token 會產生長時間執行的請求，可能觸及系統逾時與開放連線數限制。若要追蹤預算實際花費了多少，請監控回應中的 `usage.output_tokens_details.thinking_tokens` 欄位，該欄位會回報計費的輸出 token 中有多少屬於內部推理。在串流時，此細項僅會出現在最後的 `message_delta` 事件中。當您準備好不再使用手動預算時，請參閱[遷移至自適應思考](https://platform.claude.com/docs/zh-TW/build-with-claude/extended-thinking#migrating-to-adaptive-thinking)。 ## 手動模式下的交錯思考「Interleaved thinking」（交錯思考）讓 Claude 能在單一助手輪次內的工具呼叫之間進行思考，在決定下一步之前先對每個工具結果進行推理。關於其概念、輪次結構，以及它在自適應思考模型上的行為，請參閱思考概覽中的[交錯思考](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#interleaved-thinking)。本節說明在使用手動 `type: "enabled"` 思考時如何啟用它。在 Claude Opus 4.5、Claude Sonnet 4.5（已棄用）以及更早的 Claude 4 模型上，請在您的 API 請求中加入 `interleaved-thinking-2025-05-14` [beta 標頭](https://platform.claude.com/docs/zh-TW/api/beta-headers)。 4.6 世代在手動模式下有所分歧： * **Claude Sonnet 4.6**：搭配手動 `type: "enabled"` 的 beta 標頭仍可運作，但已棄用。建議改用[自適應思考](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking)，它會自動交錯且無需標頭。 * **Claude Opus 4.6**：手動模式完全沒有交錯思考。只有其自適應模式會交錯，因此如果您在此模型上需要在工具呼叫之間進行推理，請切換至 `thinking: {type: "adaptive"}`。 Claude Haiku 4.5 不支援交錯思考。在 Claude API 上，該 beta 標頭會被接受但忽略。手動模式下交錯思考的另外兩項注意事項： * 此處 `budget_tokens` 可以超過 `max_tokens`；[預算規則](https://platform.claude.com/docs/zh-TW/build-with-claude/extended-thinking#budget-rules-and-tuning)說明了此例外。 * 交錯思考僅支援[透過 Messages API 使用的工具](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/overview)。各平台處理 beta 標頭的方式有所不同。Claude API 與 [Claude Platform on AWS](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-platform-on-aws) 在任何模型上都接受 `interleaved-thinking-2025-05-14`，並在不支援的情況下忽略它。接受並不等同於生效：在拒絕 `type: "enabled"` 的模型（4.7 及更新版本）或缺乏手動模式交錯的模型（Claude Opus 4.6）上，該標頭在手動模式下沒有任何效果；在這些模型上，自適應思考會自動交錯。由合作夥伴營運的平台（[Amazon Bedrock](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-in-amazon-bedrock) 與 [Google Cloud](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-on-vertex-ai)）同樣在任何模型上接受該標頭而不回傳錯誤，並在不支援交錯思考的模型上忽略它。 ## 手動模式下的輪次結構一般的輪次結構規則，包括單輪次工具使用迴圈、輪次中途的衝突處理，以及在輪次之間切換思考，請參閱[搭配工具使用的思考](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#thinking-with-tool-use)。手動模式增加了一項要求：啟用思考的請求中，最後一個助手輪次必須以思考區塊開頭（[自適應思考](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking)取消了此要求）。在輪次之間變更思考設定也會使提示快取失效；請參閱下一節。 ## 手動模式下的提示快取在[思考與提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#thinking-and-prompt-caching)中所述的與模式無關的快取行為之上，手動模式增加了一條規則：在請求之間變更 `budget_tokens` 會使快取斷點失效，就如同切換思考模式一樣，因為預算值會被渲染到提示中。訊息層級的斷點在預算變更後一定會未命中；工具與系統提示的斷點是否也會未命中，則取決於模型在何處渲染該設定。實務上，請選定一個預算，並在快取對話的整個生命週期內保持穩定。在 Claude Sonnet 4.6 上執行一個使用訊息層級快取的多輪對話，並在第三個請求時將預算從 4,000 變更為 8,000 個 token，可直接觀察到失效情形： ```text Output wrap First request - establishing cache First response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 17, output_tokens: 700 } Second request - same thinking parameters (cache hit expected) Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 1370, input_tokens: 303, output_tokens: 874 } Third request - different thinking budget (cache miss expected) Third response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 747, output_tokens: 619 } ``` 第三個請求重新建立了快取（`cache_creation_input_tokens=1370`、`cache_read_input_tokens=0`），因為預算在請求之間發生了變更。若要查看同一實驗在自適應模式下的可執行版本（其中 effort 等級扮演了此處 `budget_tokens` 所扮演的快取角色），請參閱引導頁面上的[提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking-steering-and-cost#prompt-caching)。 ## 共通機制大多數思考行為與模式無關，並統一記載於[思考](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking)頁面。該頁面的所有內容同樣適用於手動模式： * [控制思考顯示](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#controlling-thinking-display) * [串流思考](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#streaming-thinking) * [搭配工具使用的思考](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#thinking-with-tool-use)，包括[保留思考區塊](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#preserving-thinking-blocks) * [思考與提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#thinking-and-prompt-caching) * [思考與上下文視窗](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#thinking-and-the-context-window) * [思考加密](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#thinking-encryption) * [定價](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking-steering-and-cost#pricing)（位於[引導思考](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking-steering-and-cost)頁面） ## 遷移至自適應思考如果您的模型僅支援擴展思考（Claude Sonnet 4.5（已棄用）、Claude Opus 4.5、Claude Haiku 4.5 以及更早的 Claude 4 模型），目前無需採取任何行動：這些模型不提供自適應思考，且 `type: "adaptive"` [會回傳 400 錯誤](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking-troubleshooting#error-thinking-type-adaptive)。請繼續使用 `budget_tokens`，直到您改用支援自適應思考的模型，再套用以下的對應方式。在以下情況下，您需要從 `type: "enabled"` 遷移： * 您使用 Claude Opus 4.6 或 Claude Sonnet 4.6，這些模型上的 `budget_tokens` 已被棄用。 * 您使用 Claude 4.7 或更新的模型，例如 Claude Opus 5.5、Claude Sonnet 5、Claude Sonnet 5.5、Claude Fable 5.1 或 Claude Haiku 5.5，其中 `type: "enabled"` 會回傳 400 錯誤。對應方式很簡單：移除 `budget_tokens`，設定 `thinking: {type: "adaptive"}`，並以 `output_config: {effort: ...}` 取代 token 預算來控制推理深度。 ```json { "model": "claude-sonnet-4-6", "max_tokens": 16000, "thinking": { "type": "enabled", "budget_tokens": 10000 } } ``` 變為： ```json { "model": "claude-sonnet-4-6", "max_tokens": 16000, "thinking": { "type": "adaptive" }, "output_config": { "effort": "high" } } ``` `effort: "high"` 是 Claude Sonnet 4.6 的預設值，因此在此省略它會產生相同的行為；此處列出它只是為了說明自適應模式中深度控制的位置。Claude Opus 5.5 與 Claude Haiku 5.5 的預設值為 `"medium"`，其他支援 effort 的模型預設值為 `"high"`（請參閱 [Effort 等級](https://platform.claude.com/docs/zh-TW/build-with-claude/effort#effort-levels)）。請預期行為上的差異，而不僅是語法上的變更。使用固定預算時，Claude 在每個請求中都會思考。使用自適應思考時，Claude 會在每個請求中決定是否思考以及思考多少，而在較低的 [effort](https://platform.claude.com/docs/zh-TW/build-with-claude/effort) 設定下，對於簡單的輸入可能會完全略過思考。遷移後，您也可以移除 `interleaved-thinking-2025-05-14` beta 標頭：自適應思考會自動交錯思考，且 Claude API 在這些模型上會忽略該標頭。思考區塊的保留方式也會改變：Claude Opus 4.5 以及編號 4.6 及更高的模型會將先前輪次的思考區塊保留在上下文中並以輸入計費，而 Claude Sonnet 4.5（已棄用）、Claude Haiku 4.5 及更早的模型則會將其移除；請參閱[各模型的思考區塊保留方式](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#thinking-block-preservation-by-model)。切換模式屬於思考設定變更，因此切換後的第一個請求會使快取斷點失效，如[手動模式下的提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/extended-thinking#extended-thinking-with-prompt-caching)中所述。如需完整指引，請參閱[自適應思考](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking)、[effort](https://platform.claude.com/docs/zh-TW/build-with-claude/effort) 以及[模型遷移指南](https://platform.claude.com/docs/zh-TW/about-claude/models/migration-guide)。 ## 後續步驟了解思考的運作方式：區塊、顯示、串流與工具使用。讓 Claude 在每個請求中決定何時思考以及思考多少。保留思考區塊，並在工具呼叫與輪次之間管理思考。