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. 重新计算提示的令牌数，并重新审视 max_tokens 限制和成本估算，因为相同的文本会计为更多令牌，大图像也会计为更多视觉令牌。请参阅重新计算令牌。
3. 如果您的请求发送 thinking: {"type": "enabled", "budget_tokens": N}，请将 thinking 更改为 {"type": "adaptive"}。请参阅配置思考。
4. 如果您的代码将第一个内容块读取为答案，请改为按 type 选择内容块。请参阅配置思考。
5. 从您的请求中移除 temperature、top_p 和 top_k。请参阅移除采样参数。
6. 如果您的请求以助手轮次结束 messages 以供模型续写，请改为以用户轮次结束。请参阅替换助手预填充。
7. 如果您使用计算机使用功能，请替换 computer_20250124：在 Claude API 和 Google Cloud 上，替换为 computer_toolset_20260801 工具集；在 Amazon Bedrock 上，替换为 computer_20251124 并使用 computer-use-2025-11-24 beta 标头。请参阅将计算机使用迁移到工具集。
8. 如果您通过不同的账户重放已存储的对话，请通过生成每个对话的账户来重放该对话。请参阅通过生成思考块的账户重放思考块。
9. 如果您的代码在同一对话的请求之间更改 system、tools 或较早的 messages，并将思考块发送回去，请保持对话为仅追加模式。请参阅保持较早的轮次不变。
10. 处理 stop_reason: "refusal"。Claude Haiku 5.5 运行的安全分类器可能会拒绝请求，并且它没有服务器端回退机制。请参阅安全防护拒绝。
11. 如果您在 Amazon Bedrock 上使用 结构化输出（output_config.format 或 strict: true 工具），请在提示中描述格式，或使用不带 strict 的工具，并在代码中验证输出。在 Amazon Bedrock 上，Claude Haiku 5.5 不支持结构化输出。

如果您的组织在 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-5-5 是一个固定的模型 ID，没有日期后缀，也没有单独的别名。

重新计算令牌

Claude Haiku 5.5 使用与 Claude 4.7 及更高版本模型相同的较新 "tokenizer"（分词器）。与所有使用此分词器的模型一样，相同的输入文本在 Claude Haiku 5.5 上产生的令牌数比在 Claude Haiku 4.5 上多约 30%。具体增幅取决于内容。请求、响应和 "streaming"（流式传输）事件的结构保持不变。发生变化的是您以令牌为单位衡量或预算的任何内容：

• 对于相同的文本，usage 字段和令牌计数结果会更高。
• 给定数量的令牌所能容纳的文本更少。
• 针对 Claude Haiku 4.5 调整的 max_tokens 限制可能会截断同等长度的输出。
• 基于 Claude Haiku 4.5 令牌计数得出的成本估算，需要使用 Claude Haiku 5.5 的计数和价格重新计算，包括其针对长提示的更高价格。请参阅长上下文定价。

大图像也可能消耗更多令牌。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 倍。请参阅分辨率和令牌费用。

请将 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 并附带令牌预算：

{
  "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 不使用思考或使用较小预算以节省令牌的场景中，请选择较低的 effort 级别。在较低级别下，模型思考得更少，并且在较简单的请求上可以完全跳过思考。有关提示指导，请参阅使用 effort 控制思考。请按内容块的 type 字段而非位置来选择内容块，并将 thinking 块连同工具结果原样传回。

思考令牌计入 max_tokens，因此 max_tokens 较小的请求可能会在 thinking 块之后、任何文本之前以 stop_reason: "max_tokens" 停止。如果您为 Claude Haiku 4.5 设置了较小的 max_tokens，请将其调高以为思考留出空间，或选择较低的 effort 级别。

较早助手轮次中的思考块会保留在上下文中并计为输入令牌，而 Claude Haiku 4.5 只保留最新轮次的思考块。因此，多轮对话携带的输入令牌会比仅由分词器变化所能解释的更多。要移除较旧的思考块，请使用思考块清除。请参阅各模型的思考块保留。

默认情况下，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 的思考块。请参阅在对话中途切换模型。

移除采样参数

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，并根据每个预填充的用途进行替换：

• 输出格式： 使用结构化输出，或使用带有枚举字段的工具进行分类。在 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 标头支持计算机使用。在 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 迁移中的其他请求和智能体循环更改：根据每个成员 tool_use 块的 name 和 toolset_name 而不是 input.action 进行分派，处理一个轮次中的每个此类块，并在结果中回传 toolset_name。工具集中的缩放功能默认开启；如果您的环境未实现该功能，请添加 "configs": {"zoom": {"enabled": false}}。如果您发送了 fine-grained-tool-streaming-2025-05-14 beta 标头，请将其移除。与工具集条目一起使用时，它会返回 400 错误。有关其他平台，请参阅计算机使用工具的兼容性部分。

在 Claude API 和 Google Cloud 上，Claude Haiku 5.5 还支持用于网页内任务的浏览器使用工具（browser_toolset_20260801）。Claude Haiku 4.5 不支持该工具。

通过生成思考块的账户重放思考块

来自 Claude Haiku 5.5 的思考块仅在生成它们的账户或与之关联的账户中有效。当其他账户发送这些块之一时，API 会在模型看到该块之前将其丢弃，请求会在缺少该推理的情况下成功完成。这会影响存储对话并通过不同账户重放对话的代码，例如从一个对话存储为多个客户提供服务的服务。请通过生成每个对话的账户来重放该对话。请参阅思考块仅限于生成它们的账户。

保持较早的轮次不变

Claude Haiku 5.5 的思考块仅在其之前发送的所有内容保持不变时才有效：在更改 system、tools 或较早的 messages 之后将思考块发送回去的请求会返回 400 错误。Claude Haiku 4.5 不执行此检查。请保持对话为仅追加模式。对于在 2026 年 8 月 31 日 00:00 UTC 之前创建的账户，仅在设置了 thinking.block_binding.prefix_mismatch_behavior 的请求上才会出现该错误。有关触发该错误的更改以及替代做法，请参阅谁需要做出更改。

从 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 列为已弃用，且仅对现有客户可用。请参阅模型弃用。

无论从哪个模型迁移，请先应用前面的所有部分，然后进行以下更改：

• 模型 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 中的 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 编写提示和提示最佳实践审查您的提示。