实操 · CLAUDE

CLAUDE发布日期 2026-09-28 · 阅读约 6 分钟

使用 Claude Sonnet 5.5 构建

> 何时选择 Sonnet 而非 Opus、费用是多少，以及如何调优。

原作者/来源：claude.dev

原文链接：https://claude.dev/blog/building-with-claude-sonnet-5-5/

何时选择 Sonnet 而非 Opus、费用是多少，以及如何调优。

Claude Sonnet 5.5 是 Claude 5.5 系列中的第二个模型，排在 Opus 5.5 之后。与 Sonnet 5 相比，它是一次明确的升级：它更聪明、更高效，速度也快了 30%。每 token 的价格保持不变；由于 Sonnet 5.5 通常能用少得多的 token 完成同样的工作，因此大多数工作最多能便宜 30%。

原文图 A

图 A Lance Martin 的“代码转绘画”演示：每个模型都会编写代码，重新绘制同一张照片。从左起：照片、Claude Sonnet 5、Claude Sonnet 5.5 和 Claude Opus 5.5。

代码转绘画的相关创意来自 @jkeatn，参考图片由 @IceSolst 提供。

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

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 将在未来几周内加入这一系列，服务于高吞吐量、低延迟的工作流。

你的工作负载 从哪个模型开始
范围明确的日常编码：修复 bug、快速迭代功能、根据需求验证 Sonnet 5.5
高吞吐量的日常开发 Sonnet 5.5
精致的文档、幻灯片和电子表格，例如单页文档、图表、摘要幻灯片、文档编辑和电子表格清理；这些工作需要设计眼光 Sonnet 5.5
你会反复运行的定义明确的智能体任务：调查、审查、起草 Sonnet 5.5
需要谨慎判断的复杂工作，包括长周期的智能体编码和知识工作 Opus 5.5
最难的问题，需要最强的智能 Opus 5.5

“在 Epic 的早期测试中，Claude Sonnet 5.5 达到了我们对更高档模型所期待的同一质量门槛，在系统设计审计和数据流审查中都表现出色。这个新模型处理了数万行游戏系统架构代码，响应依然迅速，能够应对持续数小时的任务，而且只需要较少的指令性提示。”（Daniel Vogel，Epic Games 首席运营官）

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

定价

每百万 token

Sonnet 5.5 Opus 5.5
输入 $2 $4
输出 $10 $20
缓存写入，5 分钟 $2.50 $5
缓存写入，1 小时 $4 $8
缓存读取 $0.20 $0.20

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 倍。如果不需要这些细节，请在发送前缩小图像。

模型详情

详情 Sonnet 5.5
模型 ID Claude API、Claude Platform on AWS、Google Cloud 和 Microsoft Foundry 上为 claude-sonnet-5-5；Amazon Bedrock 上为 anthropic.claude-sonnet-5-5
上下文窗口 1M token，原生支持，无需 beta header
最大输出 128k token；使用带有 output-300k-2026-03-24 beta header 的 Message Batches API 时最高 300k
知识截止时间 2026 年 6 月
思考 默认开启（自适应思考）；between_tools 会关闭前置思考
Effort 档位 low、medium、high、xhigh、max
默认 effort Claude API 上为 high；Claude Code 中为 medium
分词器 与 Sonnet 5 相同
最小可缓存提示 512 token（Sonnet 5 为 1,024）
速率限制 与 Sonnet 5 分开，但默认档位数值相同
Priority Tier Claude API 上可用
数据保留 符合条件的客户可使用零数据保留

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 时，思考只会发生在工具调用之间，总响应时间相同或更短。

# 之前：Claude Sonnet 5
client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    output_config={"effort": "xhigh"},
    messages=[{"role": "user", "content": "..."}],
)
# 之后：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 块的形式返回，并带有摘要文本。请按类型读取内容块，并将这些块与 assistant 轮次的其余部分一起原样传回。没有工具时，响应只包含文本。

所有提供 Sonnet 5.5 的平台都支持它，无需 beta header。如果你的 SDK 版本没有定义 between_tools，请更新 SDK。

如果你通过 between_tools 关闭了前置思考，那么对于不使用工具、但需要几步推理的请求，请改用自适应思考。

2. 用 auto 和 strict tools 替代强制 tool_choice

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

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."}
    ],
)

strict 工具使用要求每个对象都设置 additionalProperties: false。

3. 保持对话只追加

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

4. 将 computer use 移到 toolset

在 Claude API 和 Google Cloud 上，Sonnet 5.5 只能通过 {"type": "computer_toolset_20260801"} 使用 computer use；声明 computer_20251124 的请求会返回 400 错误。请从请求中删除 anthropic-beta: computer-use-2025-11-24 header；在 SDK 中，移除 betas 参数，并通过标准客户端而不是 beta 命名空间调用 Messages API。替换 tools 条目，并更新你的智能体循环，以处理 tool_use 成员块、批量操作以及结果上的 toolset_name。

如果你发送了 fine-grained-tool-streaming-2025-05-14 beta header，也请将它删除，因为它与 toolset 条目一起使用时会返回 400 错误；请改为在每个需要它的工具上设置 eager_input_streaming: true。Amazon Bedrock 仍然接受 computer_20251124。

5. 检查 advisor 配对

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

6. 从 thinking 块读取工具调用之间的文本

这一变更不会导致错误，但可能会让 UI 不再显示模型在工具调用之间的备注。当这些备注超过一两句话时，会以进度更新 thinking 块返回，而默认的 display 设置下这些块是空的。使用自适应思考时，请将 thinking.display 设为 "updates"（beta，使用 thinking-display-updates-2026-08-18 header）或 "summarized"，并在后续 tool_use 块之前渲染每个非空 thinking 块。使用 between_tools 时，文本返回时不带 display。

Sonnet 5.5 还新增了每条消息级别的 effort（beta）、对话中途的 system 消息，以及对话中途的工具变更（beta）。如果你是从 Sonnet 4.6 或更早版本，或者 Haiku 4.5 迁移过来，迁移指南为每个起始模型提供了检查清单。

调优

重新运行 effort 扫描

Effort 档位已经重新校准，因此某个档位产生的思考量不再与 Sonnet 5 上相同，你以前的设置也不会直接沿用。除非你的工作负载是智能体式的，或对延迟敏感，否则从 high 开始。对于智能体编码和多步工具使用，规格明确的任务从 medium 开始，难度更高或耗时更长的任务则提高到 high。对于聊天和其他对延迟敏感的工作，从 medium 或 low 开始。只有当评测显示质量有所提升时，才使用 xhigh 或 max。

思考会计入 max_tokens，因此要留出空间。对于智能体编码，将 max_tokens 设为 128,000（模型的最大值），并对响应进行流式传输。要减少思考量，请降低 effort 档位，因为在 system prompt 中要求模型少思考，并不能可靠地减少思考量。

移除 Sonnet 5 的权宜处理

现有的 Sonnet 5 提示无需修改通常也能表现良好。如果你的提示里带有拒答引导、工具调用重试垫片或“不要偷懒”之类的权宜处理，请将它们移除，并在调整其他内容之前重新运行评测。

在 low effort 下要求进行实际检查

Sonnet 5.5 通常会在报告某项变更已完成之前检查自己的工作，但在 low effort 下，它有时会跳过能实际验证变更的检查。如果你发现它报告变更已完成，却没有测试或构建输出，提示指南建议使用下面这段 system prompt：

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 拒答。请改为读取摘要式思考：

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

如果要单独显示面向用户的进度说明，请使用 display: "updates"（beta）。如果你希望进度更新在可预测的时点出现，例如第一次工具调用前一行，以及末尾的简短回顾，请在 system prompt 中说明。

缓存更多提示内容

最小可缓存提示长度降到了 512 token，因此更短的 system prompt 和工具定义也符合条件。缓存读取的费用是输入价格的十分之一。在请求之间更改顶层 effort 会使缓存失效；要让单轮使用不同的 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
  • Claude Platform on AWS：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 没有 fast mode。默认模型仍然是 Opus 5.5，因此对于范围明确的任务，请使用 /model sonnet 切换模型。

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