遷移至 Claude Sonnet 5

Claude Sonnet 5 在 Claude 模型家族中提供速度與智慧的最佳組合。它建立在 Claude Sonnet 4.6 的基礎之上。

Claude Sonnet 5 是 Claude Sonnet 4.6 的直接替換升級版本，定價為每百萬輸入／輸出 token $2／$10 美元；詳情請參閱定價。對於已在 Claude Sonnet 4.6 上執行的程式碼，有兩項重大的 API 變更。第一，adaptive thinking（自適應思考）預設為開啟，而手動「extended thinking」（擴展思考）（thinking: {type: "enabled", budget_tokens: N}）會回傳 400 錯誤，因此原本在不啟用思考的情況下執行的請求，現在可能會在第一個 text 區塊之前回傳 thinking 區塊，而依位置讀取內容的程式碼必須改為依 type 選取內容區塊。第二，設定為非預設值的取樣參數（temperature、top_p、top_k）會回傳 400 錯誤。請搭配 effort 參數使用自適應思考來控制思考深度。Claude Sonnet 5 支援與 Claude Sonnet 4.6 相同的功能集，包括 1M token 上下文視窗、自適應思考、提示快取、批次處理、Files API、PDF 支援、視覺，以及完整的伺服器端與用戶端工具。在 Claude API 與 Google Cloud 上，Claude Sonnet 5 也支援以穩定版 computer_toolset_20260801 工具集形式提供的 computer use（電腦使用），以及用於網頁內任務的 browser use tool（瀏覽器使用工具），這兩者 Claude Sonnet 4.6 皆不支援；使用較早 computer_20251124 版本的既有整合在兩個模型上皆可照常運作，無需變更。若要升級既有整合，請參閱從 computer_20251124 遷移。Priority Tier 在 Claude Sonnet 5 上不可用。Claude Sonnet 5 也使用新的 tokenizer（分詞器）。

從 Claude Sonnet 4.6 遷移至 Claude Sonnet 5

更新您的模型名稱

# Sonnet 遷移
model = "claude-sonnet-4-6"  # Before
model = "claude-sonnet-5"  # After

變更內容

以下清單中的第 4 項與第 5 項為重大變更。max_tokens 仍是總輸出（思考加上回應文字）的硬性上限，因此對於原本在 Claude Sonnet 4.6 上不啟用思考執行的工作負載，請重新檢視此設定。

1. 新的 tokenizer： Claude Sonnet 5 使用新的 tokenizer。相同的輸入文字所產生的 token 數量比 Claude Sonnet 4.6 多約 30%。確切的增幅取決於內容。請求、回應與串流事件的結構維持不變，無需變更程式碼，但任何以 token 衡量或編列預算的項目都會改變：相同文字的 usage 欄位與 token 計數結果會更高，1M token 上下文視窗可容納的文字更少，而針對 Claude Sonnet 4.6 調整的 max_tokens 上限可能會截斷等量的輸出。每 token 定價較低（每百萬輸入／輸出 token $2／$10 美元，相較於 Claude Sonnet 4.6 的 $3／$15 美元），但等量請求的成本並不會按相同比例下降。請針對 Claude Sonnet 5 重新執行 token 計數，而非重複使用針對較早模型測得的計數。

2. 128k 最大輸出 token（未變更）： Claude Sonnet 5 支援最多 128k 輸出 token，與 Claude Sonnet 4.6 相同。既有的 max_tokens 值仍然有效。在設定其大小時，請將新的 tokenizer 納入考量。

3. 助理訊息預填（未變更）： 在 Claude Sonnet 5 上預填助理訊息會回傳 400 錯誤，與 Claude Sonnet 4.6 相同。如果您在遷移至 Claude Sonnet 4.6 時已移除預填，則無需進一步變更。請改用結構化輸出、系統提示指令或 output_config.format。

4. 自適應思考預設開啟： 在 Claude Sonnet 4.6 上，不含 thinking 欄位的請求會在不啟用思考的情況下執行；在 Claude Sonnet 5 上，相同的請求會以自適應思考執行。若要關閉思考，請傳入 thinking: {type: "disabled"}。手動擴展思考（thinking: {type: "enabled", budget_tokens: N}）不受支援，並會回傳 400 錯誤。請使用 effort 參數（預設為 high）來控制思考深度。

   啟用思考時，回應可能會在第一個 text 區塊之前以一個或多個 thinking 區塊開頭，在預設的 display: "omitted" 下，這些區塊會以空的 thinking 欄位回傳。依位置讀取回覆的程式碼（例如 content[0].text，或將第一個內容區塊視為文字的串流處理器）必須改為依 type 欄位選取內容區塊，而工具使用迴圈必須將 thinking 區塊連同其工具結果完整且未經修改地傳回（請參閱保留思考區塊）。即使未回傳思考文字，思考 token 仍會以輸出 token 計費。如果您在 Claude Sonnet 4.6 上使用思考並顯示回傳的思考文字，請注意 thinking.display 在該模型上預設為 "summarized"，而在 Claude Sonnet 5 上預設為 "omitted"；請如以下範例所示設定 display: "summarized"，以繼續接收可讀的摘要（請參閱控制思考顯示）。

   Claude Sonnet 5Claude Sonnet 4.6

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   client = anthropic.Anthropic()
   
   response = client.messages.create(
       model="claude-sonnet-5",
       max_tokens=16000,
       thinking={"type": "adaptive", "display": "summarized"},
       output_config={"effort": "high"},
       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}")

5. 取樣參數已移除： 設定為非預設值的取樣參數（temperature、top_p、top_k）不被接受，並會回傳 400 錯誤。

6. 網路安全防護措施： Claude Sonnet 5 是第一個具備即時網路安全防護措施的 Sonnet 級模型。涉及禁止或高風險網路安全主題的請求可能會被拒絕。拒絕會以成功的 HTTP 200 回應搭配 stop_reason: "refusal" 回傳，而非錯誤。關於防護措施會阻擋哪些內容，以及合法的安全工作如何申請 Cyber Verification Program，請參閱 Claude Opus 與 Sonnet 上的即時網路防護措施。

遷移檢查清單

• 將模型名稱從 claude-sonnet-4-6 更新為 claude-sonnet-5。
• 針對 Claude Sonnet 5 重新執行 token 計數。新的 tokenizer 對相同文字會產生多約 30% 的 token，即使每 token 定價較低，這仍可能改變每次請求的成本。確切的增幅取決於內容與工作負載型態。
• 重新檢視設定值接近您預期輸出長度的 max_tokens 上限，並在有用之處將其提高至最多 128k 的上限（與 Claude Sonnet 4.6 相同，未變更）。
• 移除 thinking: {type: "enabled", budget_tokens: N} 設定（會回傳 400 錯誤）。自適應思考預設開啟；傳入 {type: "disabled"} 以關閉，或使用 effort 參數控制深度。
• 更新依位置讀取內容的回應解析程式碼，例如 content[0].text：啟用思考時，thinking 區塊會在 text 區塊之前到達。請改為依 type 選取內容區塊，並在工具使用迴圈中將 thinking 區塊未經修改地傳回；經修改的區塊會回傳 400 錯誤。
• 確認任何解析 thinking 欄位的程式碼僅將其視為顯示文字。thinking.display 在 Claude Sonnet 5 上預設為 "omitted"（在 Claude Sonnet 4.6 上預設為 "summarized"），因此思考區塊會以空的 thinking 欄位到達；請設定 display: "summarized" 以接收可讀的摘要。請參閱控制思考顯示。
• 移除設定為非預設值的 temperature、top_p 與 top_k 參數（它們在 Claude Sonnet 5 上會回傳 400 錯誤）。
• 如果您的工作負載可能涉及網路安全主題，請新增對 stop_reason: "refusal" 的處理。
• 在正式部署之前，針對您的典型工作負載重新建立成本基準。
• 針對先前在不啟用思考的情況下執行的工作負載，重新檢視 max_tokens。

從 Claude Sonnet 4.5 及更早的 Sonnet 模型遷移至 Claude Sonnet 5

如果您要從 Claude Sonnet 4.5 或更早的 Sonnet 模型直接遷移至 Claude Sonnet 5，請套用從 Claude Sonnet 4.6 遷移至 Claude Sonnet 5 的變更，再加上本節中的變更。

重大變更

從 Sonnet 4.5 遷移時

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

   在 Claude Sonnet 4.6 及之後的模型（包括 Claude Sonnet 5）上，預填助理訊息會回傳 400 錯誤。請改用結構化輸出、系統提示指令或 output_config.format。

   常見的預填使用情境與遷移方式：

   • 控制輸出格式（強制 JSON／YAML 輸出）：使用結構化輸出，或針對分類任務使用帶有 enum 欄位的工具。

   • 消除開場白（移除「Here is...」之類的語句）：在系統提示中加入直接指令：「Respond directly without preamble. Do not start with phrases like 'Here is...', 'Based on...', etc.」

   • 避免不當拒絕： Claude 現在在適當拒絕方面表現得更好。在使用者訊息中給予清楚的提示而不使用預填應已足夠。

   • 接續（恢復被中斷的回應）：將接續內容移至使用者訊息：「Your previous response was interrupted and ended with [previous_response]. Continue from where you left off.」

   • 上下文補充／角色一致性（在長對話中刷新上下文）：將先前以預填助理訊息形式提供的提醒改為注入使用者輪次中。

2. 工具參數 JSON 跳脫可能不同

   工具參數中的 JSON 字串跳脫可能與先前的模型不同。標準 JSON 解析器會自動處理此情況，但自訂的字串式解析可能需要更新。

擴展思考變更： 來自 Claude Sonnet 4.5 的 budget_tokens 設定（thinking: {type: "enabled", budget_tokens: N}）在 Claude Sonnet 5 上不受支援，並會回傳 400 錯誤。自適應思考預設開啟，因此大多數工作負載完全不需要 thinking 設定；請使用 effort 參數控制思考深度。如果您先前在不啟用擴展思考的情況下執行 Claude Sonnet 4.5，請傳入 thinking: {type: "disabled"} 以保留該行為。

從 Claude 3.x 遷移時

3. 移除取樣參數

   設定為非預設值的取樣參數（temperature、top_p、top_k）在 Claude Sonnet 5 上會回傳 400 錯誤。請將它們從請求中移除，並改用提示來引導模型的行為。

4. 更新工具版本

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

5. 處理 refusal 停止原因

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

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

   Claude 4 模型具有更簡潔、直接的溝通風格。請檢閱提示最佳實務以取得最佳化指引。

從 Claude Haiku 4.5 遷移至 Claude Sonnet 5

Claude Haiku 4.5 與 Claude Sonnet 5 在 API 層級上的差異，比同一類別中相鄰模型之間的差異更大：Claude Haiku 4.5 使用手動擴展思考（預設關閉）、200k token 上下文視窗，以及最多 64k 輸出 token；而 Claude Sonnet 5 預設以自適應思考執行、預設提供 1M token 上下文視窗，並支援最多 128k 輸出 token。

更新您的模型名稱

model = "claude-haiku-4-5-20251001"  # Before
model = "claude-sonnet-5"  # After

變更內容

1. 思考設定： Claude Haiku 4.5 支援手動擴展思考（thinking: {type: "enabled", budget_tokens: N}），並拒絕 thinking: {type: "adaptive"}。在 Claude Sonnet 5 上，支援情況相反：自適應思考預設開啟，而手動擴展思考會回傳 400 錯誤。請移除 thinking: {type: "enabled", budget_tokens: N} 設定並依賴預設值，或傳入 thinking: {type: "disabled"} 以關閉思考。budget_tokens 沒有直接的替代方案；請使用 effort 參數控制思考深度。Effort 在 Claude Haiku 4.5 上不可用，在 Claude Sonnet 5 上預設為 high。

   兩種 Claude Haiku 4.5 請求的回應結構都會改變。原本在不啟用擴展思考的情況下執行的請求，現在可能會在第一個 text 區塊之前回傳一個或多個 thinking 區塊，因此依位置讀取回覆的程式碼（例如 content[0].text）必須改為依 type 欄位選取內容區塊，而工具使用迴圈必須將 thinking 區塊連同其工具結果完整且未經修改地傳回（請參閱保留思考區塊）。原本使用擴展思考的請求會繼續接收 thinking 區塊，但 thinking.display 在 Claude Sonnet 5 上預設為 "omitted" 而非 "summarized"，因此這些區塊會以空的 thinking 欄位到達；請設定 display: "summarized" 以繼續接收可讀的摘要（請參閱控制思考顯示）。即使未回傳思考文字，思考 token 仍會以輸出 token 計費。

2. 取樣參數已移除： temperature 與 top_p 在 Claude Haiku 4.5 上可用（一次只能使用一個，不能同時使用）。在 Claude Sonnet 5 上，將 temperature、top_p 或 top_k 設定為非預設值會回傳 400 錯誤。請移除這些參數，並使用提示來引導模型的行為。

3. 助理預填已移除： 預填助理訊息在 Claude Haiku 4.5 上可用，但在 Claude Sonnet 5 上會回傳 400 錯誤。請改用結構化輸出、系統提示指令或 output_config.format。

4. 更大的上下文視窗與輸出： Claude Sonnet 5 預設提供 1M token 上下文視窗，高於 Claude Haiku 4.5 的 200k token，並支援最多 128k 輸出 token，高於 64k。Claude Sonnet 5 也使用不同的 tokenizer，因此請重新執行 token 計數，而非重複使用針對 Claude Haiku 4.5 測得的計數。

5. 定價： Claude Haiku 4.5 的定價為每百萬輸入／輸出 token $1／$5 美元。Claude Sonnet 5 的定價為每百萬輸入／輸出 token $2／$10 美元。請參閱 Claude 定價。

6. 網路安全防護措施： Claude Sonnet 5 具備即時網路安全防護措施。涉及禁止或高風險網路安全主題的請求可能會被拒絕，並以成功的 HTTP 200 回應搭配 stop_reason: "refusal" 回傳。關於防護措施會阻擋哪些內容，以及合法的安全工作如何申請 Cyber Verification Program，請參閱 Claude Opus 與 Sonnet 上的即時網路防護措施。

遷移檢查清單

• 將模型名稱從 claude-haiku-4-5-20251001（或 claude-haiku-4-5 別名）更新為 claude-sonnet-5。
• 移除 thinking: {type: "enabled", budget_tokens: N} 設定（會回傳 400 錯誤）。自適應思考預設開啟；傳入 thinking: {type: "disabled"} 以保留不啟用思考的行為，並針對原本在不啟用思考的情況下執行的工作負載重新檢視 max_tokens。
• 更新依位置讀取內容的回應解析程式碼，例如 content[0].text：啟用思考時，thinking 區塊會在 text 區塊之前到達。請改為依 type 選取內容區塊，並在工具使用迴圈中將 thinking 區塊未經修改地傳回；經修改的區塊會回傳 400 錯誤。
• 如果您的 UI 會顯示思考內容，請設定 display: "summarized"。thinking.display 在 Claude Sonnet 5 上預設為 "omitted"，因此若不設定，思考區塊會以空的 thinking 欄位到達。請參閱控制思考顯示。
• 使用 effort 參數（預設為 high）控制思考深度與 token 花費；它在 Claude Haiku 4.5 上不可用，因此沒有既有設定可沿用。
• 移除 temperature 與 top_p 設定（非預設值在 Claude Sonnet 5 上會回傳 400 錯誤）。
• 移除任何助理訊息預填（它們在 Claude Sonnet 5 上會回傳 400 錯誤）。
• 針對 Claude Sonnet 5 重新執行 token 計數，並重新檢視 max_tokens 上限，您可將其提高至最多 128k 的上限。
• 如果您的工作負載可能涉及網路安全主題，請新增對 stop_reason: "refusal" 的處理。
• 在正式部署之前，針對您的典型工作負載重新建立成本基準；每 token 定價有所不同。