---
title: Claude Haiku 5.5 迁移指南
url: https://platform.claude.com/docs/zh-CN/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-CN/build-with-claude/working-with-messages) 代码的迁移。如果您使用 [Claude Managed Agents](https://platform.claude.com/docs/zh-CN/managed-agents/overview)，则除了更新模型名称之外无需进行任何更改。
**使用 Claude API skill 自动完成迁移。** 在 Claude Code 中，运行 `/claude-api migrate` 以调用内置的 [Claude API skill](https://platform.claude.com/docs/zh-CN/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-CN/models/haiku-5-5/migration-guide#migrating-from-haiku-35) 中的更改。如果您想改为升级到 Sonnet 或 Opus 模型，请参阅[在模型版本之间升级](https://platform.claude.com/docs/zh-CN/about-claude/models/migration-guide)。有关 Claude Haiku 4.5 的可用期限，请参阅[模型弃用](https://platform.claude.com/docs/zh-CN/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-CN/models/haiku-5-5/migration-guide#use-the-claude-haiku-5-5-model-id)。
2. 重新计算提示的令牌数，并重新审视 `max_tokens` 限制和成本估算，因为相同的文本会计为更多令牌，大图像也会计为更多视觉令牌。请参阅[重新计算令牌](https://platform.claude.com/docs/zh-CN/models/haiku-5-5/migration-guide#recount-tokens)。
3. 如果您的请求发送 `thinking: {"type": "enabled", "budget_tokens": N}`，请将 `thinking` 更改为 `{"type": "adaptive"}`。请参阅[配置思考](https://platform.claude.com/docs/zh-CN/models/haiku-5-5/migration-guide#configure-thinking)。
4. 如果您的代码将第一个内容块读取为答案，请改为按 `type` 选择内容块。请参阅[配置思考](https://platform.claude.com/docs/zh-CN/models/haiku-5-5/migration-guide#configure-thinking)。
5. 从您的请求中移除 `temperature`、`top_p` 和 `top_k`。请参阅[移除采样参数](https://platform.claude.com/docs/zh-CN/models/haiku-5-5/migration-guide#remove-sampling-parameters)。
6. 如果您的请求以助手轮次结束 `messages` 以供模型续写，请改为以用户轮次结束。请参阅[替换助手预填充](https://platform.claude.com/docs/zh-CN/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-CN/models/haiku-5-5/migration-guide#computer-use-toolset)。
8. 如果您通过不同的账户重放已存储的对话，请通过生成每个对话的账户来重放该对话。请参阅[通过生成思考块的账户重放思考块](https://platform.claude.com/docs/zh-CN/models/haiku-5-5/migration-guide#replay-thinking-blocks-through-the-producing-account)。
9. 如果您的代码在同一对话的请求之间更改 `system`、`tools` 或较早的 `messages`，并将思考块发送回去，请保持对话为仅追加模式。请参阅[保持较早的轮次不变](https://platform.claude.com/docs/zh-CN/models/haiku-5-5/migration-guide#keep-earlier-turns-unchanged)。
10. 处理 `stop_reason: "refusal"`。Claude Haiku 5.5 运行的安全分类器可能会拒绝请求，并且它没有服务器端回退机制。请参阅[安全防护拒绝](https://platform.claude.com/docs/zh-CN/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#safeguard-refusals)。
11. 如果您在 Amazon Bedrock 上使用 [结构化输出](https://platform.claude.com/docs/zh-CN/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-CN/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-CN/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，没有日期后缀，也没有单独的别名。
## 重新计算令牌
Claude Haiku 5.5 使用与 Claude 4.7 及更高版本模型相同的较新 "tokenizer"（分词器）。与所有使用此分词器的模型一样，相同的输入文本在 Claude Haiku 5.5 上产生的令牌数比在 Claude Haiku 4.5 上多约 30%。具体增幅取决于内容。请求、响应和 "streaming"（流式传输）事件的结构保持不变。发生变化的是您以令牌为单位衡量或预算的任何内容：
* 对于相同的文本，`usage` 字段和[令牌计数](https://platform.claude.com/docs/zh-CN/build-with-claude/token-counting)结果会更高。
* 给定数量的令牌所能容纳的文本更少。
* 针对 Claude Haiku 4.5 调整的 `max_tokens` 限制可能会截断同等长度的输出。
* 基于 Claude Haiku 4.5 令牌计数得出的成本估算，需要使用 Claude Haiku 5.5 的计数和[价格](https://platform.claude.com/docs/zh-CN/about-claude/pricing)重新计算，包括其针对长提示的更高价格。请参阅[长上下文定价](https://platform.claude.com/docs/zh-CN/about-claude/pricing#long-context-pricing)。
大图像也可能消耗更多令牌。Claude Haiku 5.5 使用高分辨率图像层级，会对长边超过 2,576 像素或超过 4,784 个视觉令牌的图像进行缩小。Claude Haiku 4.5 及更早的 Haiku 模型使用标准层级，会对长边超过 1,568 像素或超过 1,568 个视觉令牌的图像进行缩小。一张 2,000 × 1,500 像素的图像在 Claude Haiku 5.5 上消耗的视觉令牌约为在 Claude Haiku 4.5 上的 2.5 倍。请参阅[分辨率和令牌费用](https://platform.claude.com/docs/zh-CN/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` 并附带令牌预算：
```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-CN/build-with-claude/effort) 作为调节手段：在 Claude Haiku 4.5 不使用思考或使用较小预算以节省令牌的场景中，请选择较低的 effort 级别。在较低级别下，模型思考得更少，并且在较简单的请求上可以完全跳过思考。有关提示指导，请参阅[使用 effort 控制思考](https://platform.claude.com/docs/zh-CN/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#use-effort-to-control-thinking)。请按内容块的 `type` 字段而非位置来选择内容块，并将 `thinking` 块连同工具结果原样传回。
思考令牌计入 `max_tokens`，因此 `max_tokens` 较小的请求可能会在 `thinking` 块之后、任何文本之前以 `stop_reason: "max_tokens"` 停止。如果您为 Claude Haiku 4.5 设置了较小的 `max_tokens`，请将其调高以为思考留出空间，或选择较低的 [effort](https://platform.claude.com/docs/zh-CN/build-with-claude/effort) 级别。
较早助手轮次中的思考块会保留在上下文中并计为输入令牌，而 Claude Haiku 4.5 只保留最新轮次的思考块。因此，多轮对话携带的输入令牌会比仅由分词器变化所能解释的更多。要移除较旧的思考块，请使用[思考块清除](https://platform.claude.com/docs/zh-CN/build-with-claude/context-editing#thinking-block-clearing)。请参阅[各模型的思考块保留](https://platform.claude.com/docs/zh-CN/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-CN/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 错误，包括值为 `1` 的 `top_p`。任何 `top_k` 值也会返回 400 错误，同时包含 `temperature` 和 `top_p` 的请求同样如此。
## 替换助手预填充
"Prefill"（预填充）是 `messages` 中供模型续写的最后一个助手轮次。Claude Haiku 4.5 在思考关闭时接受预填充。Claude Haiku 5.5 会以 400 错误拒绝预填充，即使思考已关闭也是如此。请以用户轮次结束 `messages`，并根据每个预填充的用途进行替换：
* **输出格式：** 使用[结构化输出](https://platform.claude.com/docs/zh-CN/build-with-claude/structured-outputs)，或使用带有枚举字段的工具进行分类。在 Amazon Bedrock 上，Claude Haiku 5.5 不支持结构化输出。在该平台上，请在提示中描述格式，或使用不带 `strict` 的工具，并在代码中验证输出。
* **开场白：**在系统提示中要求直接给出答案。
* **续写：**将其移至用户消息中，例如"Your previous response was interrupted and ended with `[previous_response]`. Continue from where you left off."
* **上下文提醒：**将其放在用户轮次中。
## 将计算机使用迁移到工具集
Claude Haiku 4.5 通过 `computer_20250124` 工具并配合 `computer-use-2025-01-24` beta 标头支持[计算机使用](https://platform.claude.com/docs/zh-CN/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-CN/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-CN/agents-and-tools/tool-use/computer-use-tool#compatibility)部分。
在 Claude API 和 Google Cloud 上，Claude Haiku 5.5 还支持用于网页内任务的[浏览器使用工具](https://platform.claude.com/docs/zh-CN/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-CN/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-CN/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-CN/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-CN/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-CN/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-CN/agents-and-tools/tool-use/text-editor-tool)。
* **停止原因：** 处理 `refusal` 和 `model_context_window_exceeded`。请参阅[处理停止原因](https://platform.claude.com/docs/zh-CN/build-with-claude/handling-stop-reasons)。
* **末尾换行符：** Claude 4.5 及更高版本的模型会保留工具调用字符串参数中的末尾换行符。如果您的代码对这些字符串进行精确匹配，请考虑这些换行符。
* **提示：** Claude 4 及更高版本的模型具有更简洁、直接的沟通风格，并且需要明确的指示。请对照[为 Claude Haiku 5.5 编写提示](https://platform.claude.com/docs/zh-CN/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5)和[提示最佳实践](https://platform.claude.com/docs/zh-CN/build-with-claude/prompt-engineering/claude-prompting-best-practices)审查您的提示。