用 Claude Sonnet 5.5 构建 · LHQ 的网络日志

Claude Sonnet 5.5 是 Claude 5.5 家族里继 Opus 5.5 之后的第二个模型。相对 Sonnet 5 是明确升级：更聪明、更高效，快约 30%。每 token 单价不变；且 Sonnet 5.5 通常用远更少的 token 做同样的事，多数工作成本可低约 30%。

视频：Lance Martin 的 code-to-painting 演示：每个模型写代码重绘同一张照片。从左：照片、Claude Sonnet 5、Claude Sonnet 5.5、Claude Opus 5.5。 — 两块空白画布分别标 Claude Sonnet 5 与 Claude Sonnet 5.5，一笔笔填满，下方是 brush-engine 调用计数；各模型写出的代码画出城市天际线的日落航拍。结束时四屏并排：照片，以及 Claude Sonnet 5、Claude Sonnet 5.5、Claude Opus 5.5 的画。

感谢 @jkeatn 提供与 code-to-painting 相关的想法，以及 @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)

按类型读每个 block，因为 Sonnet 5.5 默认会思考，响应可能以 thinking block 开头；直接读 content[0].text 会坏。

在 Sonnet 5.5 与 Opus 5.5 之间选择

在 Claude 5.5 家族里，Opus 5.5 面向需要仔细判断的复杂工作。日常、规格清晰的任务用 Sonnet 5.5：修 bug、快速迭代功能。它也擅长打磨文档、幻灯片和表格，对设计有好眼力。速度适合快迭代。Claude Haiku 5.5 将在未来几周加入家族，面向高吞吐、低延迟工作流。

你的负载	先从
规格清晰的日常编码：修 bug、快速迭代功能、对照需求验证	Sonnet 5.5
高吞吐日常开发	Sonnet 5.5
打磨文档、幻灯片和表格——如一页纸、图示、摘要页、文档编辑、表格清理——设计感有帮助时	Sonnet 5.5
你反复跑的、定义清楚的 Agent 任务：调查、审查、起草	Sonnet 5.5
需要仔细判断的复杂工作，包括长程 agentic 编码与知识工作	Opus 5.5
最难的问题，要最强智力时	Opus 5.5

「Epic 早期测试里，Claude Sonnet 5.5 达到了你对更高档模型的质量预期，扛住了系统设计审计与数据流审查。新模型能管住数万行游戏系统架构代码，响应保持干脆，能扛多小时任务，且提示词不必那么规定性。」（Daniel Vogel，Epic Games COO）

任务有清晰规格、且有办法检查结果时，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 的图大约比 Sonnet 4.6、Sonnet 4.5 或 Haiku 4.5 多花约 2.5 倍 token。不需要细节就先缩小再发。

模型细节

细节	Sonnet 5.5
Model ID	Claude API、AWS / Google Cloud / Microsoft Foundry 上的 Claude Platform：`claude-sonnet-5-5`；Amazon Bedrock：`anthropic.claude-sonnet-5-5`
上下文窗口	1M token，原生，无需 beta header
最大输出	128k token；Message Batches API 上配合 `output-300k-2026-03-24` beta header 可达 300k
知识截止日期	2026 年 6 月
Thinking	默认开启（adaptive thinking）；`between_tools` 关闭前置思考
Effort 档位	`low`、`medium`、`high`、`xhigh`、`max`
默认 effort	Claude API 上为 `high`；Claude Code 里为 `medium`
Tokenizer	与 Sonnet 5 相同
可缓存提示词最小长度	512 token（Sonnet 5 为 1,024）
速率限制	与 Sonnet 5 分开，默认档位数值相同
Priority Tier	Claude API 可用
数据留存	符合条件的客户可零数据留存

Claude API 默认 high，便于从强结果起步。先从那里评测，再选工作负载需要的 effort。若想用 xhigh 或 max，记住 Sonnet 5.5 会想更久、更贵。有些任务上你会丢掉 Sonnet 的优势：质量、速度与成本的平衡。那种情况考虑 Opus 5.5。

从 Sonnet 5 迁移

Thinking 默认开启。若你以前在 Sonnet 5 上关了 thinking，可用 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 字段会跑 adaptive thinking；thinking: {"type": "disabled"} 返回 400。改发新的 between_tools。between_tools 下思考只发生在工具调用之间，总响应时间相同或更快。

# 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 可用；xhigh 或 max 返回 400；要在那些档跑，用 adaptive thinking。
不接受其他字段。同时发 display、budget_tokens 或 block_binding 会 400。
between_tools 下对话中途不能改 effort。要按轮改 effort，用 adaptive thinking。
模型在工具调用之间写的短进度更新仍以 thinking block 回来，带摘要文本。按类型读 content block，并把这些 block 与其余 assistant 轮次一并原样传回。无工具时，响应只有 text。
提供 Sonnet 5.5 的各平台都可用，无需 beta header。若 SDK 版本未定义 between_tools，请升级。

若用 between_tools 关了前置思考，对无工具但需要几步推敲的请求，改用 adaptive thinking。

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

类型为 any 或 tool 的 tool_choice 会返回 400（含 token counting 端点）。改发 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 工具要求每个 object 都有 additionalProperties: false。

3. 保持对话 append-only

Sonnet 5.5 的 thinking block 与模型和对话绑定。Sonnet 5.5 能读 Sonnet 5 的 thinking block，因此从 Sonnet 5 切到 Sonnet 5.5 的对话保留推理。没有其他模型会读 Sonnet 5.5 的 block。

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 参数，并通过标准 client 而不是 beta namespace 调 Messages API。替换 tools 条目，并更新 Agent 循环以处理 member tool_use block、批量 action，以及结果上的 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 executor 拒绝 Opus 4.8、Opus 4.7 和 Sonnet 5 作 advisor。可接受的包括 Opus 5.5、Opus 5 以及 Sonnet 5.5 自身。所有可接受 advisor 的建议都以加密形式回来，是 advisor_redacted_result block，你的代码读不到建议正文。

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

这处变更不会报错，但 UI 可能不再显示模型在工具调用之间的备注。那些备注若超过一两句，会以进度更新类的 thinking block 回来，默认 display 下为空。

用 adaptive thinking 时，把 thinking.display 设为 "updates"（beta，需 thinking-display-updates-2026-08-18 header）或 "summarized"，并在随后的 tool_use block 之前渲染每个非空 thinking block。用 between_tools 时，文本无需 display 也会回来。

Sonnet 5.5 还增加了 per-message effort（beta）、对话中途系统消息，以及对话中途改工具（beta）。若从 Sonnet 4.6 或更早、或从 Haiku 4.5 迁，迁移指南按起始模型有检查清单。

调优

重新扫一遍 effort

Effort 档位已重新标定，同一档不会产生与 Sonnet 5 相同量的思考，旧设置不会原样继承。除非工作负载是 agentic 或对延迟敏感，否则从 high 开始。Agentic 编码与多步工具调用：规格清楚的任务从 medium 起，更难或更长的升到 high。聊天及其他延迟敏感工作从 medium 或 low 起。仅在评测显示质量提升时用 xhigh 或 max。

Thinking 计入 max_tokens，所以要留余量。Agentic 编码把 max_tokens 设为 128,000（模型上限）并流式响应。想少思考就降低 effort；在系统提示词里要求少想，并不能可靠减量。

去掉 Sonnet 5 的变通写法

现有 Sonnet 5 提示词通常无需改动也能表现良好。若提示词里带着拒绝引导、工具调用重试补丁，或「不要偷懒」之类变通，先删掉并重跑评测，再调别的。

在 low effort 上要求真实检查

Sonnet 5.5 一般会在报告改动完成前检查工作，但在 low effort 有时会跳过真正行使该改动的检查。若看到「完成」却无测试或构建输出，提示词指南建议加这段系统提示词：

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：

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

只要面向用户的进度备注，用 display: "updates"（beta）。若希望在可预期的点更新——例如第一次工具调用前一行、结束时短回顾——写进系统提示词。

缓存更多提示词

可缓存提示词下限降到 512 token，更短的系统提示词和工具定义也能进缓存。缓存读取价格是输入价的十分之一。请求之间改顶层 effort 会使缓存失效；要单轮换档，用 per-message 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）会把 cyber 与 frontier_llm 拒绝重试到 Sonnet 5。另外三类不重试。也可用 SDK middleware 或自建重试。

合法安全工作方面，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 的 thinking；effort 决定思考多少。Sonnet 5.5 无 fast mode。default 模型仍是 Opus 5.5，规格清晰的任务用 /model sonnet 切换。

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

附录：原页面上的图

这些图在原页面上，但官网的 Markdown 导出里没有，所以附在文末；它们在原文中的位置和说明请看英文原文。

原页面上的图