使用 Claude Sonnet 5.5 构建应用

Claude Sonnet 5.5 是 Claude 5.5 系列中继 Opus 5.5 之后的第二个模型。它是对 Sonnet 5 的明确升级，更智能、更高效，速度快 30%。每 token 价格保持不变，而且由于 Sonnet 5.5 完成相同工作所需的 token 通常少得多，大多数工作的成本最多可降低 30%。

感谢 @jkeatn 提供与代码转绘画相关的思路，以及 @IceSolst 提供参考图片。

本指南介绍如何使用该模型进行构建。要试用它，请按原样运行以下请求：

CODEPython

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 专为需要审慎判断的复杂工作而构建。对于范围明确的日常任务，如修复漏洞和快速迭代功能，请使用 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 每个任务通常使用的 token 比 Sonnet 5 更少。

请注意，不同平台可以为 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，让你从出色的结果开始。从这里开始，进行评估，然后选择你的工作负载所需的 effort 级别。如果你想使用 xhigh 或 max effort，请记住 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 skill，它会在你的代码库中应用模型 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": "..."}],
)

该示例还将 effort 从 xhigh 降为 high，因为 between_tools 有以下限制：

• between_tools 在 low、medium 和 high effort 下有效。在 xhigh 或 max 下会返回 400 错误；要在这些级别运行，请使用自适应思考。
• 它不接受其他字段。与之一起发送 display、budget_tokens 或 block_binding 会返回 400 错误。
• 使用 between_tools 时，effort 无法在对话中途更改。要按轮次更改 effort，请使用自适应思考。
• 模型在工具调用之间写入的简短进度更新仍会以 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. 将 computer use 移至工具集

在 Claude API 和 Google Cloud 上，Sonnet 5.5 仅通过 {"type": "computer_toolset_20260801"} 支持 computer use；声明 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. 检查您的顾问配对

使用 advisor 工具时，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"，并在其后的 tool_use 块之前渲染每个非空的 thinking 块。使用 between_tools 时，文本返回时不带 display。

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

调优

重新运行您的 effort 扫描

effort 等级已重新校准，因此某个等级产生的思考量与在 Sonnet 5 上不同，您的旧设置不会延续。除非您的工作负载是代理型或对延迟敏感，否则请从 high 开始。对于代理型编码和多步工具使用，任务明确时从 medium 开始，较难或较长的任务则转到 high。对于聊天和其他对延迟敏感的工作，从 medium 或 low 开始。仅在您的评估显示质量提升时才使用 xhigh 或 max。

思考会计入 max_tokens，所以要留出余量。对于 agentic coding，将 max_tokens 设为 128,000（模型的最大值），并流式传输响应。要减少思考，降低 effort 级别，因为在系统提示词中要求模型少思考并不能可靠地减少思考。

移除 Sonnet 5 的变通做法

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

在低 effort 下要求真实检查

Sonnet 5.5 通常会在报告更改完成之前检查其工作，但在 low effort 下，它有时会跳过对所更改内容的检查。如果看到更改被报告为完成但没有测试或构建输出，提示词指南建议使用以下系统提示词段落：

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（TypeScript 的 Agent SDK v0.3.284 或更高版本）起，Claude API 上的 sonnet 别名解析为 Sonnet 5.5。它默认以 medium effort 运行，并原生支持 1M 上下文窗口。在 Claude Code 中无法为 Sonnet 5.5 关闭思考，effort 决定模型思考多少。Sonnet 5.5 没有快速模式。default 模型仍为 Opus 5.5，因此对于范围明确的任务，请使用 /model sonnet 切换。

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