遷移指南

遷移到 Claude Opus 4.7

Claude Opus 4.7 是我們迄今為止最強大的通用可用模型。它具有高度自主性，在長期代理工作、知識工作、視覺任務和記憶任務方面表現出色。Claude Opus 4.7 應該在現有的 Claude Opus 4.6 提示和評估上具有強大的開箱即用性能，定價相同為 $5 / $25 每 MTok，但在遷移時有一些值得了解的行為和 API 變更。它支援與 Claude Opus 4.6 相同的功能集，包括 1M 代幣上下文視窗（標準 API 定價，無長上下文溢價）、128k 最大輸出代幣、自適應思考、提示快取、批次處理、Files API、PDF 支援、視覺和完整的伺服器端和用戶端工具集（bash、程式碼執行、電腦使用、文字編輯器、網路搜尋、網路擷取、MCP 連接器、記憶）。

/claude-api migrate this project to claude-opus-4-7

更新您的模型名稱

# Opus 遷移
model = "claude-opus-4-6"  # 之前
model = "claude-opus-4-7"  # 之後

破壞性變更

1. 擴展思考已移除： thinking: {type: "enabled", budget_tokens: N} 在 Claude Opus 4.7 或更新版本的模型上不再受支援，並返回 400 錯誤。切換到 自適應思考（thinking: {type: "adaptive"}）並使用 工作量參數 來控制思考深度。自適應思考在 Claude Opus 4.7 上預設關閉：沒有 thinking 欄位的請求在沒有思考的情況下執行，與 Opus 4.6 行為相符。明確設定 thinking: {type: "adaptive"} 以啟用它。

   之前（Claude Opus 4.6）：

   client.messages.create(
       model="claude-opus-4-6",
       max_tokens=64000,
       thinking={"type": "enabled", "budget_tokens": 32000},
       messages=[{"role": "user", "content": "..."}],
   )

   之後（Claude Opus 4.7）：

   client.messages.create(
       model="claude-opus-4-7",
       max_tokens=64000,
       thinking={"type": "adaptive"},
       output_config={"effort": "high"},  # 或 "max"、"xhigh"、"medium"、"low"
       messages=[{"role": "user", "content": "..."}],
   )

   自適應思考可透過提示進行調整。有關調整模型過度或不足思考時的指導，請參閱 校準工作量和思考深度。

2. 採樣參數已移除： 在 Claude Opus 4.7 上將 temperature、top_p 或 top_k 設定為任何非預設值會返回 400 錯誤。最安全的遷移路徑是從請求有效負載中完全省略這些參數。提示是在 Claude Opus 4.7 上引導模型行為的推薦方式。如果您使用 temperature = 0 以確保確定性，請注意它從未保證先前模型上的相同輸出。

3. 思考內容預設被省略： 思考區塊仍然出現在 Claude Opus 4.7 的回應流中，但除非您明確選擇加入，否則其 thinking 欄位為空。這是 Claude Opus 4.6 的無聲變更，其預設值是返回摘要思考文本。若要在 Claude Opus 4.7 上恢復摘要思考內容，請將 thinking.display 設定為 "summarized"：

   thinking = {
       "type": "adaptive",
       "display": "summarized",
   }

   Claude Opus 4.7 上的預設值是 "omitted"。如果您的產品將推理串流傳輸給使用者，新的預設值會在輸出開始前顯示為長暫停；設定 display: "summarized" 以在思考期間恢復可見進度。有關詳細資訊，請參閱 擴展思考。

4. 更新的代幣計數： Claude Opus 4.7 使用新的分詞器，有助於其在廣泛任務上的性能改進。與先前的模型相比，此新分詞器在處理文本時可能使用大約 1 倍到 1.35 倍的代幣（最多約 35% 更多，因內容而異），/v1/messages/count_tokens 將為 Claude Opus 4.7 返回與 Claude Opus 4.6 不同的代幣數。Claude Opus 4.7 的代幣效率可能因工作負載形狀而異。提示干預、task_budget 和 effort 可以幫助控制成本並確保適當的代幣使用。請記住，這些控制可能會影響模型智能。我們建議更新您的 max_tokens 參數以提供額外的空間，包括壓縮觸發器。Claude Opus 4.7 以標準 API 定價提供 1M 上下文視窗，無長上下文溢價。

5. 預填移除（從 Opus 4.6 延續）： 在 Claude Opus 4.7 上預填助手訊息會返回 400 錯誤。改用 結構化輸出、系統提示指令或 output_config.format。

選擇工作量級別

工作量參數 允許您調整 Claude 的智能與代幣支出，以速度和成本換取能力。從新的 xhigh 工作量級別開始進行編碼和代理使用案例，並對大多數智能敏感的使用案例使用至少 high 工作量。試驗其他工作量級別以進一步調整代幣使用和智能：

• max： 最大工作量在某些使用案例中可以提供性能提升，但可能會因增加的代幣使用而顯示遞減回報。此設定有時也可能容易過度思考。我們建議為智能要求高的任務測試最大工作量。
• xhigh（新）： 超高工作量是大多數編碼和代理使用案例的最佳設定。
• high： 此設定在代幣使用和智能之間取得平衡。對於大多數智能敏感的使用案例，我們建議至少使用 high 工作量。
• medium： 適合需要減少代幣使用同時權衡智能的成本敏感使用案例。
• low： 保留用於短期、範圍有限的任務和對智能不敏感的延遲敏感工作負載。

我們預期工作量對此模型的重要性將超過任何先前的 Opus，並建議在升級時積極試驗它。

行為變更

Claude Opus 4.7 與 Claude Opus 4.6 有幾個行為差異，這些不是 API 破壞性變更，但可能需要提示更新或支架移除。

1. 回應長度因使用案例而異： Claude Opus 4.7 根據其判斷任務的複雜程度來校準回應長度，而不是預設為固定的冗長性。這通常意味著簡單查詢的答案較短，開放式分析的答案要長得多。如果您的產品取決於特定的輸出風格或冗長性，您可能需要調整您的提示。例如，要減少冗長性，您可能會添加："提供簡潔、重點突出的回應。跳過非必要的上下文，並保持範例最少。" 如果您看到特定類型的冗長性範例（即過度解釋），您可以在提示中添加額外指令以防止它們。顯示 Claude 如何以適當簡潔程度進行溝通的正面範例往往比負面範例或告訴模型不要做什麼的指令更有效。

2. 更字面的指令遵循： Claude Opus 4.7 比 Claude Opus 4.6 更字面和明確地解釋提示，特別是在較低的工作量級別。它不會無聲地將指令從一個項目推廣到另一個項目，也不會推斷您未提出的請求。這種字面性的優點是精確性和更少的混亂。它通常對具有精心調整提示、結構化提取和您想要可預測行為的管道的 API 使用案例表現更好。提示和工具審查可能對遷移到 Claude Opus 4.7 特別有幫助。

3. 更直接的語調： 與任何新模型一樣，長篇寫作的散文風格可能會改變。Claude Opus 4.7 更直接和有主見，驗證轉發短語和表情符號較少，而 Claude Opus 4.6 的風格更溫暖。如果您的產品依賴特定的聲音，請根據新基準重新評估風格提示。

4. 代理跡跡中的內建進度更新： Claude Opus 4.7 在長代理跡跡中為使用者提供更定期、更高品質的更新。如果您添加了支架以強制臨時狀態訊息（"每 3 個工具呼叫後，總結進度"），請嘗試移除它。如果您發現 Claude Opus 4.7 的面向使用者的更新的長度或內容對您的使用案例校準不佳，請在提示中明確描述這些更新應該是什麼樣子並提供範例。

5. 預設生成的子代理較少： Claude Opus 4.7 傾向於預設生成較少的子代理。但是，此行為可透過提示進行調整；向 Claude Opus 4.7 提供有關何時需要子代理的明確指導。

6. 更嚴格的工作量校準： 與 Claude Opus 4.6 有意義的不同，Claude Opus 4.7 嚴格遵守 工作量級別，特別是在低端。在 low 和 medium 時，模型將其工作範圍限制在所要求的範圍內，而不是超越。這對延遲和成本很好，但在 low 工作量下執行的中等複雜任務上存在一些欠思考的風險。如果您在複雜問題上觀察到淺層推理，請將工作量提高到 high 或 xhigh，而不是圍繞它進行提示。如果您需要為延遲保持 low 工作量，請添加有針對性的指導："此任務涉及多步推理。在回應前仔細思考問題。" 請參閱 Claude Opus 4.7 的推薦工作量級別。

7. 預設工具呼叫較少： Claude Opus 4.7 傾向於比 Claude Opus 4.6 使用工具的頻率較低，並更多地使用推理。在大多數情況下，這會產生更好的結果。但是，增加工作量設定是增加工具使用級別的有用槓桿，特別是在知識工作中。high 或 xhigh 工作量設定在代理搜尋和編碼中顯示實質上更多的工具使用。對於您想要更多工具使用的情況，您也可以調整提示以明確指示模型何時以及如何正確使用其工具。

8. 實時網路安全防護： Claude Opus 4.7 新增的功能，涉及禁止或高風險主題的請求可能導致拒絕。對於合法的安全工作，例如滲透測試、漏洞研究或紅隊，請申請 網路驗證計畫 以請求降低對網路內容的限制。有關背景，請參閱 防護、警告和上訴。

9. 高解析度影像支援： Claude Opus 4.7 是第一個具有高解析度影像支援的 Claude 模型，長邊的最大影像解析度為 2576 像素（從先前模型的 1568 像素提高）。這為視覺密集型工作負載帶來了收益，對於電腦使用、螢幕截圖理解和文件分析特別有價值。高解析度支援是自動的，不需要測試版標頭或用戶端選擇加入。全解析度影像可以使用比先前模型多約 3 倍的影像代幣（每個影像最多 4,784 代幣，相比之前的大約 1,600 代幣上限），因此請重新預算影像密集型工作負載的 max_tokens 和成本預期，或在發送前進行下採樣（如果您不需要額外的保真度）。模型返回的指向和邊界框座標在 Claude Opus 4.7 上與實際影像像素 1

   ，因此不需要縮放因子轉換。有關詳細資訊，請參閱 Claude Opus 4.7 上的高解析度影像支援。

推薦的變更

這些不是必需的，但會改善您的體驗：

1. 重新評估 max_tokens： 因為相同的文本在 Claude Opus 4.7 上產生更高的代幣計數，我們建議更新您的 max_tokens 參數以提供額外的空間，包括壓縮觸發器。提示干預、task_budget 和 effort 可以幫助控制成本並確保適當的代幣使用。

2. 審計代幣計數預期： 任何估計用戶端代幣或假設固定代幣對字元比率的程式碼路徑應根據 Claude Opus 4.7 重新測試。使用 代幣計數端點 進行驗證。

3. 採用 任務預算（測試版）： Claude Opus 4.7 引入了任務預算。這些預算讓您告知 Claude 它有多少代幣用於完整的代理迴圈，包括思考、工具呼叫、工具結果和最終輸出。模型看到一個執行倒計時並使用它來優先處理工作並在預算消耗時優雅地完成任務。若要使用，請設定測試版標頭 task-budgets-2026-03-13 並將以下內容添加到您的輸出配置：

   output_config = {
       "effort": "high",
       "task_budget": {"type": "tokens", "total": 128000},
   }

   您可能需要為您的使用案例試驗不同的任務預算。如果模型被賦予對給定任務過於限制的任務預算，它可能會不太徹底地完成任務，將其預算作為約束進行參考。對於品質比速度更重要的開放式代理任務，不要設定任務預算；將任務預算保留用於您需要模型將其工作範圍限制在代幣額度的工作負載。任務預算的最小值為 20k 代幣。

   這不是硬上限；這是模型意識到的建議。這與 max_tokens 不同，max_tokens 是對生成代幣的硬每請求上限（max_tokens 不傳遞給模型，模型不知道它），而 task_budget 是跨完整代理迴圈的建議上限。當您想要模型自我調節時使用 task_budget，並使用 max_tokens 作為硬每請求上限以限制使用。

4. 在 max 或 xhigh 工作量時設定大型 max_tokens： 如果您在 max 或 xhigh 工作量下執行 Claude Opus 4.7，請設定大型最大輸出代幣預算，以便模型有空間在其子代理和工具呼叫中思考和行動。我們建議從 64k 代幣開始，然後從那裡進行調整。

5. 如果高解析度不必要，請下採樣影像： Claude Opus 4.7 支援最大 2576px / 3.75MP 的影像。高解析度影像使用更多代幣。如果額外的影像保真度不必要，請在發送給 Claude 前下採樣影像以避免代幣使用增加。請參閱 影像和視覺。

遷移檢查清單

• 將模型名稱從 claude-opus-4-6 更新為 claude-opus-4-7（或更新別名）。
• 從請求有效負載中移除 temperature、top_p 和 top_k。
• 將 thinking: {type: "enabled", budget_tokens: N} 替換為 thinking: {type: "adaptive"} 加上 工作量參數。
• 移除任何助手訊息預填。
• 如果您的 UI 顯示思考內容，明確選擇加入思考摘要。
• 在更新的分詞下重新基準化端到端成本和延遲。
• 重新調整 max_tokens 以考慮更新的分詞。
• 重新測試任何用戶端代幣計數估計。
• 如果您的應用程式發送影像，重新預算 高解析度影像支援（每個全解析度影像最多約 3 倍更多影像代幣）。如果您不需要額外的保真度，請在發送前下採樣。如果您從模型使用指向或邊界框座標，請移除任何縮放因子轉換；座標在 Claude Opus 4.7 上與實際影像像素 1
  。
• 檢查上述行為變更的提示（回應長度、字面性、語調、進度更新、子代理、工作量校準、工具觸發、網路防護、高解析度影像處理）。
• 移除現有長度控制提示後重新基準化回應長度，然後明確調整。
• 如果使用 xhigh 或 max 工作量，將 max_tokens 提高到至少 64k 作為起點。
• 考慮為代理工作流採用任務預算（測試版）。
• 如果您的產品進行合法的安全工作，請申請 網路驗證計畫 以獲得對網路內容的較低限制。

從 Opus 4.5 或更早版本遷移到 Claude Opus 4.7

如果您從 Claude Opus 4.5、Opus 4.1 或更早的模型直接遷移到 Claude Opus 4.7，請應用上面的所有 Opus 4.7 變更 加上本節中在 Opus 4.5 和 Opus 4.7 之間生效的累積變更。如果您從 Opus 4.6 遷移，您只需要上面的 Opus 4.7 部分。

更新您的模型名稱

# Opus 遷移
model = "claude-opus-4-5"  # 之前
model = "claude-opus-4-7"  # 之後

破壞性變更

1. 預填移除 在上面的 Opus 4.7 破壞性變更 中涵蓋。

2. 工具參數引用： Claude Opus 4.6 及更新版本的模型可能在工具呼叫參數中產生略微不同的 JSON 字串轉義（例如，不同的 Unicode 轉義或正斜杠轉義處理）。如果您將工具呼叫 input 解析為原始字串而不是使用 JSON 解析器，請驗證您的解析邏輯。標準 JSON 解析器（如 json.loads() 或 JSON.parse()）會自動處理這些差異。

推薦的變更

這些變更改善了您在 Opus 4.7 上的體驗。標記為 (Opus 4.7 上必需) 的項目在 Opus 4.6 推出時是可選建議，但現在是強制性的；其餘的仍然是推薦的。

1. 遷移到自適應思考（Opus 4.7 上必需）： thinking: {type: "enabled", budget_tokens: N} 在 Claude Opus 4.7 上返回 400 錯誤。切換到 thinking: {type: "adaptive"} 並使用 工作量參數 來控制思考深度。請參閱 自適應思考。

   BeforeAfterCLITypeScriptC#GoJavaPHPRuby

   response = client.beta.messages.create(
       model="claude-opus-4-5",
       max_tokens=16000,
       thinking={"type": "enabled", "budget_tokens": 32000},
       betas=["interleaved-thinking-2025-05-14"],
       messages=[...],
   )

   請注意，遷移也從 client.beta.messages.create 移動到 client.messages.create。自適應思考和工作量是 GA 功能，不需要測試版 SDK 命名空間或任何測試版標頭。

2. 移除工作量測試版標頭： 工作量參數現在是 GA。從您的請求中移除 betas=["effort-2025-11-24"]。

3. 移除細粒度工具串流測試版標頭： 細粒度工具串流現在是 GA。從您的請求中移除 betas=["fine-grained-tool-streaming-2025-05-14"]。

4. 移除交錯思考測試版標頭： 自適應思考在 Claude Opus 4.7、Opus 4.6 和 Sonnet 4.6 上自動啟用交錯思考。從您的請求中移除 betas=["interleaved-thinking-2025-05-14"]。標頭在 Sonnet 4.6 上仍然可用於手動擴展思考，但手動模式已棄用。

5. 遷移到 output_config.format： 如果使用結構化輸出，請將 output_format={...} 更新為 output_config={"format": {...}}。舊參數保持功能但已棄用，將在未來模型版本中移除。

從 Claude 4.1 或更早版本遷移

如果您從 Opus 4.1、Sonnet 4（已棄用）或更早的模型直接遷移到 Claude Opus 4.7，請應用本指南頂部的 Claude Opus 4.7 變更和上面的累積變更加上本節中的額外變更。

# 從 Opus 4.1
model = "claude-opus-4-1-20250805"  # 之前
model = "claude-opus-4-7"  # 之後

# 從 Sonnet 4
model = "claude-sonnet-4-20250514"  # 之前
model = "claude-opus-4-7"  # 之後

# 從 Sonnet 3.7
model = "claude-3-7-sonnet-20250219"  # 之前
model = "claude-opus-4-7"  # 之後

額外的破壞性變更

1. 移除採樣參數

   從 Claude 3.x 模型遷移時，這是一項破壞性變更。

   從 Claude Opus 4.7 開始，將 temperature、top_p 或 top_k 設定為任何非預設值將返回 400 錯誤。最安全的遷移路徑是從請求中完全省略這些參數，並使用提示來引導模型的行為。如果您使用 temperature = 0 以確保確定性，請注意它從未保證相同的輸出。

   Python

   # 之前 - 這將在 Claude 4+ 模型中出錯
   response = client.messages.create(
       model="claude-3-7-sonnet-20250219",
       temperature=0.7,
       top_p=0.9,  # 非預設採樣參數在 Opus 4.7 上返回 400
       # ...
   )
   
   # 之後
   response = client.messages.create(
       model="claude-opus-4-7",
       # ...
   )

2. 更新工具版本

   從 Claude 3.x 模型遷移時，這是一項破壞性變更。

   更新到最新的工具版本。移除任何使用 undo_edit 命令的程式碼。

   # 之前
   tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]
   
   # 之後
   tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]
   • 文字編輯器： 使用 text_editor_20250728 和 str_replace_based_edit_tool。有關詳細資訊，請參閱 文字編輯器工具文件。
   • 程式碼執行： 升級到 code_execution_20250825。有關遷移指令，請參閱 程式碼執行工具文件。

3. 處理 refusal 停止原因

   更新您的應用程式以 處理 refusal 停止原因：

   Python

   response = client.messages.create(...)
   
   if response.stop_reason == "refusal":
       # 適當地處理拒絕
       pass

4. 處理 model_context_window_exceeded 停止原因

   Claude 4.5+ 模型在生成因達到上下文視窗限制而停止時返回 model_context_window_exceeded 停止原因，而不是請求的 max_tokens 限制。更新您的應用程式以處理此新停止原因：

   Python

   response = client.messages.create(...)
   
   if response.stop_reason == "model_context_window_exceeded":
       # 適當地處理上下文視窗限制
       pass

5. 驗證工具參數處理（尾隨換行符）

   Claude 4.5+ 模型保留工具呼叫字串參數中以前被剝離的尾隨換行符。如果您的工具依賴於針對工具呼叫參數的精確字串匹配，請驗證您的邏輯正確處理尾隨換行符。

6. 更新您的提示以應對行為變更

   Claude 4+ 模型具有更簡潔、直接的溝通風格，需要明確的方向。檢查 提示最佳實踐 以獲得最佳化指導。

額外的推薦變更

• 移除舊版測試版標頭： 移除 token-efficient-tools-2025-02-19 和 output-128k-2025-02-19。所有 Claude 4+ 模型都具有內建的代幣高效工具使用，這些標頭無效。

遷移檢查清單（從 Opus 4.5 或更早版本）

• 將模型 ID 更新為 claude-opus-4-7
• 應用所有 Opus 4.7 破壞性變更（擴展思考已移除、採樣參數已移除、思考顯示預設被省略、更新的分詞）
• 破壞性： 移除助手訊息預填（返回 400 錯誤）；改用結構化輸出或 output_config.format
• Opus 4.7 上的破壞性： 將 thinking: {type: "enabled", budget_tokens: N} 替換為 thinking: {type: "adaptive"} 加上 工作量參數（在 Opus 4.7 上返回 400）
• 驗證工具呼叫 JSON 解析使用標準 JSON 解析器
• 移除 effort-2025-11-24 測試版標頭（工作量現在是 GA）
• 移除 fine-grained-tool-streaming-2025-05-14 測試版標頭
• 移除 interleaved-thinking-2025-05-14 測試版標頭（自適應思考自動啟用交錯思考）
• 將 output_format 遷移到 output_config.format（如適用）
• 如果從 Claude 4.1 或更早版本遷移：移除 temperature、top_p 和 top_k（非預設值在 Opus 4.7 上返回 400）
• 如果從 Claude 4.1 或更早版本遷移：更新工具版本（text_editor_20250728、code_execution_20250825）
• 如果從 Claude 4.1 或更早版本遷移：處理 refusal 停止原因
• 如果從 Claude 4.1 或更早版本遷移：處理 model_context_window_exceeded 停止原因
• 如果從 Claude 4.1 或更早版本遷移：驗證工具字串參數處理尾隨換行符
• 如果從 Claude 4.1 或更早版本遷移：移除舊版測試版標頭（token-efficient-tools-2025-02-19、output-128k-2025-02-19）
• 按照 提示最佳實踐 檢查和更新提示
• 在生產部署前在開發環境中測試

遷移到 Claude Sonnet 4.6

Claude Sonnet 4.6 結合了強大的智能和快速性能，具有改進的代理搜尋功能和與網路搜尋或網路擷取一起使用時的免費程式碼執行。它非常適合日常編碼、分析和內容任務。

有關功能的完整概述，請參閱 模型概述。

更新您的模型名稱：

# 從 Sonnet 4.5
model = "claude-sonnet-4-5"  # 之前
model = "claude-sonnet-4-6"  # 之後

# 從 Sonnet 4
model = "claude-sonnet-4-20250514"  # 之前
model = "claude-sonnet-4-6"  # 之後

破壞性變更

從 Sonnet 4.5 遷移時

1. 不再支援預填助手訊息

   從 Sonnet 4.5 或更早版本遷移時，這是一項破壞性變更。

   在 Sonnet 4.6 上預填助手訊息會返回 400 錯誤。請改用結構化輸出、系統提示指令或 output_config.format。

   常見的預填使用案例和遷移方式：

   • 控制輸出格式（強制 JSON/YAML 輸出）：使用結構化輸出或具有列舉欄位的工具進行分類任務。

   • 消除前言（移除「以下是...」短語）：在系統提示中新增直接指令：「直接回應，不要前言。不要以『以下是...』、『根據...』等短語開頭。」

   • 避免不當拒絕： Claude 現在在適當拒絕方面表現得更好。在使用者訊息中進行清晰的提示，無需預填應該就足夠了。

   • 延續（繼續被中斷的回應）：將延續移至使用者訊息：「您之前的回應被中斷，結束於 [previous_response]。從您停止的地方繼續。」

   • 上下文補充 / 角色一致性（在長對話中重新整理上下文）：將之前預填的助手提醒注入到使用者回合中。

2. 工具參數 JSON 轉義可能不同

   從 Sonnet 4.5 或更早版本遷移時，這是一項破壞性變更。

   工具參數中的 JSON 字串轉義可能與先前的模型不同。標準 JSON 解析器會自動處理此問題，但自訂的基於字串的解析可能需要更新。

從 Claude 3.x 遷移時

1. 更新採樣參數

   從 Claude 3.x 模型遷移時，這是一項破壞性變更。

   僅使用 temperature 或 top_p，不要同時使用兩者。

2. 更新工具版本

   從 Claude 3.x 模型遷移時，這是一項破壞性變更。

   更新至最新工具版本（text_editor_20250728、code_execution_20250825）。移除任何使用 undo_edit 命令的程式碼。

3. 處理 refusal 停止原因

   更新您的應用程式以處理 refusal 停止原因。

4. 為行為變更更新您的提示

   Claude 4 模型具有更簡潔、直接的通訊風格。查看提示工程最佳實踐以獲得最佳化指導。

建議的變更

1. 移除 fine-grained-tool-streaming-2025-05-14 測試版標頭： 細粒度工具串流現在在 Sonnet 4.6 上是 GA，不再需要測試版標頭。
2. 將 output_format 遷移至 output_config.format： output_format 參數已棄用。請改用 output_config.format。

從 Sonnet 4.5 遷移

考慮從 Sonnet 4.5 遷移至 Sonnet 4.6，它以相同的價格點提供更高的智能。

如果您未使用擴展思考

如果您在 Sonnet 4.5 上未使用擴展思考，您可以在 Sonnet 4.6 上繼續不使用它。您應該明確設定努力級別以適應您的使用案例。在禁用思考的 low 努力下，您可以期望相對於沒有擴展思考的 Sonnet 4.5 有相似或更好的效能。

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=8192,
    output_config={"effort": "low"},
    messages=[{"role": "user", "content": "Your prompt here"}],
)

如果您使用擴展思考

如果您在 Sonnet 4.5 上使用具有 budget_tokens 的擴展思考，它在 Sonnet 4.6 上仍然可用，但已棄用。遷移至自適應思考與努力參數。

遷移至自適應思考

自適應思考是 Sonnet 4.6 上 budget_tokens 的建議替代品。它特別適合以下工作負載模式：

• 自主多步驟代理： 將需求轉化為可運作軟體的編碼代理、資料分析管道和錯誤查找，其中模型在許多步驟中獨立運行。自適應思考讓模型能夠根據每個步驟校準其推理，在更長的軌跡上保持在正軌。對於這些工作負載，從 high 努力開始。如果延遲或令牌使用是一個問題，縮小至 medium。
• 電腦使用代理： Sonnet 4.6 在使用自適應模式的電腦使用評估中達到了同類最佳的準確度。
• 雙模態工作負載： 簡單和困難任務的混合，其中自適應在簡單查詢上跳過思考，在複雜查詢上進行深度推理。

使用自適應思考時，在您的任務上評估 medium 和 high 努力。正確的級別取決於您的工作負載在品質、延遲和令牌使用之間的權衡。

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Your prompt here"}],
)

在遷移期間保留 budget_tokens

如果您在遷移時需要暫時保留 budget_tokens，大約 16k 令牌的預算為更困難的問題提供了迴旋空間，而不會有失控令牌使用的風險。此配置已棄用，將在未來的模型版本中移除。

編碼和代理使用案例

對於代理編碼、前端設計、工具繁重的工作流程和複雜的企業工作流程，從 medium 努力開始。如果您發現延遲太高，請考慮將努力降低至 low。如果您需要更高的智能，請考慮將努力增加至 high 或遷移至 Opus 4.7。

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16384,
    thinking={"type": "enabled", "budget_tokens": 16384},
    output_config={"effort": "medium"},
    betas=["interleaved-thinking-2025-05-14"],
    messages=[{"role": "user", "content": "Your prompt here"}],
)

聊天和非編碼使用案例

對於聊天、內容生成、搜尋、分類和其他非編碼任務，從具有擴展思考的 low 努力開始。如果您需要更多深度，將努力增加至 medium。

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=8192,
    thinking={"type": "enabled", "budget_tokens": 16384},
    output_config={"effort": "low"},
    betas=["interleaved-thinking-2025-05-14"],
    messages=[{"role": "user", "content": "Your prompt here"}],
)

Sonnet 4.6 遷移檢查清單

• 將模型 ID 更新至 claude-sonnet-4-6
• 破壞性： 移除助手訊息預填；改用結構化輸出或 output_config.format
• 破壞性： 驗證工具參數 JSON 解析處理轉義差異
• 破壞性： 將工具版本更新至最新（text_editor_20250728、code_execution_20250825）；不支援舊版本（如果從 3.x 遷移）
• 破壞性： 移除任何使用 undo_edit 命令的程式碼（如果適用）
• 破壞性： 將採樣參數更新為僅使用 temperature 或 top_p，不要同時使用兩者（如果從 3.x 遷移）
• 在您的應用程式中處理新的 refusal 停止原因
• 移除 fine-grained-tool-streaming-2025-05-14 測試版標頭（現在是 GA）
• 將 output_format 遷移至 output_config.format
• 查看並更新提示，遵循提示工程最佳實踐
• 建議： 從 thinking: {type: "enabled", budget_tokens: N} 遷移至 thinking: {type: "adaptive"} 與努力參數（budget_tokens 已棄用，將在未來版本中移除）
• 在生產部署前在開發環境中測試

遷移至 Claude Sonnet 4.5

Claude Sonnet 4.5 結合了強大的智能與快速效能，使其成為日常編碼、分析和內容任務的理想選擇。

如需完整的功能概述，請參閱模型概述。

更新您的模型名稱：

# 從 Sonnet 4
model = "claude-sonnet-4-20250514"  # 之前
model = "claude-sonnet-4-5-20250929"  # 之後

# 從 Sonnet 3.7
model = "claude-3-7-sonnet-20250219"  # 之前
model = "claude-sonnet-4-5-20250929"  # 之後

破壞性變更

這些破壞性變更適用於從 Claude 3.x Sonnet 模型遷移時。

1. 更新採樣參數

   從 Claude 3.x 模型遷移時，這是一項破壞性變更。

   僅使用 temperature 或 top_p，不要同時使用兩者。

2. 更新工具版本

   從 Claude 3.x 模型遷移時，這是一項破壞性變更。

   更新至最新工具版本（text_editor_20250728、code_execution_20250825）。移除任何使用 undo_edit 命令的程式碼。

3. 處理 refusal 停止原因

   更新您的應用程式以處理 refusal 停止原因。

4. 為行為變更更新您的提示

   Claude 4 模型具有更簡潔、直接的通訊風格。查看提示工程最佳實踐以獲得最佳化指導。

Sonnet 4.5 遷移檢查清單

• 將模型 ID 更新至 claude-sonnet-4-5-20250929
• 破壞性： 將工具版本更新至最新（text_editor_20250728、code_execution_20250825）；不支援舊版本（如果從 3.x 遷移）
• 破壞性： 移除任何使用 undo_edit 命令的程式碼（如果適用）
• 破壞性： 將採樣參數更新為僅使用 temperature 或 top_p，不要同時使用兩者（如果從 3.x 遷移）
• 在您的應用程式中處理新的 refusal 停止原因
• 查看並更新提示，遵循提示工程最佳實踐
• 考慮為複雜推理任務啟用擴展思考
• 在生產部署前在開發環境中測試

遷移至 Claude Haiku 4.5

Claude Haiku 4.5 是最快且最聰慧的 Haiku 模型，具有接近前沿的效能，為互動應用程式和大量處理提供高級模型品質。

如需完整的功能概述，請參閱模型概述。

更新您的模型名稱：

# 從 Haiku 3.5
model = "claude-3-5-haiku-20241022"  # 之前
model = "claude-haiku-4-5-20251001"  # 之後

# 從 Haiku 3
model = "claude-3-haiku-20240307"  # 之前
model = "claude-haiku-4-5-20251001"  # 之後

查看新的速率限制： Haiku 4.5 與 Haiku 3.5 和 Haiku 3 有不同的速率限制。詳見速率限制文件。

探索新功能： 詳見模型概述，了解上下文感知、增加的輸出容量（64k 令牌）、更高的智能和改進的速度。

破壞性變更

這些破壞性變更適用於從 Claude 3.x Haiku 模型遷移時。

1. 更新採樣參數

   從 Claude 3.x 模型遷移時，這是一項破壞性變更。

   僅使用 temperature 或 top_p，不要同時使用兩者。

2. 更新工具版本

   從 Claude 3.x 模型遷移時，這是一項破壞性變更。

   更新至最新工具版本（text_editor_20250728、code_execution_20250825）。移除任何使用 undo_edit 命令的程式碼。

3. 處理 refusal 停止原因

   更新您的應用程式以處理 refusal 停止原因。

4. 為行為變更更新您的提示

   Claude 4 模型具有更簡潔、直接的通訊風格。查看提示工程最佳實踐以獲得最佳化指導。

Haiku 4.5 遷移檢查清單

• 將模型 ID 更新至 claude-haiku-4-5-20251001
• 破壞性： 將工具版本更新至最新（text_editor_20250728、code_execution_20250825）；不支援舊版本
• 破壞性： 移除任何使用 undo_edit 命令的程式碼（如果適用）
• 破壞性： 將採樣參數更新為僅使用 temperature 或 top_p，不要同時使用兩者
• 在您的應用程式中處理新的 refusal 停止原因
• 查看並調整新的速率限制（與 Haiku 3.5 分開）
• 查看並更新提示，遵循提示工程最佳實踐
• 考慮為複雜推理任務啟用擴展思考
• 在生產部署前在開發環境中測試

獲得幫助

• 查看 API 文件以了解詳細規格
• 查看模型功能以進行效能比較
• 查看 API 發行說明以了解 API 更新
• 如果在遷移期間遇到任何問題，請聯絡支援