Anthropic 发布 Claude Sonnet 5.5，附模型选型与迁移指南

Claude Sonnet 5.5 是继 Opus 5.5 之后，Claude 5.5 家族中的第二个模型。相比 Sonnet 5 它是一次明显的升级，更智能、更高效，速度提升 30%。每 token 价格保持不变，而且由于 Sonnet 5.5 完成同样的工作通常需要的 token 少得多，大多数工作的成本可降低多达 30%。

感谢 @jkeatn 提供代码作画相关的想法，以及 @IceSolst 提供参考图像。

本指南讲的是如何用该模型进行构建。想试用的话，按原样运行这个请求：

代码Python

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between microservices and monolithic architectures",
        }
    ],
    output_config={"effort": "medium"},
)

for block in response.content:
    if block.type == "text":
        print(block.text)

循环按类型读取每个块，因为 Sonnet 5.5 默认会思考，所以响应可能以 thinking 块开头，而读取 content[0].text 的代码会出错。

在 SONNET 5.5 和 OPUS 5.5 之间选择

在 Claude 5.5 家族中，Opus 5.5 专为需要审慎判断的复杂工作而打造。对于范围明确的日常任务，如修复 bug 和快速迭代功能，请使用 Sonnet 5.5。它还能制作精美的文档、幻灯片和电子表格，并且对设计有很强的眼光。它的速度使其非常适合快速迭代。Claude Haiku 5.5 将在未来几周加入该家族，面向高吞吐量、低延迟的工作流。

“在 Epic 的早期测试中，Claude Sonnet 5.5 达到了你对更高层级模型所期望的同等质量水准，在系统设计审计和数据流审查中表现稳健。这个新模型管理了游戏系统架构中数万行代码，保持响应迅速，处理了数小时的任务，并且用更少的指令性提示就能交付。”（Daniel Vogel，Epic Games 首席运营官）

当任务有明确的规格和验证结果的方法时，Sonnet 5.5 最为合适。正如提示指南所说，“对于最难的长周期工作，Opus 模型是更好的选择。”

定价

Sonnet 5.5 的所有价格，包括批处理和提示缓存，都与 Sonnet 5 相同，因此更换模型 ID 不会改变你的每 token 账单。仅限美国境内的推理（inference_geo: "us"）费用为标准价格的 1.1 倍。

虽然每 token 价格不变，但总账单会变化，因为如前所述，Sonnet 5.5 完成每个任务通常比 Sonnet 5 使用更少的 token。

请注意，各平台发布时 Sonnet 的默认 effort 可能不同，例如在 Claude Platform 上为 high，在 Claude Code 中为 medium。

Sonnet 5.5 使用高分辨率图像层级，长边最高 2576 像素，一张 2000×1500 的图像消耗的 token 约为 Sonnet 4.6、Sonnet 4.5 或 Haiku 4.5 上的 2.5 倍。如果你不需要这些细节，发送前请先缩小尺寸。

模型详情

Claude API 默认使用 high，因此你可以从出色的结果开始。从这里开始，进行评估，然后选择你的工作负载所需的努力级别。如果你倾向于使用 xhigh 或 max 努力级别，请记住 Sonnet 5.5 会思考更久，成本更高。在某些任务上，你可能会失去 Sonnet 的一些优势：它在质量、速度和成本之间的平衡。在这种情况下，请考虑 Opus 5.5。

从 SONNET 5 迁移

思考默认开启。如果你在关闭思考的情况下运行 Sonnet 5，可以使用 between_tools 关闭前置思考。下面的第 1 步展示了如何操作。

将模型 ID 改为 claude-sonnet-5-5，然后处理五个破坏性变更和一个响应结构变更。Sonnet 5.5 迁移指南 完整介绍了每一项。

Claude Code 也可以为你执行迁移。运行 /claude-api migrate this project to claude-sonnet-5-5 来调用内置的 Claude API 技能，它会在你的代码库中应用模型 ID 替换和破坏性参数变更。

1. 使用 between_tools 关闭前置思考

在 Sonnet 5.5 上，没有 thinking 字段的请求会以自适应思考运行，而 thinking: {"type": "disabled"} 会返回 400 错误。请改为发送新的 between_tools 设置。使用 between_tools 时，思考只发生在工具调用之间，总响应时间相同或更快。

CODEPython

# Before: Claude Sonnet 5
client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    output_config={"effort": "xhigh"},
    messages=[{"role": "user", "content": "..."}],
)

# After: Claude Sonnet 5.5
client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    thinking={"type": "between_tools"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "..."}],
)

该示例还将努力级别从 xhigh 降至 high，因为 between_tools 有以下限制：

• between_tools 在 low、medium 和 high 努力级别下可用。在 xhigh 或 max 下会返回 400 错误；要在这些级别运行，请使用自适应思考。
• 它不接受其他字段。随它发送 display、budget_tokens 或 block_binding 会返回 400 错误。
• 使用 between_tools 时，努力级别无法在对话中途更改。要按轮次调整努力级别，请使用自适应思考。
• 模型在工具调用之间写入的简短进度更新仍会以 thinking 块的形式返回，并带有摘要文本。按类型读取内容块，并将这些块与助手回合的其余部分原样传回。没有工具时，响应仅包含文本。
• 它适用于所有提供 Sonnet 5.5 的平台，无需 beta 标头。如果你的 SDK 版本未定义 between_tools，请更新它。

如果你使用 between_tools 关闭了前置思考，请对没有工具但需要几步推理的请求改用自适应思考。

2. 将强制 tool_choice 替换为 auto 加严格工具

类型为 any 或 tool 的 tool_choice 会返回 400 错误，包括在 token 计数端点上。发送 auto，将工具标记为 strict: true 以使其输入符合 schema，并在提示中说明何时使用它：

CODEPython

weather_tool = {
    "name": "get_weather",
    "description": "Get the current weather in a given location",
    "input_schema": {
        "type": "object",
        "properties": {"location": {"type": "string"}},
        "required": ["location"],
        "additionalProperties": False,
    },
    "strict": True,
}

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    tools=[weather_tool],
    tool_choice={"type": "auto"},  # was {"type": "tool", "name": "get_weather"}
    messages=[
        {"role": "user", "content": "What's the weather in Paris? Use the get_weather tool."}
    ],
)

严格工具使用要求每个对象上都有 additionalProperties: false。

3. 保持对话仅追加

Sonnet 5.5 的思考块与模型和对话绑定。Sonnet 5.5 会读取 Sonnet 5 的思考块，因此从 Sonnet 5 切换到 Sonnet 5.5 的对话会保留其推理过程。其他模型无法读取 Sonnet 5.5 的思考块。

4. 将计算机使用移至工具集

在 Claude API 和 Google Cloud 上，Sonnet 5.5 仅通过 {"type": "computer_toolset_20260801"} 支持计算机使用；声明 computer_20251124 的请求会返回 400 错误。从请求中移除 anthropic-beta: computer-use-2025-11-24 标头，并在 SDK 中移除 betas 参数，通过标准客户端而非 beta 命名空间调用 Messages API。替换 tools 条目，并更新你的代理循环以处理成员 tool_use 块、批量操作和结果上的 toolset_name。如果你发送了 fine-grained-tool-streaming-2025-05-14 beta 标头，也请移除它，因为与工具集条目一起使用时它会返回 400 错误；改为在每个需要它的工具上设置 eager_input_streaming: true。Amazon Bedrock 仍然接受 computer_20251124。

5. 检查你的顾问配对

使用顾问工具时，Sonnet 5.5 执行器会拒绝 Opus 4.8、Opus 4.7 和 Sonnet 5 作为顾问。可接受的顾问包括 Opus 5.5、Opus 5 和 Sonnet 5.5 本身。来自每个可接受顾问的建议都会以 advisor_redacted_result 块的形式加密返回，因此你的代码无法读取建议文本。

6. 从思考块中读取工具调用之间的文本

此更改不会导致错误，但 UI 可能会停止显示工具调用之间模型的注释。这些注释如果超过一两句话，会以进度更新 thinking 块的形式返回，而在默认的 display 下这些块为空。

使用自适应思考时，将 thinking.display 设置为 "updates"（beta，使用 thinking-display-updates-2026-08-18 标头）或 "summarized"，并在每个非空的 thinking 块之后、紧随其后的 tool_use 块之前渲染它。使用 between_tools 时，文本返回时不带 display。

Sonnet 5.5 还新增了每消息努力程度（beta）、对话中途系统消息和对话中途工具更改（beta）。如果你从 Sonnet 4.6 或更早版本，或从 Haiku 4.5 迁移，迁移指南为每个起始模型提供了检查清单。

调优

重新运行你的努力程度扫描

努力程度级别已重新校准，因此某个级别产生的思考量不再与 Sonnet 5 上相同，你之前的设置也不会延续。除非你的工作负载是代理式的或对延迟敏感，否则从 high 开始。对于代理式编码和多步工具使用，从 medium 开始处理定义明确的任务，对于更难或更长的任务则转向 high。对于聊天和其他对延迟敏感的工作，从 medium 或 low 开始。仅在你的评估显示质量提升的地方使用 xhigh 或 max。

思考会计入 max_tokens，因此要留出空间。对于代理式编码，将 max_tokens 设置为 128,000，即模型的最大值，并流式传输响应。要减少思考，请降低努力程度级别，因为在系统提示中要求模型少思考并不能可靠地减少思考。

移除 Sonnet 5 的变通方法

现有的 Sonnet 5 提示应无需更改即可良好运行。如果你的提示带有拒绝引导、工具调用重试垫片或“不要偷懒”等变通方法，请移除它们并在调整其他任何内容之前重新运行你的评估。

在低努力程度下要求真实检查

Sonnet 5.5 通常会在报告更改已完成之前检查其工作，但在 low 努力程度下，它有时会跳过对更改进行实际检验的检查。如果你看到更改被报告为已完成但没有测试或构建输出，提示指南推荐以下系统提示段落：

CODEText

When you change code that can be run, built, or type-checked, run a real
check that exercises the change before reporting it done: the project's
tests, type-checker, or build, or the changed command itself. A syntax-only
check, or a check command that failed to start, does not count; if all
that is missing is the project's declared dependencies, install them with
its own package manager and lockfile (e.g. npm install, pip
install -r requirements.txt), never via sudo or the system package manager,
unless told not to. Only if no real check can run here, say which one you
did not run and why instead of reporting the change as done.

使用 thinking.display 显示进度

不要要求模型在响应中写出其推理过程，因为这会招致 reasoning_extraction 拒绝。改为读取摘要思考：

CODEPython

thinking={"type": "adaptive", "display": "summarized"}

如需自行向用户展示进度说明，请使用 display: "updates"（beta）。如果你希望在可预测的节点获得更新，例如首次工具调用前的一行提示以及结尾的简短回顾，请在系统提示中说明。

缓存更多提示内容

最小可缓存提示降至 512 个 token，因此更短的系统提示和工具定义现在也符合条件。缓存读取的费用为输入价格的十分之一。在请求之间更改顶层 effort 会使缓存失效；若要在某一轮使用不同的级别，请使用按消息 effort（beta），这样可保留缓存。

拒绝与回退

在我们的自动化行为审计中，Sonnet 5.5 在大多数对齐与诚实度指标上优于或持平 Sonnet 5。它也是首个具备与我们最强模型类似网络安全防护的 Sonnet 模型。大多数常规软件开发不受影响。

被拒绝的请求会返回 HTTP 200 及 stop_reason: "refusal"，而 stop_details 会指明五类之一：cyber、bio、frontier_llm、reasoning_extraction 或 general_harms。服务端回退（fallbacks: "default"，beta，Claude API）会在 Sonnet 5 上重试 cyber 和 frontier_llm 拒绝。它不会重试其余三类。你也可以使用 SDK 中间件或自行重试。

对于合法的安全工作，Cyber Verification Program 很快将扩展至涵盖 Sonnet 5.5。

可用性

Claude Sonnet 5.5 即日起在以下平台可用。在开发者平台上，请使用这些模型 ID：

• Claude API，为 claude-sonnet-5-5
• Amazon Bedrock，为 anthropic.claude-sonnet-5-5
• AWS 上的 Claude Platform，为 claude-sonnet-5-5
• Google Cloud，为 claude-sonnet-5-5
• Microsoft Foundry，为 claude-sonnet-5-5，仅限 Global Standard 部署

在 Claude Code 中

从 Claude Code v2.1.284（Agent SDK for TypeScript v0.3.284 或更高版本）起，sonnet 别名在 Claude API 上解析为 Sonnet 5.5。它默认以 medium effort 运行，原生支持 1M 上下文窗口。在 Claude Code 中无法为 Sonnet 5.5 关闭思考，而 effort 决定模型思考的程度。Sonnet 5.5 没有快速模式。default 模型仍为 Opus 5.5，因此对于范围明确的任务，可用 /model sonnet 切换。

我们希望你会喜欢试用 Sonnet 5.5，并一如既往地欢迎分享反馈。