---
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、會傳回錯誤的設定、思考方面的變更，以及針對每個起始模型的檢查清單。
---

<Note>
  本指南涵蓋遷移 [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)，除了更新模型名稱之外，不需要進行任何其他變更。
</Note>

讓 Claude Code 為您遷移程式碼

```text
/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](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. 重新計算您的提示的 token 數，並重新檢視 `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` 替換為 `computer_toolset_20260801` 工具集。在 Amazon Bedrock 上，`computer_20251124` 也可使用。請參閱[將電腦使用移至工具集](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. 如果您的提示要求模型在回應中寫出其推理，例如在 `<thinking>` 或 `<reasoning>` 標籤中，請移除這些指示。Claude Haiku 5.5 可能會拒絕包含這些指示的請求，並傳回 `reasoning_extraction` 類別。請參閱[安全防護拒絕](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#safeguard-refusals)。

若您的組織在 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` |
| 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 計數](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 的 token 數和價格重新計算，包括其長提示的較高價格。請參閱[定價](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` 來計算您提示的 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 預算：

```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 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 切換至任何其他模型 | 否 |

請參閱[切換模型再切換回來](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking#switching-models)。對於不涉及 Claude Haiku 5.5 的切換，請參閱[在 Claude API 上哪些模型切換會保留推理](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking#which-model-switches-keep-reasoning)。

## 移除取樣參數

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

## 取代助理預填

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

* **輸出格式：** 使用[結構化輸出](https://platform.claude.com/docs/zh-TW/build-with-claude/structured-outputs)，或使用帶有列舉欄位的工具進行分類。
* **開場白：** 在系統提示中要求直接回答。
* **接續內容：** 將其移至使用者訊息，例如「您先前的回應被中斷，結尾為 `[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 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` 遷移](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 錯誤。

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

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)。

## 保持較早的回合不變

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

未通過[前綴檢查](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking/prefix-checks#prefix-check)可能會、也可能不會導致 [400 錯誤](https://platform.claude.com/docs/zh-TW/api/errors#thinking-block-conversation-mismatch)。若要識別並處理這兩種情況，請參閱[思考區塊的前綴檢查](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking/prefix-checks)。

如需了解會觸發錯誤的變更以及應改為採取的做法，請參閱[如果您的程式碼會變更系統提示、工具或歷史](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking/prefix-checks#what-to-check)。

## 從 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) 上停用。請參閱[模型棄用](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`。在 Claude Models on Google Cloud (Google managed) 上，將 `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)檢閱您的提示。
