Claude Haiku 5.5 遷移指南

本指南說明如何將呼叫 Claude Haiku 4.5 的程式碼遷移至 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。
3. 如果您的請求傳送 thinking: {"type": "enabled", "budget_tokens": N}，請將 thinking 變更為 {"type": "adaptive"}。請參閱設定思考。
4. 如果您的程式碼將第一個內容區塊讀取為答案，請改為依 type 選取區塊。請參閱設定思考。
5. 從您的請求中移除 temperature、top_p 和 top_k。請參閱移除取樣參數。
6. 如果您的請求以助理回合結束 messages 以讓模型接續，請改為以使用者回合結束。請參閱取代助理預填。
7. 如果您在 Claude API 或 Google Cloud 上使用電腦使用功能，請從 computer_20250124 改用 computer_toolset_20260801 工具集。請參閱將電腦使用遷移至工具集。
8. 如果您透過不同的帳戶重播已儲存的對話，請透過產生該對話的帳戶重播每個對話。請參閱透過產生思考區塊的帳戶重播思考區塊。
9. 如果您的程式碼在對話的請求之間變更 system、tools 或較早的 messages，並將思考區塊傳回，請讓對話保持僅附加（append-only）。請參閱保持較早的回合不變。
10. 處理 stop_reason: "refusal"。Claude Haiku 5.5 會執行可能拒絕請求的安全分類器，且沒有伺服器端備援。請參閱安全防護拒絕。

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

使用 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 的計數和價格重新計算。

請將 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 等級。

預設情況下，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 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，並依據每個預填的用途加以取代：

• 輸出格式：使用結構化輸出，或使用帶有 enum 欄位的工具進行分類。在不支援結構化輸出的 Claude in Amazon Bedrock 上，請使用工具。
• 開場白：在系統提示中要求直接回答。
• 接續：將其移至使用者訊息中，例如「您先前的回應被中斷，結尾為 [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 錯誤。

若要遷移整合，請移除 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 的請求才會出現此錯誤。關於會觸發此錯誤的變更以及替代做法，請參閱誰需要做出變更。