---
title: Claude Haiku 5.5 遷移指南
url: https://platform.claude.com/docs/zh-TW/models/haiku-5-5/migration-guide
description: 透過本遷移指南，從較早的 Haiku 模型切換至 Claude Haiku 5.5。啟用 Claude Haiku 5.5 的指引包括新的模型 ID、會傳回錯誤的設定、思考方面的變更，以及針對每個起始模型的檢查清單。
---
本指南涵蓋遷移 [Messages API](https://platform.claude.com/docs/zh-TW/build-with-claude/working-with-messages) 程式碼的相關內容。如果您使用 [Claude Managed Agents](https://platform.claude.com/docs/zh-TW/managed-agents/overview)，除了更新模型名稱之外，不需要進行任何其他變更。
**使用 Claude API skill 自動化您的遷移。** 在 Claude Code 中，執行 `/claude-api migrate` 以呼叫內建的 [Claude API skill](https://platform.claude.com/docs/zh-TW/agents-and-tools/agent-skills/claude-api-skill#migrating-to-a-newer-claude-model)。它適用於以任何目前的 Claude 模型作為目標：
讓 Claude Code 為您遷移程式碼
```text
/claude-api migrate 將此專案遷移至 claude-haiku-5-5
```
此 skill 會在您的整個程式碼庫中套用模型 ID 替換，並視需要處理破壞性參數變更、prefill（預填）替換，以及針對目標模型的 effort（努力程度）校準，然後產生一份需要手動驗證的項目清單。在編輯任何檔案之前，它會請您確認遷移範圍（整個工作目錄、某個子目錄，或特定的檔案清單）。此 skill 也會偵測 Amazon Bedrock 與 Claude Platform on AWS 用戶端，並針對這些平台調整模型 ID 格式與功能變更。
本指南說明如何將呼叫 Claude Haiku 4.5 的程式碼遷移至 Claude Haiku 5.5。對於呼叫 Claude Haiku 3.5 或 Claude Haiku 3 的程式碼，也請進行[從 Claude Haiku 3.5 及更早的 Haiku 模型遷移至 Claude Haiku 5.5](https://platform.claude.com/docs/zh-TW/models/haiku-5-5/migration-guide#migrating-from-haiku-35) 中的變更。若要改為升級至 Sonnet 或 Opus 模型，請參閱[在模型版本之間升級](https://platform.claude.com/docs/zh-TW/about-claude/models/migration-guide)。關於 Claude Haiku 4.5 的可用期限，請參閱[模型棄用](https://platform.claude.com/docs/zh-TW/about-claude/model-deprecations)。
## 依起始模型分類的遷移檢查清單
請依序往下處理各組，並在列出您目前模型的那一組之後停止。如果您使用的是 Claude Haiku 4.5，第一組就是完整的清單。每個項目都是您需要在程式碼中進行的一項變更。
### 所有起始模型
1. 將模型 ID 替換為您平台上的 Claude Haiku 5.5 ID。請參閱[使用 Claude Haiku 5.5 模型 ID](https://platform.claude.com/docs/zh-TW/models/haiku-5-5/migration-guide#use-the-claude-haiku-5-5-model-id)。
2. 重新計算您的提示，並重新檢視 `max_tokens` 限制和成本估算，因為相同的文字會計為更多 token，而大型圖片會計為更多視覺 token。請參閱[重新計算 token](https://platform.claude.com/docs/zh-TW/models/haiku-5-5/migration-guide#recount-tokens)。
3. 如果您的請求傳送 `thinking: {"type": "enabled", "budget_tokens": N}`，請將 `thinking` 變更為 `{"type": "adaptive"}`。請參閱[設定思考](https://platform.claude.com/docs/zh-TW/models/haiku-5-5/migration-guide#configure-thinking)。
4. 如果您的程式碼將第一個內容區塊讀取為答案，請改為依 `type` 選取區塊。請參閱[設定思考](https://platform.claude.com/docs/zh-TW/models/haiku-5-5/migration-guide#configure-thinking)。
5. 從您的請求中移除 `temperature`、`top_p` 和 `top_k`。請參閱[移除取樣參數](https://platform.claude.com/docs/zh-TW/models/haiku-5-5/migration-guide#remove-sampling-parameters)。
6. 如果您的請求以助理回合結束 `messages` 以讓模型接續，請改為以使用者回合結束。請參閱[取代助理預填](https://platform.claude.com/docs/zh-TW/models/haiku-5-5/migration-guide#replace-assistant-prefill)。
7. 如果您使用電腦使用功能，請替換 `computer_20250124`：在 Claude API 和 Google Cloud 上，替換為 `computer_toolset_20260801` 工具集；在 Amazon Bedrock 上，替換為 `computer_20251124` 並搭配 `computer-use-2025-11-24` beta 標頭。請參閱[將電腦使用遷移至工具集](https://platform.claude.com/docs/zh-TW/models/haiku-5-5/migration-guide#computer-use-toolset)。
8. 如果您透過不同的帳戶重播已儲存的對話，請透過產生該對話的帳戶重播每個對話。請參閱[透過產生思考區塊的帳戶重播思考區塊](https://platform.claude.com/docs/zh-TW/models/haiku-5-5/migration-guide#replay-thinking-blocks-through-the-producing-account)。
9. 如果您的程式碼在對話的請求之間變更 `system`、`tools` 或較早的 `messages`，並將思考區塊傳回，請讓對話保持僅附加（append-only）。請參閱[保持較早的回合不變](https://platform.claude.com/docs/zh-TW/models/haiku-5-5/migration-guide#keep-earlier-turns-unchanged)。
10. 處理 `stop_reason: "refusal"`。Claude Haiku 5.5 會執行可能拒絕請求的安全分類器，且沒有伺服器端備援。請參閱[安全防護拒絕](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#safeguard-refusals)。
11. 如果您在 Amazon Bedrock 上使用[結構化輸出](https://platform.claude.com/docs/zh-TW/build-with-claude/structured-outputs)（`output_config.format` 或 `strict: true` 工具），請在提示中描述格式，或使用不含 `strict` 的工具，並在您的程式碼中驗證輸出。Amazon Bedrock 上的 Claude Haiku 5.5 不提供結構化輸出。
如果您的組織在 Claude Haiku 4.5 上有 [Priority Tier](https://platform.claude.com/docs/zh-TW/api/service-tiers#supported-models) 承諾，請另行規劃容量：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](https://platform.claude.com/docs/zh-TW/models/haiku-5-5/migration-guide#migrating-from-haiku-35)。
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.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` |
| Google Cloud | `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%。確切的增幅取決於內容。請求、回應和串流事件保持相同的結構。改變的是您以 token 衡量或編列預算的任何項目：
* 對於相同的文字，`usage` 欄位和 [token 計數](https://platform.claude.com/docs/zh-TW/build-with-claude/token-counting)結果會更高。
* 特定數量的 token 所容納的文字較少。
* 針對 Claude Haiku 4.5 調整的 `max_tokens` 限制可能會截斷同等的輸出。
* 根據 Claude Haiku 4.5 的 token 計數所做的成本估算，需要以 Claude Haiku 5.5 的計數和[價格](https://platform.claude.com/docs/zh-TW/about-claude/pricing)重新計算，包括其針對長提示的較高價格。請參閱[長上下文定價](https://platform.claude.com/docs/zh-TW/about-claude/pricing#long-context-pricing)。
大型圖片也可能耗用更多 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 費用](https://platform.claude.com/docs/zh-TW/build-with-claude/vision#evaluate-image-size)。
請將 `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 預算：
```json
{
"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` 設定模型思考的程度：
```json
{
"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](https://platform.claude.com/docs/zh-TW/build-with-claude/effort) 作為調整手段：在 Claude Haiku 4.5 不使用思考、或使用小額預算以節省 token 的情況下，請選擇較低的 effort 等級。在較低的等級下，模型思考較少，且在較簡單的請求上可能完全略過思考。關於提示指引，請參閱[使用 effort 控制思考](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#use-effort-to-control-thinking)。請依內容區塊的 `type` 欄位而非位置來選取區塊，並將 `thinking` 區塊連同工具結果原封不動地傳回。
思考 token 會計入 `max_tokens`，因此 `max_tokens` 較小的請求可能會在 `thinking` 區塊之後、任何文字之前以 `stop_reason: "max_tokens"` 停止。如果您為 Claude Haiku 4.5 設定了較小的 `max_tokens`，請將其調高以保留思考空間，或選擇較低的 [effort](https://platform.claude.com/docs/zh-TW/build-with-claude/effort) 等級。
較早助理回合的思考區塊會保留在上下文中並計為輸入 token，而 Claude Haiku 4.5 只保留最新回合的思考區塊。因此，多回合對話所攜帶的輸入 token 會比單純分詞器變更所能解釋的更多。若要移除較舊的區塊，請使用[思考區塊清除](https://platform.claude.com/docs/zh-TW/build-with-claude/context-editing#thinking-block-clearing)。請參閱[各模型的思考區塊保留方式](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#thinking-block-preservation-by-model)。
預設情況下，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 的區塊。請參閱[在對話中途切換模型](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking#switching-models)。
## 移除取樣參數
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`，並依據每個預填的用途加以取代：
* **輸出格式：**使用[結構化輸出](https://platform.claude.com/docs/zh-TW/build-with-claude/structured-outputs)，或針對分類使用帶有列舉欄位的工具。在 Amazon Bedrock 上，Claude Haiku 5.5 不提供結構化輸出。在該平台上，請在提示中描述格式，或使用不含 `strict` 的工具，並在您的程式碼中驗證輸出。
* **開場白：**在系統提示中要求直接回答。
* **接續：**將其移至使用者訊息中，例如「您先前的回應被中斷，結尾為 `[previous_response]`。請從中斷處繼續。」
* **上下文提醒：**將其放在使用者回合中。
## 將電腦使用遷移至工具集
Claude Haiku 4.5 透過 `computer_20250124` 工具並搭配 `computer-use-2025-01-24` beta 標頭支援[電腦使用](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/computer-use-tool)。在 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` 遷移](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124)中的其他請求和代理迴圈變更：依每個成員 `tool_use` 區塊的 `name` 和 `toolset_name` 而非 `input.action` 進行分派，處理一個回合中的每個此類區塊，並在結果中回傳 `toolset_name`。工具集中的縮放功能預設為開啟；如果您的環境未實作此功能，請加入 `"configs": {"zoom": {"enabled": false}}`。如果您傳送 `fine-grained-tool-streaming-2025-05-14` beta 標頭，請將其移除。與工具集項目一起使用時，它會傳回 400 錯誤。關於其他平台，請參閱電腦使用工具的[相容性](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/computer-use-tool#compatibility)章節。
在 Claude API 和 Google Cloud 上，Claude Haiku 5.5 也支援用於網頁內任務的[瀏覽器使用工具](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/browser-use-tool)（`browser_toolset_20260801`）。Claude Haiku 4.5 不支援此工具。
## 透過產生思考區塊的帳戶重播思考區塊
來自 Claude Haiku 5.5 的思考區塊僅在產生它們的帳戶或與其連結的帳戶中有效。當其他帳戶傳送這些區塊之一時，API 會在模型看到該區塊之前將其捨棄，請求會在缺少該推理的情況下成功。這會影響儲存對話並透過不同帳戶重播的程式碼，例如以單一對話儲存區支援多個客戶的服務。請透過產生每個對話的帳戶重播該對話。請參閱[思考區塊僅限產生它們的帳戶使用](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking#account-bound-thinking)。
## 保持較早的回合不變
Claude Haiku 5.5 的思考區塊僅在其之前傳送的所有內容保持不變時才有效：在變更 `system`、`tools` 或較早的 `messages` 之後將思考區塊傳回的請求，會傳回 400 錯誤。Claude Haiku 4.5 不會執行此檢查。請讓對話保持僅附加。在 2026 年 8 月 31 日 00:00 UTC 之前建立的帳戶上，只有設定 `thinking.block_binding.prefix_mismatch_behavior` 的請求才會出現此錯誤。關於會觸發此錯誤的變更以及替代做法，請參閱[誰需要做出變更](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking#who-is-affected)。
## 從 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 列為已棄用，且僅供現有客戶使用。請參閱[模型棄用](https://platform.claude.com/docs/zh-TW/about-claude/model-deprecations)。
無論從哪個模型遷移，請先套用前面的每個章節，然後進行以下變更：
* **模型 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](https://platform.claude.com/docs/zh-TW/models/haiku-5-5/migration-guide#use-the-claude-haiku-5-5-model-id) 中的 Claude Haiku 5.5 ID。
* **程式碼執行：**Claude Haiku 5.5 接受 `code_execution_20250825` 及更新版本。如果您使用舊版僅支援 Python 的 `code_execution_20250522`，請改用其中一個版本。請參閱[升級至最新工具版本](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/code-execution-tool#upgrade-to-latest-tool-version)。
* **文字編輯器：**如果您使用文字編輯器工具，請改用 `text_editor_20250728`（工具名稱 `str_replace_based_edit_tool`），此版本沒有 `undo_edit` 命令。請參閱[文字編輯器工具](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/text-editor-tool)。
* **停止原因：**處理 `refusal` 和 `model_context_window_exceeded`。請參閱[處理停止原因](https://platform.claude.com/docs/zh-TW/build-with-claude/handling-stop-reasons)。
* **結尾換行字元：**Claude 4.5 及更新模型會在工具呼叫字串參數中保留結尾換行字元。如果您的程式碼精確比對這些字串，請允許這些換行字元。
* **提示：**Claude 4 及更新模型具有更簡潔、直接的溝通風格，且需要明確的指示。請對照[為 Claude Haiku 5.5 撰寫提示](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5)和[提示最佳實踐](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/claude-prompting-best-practices)檢視您的提示。