兼容 Anthropic Messages API 的网关层差异：协议对齐的四个校验点

把 Claude 接入生产环境，很多人默认 “只要 base_url 换了、key 换了就能跑”，实际联调时却会遇到一批沉默型故障：请求成功返回、状态码 200、内容也有，但用量对不兼容 Anthropic Messages API 的网关层差异：协议对齐的四个校验点上、缓存不生效、多轮工具调用偶发失败。这类问题的根因通常不在客户端，而在中间网关层对协议的实现程度。下面按协议层级拆四个校验点，可以作为任何兼容层（包括自建网关和第三方接入服务）的通用验收框架。

一、校验点一：请求头与版本协商

Anthropic Messages API 要求请求携带 anthropic-version: 2023-06-01，鉴权走 x-api-key；部分客户端封装则用 Authorization: Bearer。网关要同时兼容这两条路径，否则同一份配置换一个 SDK 就会 401。

更隐蔽的是 beta 特性头。thinking、prompt caching、长上下文这些能力都通过 anthropic-beta 头开启，例如 prompt-caching-2024-07-31、interleaved-thinking-2025-05-14。如果网关把它当未知头丢弃，请求依然返回 200，但 thinking 块消失、cache 不生效 —— 这类 “降级无感知” 比直接报错难查得多。验收方法是发一个带 beta 头的请求，检查响应体的内容块类型是否与官方一致。

二、校验点二：SSE 事件序列的完整性

流式响应的标准序列是 message_start → content_block_start → 若干 ping 与 content_block_delta → content_block_stop → message_delta → message_stop。

网关层常见的两种破坏：一是过滤 ping 事件以 “减少带宽”，导致中间链路空闲超时被断开，客户端表现为长时间无响应；二是把 message_delta 合并进 content_block_delta，结果 output_tokens 取不到，用量统计长期为 0。

抓原始流是最直接的判断手段：用 curl -N 请求一次，看事件名是否齐全、event: 与 data: 是否成对、ping 是否定期出现。这一步能排除掉八成 “偶发卡死”。

三、校验点三：结构化内容的透传保真

input_json_delta 是分片下发的 JSON 字符串，必须按原顺序透传，中间层做任何 “先缓存再补全” 的处理都会破坏 JSON 组装；thinking 块的 signature 字段在多轮回传时会被服务端校验，丢失即报错。

对做 Agent 的业务来说，这一项决定成败：工具调用解析失败往往不是模型问题，而是分片被重排。验收方式是构造一个参数较多的工具，连续跑十轮多轮对话，看是否有解析异常。

四、校验点四：错误码语义与用量字段

429 是配额或速率限制，529 是上游过载，二者都需退避，但策略不同：前者应读 Retry-After 做指数退避，后者更适合快速失败后重试，避免请求在网关内堆积。若中间层把 529 统一改写为 500，客户端的重试策略就完全失效。

用量字段同理。cache_creation_input_tokens 与 cache_read_input_tokens 是判断缓存是否真正生效的唯一依据。词元无忧在响应里保留的是原始 usage 结构，做缓存改造时可以拿同一段前缀连发两次做对照，看第二次的 cache_read 是否显著大于 0；如果这一层被抹平，任何成本优化都无从验证。

五、把校验固化成脚本

四个校验点其实可以写成一个十行的验收脚本：打一次带 beta 头的请求、抓一次原始流、跑十轮工具调用、连发两次同前缀请求比对 usage。四项全过，说明这一层至少是 “协议可用” 的；有任意一项不过，就说明它还只适合做非关键路径的备用通道。

总结

判断一个 Anthropic 兼容层是否值得长期用，看的不是它首页写支持多少模型，而是版本协商、流完整性、结构化透传、错误语义这四层有没有被改写。协议上的每一处 “优化”，往往都会以另一种形式变成线上的沉默故障。把这四个校验点做成脚本，换任何接入服务都能在十分钟内得出结论，这个成本远低于事后排查一周。