Claude Haiku 5.5 迁移指南：旧请求为什么报错，现有代码应该怎样改？

从 Haiku 4.5 或更早版本升级：对照请求改写、思考块解析、电脑操作工具集与会话回放规则，附升级核对清单。

作者：Anthropic10-09 · 15 分钟

Anthropic 发布了 Claude Haiku 5.5。这款轻量模型主要面向调用频繁、对费用和响应速度敏感的应用，也能作为子 Agent 配合旗舰模型处理具体任务。

它的主要功能特点与这次发布的配套更新包括：

  • 高频任务更便宜：平均运行成本较 Haiku 4.5 降低约 75%，面向摘要、上下文压缩、数据库查询和分类等重复工作。
  • 响应更快：在标准速度下是最快的 Claude 模型，适合实时客服等需要快速回应的场景。（开启 Fast Mode 的 Opus 更快。）
  • 配合旗舰模型做编码子任务：可作为子 Agent 与 Sonnet 5.5、Opus 5.5 搭配，接手范围明确的工作。
  • 首次支持可调推理投入：Haiku 系列加入 effort 设置，可以按任务调整思考投入，在费用与表现之间取舍。
  • 多项能力提升：官方评测中，电脑操作、知识工作和编码成绩均高于 Haiku 4.5。
  • Sonnet 缓存读取降价：单价减半；Anthropic 测算，多数 Sonnet 5.5 Agent 任务的总成本因此降低约 20%。
  • SDK 增加操作支持：Python 与 TypeScript SDK 加入电脑操作和浏览器操作的 Beta 支持。
  • 订阅用户获得 API 额度：伴随发布，Anthropic 将逐步向 Max 与 Team 用户推出月度 API 信用额度，可用于 Claude Platform 上的任意模型。

已经接入 Haiku 4.5 的应用，升级到 Claude Haiku 5.5 时，需要同时检查请求参数、响应解析和多轮会话。旧的思考配置、采样参数或助手消息预填充可能返回 HTTP 400；沿用按位置取答案的代码，也可能读不到正文。

这份官方迁移指南针对 Messages API （向 Claude 发送对话并接收响应的接口）。使用 Claude Managed Agents 的应用，文档要求只更新模型名；已有 API 集成则按下面的项目检查。Haiku 3.5 或 Haiku 3 用户，还要完成文末的跨代补充项。

模型的能力与价格变化可先看Haiku 5.5 发布解读。本篇集中说明现有代码怎样升级。

升级捷径：用命令行工具自动化排查

在手动翻改代码之前，如果你使用官方的 Claude Code 开发环境，可以直接借助内置的迁移技能辅助检查并修改代码：

/claude-api migrate this project to claude-haiku-5-5

这套自动化工具会检查代码库，替换模型 ID，并按需修改不兼容参数、替换助手消息预填充和调整 effort。在正式修改文件前，它会提示你确认改动范围（支持整个工作目录、子目录或指定文件列表）；同时，它还能识别 Amazon Bedrock 以及 AWS 版 Claude 客户端，自动把模型 ID 调整为该平台对应的格式。

迁移技能还会调整 effort，并输出需要人工验证的清单。自动修改后，仍要核对请求、响应解析和会话处理是否符合下面的规则。

请求怎么改：模型 ID、思考配置与旧参数

这一层改动直接发生在向 Messages API 发送 HTTP 请求的 Request Body 中。其中几种旧写法在 Haiku 5.5 中会返回 HTTP 400，具体条件如下。

1. 模型 ID 替换：统一固定标识

Haiku 5.5 采用了无日期后缀的固定模型 ID，不再提供单独的最新别名（alias）。各云服务平台的对应关系如下：

平台环境 旧版写法 (Haiku 4.5) 新版固定写法 (Haiku 5.5) 说明
Claude API (官方直连) claude-haiku-4-5-20251001 或 claude-haiku-4-5 claude-haiku-5-5 固定 ID，无日期后缀
Amazon Bedrock anthropic.claude-haiku-4-5 anthropic.claude-haiku-5-5 需注意平台特有前缀
Claude Platform on AWS claude-haiku-4-5 claude-haiku-5-5 统一固定 ID
Google Cloud (Vertex AI) claude-haiku-4-5@20251001 claude-haiku-5-5 去掉 @版本日期 后缀
Microsoft Foundry claude-haiku-4-5 claude-haiku-5-5 统一固定 ID

2. 用 effort 调整思考投入

  • 旧写法现象：在 Haiku 4.5 中，开启深度思考通常使用 thinking: {"type": "enabled", "budget_tokens": 8000}。如果在 Haiku 5.5 沿用此写法，API 会直接返回 HTTP 400 错误。
  • 机制变动：Haiku 5.5 废弃了显式的数字 Token 预算，改为 自适应思考（Adaptive Thinking）。控制思考强度的杠杆转移到了 output_config.effort 字段。
  • 默认开启机制：自适应思考是默认开启的。即使你的请求体完全不写 thinking 参数，模型返回的响应中也可能会包含思考块。如果你希望模型少思考以节省时间和 Token，可以把 effort 调低（如 "low"）；投入较低时，模型思考更少，也可能在简单请求中跳过思考。
  • 思考摘要展示：旧版 4.5 会返回带有摘要文本的思考内容；而在 5.5 中，默认返回的思考块内 thinking 文本字段是空的，只保留 signature 签名字段。如果你的业务前端必须展示思考过程摘要，请求中必须显式声明 thinking: {"type": "adaptive", "display": "summarized"}。
  • 强制工具调用时的行为：如果在请求中配置了强制工具调用（例如 tool_choice: {"type": "any"} 或指定具体工具名），Haiku 5.5 会直接输出工具调用指令，不会生成任何思考块。如果业务必须让模型“先想再调”，必须将工具调用设为 auto 模式 tool_choice: {"type": "auto"}，并在 Prompt 中明确说明触发工具的时机。

3. 删除旧的采样参数

  • 旧写法现象：旧代码习惯性配置 temperature: 0.7、top_p: 0.9 或自定义 top_k。在 Haiku 5.5 中，这些全都会触发 HTTP 400 校验失败。
  • 新版规范：直接从请求中完全删除 temperature、top_p 和 top_k，把输出风格和发散程度交由 Prompt 提示词来控制。
  • 严格硬性校验规则：
    • 如果请求一定要带 temperature，其数值必须且只能是 1；
    • 如果请求一定要带 top_p，其数值必须且只能是默认值 0.99（注意：即使传 top_p: 1 也会报 400）；
    • 只要请求中出现任何 top_k 值，立即报 400；
    • 如果在一个请求中同时携带了 temperature 和 top_p，哪怕都是上述合法值，依然直接报 400 错误。

4. 替换助手消息预填充

  • 旧写法现象：在旧版中，一些应用会在 messages 数组最后塞一条未闭合的助手消息（如 {"role": "assistant", "content": "{"} 或 {"role": "assistant", "content": "Sure, here is the answer:"}），以此引导模型输出纯 JSON 或跳过礼貌性废话。在 Haiku 5.5 中，用末尾 assistant 消息让模型续写，会返回 HTTP 400，即使关闭思考也一样。将请求的 messages 列表改为以 user 消息结尾。
  • 针对性改造方案：
旧模式：依赖 Assistant 消息末尾引导
[User: "..."] -> [Assistant: "引导内容..."] -> 触发 400 错误！

新模式：依用途分别化解到系统提示、结构化接口或用户轮次
├─ 强约束格式（如 JSON） ────> 改用结构化输出（Structured Outputs）或带 Enum 的工具定义
├─ 消除开场废话（Preambles） ─> 移至 System Prompt 明确指令（如“请直接给出答案，禁止任何前置客套”）
├─ 断点续写（Continuations） ──> 移至 User 消息（“上轮回答在 [...] 处中断，请紧接此处继续输出”）
└─ 上下文强提醒 ──────────────> 直接追加在当前的 User 消息末尾

特殊平台限制注意：Amazon Bedrock 平台目前不支持原生结构化输出（Structured Outputs），如果在 Bedrock 上需要对输出做严格格式约束，推荐定义一个包含参数结构的工具（Tool），并引导模型调用该工具来承载结构化结果。

Token 和会话怎么处理：重算用量，保留思考块的上下文

这一层改动不一定会在单次简单调用中暴露，但会影响多轮对话系统、聊天记录存储服务、计费系统以及长文本处理的稳定性。

1. 重新计数：同一段输入约多 30% Token

  • 机制变化：Haiku 5.5 使用了与 Claude 4.7 及后续模型相同的更新分词器。对于完全相同的一段文本，在 Haiku 5.5 下解析出的 Token 数量比在 Haiku 4.5 下 多出大约 30%，具体增幅取决于内容。
  • 引发的生产问题：
    1. 输出截断：固定数量的 Token 能容纳的文字变少。沿用为 Haiku 4.5 调好的 max_tokens 上限，可能截断同等长度的输出。
    2. 思考耗尽配额：思考 Token 同样占用 max_tokens 配额。如果旧代码设了一个较小的 max_tokens，模型可能在自适应思考阶段用完额度，最后给出的响应只有思考块，而没有任何实际的正文回复，停止原因返回 stop_reason: "max_tokens"。
    3. 计费与预估偏差：凡是本地依赖 Token 计数器评估预算、计算单次调用成本的模块，要重新测算；调用 Token 计数接口时，显式传入 model: "claude-haiku-5-5"，不能复用旧版 4.5 的测算数据。

2. 回传思考块时，前面的对话保持不变

  • 需要排查的代码：应用可能会裁剪早先的对话，或调整 system 和 tools，再把包含历史思考块的消息回传。Haiku 4.5 不执行下面这项前缀检查。
  • 新版严格检查：Haiku 5.5 的思考块在它前面的内容保持不变时才有效。如果回传思考块时修改了此前的 system、tools 或早先的 messages，请求会返回 400。文档列出的兼容情况是：创建于 2026 年 8 月 31 日 00:00 UTC 之前的账户，只有在请求设置 thinking.block_binding.prefix_mismatch_behavior 时才会触发这类错误。
  • 改造原则：维护带思考块的会话必须采用纯追加模式（Append-Only）。保留思考块时，不修改它之前的系统提示、工具或消息。

3. 重放会话时使用生成思考块的账户

在多租户 SaaS 架构或大型中台网关中，有些架构会把用户历史会话存储在统一的数据库中，当不同租户或负载均衡器调度时，可能会用另一个 API 账号将历史上下文灌入重放。

  • 请求成功但思考块被丢弃：Haiku 5.5 生成的思考块只在生成它的账户或关联账户中可用。如果用无关联的账户 B 重放账户 A 生成的思考块，API 不会抛出 400 报错，而是静默丢弃（drop）这些思考块。
  • 后果：请求仍然成功，但模型看不到被丢弃的思考内容。跨账号存储重放时，应把每段会话派发到最初生成它的账户；关联账户的适用规则见官方说明。

电脑操作怎么迁移：请求声明和执行循环都要改

如果你的业务不仅是简单聊天，还涉及 Agent 工具链调用、代码执行或自动化操作，需要同步排查工具层的协议版本。

1. 换成电脑操作工具集

  • 适用平台：Claude API 官方直连通道与 Google Cloud 平台。
  • 废弃旧协议：旧版工具名 computer_20250124 及对应的 Beta 协议头 computer-use-2025-01-24 在 5.5 下被彻底弃用，发起请求会收到 400 报错。
  • 接入新版 Toolset：
    1. 移除请求头中的 computer-use-2025-01-24。
    2. 在 tools 列表中不再声明单一 tool，而是声明工具集：{"type": "computer_toolset_20260801"}。
    3. 分发逻辑重构：代码中不能再依赖 input.action 来判断鼠标键盘动作，而是必须检查每一个 tool_use 块的 name 以及 toolset_name。
    4. 全量响应与回传：在同一轮对话中如果出现多个该工具集的调用块，必须在当前轮次处理每一个块，并在回传执行结果（tool_result）时显式带上 toolset_name。
    5. 屏幕缩放（Zoom）默认开启处理：新工具集默认开启了缩放功能。如果你的执行环境尚未实现 Zoom 功能，必须在配置中显式关闭："configs": {"zoom": {"enabled": false}}。
    6. 流式头冲突排除：如果旧请求带有 fine-grained-tool-streaming-2025-05-14 请求头，必须移除。它不能与新的 toolset 并存，否则接口返回 400。
  • 新增网页操作能力：在 Claude API 与 Google Cloud 上，Haiku 5.5 新增支持专门针对网页交互的 browser_toolset_20260801，这是 4.5 所不具备的新特性。

2. 重新规划 Priority Tier 容量

如果你的团队此前在 Claude Haiku 4.5 上购买了 Priority Tier（优先保障层） 算力承诺，请务必注意：Claude Haiku 5.5 目前不支持 Priority Tier。升级至 5.5 时需要单独规划容量。

收到响应后怎么处理：按类型取正文，识别停止原因

升级到 Haiku 5.5 后，客户端还要检查拿到响应后的解析代码。

1. 按 content 块的 type 取正文

很多旧版代码为了省事，直接写成：

# 旧写法：假定第一块就是正文
reply_text = response.content[0].text

在 Haiku 5.5 中，由于自适应思考是默认开启的，模型返回的 response.content 数组中，响应开头可能是 type: "thinking" 的思考块，真正的回答内容在后面的 type: "text" 块中。继续按索引 0 取文本，可能因该块没有 text 字段而出错，也可能漏掉后面的正文。

改造后解析逻辑：遍历 content 数组，按照 type 进行严格条件分支处理。遇到 type == "text" 拼接为用户正文；遇到 type == "thinking"，与工具结果一同回传时保留原块，不修改它。

2. 处理 refusal 停止原因

Haiku 5.5 的安全分类器可以拒绝请求，模型没有服务端后备处理。客户端需要识别这类停止原因：

{ "stop_reason": "refusal" }

代码中必须新增对 "refusal" 的判断。如果旧代码只认 "end_turn"、"max_tokens"、"tool_use"，一旦遭遇拒绝，业务流程可能会直接挂起或当作异常崩溃。

从 Haiku 3.5 或 Haiku 3 升级，还要检查哪些项目？

如果你的业务代码至今仍停留在 Claude Haiku 3.5 或 Haiku 3，文档列出的状态是：Haiku 3.5 已在 Claude API 与 Amazon Bedrock 退役，Haiku 3 已在 Claude API 退役；调用退役型号会失败。Google Cloud 将 Haiku 3.5 列为已弃用，仅向已有客户提供。此时在完成上述全部改造后，还需要追加以下改动：

  1. 模型 ID 与旧工具：
    • 将 claude-3-5-haiku-20241022、claude-3-5-haiku-latest 或 claude-3-haiku-20240307 改为 claude-haiku-5-5；Google Cloud 的旧 ID claude-3-5-haiku@20241022 也改为它，Bedrock 则使用前表带平台前缀的 ID。
    • 早期纯 Python 执行工具 code_execution_20250522 必须升级为 code_execution_20250825 或更新版本。
    • 文本编辑工具必须切换为 text_editor_20250728（对应内部工具名 str_replace_based_edit_tool），注意该版本已经删除了 undo_edit（撤销编辑）命令。
  2. 上下文超限识别：除了捕获 refusal 外，还要在停止原因中额外处理 model_context_window_exceeded。
  3. 工具参数的换行符容错：4.5 及后续模型会在工具调用的字符串参数末尾保留换行符 \n。后端解析工具参数时如果做了精确全等匹配，需要允许末尾换行符。
  4. 提示词重构：Claude 4 及后续模型的沟通风格更简洁直接，需要更具体、指向更明确的系统指令。

对照请求示例，并检查响应解析

以下示例为根据官方文档规范整理的迁移逻辑示意（用于展示参数结构变化，非实测 SDK 运行输出）。

1. 官方请求的前后对照

旧请求通过 budget_tokens 固定思考预算：

{
  "model": "claude-haiku-4-5",
  "max_tokens": 16000,
  "thinking": { "type": "enabled", "budget_tokens": 8000 },
  "messages": [{ "role": "user", "content": "..." }]
}

迁移后，模型 ID 改为 claude-haiku-5-5，思考模式改为 adaptive，并用 output_config.effort 控制投入：

{
  "model": "claude-haiku-5-5",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive" },
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

这里沿用文档示例的 max_tokens，实际应用仍需按任务重新计数和检查截断情况。需要思考摘要时，再加入 display: "summarized"。

2. Python 客户端响应处理示例

# 根据官方迁移规则整理的解析处理逻辑示例（教学参考）
from anthropic import Anthropic

client = Anthropic()

response = client.messages.create(
    model="claude-haiku-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=[
        {"role": "user", "content": "请评估该方案的可行性并给出三条建议。"}
    ]
)

# 1. 容错检查：捕获安全拒绝
if response.stop_reason == "refusal":
    print("请求被安全分类器拦截，未能生成回答。")
elif response.stop_reason == "max_tokens":
    print("警告：Token 预算达到上限被截断（可能是思考占用过多或设置过小）。")

# 2. 只提取当前响应正文；工具循环回传思考时需保留原始块
thinking_process = []
final_answers = []

for block in response.content:
    if block.type == "thinking":
        # 默认模式下 block.thinking 为空字符串，仅包含 signature
        # 若开启 display: "summarized" 则包含摘要文字
        if hasattr(block, "thinking") and block.thinking:
            thinking_process.append(block.thinking)
    elif block.type == "text":
        final_answers.append(block.text)

print("最终回答内容：")
print("\n".join(final_answers))

升级上线验证清单

按请求、响应、会话和工具四组检查。没有使用的功能可跳过对应项目；准备上线时，用现有任务核对改动后的结果。

请求配置

  • 模型 ID：按所在平台更换型号，检查环境变量和网关路由。
  • 采样参数：移除 temperature、top_p 和 top_k。
  • 思考投入：不再发送 budget_tokens；使用自适应思考，通过 effort 调整投入。
  • 消息结尾：替换末尾助手预填充；严格格式用结构化输出或工具，续写和提醒放入用户消息。

响应与输出额度

  • 正文读取：按 type == "text" 取内容，不再固定读取 content[0]。
  • 停止原因：处理 refusal；确认达到 max_tokens 时能够识别截断。
  • 输出额度：重新计数，按任务调整 max_tokens 或降低 effort，检查是否在正文生成前耗尽额度。
  • 思考摘要：需要显示摘要时，显式设置 display: "summarized"。

多轮会话

  • 前文保持不变：回传思考块时，保留它之前的系统提示、工具与历史消息。旧账户的兼容条件见前文。
  • 账户保持关联：把会话交给生成思考块的账户或关联账户，避免派发到无关联账户。

工具执行

  • 电脑操作：换成新工具集，移除旧 Beta 请求头，并检查 Zoom 支持。
  • 执行循环：处理同一轮的全部工具块，按名称派发，结果回传时保留工具集标识。

Haiku 3.5 或 Haiku 3 用户还需完成前面的跨代补充项；已有 Priority Tier 容量承诺的团队，另行核对容量安排。

实操带走包

滚动查看原始 Markdown，复制后可按团队实际系统与政策修改。

Markdown · 会员
正在载入 Markdown…
来源
Claude Haiku 5.5 migration guideAnthropic·查看主材料
延伸
Introducing Claude Haiku 5.5
↑ 正文结束
✓ 本篇全文免费开放

会员可复制、下载全文 Markdown，还能让你的 AI 订阅和提问。

订年卡 $59/年看权益对比 →
阅读原文 ↗
📮 新解读第一时间进邮箱

读完觉得有用？留个邮箱，每篇新解读发布就送达，随时退订。

相关解读

产品发布
Anthropic 发布 Claude Haiku 5.5：平均成本降75%，擅长高频重复工作，是旗舰模型的好帮手
10-09 · 12 分钟
深度
Sonnet 5.5 上手指南：怎么选、多少钱、从 Sonnet 5 怎么迁
09-29 · 约 12 分钟
深度
我们需要“更有野心”地使用AI
10-15 · 9 分钟