Claude Haiku 5.5 迁移指南

借助本迁移指南,从早期 Haiku 模型切换到 Claude Haiku 5.5。启用 Claude Haiku 5.5 的指导内容包括新的模型 ID、会返回错误的设置、思考方面的变更,以及针对每个起始模型的检查清单。

让 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,第一组就是完整清单。每一项都是您需要在代码中进行的一处更改。

所有起始模型

  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 替换为 computer_toolset_20260801 工具集。在 Amazon Bedrock 上,computer_20251124 也可以使用。请参阅将计算机使用迁移到工具集。
  8. 如果您通过不同的账户重放已存储的对话,请通过生成每个对话的账户来重放该对话。请参阅通过生成思考块的账户重放思考块。
  9. 如果您的代码在同一对话的请求之间更改 system、tools 或较早的 messages,并将思考块发回,请保持对话仅追加(append-only)。请参阅保持较早的轮次不变。
  10. 处理 stop_reason: "refusal"。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 4.5Claude Haiku 5.5
Claude APIclaude-haiku-4-5-20251001 或 claude-haiku-4-5claude-haiku-5-5
Amazon Bedrockanthropic.claude-haiku-4-5anthropic.claude-haiku-5-5
Claude Platform on AWSclaude-haiku-4-5claude-haiku-5-5
Claude Models on Google Cloud (Anthropic managed)claude-haiku-4-5-20251001claude-haiku-5-5
Claude Models on Google Cloud (Google managed)claude-haiku-4-5@20251001claude-haiku-5-5
Microsoft Foundryclaude-haiku-4-5claude-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 字段和令牌计数结果会更高。
  • 相同数量的令牌所能容纳的文本更少。
  • 针对 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 不同。thinking 值为 {"type": "enabled", "budget_tokens": N} 时会返回 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 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 请求头支持 “computer use”(计算机使用)。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 会在模型接收之前丢弃该块,请求仍会成功,但不包含该推理内容。这会影响存储对话并通过不同账户重放对话的代码,例如从同一个对话存储为多个客户提供服务的服务。请通过生成对话的账户重放每个对话。请参阅账户和云平台。

保持较早的轮次不变

请保持对话仅追加。Claude Haiku 5.5 的思考块仅在其之前发送的所有内容保持不变时才有效:包括 system 提示、tools 以及之前的每条消息。

未通过 “prefix check”(前缀检查)可能会也可能不会导致 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 编写提示和提示最佳实践检查您的提示。
文档内容持续同步更新