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,第一組即為完整清單。每個項目都是您需要在程式碼中進行的一項變更。
所有起始模型
- 將模型 ID 替換為您平台上的 Claude Haiku 5.5 ID。請參閱使用 Claude Haiku 5.5 模型 ID。
- 重新計算您的提示的 token 數,並重新檢視
max_tokens限制與成本估算,因為相同的文字會計算為更多 token,大型圖片也會計算為更多視覺 token。請參閱重新計算 token。 - 如果您的請求傳送
thinking: {"type": "enabled", "budget_tokens": N},請將thinking改為{"type": "adaptive"}。請參閱設定思考。 - 如果您的程式碼將第一個內容區塊讀取為答案,請改為依
type選取區塊。請參閱設定思考。 - 從您的請求中移除
temperature、top_p和top_k。請參閱移除取樣參數。 - 如果您的請求以助理回合結束
messages以讓模型接續,請改為以使用者回合結束。請參閱取代助理預填。 - 如果您使用電腦使用工具,請將
computer_20250124替換為computer_toolset_20260801工具集。在 Amazon Bedrock 上,computer_20251124也可使用。請參閱將電腦使用移至工具集。 - 如果您透過不同的帳戶重播已儲存的對話,請透過產生該對話的帳戶重播每一段對話。請參閱透過產生思考區塊的帳戶重播思考區塊。
- 如果您的程式碼在同一對話的請求之間變更
system、tools或先前的messages,並將思考區塊傳回,請保持對話為僅附加(append-only)。請參閱保持較早的回合不變。 - 處理
stop_reason: "refusal"。Claude Haiku 5.5 會執行可能拒絕請求的安全分類器,且沒有伺服器端備援。請參閱安全防護拒絕。 - 如果您的提示要求模型在回應中寫出其推理,例如在
<thinking>或<reasoning>標籤中,請移除這些指示。Claude Haiku 5.5 可能會拒絕包含這些指示的請求,並傳回reasoning_extraction類別。請參閱安全防護拒絕。
若您的組織在 Claude Haiku 4.5 上有 Priority Tier 承諾,請另行規劃容量:Claude Haiku 5.5 不支援 Priority Tier。
Claude Haiku 3.5 或更早版本
- 將 Claude Haiku 3.5 或 Claude Haiku 3 的模型 ID 替換為您平台上的 Claude Haiku 5.5 ID。請參閱從 Claude Haiku 3.5 及更早的 Haiku 模型遷移至 Claude Haiku 5.5。
- 若您使用
code_execution_20250522工具,請改用code_execution_20250825或更新版本。 - 若您使用文字編輯器工具,請改用
text_editor_20250728。 - 處理
refusal和model_context_window_exceeded停止原因。 - 若您的程式碼會完全比對工具呼叫的字串參數,請容許結尾換行字元。
- 檢閱您的提示。
使用 Claude Haiku 5.5 模型 ID
將 Claude Haiku 4.5 模型 ID 替換為您平台上的 Claude Haiku 5.5 ID。
| 平台 | Claude Haiku 4.5 | Claude Haiku 5.5 |
|---|---|---|
| Claude API | claude-haiku-4-5-20251001 或 claude-haiku-4-5 | claude-haiku-5-5 |
| Amazon Bedrock | anthropic.claude-haiku-4-5 | anthropic.claude-haiku-5-5 |
| Claude Platform on AWS | claude-haiku-4-5 | claude-haiku-5-5 |
| Claude Models on Google Cloud (Anthropic managed) | claude-haiku-4-5-20251001 | claude-haiku-5-5 |
| Claude Models on Google Cloud (Google managed) | claude-haiku-4-5@20251001 | claude-haiku-5-5 |
| Microsoft Foundry | claude-haiku-4-5 | claude-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 撰寫提示 和提示最佳實踐檢閱您的提示。
這個頁面有幫助嗎?