Claude Haiku 5.5 遷移指南

本指南說明如何將呼叫 Claude Haiku 4.5 的程式碼遷移至 Claude Haiku 5.5。對於呼叫 Claude Haiku 3.5 或 Claude Haiku 3 的程式碼，也請進行從 Claude Haiku 3.5 及更早的 Haiku 模型遷移至 Claude Haiku 5.5 中的變更。若要改為升級至 Sonnet 或 Opus 模型，請參閱在模型版本之間升級。關於 Claude Haiku 4.5 的可用期限，請參閱模型棄用。

依起始模型分類的遷移檢查清單

請依序往下處理各組，並在列出您目前模型的那一組之後停止。如果您使用的是 Claude Haiku 4.5，第一組就是完整的清單。每個項目都是您需要在程式碼中進行的一項變更。

所有起始模型

1. 將模型 ID 替換為您平台上的 Claude Haiku 5.5 ID。請參閱使用 Claude Haiku 5.5 模型 ID。
2. 重新計算您的提示，並重新檢視 max_tokens 限制和成本估算，因為相同的文字會計為更多 token，而大型圖片會計為更多視覺 token。請參閱重新計算 token。
3. 如果您的請求傳送 thinking: {"type": "enabled", "budget_tokens": N}，請將 thinking 變更為 {"type": "adaptive"}。請參閱設定思考。
4. 如果您的程式碼將第一個內容區塊讀取為答案，請改為依 type 選取區塊。請參閱設定思考。
5. 從您的請求中移除 temperature、top_p 和 top_k。請參閱移除取樣參數。
6. 如果您的請求以助理回合結束 messages 以讓模型接續，請改為以使用者回合結束。請參閱取代助理預填。
7. 如果您使用電腦使用功能，請替換 computer_20250124：在 Claude API 和 Google Cloud 上，替換為 computer_toolset_20260801 工具集；在 Amazon Bedrock 上，替換為 computer_20251124 並搭配 computer-use-2025-11-24 beta 標頭。請參閱將電腦使用遷移至工具集。
8. 如果您透過不同的帳戶重播已儲存的對話，請透過產生該對話的帳戶重播每個對話。請參閱透過產生思考區塊的帳戶重播思考區塊。
9. 如果您的程式碼在對話的請求之間變更 system、tools 或較早的 messages，並將思考區塊傳回，請讓對話保持僅附加（append-only）。請參閱保持較早的回合不變。
10. 處理 stop_reason: "refusal"。Claude Haiku 5.5 會執行可能拒絕請求的安全分類器，且沒有伺服器端備援。請參閱安全防護拒絕。
11. 如果您在 Amazon Bedrock 上使用結構化輸出（output_config.format 或 strict: true 工具），請在提示中描述格式，或使用不含 strict 的工具，並在您的程式碼中驗證輸出。Amazon Bedrock 上的 Claude Haiku 5.5 不提供結構化輸出。

如果您的組織在 Claude Haiku 4.5 上有 Priority Tier 承諾，請另行規劃容量：Claude Haiku 5.5 不支援 Priority Tier。

Claude Haiku 3.5 或更早版本

1. 將 Claude Haiku 3.5 或 Claude Haiku 3 的模型 ID 替換為您平台上的 Claude Haiku 5.5 ID。請參閱從 Claude Haiku 3.5 及更早的 Haiku 模型遷移至 Claude Haiku 5.5。
2. 如果您使用舊版的 code_execution_20250522 工具，請改用 code_execution_20250825 或更新版本。
3. 如果您使用文字編輯器工具，請改用 text_editor_20250728。
4. 處理 refusal 和 model_context_window_exceeded 停止原因。
5. 如果您的程式碼精確比對工具呼叫的字串參數，請允許結尾換行字元。
6. 檢視您的提示。

使用 Claude Haiku 5.5 模型 ID

將 Claude Haiku 4.5 模型 ID 替換為您平台上的 Claude Haiku 5.5 ID。

claude-haiku-5-5 是固定的模型 ID，沒有日期後綴，也沒有另外的別名。

重新計算 token

Claude Haiku 5.5 使用與 Claude 4.7 及更新模型相同的較新「tokenizer」（分詞器）。與所有使用此分詞器的模型一樣，相同的輸入文字在 Claude Haiku 5.5 上產生的 token 比在 Claude Haiku 4.5 上多約 30%。確切的增幅取決於內容。請求、回應和串流事件保持相同的結構。改變的是您以 token 衡量或編列預算的任何項目：

• 對於相同的文字，usage 欄位和 token 計數結果會更高。
• 特定數量的 token 所容納的文字較少。
• 針對 Claude Haiku 4.5 調整的 max_tokens 限制可能會截斷同等的輸出。
• 根據 Claude Haiku 4.5 的 token 計數所做的成本估算，需要以 Claude Haiku 5.5 的計數和價格重新計算，包括其針對長提示的較高價格。請參閱長上下文定價。

大型圖片也可能耗用更多 token。Claude Haiku 5.5 使用高解析度圖片層級，會將長邊超過 2,576 像素或超過 4,784 個視覺 token 的圖片縮小。Claude Haiku 4.5 及更早的 Haiku 模型使用標準層級，會將長邊超過 1,568 像素或超過 1,568 個視覺 token 的圖片縮小。一張 2,000 × 1,500 像素的圖片在 Claude Haiku 5.5 上耗用的視覺 token 約為在 Claude Haiku 4.5 上的 2.5 倍。請參閱解析度與 token 費用。

請將 model 設為 claude-haiku-5-5 來計算您的提示，而不是重複使用在 Claude Haiku 4.5 上測得的計數。

設定思考

Claude Haiku 5.5 設定思考的方式與 Claude Haiku 4.5 不同。{"type": "enabled", "budget_tokens": N} 的 thinking 值會傳回 400 錯誤，因此傳送此值的請求需要新的 thinking 值。

變更前，對 Claude Haiku 4.5 的請求將 thinking 設為 enabled 並附帶 token 預算：

{
  "model": "claude-haiku-4-5",
  "max_tokens": 16000,
  "thinking": { "type": "enabled", "budget_tokens": 8000 },
  "messages": [{ "role": "user", "content": "..." }]
}

變更後，對 Claude Haiku 5.5 的相同請求使用「adaptive thinking」（自適應思考）。thinking 值會改變，並由 output_config.effort 設定模型思考的程度：

{
  "model": "claude-haiku-5-5",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive" },
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

自適應思考預設為開啟，因此即使請求未設定 thinking，回應也可能以一個或多個 thinking 區塊開頭。請將 thinking 保持未設定或設為 {"type": "adaptive"}，並使用 effort 作為調整手段：在 Claude Haiku 4.5 不使用思考、或使用小額預算以節省 token 的情況下，請選擇較低的 effort 等級。在較低的等級下，模型思考較少，且在較簡單的請求上可能完全略過思考。關於提示指引，請參閱使用 effort 控制思考。請依內容區塊的 type 欄位而非位置來選取區塊，並將 thinking 區塊連同工具結果原封不動地傳回。

思考 token 會計入 max_tokens，因此 max_tokens 較小的請求可能會在 thinking 區塊之後、任何文字之前以 stop_reason: "max_tokens" 停止。如果您為 Claude Haiku 4.5 設定了較小的 max_tokens，請將其調高以保留思考空間，或選擇較低的 effort 等級。

較早助理回合的思考區塊會保留在上下文中並計為輸入 token，而 Claude Haiku 4.5 只保留最新回合的思考區塊。因此，多回合對話所攜帶的輸入 token 會比單純分詞器變更所能解釋的更多。若要移除較舊的區塊，請使用思考區塊清除。請參閱各模型的思考區塊保留方式。

預設情況下，Claude Haiku 5.5 傳回的每個 thinking 區塊都帶有空的 thinking 欄位且僅有 signature，而 Claude Haiku 4.5 則傳回摘要式思考。若要接收摘要式思考，請設定 thinking: {"type": "adaptive", "display": "summarized"}。

Claude Haiku 5.5 接受強制的 tool_choice（any 或指定名稱的工具），但回應會以工具呼叫開頭，且沒有 thinking 區塊。若要讓模型在呼叫工具前先思考，請使用 tool_choice: {"type": "auto"}，並在提示中說明何時使用該工具。

Claude Haiku 5.5 可讀取來自 Claude Sonnet 5、Claude Opus 4.8、Claude Haiku 4.5 及更早模型的思考區塊，因此您從 Claude Haiku 4.5 切換至 Claude Haiku 5.5 的對話會保留其推理。它無法讀取來自 Claude Opus 5、Claude Opus 5.5、Claude Sonnet 5.5 或任何 Claude Fable 或 Claude Mythos 模型的區塊；API 會捨棄這些區塊而不傳回錯誤。在 Claude API 和 Google Cloud 上，Claude Opus 5.5 和 Claude Sonnet 5.5 可讀取 Claude Haiku 5.5 的區塊。請參閱在對話中途切換模型。

移除取樣參數

Claude Haiku 4.5 接受 temperature、top_p 和 top_k。在 Claude Haiku 5.5 上，請省略這三個參數，改用提示來引導模型的行為。如果請求包含 temperature，其值必須為 1。如果包含 top_p，其值必須為預設值 0.99。任何其他 temperature 或 top_p 值都會傳回 400 錯誤，包括 top_p 為 1 的情況。任何 top_k 值也會如此，同時包含 temperature 和 top_p 的請求亦然。

取代助理預填

「Prefill」（預填）是 messages 中由模型接續的最後一個助理回合。Claude Haiku 4.5 在思考關閉時接受預填。Claude Haiku 5.5 會以 400 錯誤拒絕預填，即使思考已關閉也是如此。請以使用者回合結束 messages，並依據每個預填的用途加以取代：

• 輸出格式：使用結構化輸出，或針對分類使用帶有列舉欄位的工具。在 Amazon Bedrock 上，Claude Haiku 5.5 不提供結構化輸出。在該平台上，請在提示中描述格式，或使用不含 strict 的工具，並在您的程式碼中驗證輸出。
• 開場白：在系統提示中要求直接回答。
• 接續：將其移至使用者訊息中，例如「您先前的回應被中斷，結尾為 [previous_response]。請從中斷處繼續。」
• 上下文提醒：將其放在使用者回合中。

將電腦使用遷移至工具集

Claude Haiku 4.5 透過 computer_20250124 工具並搭配 computer-use-2025-01-24 beta 標頭支援電腦使用。在 Claude API 和 Google Cloud 上，Claude Haiku 5.5 僅透過 computer_toolset_20260801 工具集支援電腦使用，宣告 computer_20250124 的請求會傳回 400 錯誤。在 Amazon Bedrock 上，Claude Haiku 5.5 同樣不接受 computer_20250124；請使用 computer_20251124 工具版本並搭配 computer-use-2025-11-24 beta 標頭。

若要將整合移至工具集，請移除 computer-use-2025-01-24 beta 標頭，並將 tools 項目替換為 {"type": "computer_toolset_20260801"}。接著進行從 computer_20251124 遷移中的其他請求和代理迴圈變更：依每個成員 tool_use 區塊的 name 和 toolset_name 而非 input.action 進行分派，處理一個回合中的每個此類區塊，並在結果中回傳 toolset_name。工具集中的縮放功能預設為開啟；如果您的環境未實作此功能，請加入 "configs": {"zoom": {"enabled": false}}。如果您傳送 fine-grained-tool-streaming-2025-05-14 beta 標頭，請將其移除。與工具集項目一起使用時，它會傳回 400 錯誤。關於其他平台，請參閱電腦使用工具的相容性章節。

在 Claude API 和 Google Cloud 上，Claude Haiku 5.5 也支援用於網頁內任務的瀏覽器使用工具（browser_toolset_20260801）。Claude Haiku 4.5 不支援此工具。

透過產生思考區塊的帳戶重播思考區塊

來自 Claude Haiku 5.5 的思考區塊僅在產生它們的帳戶或與其連結的帳戶中有效。當其他帳戶傳送這些區塊之一時，API 會在模型看到該區塊之前將其捨棄，請求會在缺少該推理的情況下成功。這會影響儲存對話並透過不同帳戶重播的程式碼，例如以單一對話儲存區支援多個客戶的服務。請透過產生每個對話的帳戶重播該對話。請參閱思考區塊僅限產生它們的帳戶使用。

保持較早的回合不變

Claude Haiku 5.5 的思考區塊僅在其之前傳送的所有內容保持不變時才有效：在變更 system、tools 或較早的 messages 之後將思考區塊傳回的請求，會傳回 400 錯誤。Claude Haiku 4.5 不會執行此檢查。請讓對話保持僅附加。在 2026 年 8 月 31 日 00:00 UTC 之前建立的帳戶上，只有設定 thinking.block_binding.prefix_mismatch_behavior 的請求才會出現此錯誤。關於會觸發此錯誤的變更以及替代做法，請參閱誰需要做出變更。

從 Claude Haiku 3.5 及更早的 Haiku 模型遷移至 Claude Haiku 5.5

Claude Haiku 3.5 已在 Claude API 和 Amazon Bedrock 上停用，Claude Haiku 3 已在 Claude API 和 Google Cloud 上停用。對已停用模型的請求會失敗。Google Cloud 將 Claude Haiku 3.5 列為已棄用，且僅供現有客戶使用。請參閱模型棄用。

無論從哪個模型遷移，請先套用前面的每個章節，然後進行以下變更：

• 模型 ID：將 claude-3-5-haiku-20241022、其別名 claude-3-5-haiku-latest 或 claude-3-haiku-20240307 替換為 claude-haiku-5-5。在 Google Cloud 上，將 claude-3-5-haiku@20241022 替換為 claude-haiku-5-5。在 Amazon Bedrock 上，請使用使用 Claude Haiku 5.5 模型 ID 中的 Claude Haiku 5.5 ID。
• 程式碼執行：Claude Haiku 5.5 接受 code_execution_20250825 及更新版本。如果您使用舊版僅支援 Python 的 code_execution_20250522，請改用其中一個版本。請參閱升級至最新工具版本。
• 文字編輯器：如果您使用文字編輯器工具，請改用 text_editor_20250728（工具名稱 str_replace_based_edit_tool），此版本沒有 undo_edit 命令。請參閱文字編輯器工具。
• 停止原因：處理 refusal 和 model_context_window_exceeded。請參閱處理停止原因。
• 結尾換行字元：Claude 4.5 及更新模型會在工具呼叫字串參數中保留結尾換行字元。如果您的程式碼精確比對這些字串，請允許這些換行字元。
• 提示：Claude 4 及更新模型具有更簡潔、直接的溝通風格，且需要明確的指示。請對照為 Claude Haiku 5.5 撰寫提示和提示最佳實踐檢視您的提示。