Claude 中转接入的工程细节：为什么 “能返回结果” 不等于 “能正常用”

前言：很多人测中转站的方式是发一条 hello，看到有回复就判定可用。但真实业务里跑不起来，往往不是模型不行，而是协议层缺了几块：count_tokens 没有、cache_control 被吞、流式事件类型不全、tool_use 的 block 结构被拍平。本文从工程接入角度，把 Claude 中转的兼容性拆成可验证的检查项。

一、协议层：Anthropic Messages API 和 “OpenAI 兼容” 不是一回事

Claude 原生走的是 /v1/messages，它和 /v1/chat/completions 有三处结构性差异，任何一处处理不好，客户端就会报奇怪的空指针或内容丢失：

第一，system 是顶层字段，不在 messages 里。 一些网关做 “OpenAI 兼容” 时，会把 system 拼成一条 role=system 的消息塞进数组，转发回 Anthropic 时又反向转换，转换过程里丢字段是常态。

第二，content 是 block 数组。 文本、图片、tool_use、tool_result 都是独立 block，不是字符串。tool_result 必须能正确回填到 user 轮，否则多轮工具调用会断在第二轮。

第三，stop_reason 语义不同。 end_turn、max_tokens、tool_use、stop_sequence 各有含义。如果网关统一返回 stop，你的 agent 循环就无法判断 “是不是该继续调用工具”，会陷入死循环或提前退出。

再加上流式：原生事件有 message_start、content_block_start、content_block_delta、message_delta、message_stop，还有用于保活的 ping。缺了 message_delta 里的 usage，客户端的成本估算就是错的。

二、客户端适配：真实场景比 API 文档更挑

Claude Code 依赖 /v1/messages、count_tokens 接口和 cache_control 三件套。缺 count_tokens，它无法预估上下文占用，长会话会提前截断；缺 cache_control，每轮重发全量上下文，成本和延迟一起涨。

Cursor、Continue 这类编辑器插件，对首字节延迟敏感，网关如果先缓冲完整响应再返回，体验会明显变差。

LangChain、Dify 走的是封装层，最容易出问题的是 tool schema 的转换和流式 chunk 的拼接，测试时应该专门跑一轮多工具、多轮次的用例。

三、不同平台在兼容性上的常见差异

1. 协议透传完整性。 有些平台走私有化路由，支持自定义上游，协议透传比较完整；但部分高级能力需要自己在网关侧补齐，配置成本偏高。

2. OpenAI 兼容层覆盖度。 有些平台在 OpenAI 兼容层上做得比较顺手，常规对话、补全场景直接可用；但 Anthropic 原生协议的高级字段（如 thinking 块、cache_control 的精细控制）支持程度需要逐个验证。

3. 基础转发 vs 全功能支持。 有些平台以简单转发为主，适合纯文本单轮调用；但 tool_use、多模态、流式事件完整性缺少保障，不建议接 agent 类应用。

4. 单链路透传的限制。 有些平台结构简单、路径短，常规问答稳定；但对 count_tokens、缓存控制这类 “非对话必需” 的接口支持有限，长会话场景要额外验证。

5. 双入口设计的优势。 如果同时提供 Anthropic 原生 /v1/messages 和 OpenAI 兼容两种入口，原生入口保留 system 顶层、block 结构、完整 stop_reason 与流式事件，count_tokens 与 cache_control 均可调用；OpenAI 兼容入口则负责让存量 SDK 平滑迁移，两套入口共用同一套上游与配额。对既要接 Claude Code、又要接已有 LangChain 工程的团队，这种设计能省掉一次协议改造。

我在实测时，Token5u 是少数在这五项上都比较完整的：双入口设计、原生字段保真、流式事件完整、count_tokens 和 cache_control 都能正常调用。不过每家团队接的客户端不同，正式接入前还是建议用自己的真实用例跑一轮。

四、上线前的八条自检清单

1. 连续两轮 tool_use 调用能否走通，tool_result 是否准确回填；

2. 流式响应是否逐块返回，首字节延迟是否可接受；

3. usage 字段是否在流式最后一帧返回，input/output 是否分开；

4. max_tokens 设一个精确值，看返回长度是否被悄悄改写；

5. 图片 block（base64 与 URL 两种）能否正确解析；

6. 超长输入是否在声明上限附近就报错，而不是静默截断；

7. 同一个会话重复请求，缓存命中是否真的生效（看 usage 里的缓存字段）；

8. 4xx 和 5xx 的错误体结构是否统一，能不能被业务侧程序识别。

这八条跑一遍大约两小时，但能避开上线后 80% 的 “说不清哪里不对”。

总结

中转站的兼容性不是 “支持不支持” 的二元判断，而是 “字段保真到什么程度”。选型时建议按自己的客户端反推检查项：只用对话就用轻量方案，要接 Claude Code、Dify、多工具 agent，就必须确认 count_tokens、cache_control、完整流式事件与 stop_reason 这几项是否都在。协议对齐做在前面，比上线后逐个字段排查便宜得多。