Claude Sonnet 5.5与Haiku 5.5 Python实战：双SDK、缓存与100K定价悬崖

Anthropic 的 Claude 5.5 系列把中杯和小杯同时端了上来：Sonnet 5.5 与 Haiku 5.5 共享 1M token 上下文窗口、128K 最大输出，以及默认开启的自适应思考（adaptive thinking）。两者都能通过 Anthropic SDK 调用，也能经由网关走 OpenAI SDK。真正需要提前算清楚的，是 Haiku 5.5 那条 100K token 的定价分界线——超过之后，整个请求的所有费率乘以五。

两个模型怎么分工

选择逻辑并不复杂。分类、抽取、路由、摘要、上下文压缩这类短提示、大并发的活，交给 Haiku 5.5；多文件编码、调试、长时间工具循环，交给 Sonnet 5.5。Anthropic 自己的 Haiku 发布表里，Terminal-Bench 4.0 上 Sonnet 5.5 拿到 70.6%，Haiku 5.5 是 39.2%，差距摆在那里。

清单价格上，Sonnet 5.5 是每百万输入/输出 token 2 美元 / 10 美元，Haiku 5.5 是 0.10 美元 / 0.50 美元，正好 20 倍。Anthropic 还明确说 Haiku 5.5「很适合作为 Opus 5.5 和 Sonnet 5.5 的子代理」，这条对做编码代理的团队有直接参考价值。

超过 100K token 的提示该怎么选？原文给了一个反直觉的答案：Haiku 虽然按 5 倍计费，但换算下来仍是 Sonnet 单价的一个零头，所以决定因素应该是质量而不是省钱。

Terminal-Bench 4.0 是一个面向终端操作任务的评测基准，专门衡量模型在真实命令行环境中完成多步骤任务的能力——比如在文件系统里定位文件、执行构建脚本、调试失败的测试、修复后重新验证。任务以容器化沙盒形式运行，模型需要通过 shell 命令而非直接编辑文件来完成目标，因此同时考察工具调用的稳定性、错误恢复能力和长程规划。70.6% 与 39.2% 的分数差距，反映的正是 Sonnet 5.5 在长工具循环中维持上下文、从失败命令中纠错的能力显著更强；Haiku 5.5 在需要多轮试错的终端任务上更容易中途丢失目标。这也解释了文中为何建议编码代理场景优先选择 Sonnet，而不是仅凭单价做判断。

Anthropic SDK 调 Haiku 5.5：三个容易踩的坑

原文用工单分类器做示例，output_config.effort 设为 low，因为这个任务只需要一个标签，不需要推理链。代码里 max_tokens 给得比较宽裕，原因是思考 token 也计入这个上限，设小了可能在思考块之后就断掉，一个文字块都不返回。

三个细节值得单独拎出来：Haiku 5.5 不接受 temperature（只允许 1 或 top_p 0.99，带 top_k 直接 400）；请求必须以用户轮结束，assistant 预填充即使关闭思考也会被拒绝；解析响应时不能拿 content[0].text，因为第一个块可能是思考块，要按 type == "text" 过滤后拼接。

自适应思考（adaptive thinking） 是 5.5 系列默认开启的机制：模型会根据任务复杂度自行决定是否、以及投入多少思考 token，而非由调用方显式指定固定预算。这带来两个直接影响。其一，max_tokens 是思考与正文共享的总上限，设得过紧会出现思考块已生成、正文尚未开始就被截断的情况，响应中只剩思考内容、stop_reason 为 max_tokens。其二，响应内容不再是单一文本块，content 数组可能包含 thinking 与 text 两种块，且顺序不保证文本在前，因此任何取值代码都必须按 type 过滤。此外，思考消耗的 token 按输出价格计费，在核算成本时需要把它归入输出侧统计，这也是账单与自算结果对不上时最常见的差异来源。

OpenAI SDK 调 Sonnet 5.5：网关做了哪些翻译

如果代码库建在 OpenAI SDK 上，把 base_url 指向网关的兼容端点、改一下模型字符串就行。原文提到网关在这条路径上做了三件事：没传 max_tokens 时填入模型自身的输出上限，而不是一个小默认值（此前用 4096，会把长代码文件从函数中间截断）；对两个 5.5 模型丢弃 temperature、top_p、top_k，让带默认温度的客户端不会撞上 Anthropic 的 400；reasoning_effort 映射为 Anthropic 的 effort 等级。

工具调用上有个硬限制：Sonnet 5.5 不支持强制工具使用，tool_choice 设成 tool 或 any 会报错。正确姿势是保持 auto，并在函数上设 strict: true，同时在提示里说清楚什么情况下该用工具。

强制工具调用（forced tool use） 指通过 tool_choice 指定模型必须调用某个工具或必须调用某一类工具，OpenAI 侧对应 tool_choice: "required" 或指定函数名。Sonnet 5.5 不支持这一模式，设成 tool 或 any 会直接报错。可行的替代是保持 auto 让模型自行判断，同时在函数定义上开启 strict: true，由服务端按 JSON Schema 约束参数结构，从而把「参数格式错误」这类失败排除掉；再在系统提示中明确写出触发条件与不适用场景，用提示约束代替强制机制。需要区分的是，strict 只保证参数符合 schema，并不保证模型一定会调用工具，因此对必须产出结构化结果的流程，仍应在外层代码里做校验与重试。

提示缓存：第一次写，第二次读

缓存对任何重复发送的内容都划算：长系统提示、政策文档、仓库摘要。两个模型的最小可缓存提示都是 512 token。示例把退款政策文档放进 system，并打上 cache_control: {"type": "ephemeral"}。

预期行为是第一次调用报告缓存写入，五分钟内的第二次调用报告缓存读取。原文称在 Sonnet 5.5 发布时用同一前缀连发三次，得到一次写入、两次读取，这个模式可以直接用来验证自己的缓存是否真的命中。

按网关价格，缓存读取是新鲜输入的十分之一：Sonnet 5.5 为每百万 0.12 美元（输入 1.20，缓存写入 1.50），Haiku 5.5 为 0.009 美元（输入 0.09，缓存写入 0.1125）。

提示缓存（prompt caching） 是 Anthropic API 的一项能力：当请求前缀完全一致时，服务端可以复用上一次计算出的 KV 缓存，从而跳过对重复内容的重新编码，既降低延迟也降低费用。使用时要在消息或系统提示中标记 cache_control: {"type": "ephemeral"}，缓存有效期约五分钟，期间再次命中即按缓存读取价格计费，过期后需重新写入。缓存以「前缀完全匹配」为前提，因此系统提示若包含动态时间戳或用户 ID，命中率会直接归零。最小可缓存长度为 512 token，低于该阈值的提示不会产生缓存条目。需要特别注意的是，缓存读取与缓存写入的 token 量都会计入 Haiku 5.5 的 100K 定价阈值判定，所以缓存能省钱，却不能帮你绕开定价悬崖。

100K 定价悬崖：算法与实测数字

Anthropic 对 Haiku 5.5 的规则是：请求的提示超过 100,000 token 时——新输入、缓存读取、缓存写入都算进去——该请求上的每一个费率乘以五，输出费率也不例外。Sonnet 5.5 的 1M 窗口内没有这个台阶。

原文给出的成本函数复现了这条规则，跑出来的几组数字很能说明问题：

• 99K 提示 + 1K 输出：Haiku 0.00936 美元，Sonnet 0.12480 美元
• 101K 提示 + 1K 输出：Haiku 0.04770 美元，Sonnet 0.12720 美元
• 同样的 101K 拆成两个 50.5K 请求：Haiku 0.01000 美元
• 150K 提示（140K 缓存读 + 10K 新输入）+ 2K 输出：Haiku 0.01530 美元，Sonnet 0.04080 美元

多了两千个 token，Haiku 的请求成本变成 5.1 倍。拆成两个低于阈值的请求，成本降约 79%，当然还要额外付一次合并步骤。缓存救不了你，因为缓存读取同样计入阈值。

但这张表不能读成「超过 100K 就换 Sonnet」。原文点得很清楚：越过悬崖后，Haiku 5.5 仍然是同请求下 Sonnet 5.5 价格的 37.5%，按 Anthropic 清单价则是四分之一。长提示任务迁到 Sonnet，理由应该是 Haiku 答得不够好，而不是省钱。

生产环境里要抓住这个悬崖，可以从每个响应的 usage 里算提示大小：input_tokens + cache_read_input_tokens + cache_creation_input_tokens，超过 100,000 就打日志。

账单核对与常见报错

网关的每个响应都带 x-apimodels-request-id 头，非流式响应还带 x-apimodels-cost。用记录端点 GET /v1/records/{id} 能拿到结算金额和背后的 token 用量。如果和自己算的对不上，先对比 usage——思考 token 计入输出、缓存的三段拆分，是最常见的差异来源。

原文列出的报错里，有几个值得提前知道：Sonnet 5.5 上 thinking: {"type": "disabled"} 会 400，要改用 between_tools；Haiku 5.5 上以 assistant 消息结尾会 400；stop_reason 是 max_tokens 却没有文字，说明思考吃光了上限；流式界面在工具调用之间静默，是因为工具间隔的说明以思考块形式到达，而文本默认为空。还有一条来自网关自身：估算超过 1M 窗口的提示会在发送前被拒绝，比如报出约 306 万 token 超限的那种。

关于网关的取舍

原文作者披露自己就职于 apimodels.app，示例里的 base_url 指向该网关。它的定位是一个 API key 打通 Anthropic 原生 Messages 端点和 OpenAI 兼容端点，覆盖 140 多个图像、视频、音频和语言模型；两个 5.5 模型各有多个上游通道并自动故障转移，失败请求不计费。价格方面，Sonnet 5.5 为 1.20 / 6.00 美元（清单价的 60%），Haiku 5.5 为 0.09 / 0.45 美元（90%）。

作者也写明了不适用的场景：需要 Anthropic 的 Message Batches API（网关没有批量端点），或者需要与 Anthropic 本身签合同、签数据处理协议，就不该走这条路。

最后是原文自己标注的局限：代码按 Anthropic 文档的请求形状编写，但作者并未实际执行；价格和行为核对于 2026 年 10 月 17 日，规划季度预算前应重新查证。