Claude Sonnet 5 的三项破坏性 API 变更：迁移前每位 Operator 必须完成的审查

Sonnet 5 上线后，外界的报道聚焦在定价和 benchmark 成绩上。被严重低估的是：三处 API 层面的行为变更，会在从 Sonnet 4.6 迁移时悄无声息地击垮生产集成——它们不是偶发的边缘情况，而是在最常见的 API 调用模式下必然触发。

如果你的路由策略已经将流量切到 claude-sonnet-5，现在就运行下面的审查清单。

发生了什么变化

Anthropic 官方文档 What's new in Claude Sonnet 5 记录了三项破坏性变更和一个隐性成本放大器：

1. Adaptive thinking 默认开启

Sonnet 4.6 上，没有 thinking 字段的请求不会启用任何 extended thinking。Sonnet 5 上，同样的请求现在会默认开启 adaptive thinking——模型自行决定何时、用多少 token 进行思考。

若要明确关闭 thinking：

thinking = {"type": "disabled"}

影响有两个维度。其一，任何依赖 Sonnet 4.6 无 thinking 状态的低延迟路径，在未显式禁用 thinking 的情况下，延迟将变得不可预测。其二，max_tokens 是对全部输出（包括 thinking token）的硬性上限——为 Sonnet 4.6 的响应文本调校过的 max_tokens 值，在加入 thinking token 后可能导致输出截断。需要重新审查所有未曾使用 thinking 的工作负载上的 max_tokens 设置。

2. 采样参数传非默认值将返回 400

将 temperature、top_p 或 top_k 设置为任何非默认值，现在会触发 400 错误。这一限制此前已在 Opus 4.7 和 Fable 5 上引入，Sonnet 5 是首次将其扩展到 Sonnet 档位。

# Sonnet 5 上将返回 400
response = client.messages.create(
    model="claude-sonnet-5",
    temperature=0.7,  # 不被接受
    ...
)

# 正确做法：省略该参数或使用默认值
response = client.messages.create(
    model="claude-sonnet-5",
    # temperature 省略，使用默认值
    ...
)

任何在调用 Sonnet 4.6 时传入非默认 temperature、top_p 或 top_k 的系统，迁移后将立即收到 400 错误。这覆盖了大量生产集成：LangChain、LlamaIndex 以及多数 SDK wrapper 都会将 temperature 作为顶层参数暴露，且默认值往往非零。

3. 手动 extended thinking 已移除

thinking: {type: "enabled", budget_tokens: N} 模式在 Sonnet 4.6 上已被弃用，Sonnet 5 上已完全移除，调用时将返回 400 错误。

# Sonnet 5 不支持（返回 400）
thinking = {"type": "enabled", "budget_tokens": 32000}

# 改用 adaptive 模式
thinking = {"type": "adaptive"}
# 或显式设置 effort 级别
effort = {"level": "high"}

若你的生产代码在 Sonnet 4.6 上携带手动 thinking budget 进行调用——例如推理密集型的代码审查工作流——在不修改代码的情况下迁移到 Sonnet 5 后会立即中断。

4. 新 tokenizer——相同文本 token 数量膨胀约 30%

Sonnet 5 采用新的 tokenizer。相同输入文本在 Sonnet 5 上产生的 token 数量比 Sonnet 4.6 多约 30%。这不是 API 合约的变化——请求/响应结构保持不变——但影响所有与 token 相关的计量和预算：

• usage 字段：相同 prompt 在 API 响应中的 token 计数将更高。
• 上下文窗口容量：100 万 token 的上下文窗口每个 token 承载的文本量更少，接近旧上限的 prompt 可能超限。
• max_tokens 输出预算：为 Sonnet 4.6 设置的输出上限可能在 Sonnet 5 上更早触发截断。
• 单次请求成本：每 token 定价不变，但每个 token 覆盖的文本量更少，等价 prompt 的成本最多上涨约 30%。

不要复用针对 Sonnet 4.6 测量的 token 计数，需直接对 Sonnet 5 重新计数。

对 AI 工程团队的意义

使用 AI gateway 或多 provider routing 层的团队需要从两个层面看待这些变更。

对直接 API 调用方，风险很明确：迁移前未移除 temperature 和 thinking 参数会产生硬 400 错误；adaptive thinking 在低延迟路径上触发会导致延迟悄然恶化；token 预算未重新校准会导致成本悄然上升。

对 gateway operator 和路由策略制定者，问题更隐蔽。若你将 claude-sonnet-latest 通过别名自动更新指向 Sonnet 5，任何仍在传入 temperature 的下游调用方将立即开始收到 400 错误。若你的 gateway 透传参数字段而不过滤模型不兼容参数，你就成了无声的故障点。这是路由策略应包含参数转换规则（而非仅模型名称替换）的重要论据。

fallback 链同样存在隐患。若你的主模型是 GPT-5.5 或 Gemini 3.5 Flash，且设置了 temperature=0.8，fallback 目标是 Sonnet 5，那么每次 fallback 调用都将返回 400 而非成功的 fallback 响应。

Router/Operator 视角的深度解读

路由分级的参数兼容性矩阵

跨 provider 维护路由策略需要清楚每个模型接受哪些参数。Sonnet 5 使这一问题更加关键：

Gateway 层的参数归一化——在转发前剥离或还原模型不兼容字段——如果你将来自设置了 temperature 的调用方的流量路由至 Sonnet 5，这已经是正确性要求，而非可选优化。

Token 预算重新校准清单

在将生产路由分级切换到 Sonnet 5 之前：

1. 重新运行 token 计数，针对你的第 10、50、90 百分位 prompt 长度对 claude-sonnet-5 重新测量。基线已偏移约 30%。
2. 上调输出密集路径的 max_tokens 预算，至少上调 30%，以避免截断。
3. 重新检查接近上下文窗口上限的工作负载利用率。在 Sonnet 4.6 上能舒适放入的 prompt，若文本量超过约 77 万个 Sonnet 4.6 token 的等价量，在 Sonnet 5 上可能溢出。
4. 重新运行成本预估。在 8 月 31 日定价窗口关闭之前，用 Sonnet 5 的 token 计数重新计算主要请求类型的预期月成本。

这四步的顺序很重要。如果先做成本预估、再调整 max_tokens 预算，在实际测试中可能发现截断比预想频繁，导致需要二次调整——反而引入更多不确定性。建议先完成 token 计数基准测量，再依此推导所有下游预算和成本数字。

Routing 层的 Thinking Token 计费

Adaptive thinking 引入了隐性 token 消耗。若你的 routing 层基于 usage 字段的 token 计数向下游用户计费，thinking token 现在会体现在 output token 总量中，这改变了你的路由分级的计费语义。Sonnet 5 的 usage.output_tokens 在 adaptive thinking 触发时包含 thinking token；Sonnet 4.6 对同样的调用（未启用 thinking）则不包含。

如果你向用户展示单次请求成本，很可能需要单独处理 thinking token 计费，或告知用户这一变化。

TheRouter 用户应关注和尝试的事项

通过 TheRouter 或任何 AI gateway 路由到 Anthropic 的团队应：

1. 确认你的 provider 的 Sonnet 别名当前指向 claude-sonnet-5 还是会在未来自动更新。在切换发生前与你的 gateway 的模型列表核实。
2. 若直接路由到 claude-sonnet-5，针对你的请求 schema 运行参数兼容性检查——重点关注 temperature、top_p、top_k 和 thinking 字段。
3. 参阅 Claude API 模型概览 获取当前模型 ID，以及 Anthropic 迁移指南 获取结构化迁移清单。

若需要批量更新多处集成点，Claude Code 中的 /claude-api migrate skill 可以自动化跨代码库的参数修复。