Claude Platform Docs
模型與定價Claude Haiku 5.5

Claude Haiku 5.5 遷移指南

透過本遷移指南,從較早的 Haiku 模型切換至 Claude Haiku 5.5。啟用 Claude Haiku 5.5 的指引包括新的模型 ID、會傳回錯誤的設定、思考方面的變更,以及針對每個起始模型的檢查清單。

Claude Code

讓 Claude Code 為您遷移程式碼

/claude-api migrate 將此專案遷移至 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. 重新計算您的提示的 token 數,並重新檢視 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 替換為 computer_toolset_20260801 工具集。在 Amazon Bedrock 上,computer_20251124 也可使用。請參閱將電腦使用移至工具集。
  8. 如果您透過不同的帳戶重播已儲存的對話,請透過產生該對話的帳戶重播每一段對話。請參閱透過產生思考區塊的帳戶重播思考區塊。
  9. 如果您的程式碼在同一對話的請求之間變更 system、tools 或先前的 messages,並將思考區塊傳回,請保持對話為僅附加(append-only)。請參閱保持較早的回合不變。
  10. 處理 stop_reason: "refusal"。Claude Haiku 5.5 會執行可能拒絕請求的安全分類器,且沒有伺服器端備援。請參閱安全防護拒絕。
  11. 如果您的提示要求模型在回應中寫出其推理,例如在 <thinking> 或 <reasoning> 標籤中,請移除這些指示。Claude Haiku 5.5 可能會拒絕包含這些指示的請求,並傳回 reasoning_extraction 類別。請參閱安全防護拒絕。

若您的組織在 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 4.5Claude Haiku 5.5
Claude APIclaude-haiku-4-5-20251001 或 claude-haiku-4-5claude-haiku-5-5
Amazon Bedrockanthropic.claude-haiku-4-5anthropic.claude-haiku-5-5
Claude Platform on AWSclaude-haiku-4-5claude-haiku-5-5
Claude Models on Google Cloud (Anthropic managed)claude-haiku-4-5-20251001claude-haiku-5-5
Claude Models on Google Cloud (Google managed)claude-haiku-4-5@20251001claude-haiku-5-5
Microsoft Foundryclaude-haiku-4-5claude-haiku-5-5

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

重新計算 token

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

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

大型圖片也可能耗用更多 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 來計算您提示的 token 數,而非沿用在 Claude Haiku 4.5 上測得的計數。

設定思考

Claude Haiku 5.5 設定思考的方式與 Claude Haiku 4.5 不同。thinking 值為 {"type": "enabled", "budget_tokens": N} 時會傳回 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 4.5 切換至 Claude Haiku 5.5 的對話會保留其推理。至於其他切換情形,則取決於兩個模型:

切換是否保留其推理
切換至 Claude Haiku 5.5,來源為 Claude Haiku 4.5 或更早版本、Claude Sonnet 5 或更早版本,或 Claude Opus 4.8 或更早版本是
切換至 Claude Haiku 5.5,來源為任何其他模型否。API 會捨棄該模型的思考區塊而不傳回錯誤。
從 Claude Haiku 5.5 切換至 Claude Opus 5.5、Claude Sonnet 5.5、Claude Fable 5.2 或 Claude Mythos 5.2是,但僅限於 Claude API 和 Claude Models on Google Cloud (Google managed)
從 Claude Haiku 5.5 切換至任何其他模型否

請參閱切換模型再切換回來。對於不涉及 Claude Haiku 5.5 的切換,請參閱在 Claude API 上哪些模型切換會保留推理。

移除取樣參數

在 Claude Haiku 5.5 上,請省略 temperature、top_p 和 top_k,改用提示來引導模型的行為。

取代助理預填

「prefill」(預填)是 messages 中讓模型接續生成的最後一個助理回合。Claude Haiku 4.5 在思考關閉時接受預填。Claude Haiku 5.5 則會以 400 錯誤拒絕預填,即使思考已關閉也一樣。請以使用者回合結束 messages,並依各預填的用途加以取代:

  • 輸出格式: 使用結構化輸出,或使用帶有列舉欄位的工具進行分類。
  • 開場白: 在系統提示中要求直接回答。
  • 接續內容: 將其移至使用者訊息,例如「您先前的回應被中斷,結尾為 [previous_response]。請從中斷處繼續。」
  • 上下文提醒: 將其放在使用者回合中。

將電腦使用移至工具集

Claude Haiku 4.5 透過 computer_20250124 工具並搭配 computer-use-2025-01-24 beta 標頭來支援電腦使用。Claude Haiku 5.5 則透過 computer_toolset_20260801 工具集支援電腦使用。向 Claude Haiku 5.5 發出宣告 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 錯誤。

在 Amazon Bedrock 上,Claude Haiku 5.5 也接受搭配 computer-use-2025-11-24 beta 標頭的 computer_20251124 工具。

Claude Haiku 5.5 支援瀏覽器使用工具(browser_toolset_20260801),用於網頁內的任務。Claude Haiku 4.5 不支援此工具。

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

Claude Haiku 5.5 的思考區塊僅在產生它們的帳戶或與該帳戶連結的帳戶中有效。當其他帳戶傳送這些區塊之一時,API 會在模型接收之前捨棄該區塊,而請求會在缺少該推理的情況下成功完成。這會影響儲存對話並透過不同帳戶重播對話的程式碼,例如從單一對話儲存區為多位客戶提供服務的服務。請透過產生對話的帳戶重播每段對話。請參閱帳戶與雲端平台。

保持較早的回合不變

請讓對話保持僅附加(append-only)。Claude Haiku 5.5 的思考區塊只有在其之前傳送的所有內容都保持不變時才有效:包括 system 提示、tools,以及每一則先前的訊息。

未通過前綴檢查可能會、也可能不會導致 400 錯誤。若要識別並處理這兩種情況,請參閱思考區塊的前綴檢查。

如需了解會觸發錯誤的變更以及應改為採取的做法,請參閱如果您的程式碼會變更系統提示、工具或歷史。

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

Claude Haiku 3.5 已在 Claude API、Amazon Bedrock 和 Claude Models on Google Cloud (Google managed) 上停用。Claude Haiku 3 已在 Claude API 和 Claude Models on Google Cloud (Google managed) 上停用。請參閱模型棄用。

無論從哪一個模型遷移,請先套用前述所有章節,再進行以下變更:

  • 模型 ID: 將 claude-3-5-haiku-20241022、其別名 claude-3-5-haiku-latest 或 claude-3-haiku-20240307 替換為 claude-haiku-5-5。在 Claude Models on Google Cloud (Google managed) 上,將 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 撰寫提示 和提示最佳實踐檢閱您的提示。

這個頁面有幫助嗎?