Claude Haiku 5.5 迁移指南

本指南介绍如何将调用 Claude Haiku 4.5 的代码迁移到 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. 如果您在 Claude API 或 Google Cloud 上使用计算机使用功能，请从 computer_20250124 迁移到 computer_toolset_20260801 工具集。请参阅将计算机使用迁移到工具集。
8. 如果您通过不同的账户重放已存储的对话，请通过生成每个对话的账户来重放该对话。请参阅通过生成思考块的账户重放思考块。
9. 如果您的代码在同一对话的请求之间更改 system、tools 或较早的 messages，并将思考块发送回去，请保持对话为仅追加模式。请参阅保持较早的轮次不变。
10. 处理 stop_reason: "refusal"。Claude Haiku 5.5 运行的安全分类器可能会拒绝请求，并且它没有服务器端回退机制。请参阅安全防护拒绝。

如果您的组织在 Claude Haiku 4.5 上有 Priority Tier 承诺，请单独规划容量：Claude Haiku 5.5 不支持 Priority Tier。

使用 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 的计数和价格重新计算。

请将 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 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 接受 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 中，请使用工具。
• 开场白：在系统提示中要求直接给出答案。
• 续写：将其移至用户消息中，例如"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 错误。

要迁移集成，请删除 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 的请求上才会出现该错误。有关触发该错误的更改以及替代做法，请参阅谁需要做出更改。