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,第一组就是完整清单。每一项都是您需要在代码中进行的一处更改。
所有起始模型
- 将模型 ID 替换为您所用平台上的 Claude Haiku 5.5 ID。请参阅使用 Claude Haiku 5.5 模型 ID。
- 重新计算提示的令牌数,并重新审视
max_tokens限制和成本估算,因为相同的文本会计为更多令牌,大尺寸图像也会计为更多视觉令牌。请参阅重新计算令牌。 - 如果您的请求发送
thinking: {"type": "enabled", "budget_tokens": N},请将thinking改为{"type": "adaptive"}。请参阅配置思考。 - 如果您的代码将第一个内容块读取为答案,请改为按
type选择内容块。请参阅配置思考。 - 从您的请求中移除
temperature、top_p和top_k。请参阅移除采样参数。 - 如果您的请求以助手轮次结束
messages以便模型继续生成,请改为以用户轮次结束。请参阅替换助手预填充。 - 如果您使用计算机使用功能,请将
computer_20250124替换为computer_toolset_20260801工具集。在 Amazon Bedrock 上,computer_20251124也可以使用。请参阅将计算机使用迁移到工具集。 - 如果您通过不同的账户重放已存储的对话,请通过生成每个对话的账户来重放该对话。请参阅通过生成思考块的账户重放思考块。
- 如果您的代码在同一对话的请求之间更改
system、tools或较早的messages,并将思考块发回,请保持对话仅追加(append-only)。请参阅保持较早的轮次不变。 - 处理
stop_reason: "refusal"。Claude Haiku 5.5 运行的安全分类器可能会拒绝请求,并且它没有服务器端回退机制。请参阅安全防护拒绝。
如果您的组织在 Claude Haiku 4.5 上有 Priority Tier 承诺,请单独规划容量:Claude Haiku 5.5 不支持 Priority Tier。
Claude Haiku 3.5 或更早版本
- 将 Claude Haiku 3.5 或 Claude Haiku 3 的模型 ID 替换为您所用平台的 Claude Haiku 5.5 ID。请参阅从 Claude Haiku 3.5 及更早的 Haiku 模型迁移到 Claude Haiku 5.5。
- 如果您使用
code_execution_20250522工具,请迁移到code_execution_20250825或更高版本。 - 如果您使用文本编辑器工具,请迁移到
text_editor_20250728。 - 处理
refusal和model_context_window_exceeded停止原因。 - 如果您的代码对工具调用的字符串参数进行精确匹配,请允许末尾换行符的存在。
- 检查您的提示。
使用 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,没有日期后缀,也没有单独的别名。
重新计算令牌
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 编写提示和提示最佳实践检查您的提示。