不造网关，自建适配端点：Java如何无缝兼容OpenAI与Anthropic协议

做对接大模型 API 这种活儿干多了就会发现团队里最容易出现的争论不是“用哪个模型”而是“怎么让所有模型长得一样”。我最近一个项目是典型的 Java 后端内部推理服务暴露的是 OpenAI 兼容接口但业务方希望同时支持 Anthropic 的调用风格让下游用 Anthropic SDK 直接接入。当时组里几乎所有人都提议上一个现成的协议转换网关把它当基础设施统一管。我坚持没这么干最后在 Java 服务里写了一个轻量适配端点把 Anthropic 的请求体转成 OpenAI 语义再把 OpenAI 响应转回 Anthropic 格式。项目上线后这个方案被证明成本低得多。这篇就讲讲我为什么反对一上来就造网关以及“在边界上做协议适配”到底怎么落地。1. 先把概念掰清楚协议适配和网关不是一回事1.1 建议上网关的理由听着都对等你部署就变味了“网关”很诱人。有了它团队就有一个统一地址业务不用关心后端是哪个供应商而且很多现成的网关号称自带路由、密钥管理、限流、日志看起来是所有 API 团队的标准答案。但如果你只是想把 Anthropic 协议和 OpenAI 协议互相映射事情就变味了这个网关需要单独运维、单独监控、单独高可用它作为一个独立进程出现在调用链里等于新增了一个天然的故障点。我见过最典型的场景网关把上游的错误信息重新包装下游拿着新的报错去翻日志日志又在网关里存了一份两边对不上。排查一个问题要同时打开路由、网关、业务服务三个控制台最后发现是网关版本升级后把某个响应字段悄悄改了。这种问题不是个例是网关方案的固有问题——只要中间层不理解业务上下文它就很难准确传递语义。1.2 适配器不是网关是贴在边界上的端点协议适配的本质不是“转发”而是“翻译”。转发是网关干的事请求进来按规则送到上游再把响应原样带回来。翻译不一样翻译需要知道两边的语法和语义需要把你自己的业务模型作为中间媒介而不是把字节原封不动地搬来搬去。所以我的观点是如果只是给自己的 Java 服务增加一个对外协议入口那就应该写一个普通的 HTTP 端点。这个端点长在业务进程内部跟随业务版本一起发布一起扩缩容一起打日志。它不是一个独立的系统而是服务的一个方法。这样做之后协议转换产生的异常、超时、参数校验全部落到业务自己的监控体系里不会再有一层绕过你监控的隐形通道。1.3 两种方案的对比数据比感受更直白我习惯把决策依据落到一张表上这张表后来也成了我劝组里同事放弃网关的主要论据。维度独立协议转换网关应用内适配端点部署复杂度单独进程、单独配置、单独证书随业务应用一起部署故障排查跨系统串联日志确认责任边界困难全链路在同一个服务内配置同步上游地址、密钥、模型名要额外维护复用服务自身的配置中心流式连接网关层容易断开或缓冲导致超时直接复用 JVM 连接池版本一致性网关版本可能滞后于业务和业务代码同版本发布扩展成本多一个团队都要遵守的规范只影响当前服务这倒不是说网关绝对不能用而是说当你只有一个服务需要兼容两种协议时为它单独立一套网关性价比非常低。真正的复杂场景是公司里十几个团队、几十个服务都要走统一出口那时候网关才值得你投入。2. 协议差异拆解OpenAI 和 Anthropic 的对话模型差在哪2.1 请求体system 参数和 messages 数组的冲突很多人以为 OpenAI 和 Anthropic 的协议差别只是 URL 和字段名不一样实际上它们的对话模型设计思路就有区别。OpenAI 把 system 提示塞进 messages 数组里用 role 区分Anthropic 则把 system 单独拎出来作为请求体的一个顶级参数messages 里只放 user 和 assistant。这个差异看着小落到代码里全是坑。如果你直接按照 OpenAI 的 model 类去接 Anthropic 请求会发现 Anthropic 的 system 字段没法映射到 OpenAI 的 messages 里必须在适配层做一次“重建 messages”的处理。我当时的做法是把 system 从 Anthropic 请求中提出来变成 OpenAI messages 数组的第一条 system 消息反过来当 OpenAI 响应回来时我又把 messages 里的 system 内容还原成 Anthropic 的顶层 system 字段。2.2 工具调用两套完全不同的结构协议适配里最容易翻车的是工具调用。OpenAI 的 tool_calls 是在 assistant 消息里平铺一个数组每个元素有 id、type、function 和 arguments对应的工具结果放在 roletool 的消息里。Anthropic 则把工具调用表达成 content blockassistant 回复里的 content 是一个数组里面混着 text block 和 tool_use block工具执行结果又变成 user 消息里的 tool_result block。这两套结构底层语义差不多但外层包装差异极大。适配的时候如果不小心最常见的错误就是把 Anthropic 的 tool_use block 当成纯文本拼进 OpenAI 的 content 字段导致下游大模型收到一堆 JSON 字符串而不是结构化工具调用。我在项目里专门为 content block 设计了一个转换器逐个判断 block 类型把 tool_use 翻译成 OpenAI 的 tool_calls把 tool_result 翻译成 roletool 的消息。2.3 响应体content 字段的形态差异和 stop 原因非流式响应也有很多细节。OpenAI 的响应里choices[0].message.content 通常是一个字符串或者在某些场景下是 nullAnthropic 的响应里content 永远是数组里面包含若干个 content block。所以适配响应的第一步就是把 OpenAI 的字符串 content 包成一个 text block再把 Anthropic 的 text block 拆回来。还有一个容易忽略的字段是结束原因。OpenAI 用 finish_reason取值有 stop、length、tool_calls、content_filterAnthropic 用 stop_reason取值有 end_turn、max_tokens、stop_sequence、tool_use。虽然大部分情况下 stop 对应 end_turn、length 对应 max_tokens但 tool_calls 和 tool_use 的对应关系一旦写错下游的循环调用逻辑就会出问题。这里我建议不要偷懒要单独写一个映射函数把所有组合都覆盖到。3. Java 里的统一模型先把两个协议耦合成一套内部结构3.1 DTO 设计用 record 还是 classJava 后端做协议适配第一步不是写 Controller而是设计一套与具体厂商无关的内部模型。我推荐用 record 来做请求和响应的不可变载体因为协议转换过程中大多数对象只是传递数据不需要可变状态。record 自带 equals、hashCode 和 toString调试打印请求体时非常方便。当然如果团队还在用 Java 8record 用不了那就退而求其次用 Lombok 的 Value 或手写不可变类核心是不想让协议对象变成可以随意修改的“万能类”。在适配层一旦对象可变就会出现某个字段在某个分支被悄悄改了值到下游怎么查都查不出来的局面。3.2 定义一个 UnifiedRequest 和 UnifiedResponse我的内部模型大概长这样public record ChatMessage( String role, String content, ListToolCall toolCalls, String toolCallId ) {} public record ChatRequest( String model, String system, ListChatMessage messages, ListToolDefinition tools, Double temperature, Integer maxTokens, ListString stop, boolean stream ) {} public record ChatResponse( String text, String finishReason, TokenUsage usage, ListToolCall toolCalls ) {}这套模型故意做得很朴素没有直接照搬 OpenAI 或者 Anthropic 的字段命名。它的作用只是桥梁适配器的方向是AnthropicRequest - ChatRequest - OpenAIRequest以及 OpenAIResponse - ChatResponse - AnthropicResponse。如果以后要接入第三个厂商也只需要写一个新的转换器内部模型不用动。3.3 用 JsonNode 承接协议专用字段保持边界干净有一种情况要特别注意某些字段只在特定协议里存在或者不同协议对同一字段的嵌套层次不同。这时候不要把所有的字段都展开到内部模型里否则你的 record 会越来越膨胀最终变成一个大杂烩。我在工具调用上就是这么处理的内部模型的 ToolCall 只保留 id、name、arguments 三个最核心字段arguments 直接用一个 JsonNode 存原始 JSON 对象而不是提前解析成 Map。这样无论是 OpenAI 的 JSON 字符串 arguments还是 Anthropic 的 input 对象都能统一塞进去等到转换目标协议时再按需序列化。4. 核心实操在 Java 里自建 Anthropic 兼容端点4.1 端点的路由和鉴权既然目标是让下游拿 Anthropic SDK 直接接入端点的路由就要严格贴合 Anthropic 的规范。Anthropic 的聊天接口是 POST /v1/messages所以我直接用 Spring Boot 的 RestController 把这个路径暴露出来并在 header 里校验 x-api-key 和 anthropic-version。RestController public class AnthropicCompatibleController { private final LlmProvider provider; private final KeyValidator keyValidator; private final ProtocolMapper mapper; public AnthropicCompatibleController(LlmProvider provider, KeyValidator keyValidator, ProtocolMapper mapper) { this.provider provider; this.keyValidator keyValidator; this.mapper mapper; } PostMapping(value /v1/messages, produces MediaType.APPLICATION_JSON_VALUE) public ResponseEntity? messages( RequestBody AnthropicRequest request, RequestHeader(value x-api-key, required false) String apiKey) { if (apiKey null || !keyValidator.isValid(apiKey)) { return errorResponse(401, authentication_error, invalid x-api-key); } if (request.maxTokens() 0) { return errorResponse(400, invalid_request_error, max_tokens is required); } ChatRequest unified mapper.toUnified(request); ChatResponse response provider.complete(unified); return ResponseEntity.ok(mapper.toAnthropicResponse(response)); } }鉴权这件事千万别省。即使这个端点只在内网开放也建议至少校验一个服务级别的密钥否则公司里的横向扫描可能把你的推理资源变成免费算力。4.2 非流式请求怎么映射核心转换逻辑集中在 ProtocolMapper 里。它的内部逻辑很简单先解析 Anthropic 请求体按 message role 拆解把顶层 system 字段放到内部模型的 system 属性里再把剩余消息映射成 ChatMessage 列表。OpenAI 请求体的构造也不复杂但有一个关键点OpenAI 的 max_tokens 是可选的Anthropic 则必填。所以在转成 OpenAI 请求时如果用户没传 max_tokens我会给一个默认值避免上游拒绝请求。另外OpenAI 的 system 消息必须放在 messages 数组第一个位置如果你把 system 插到中间有些模型会表现异常。public OpenAiRequest toOpenAiRequest(ChatRequest unified) { ListOpenAiMessage messages new ArrayList(); if (unified.system() ! null !unified.system().isBlank()) { messages.add(new OpenAiMessage(system, unified.system(), null, null)); } for (ChatMessage msg : unified.messages()) { messages.add(new OpenAiMessage(msg.role(), msg.content(), msg.toolCalls(), msg.toolCallId())); } return new OpenAiRequest( unified.model(), messages, unified.temperature(), unified.maxTokens() ! null ? unified.maxTokens() : 2048, unified.stream() ); }4.3 参数校验与错误响应映射协议适配最容易被下游感知到的地方就是错误格式。Anthropic 的错误响应格式是{ type: error, error: { type: invalid_request_error, message: max_tokens is required } }OpenAI 则是{ error: { message: ..., type: invalid_request_error, code: ..., param: ... } }如果直接把 OpenAI 的错误体原样返回给 Anthropic 客户端SDK 可能解析失败或者把错误信息当成未知结构。所以我在适配层维护了一张映射表上游 OpenAI 错误类型 / HTTP 状态映射为 Anthropic 错误类型对外 HTTP 状态invalid_request_error / 400invalid_request_error400invalid_api_key / 401authentication_error401模型不存在 / 404invalid_request_error400rate_limit_exceeded / 429rate_limit_error429上游 5xxapi_error500这里特别要注意不要把上游的 404 原样传到下游Anthropic 客户端看到 404 会以为 endpoint 不存在从而直接放弃重试。应该把“模型不存在”归为参数错误返回 400客户端才会正确处理。5. 流式适配协议最容易破功的地方5.1 两种 SSE 协议的差异非流式请求只是热身流式才是真正的坎。OpenAI 的流式响应用的是最朴素的 SSE每一行 data: 开头最后以 data: [DONE] 结尾事件类型完全靠内容里的字段区分。Anthropic 的流式则更讲究它定义了明确的 event 类型message_start、content_block_start、content_block_delta、content_block_stop、message_delta、message_stop。每个 event 后面跟一个 data: 行携带这个事件的具体数据。如果你只是简单地把 OpenAI 的 data: 行透传给 Anthropic 客户端客户端会因为找不到预期的 event 序列而报错。轻则流式截断重则客户端直接超时断开。5.2 流式转发的状态机我在适配层里维护了一个简单的状态机用来把 OpenAI 的增量内容包装成 Anthropic 的事件序列public final class OpenAiToAnthropicStreamAdapter { private boolean started false; private boolean ended false; public void accept(String openAiLine) { if (openAiLine.isBlank()) return; if (data: [DONE].equals(openAiLine.trim())) { emitStop(); ended true; return; } if (!started) { emitStart(); started true; } String deltaText extractDeltaText(openAiLine); if (!deltaText.isEmpty()) { emitDelta(deltaText); } } }这个状态机的核心规则是第一条内容增量到达之前必须先发 message_start 和 content_block_start后面每条增量都发 content_block_delta流结束时发 content_block_stop、message_delta 和 message_stop。顺序一旦错乱Anthropic SDK 就会抛错。5.3 处理不完整的 packet缓冲合并实际网络环境下SSE 的行不一定会完整地到达。TCP 分包可能让你在第一次回调里只收到半个 data 行第二次回调收到剩下的半个。如果直接按行解析就会产生 JSON parse error。我的做法是维护一个 StringBuilder 作为缓冲区每次收到字节都先 append再尝试按换行符切出完整行处理。处理完的行从缓冲区移除剩余的留在里面等下一次数据。StringBuilder buffer new StringBuilder(); void onBytes(String chunk) { buffer.append(chunk); String raw buffer.toString(); ListString lines raw.lines().toList(); int lastNewline raw.lastIndexOf(\n); buffer.delete(0, lastNewline 1); for (String line : lines) { streamAdapter.accept(line); } }这里有个细节如果最后一行没换行符那它很可能是不完整的不能立刻处理必须留在缓冲区里继续等。很多新手在这里踩坑把最后半个消息直接丢了解析流式就莫名其妙少一段文字。5.4 网络中断与取消流式适配还有一层容易被忽略调用方的连接随时可能断开。客户端点开页面刷一下或者模型生成到一半用户取消了请求你的代码就得立刻感知并释放相关资源。在 Spring Boot 的 SseEmitter 里我会注册 onCompletion 和 onTimeout 回调手动关闭上游的 HTTP 连接。如果不主动关闭上游的推理服务会继续把整段内容推完白白浪费算力。更严重的是连接池里的连接可能被半开状态的响应占住时间一长就把线程池拖垮。6. 真实工程踩坑清单每条都是血泪6.1 不要把 Provider 全塞进一个 HttpClient刚开始我图省事把所有厂商的请求共用一个 HttpClient觉得连接池复用可以提高效率。后来发现问题很大OpenAI 和 Anthropic 的超时策略、连接复用、证书策略都不一样混在一起之后一个厂商的慢请求会占光连接池的配额另一个厂商的请求全部排队。正确做法是给每个上游单独建一个 HttpClient单独配置 connectTimeout、readTimeout 和连接池大小。最好再按厂商隔离线程池避免某个厂商整体变慢时拖垮整个服务。6.2 错误信息不能只透传这里的坑和错误码映射类似但更隐蔽。上游的 OpenAI 兼容服务经常会在 error.message 里写一些内部细节比如“model xxx not found”或者带了内网地址的日志直接透传给下游既不美观也不安全。我在适配层增加了一个 sanitize 方法把错误信息里的敏感信息替换掉同时保留对用户有用的关键部分。比如把“model not found: gpt-xxx”保留但把内部的 request id 和 hostname 摘掉。6.3 Jackson 反序列化要小心 content 的多态结构Anthropic 的 content 是数组里面可能是 text block也可能是 tool_use block。如果只用普通 POJO 去反序列化强转类型时很容易出问题。我建议直接用 JsonNode 接住 content 字段再按 type 字段分发处理而不是硬写一层多态注解。因为 Anthropic 未来大概率还会加新的 block 类型硬编码多态意味着每次上游新增类型你都要发版直接用 JsonNode 则能天然兼容未知类型最多是少处理一种而已。6.4 编码问题比你想的更常见SSE 流式传输时中文和 emoji 都可能被拆到两个 chunk 里。如果你用 String.getBytes(StandardCharsets.UTF_8) 之后按 byte 去切分很容易把多字节字符切成半个导致乱码。我的建议是始终用字符流处理不要用字节流切分。Java 的 BufferedReader 可以按行读读出来的一定是完整字符。配合缓冲区按换行切行处理中文和特殊符号都很稳。7. 我个人的取舍标准什么时候真的需要独立网关7.1 一个服务的场景不要直接上网关如果只是你所在的服务需要兼容多协议那就老老实实写适配端点。它就在你的进程里随业务一起测试、一起发布、一起监控。出了任何问题你可以直接用断点在本地调试不用去翻另一套系统的日志。7.2 什么时候我才会考虑网关当协议兼容成为公司级需求需要十几个团队共同使用的时候独立的协议转换网关才值得考虑。判断标准有三条是否有多个团队需要复用是否需要对所有请求做统一审计或计费是否需要一个独立的流量出口来屏蔽后端拓扑变化。三条只要中了一条麻烦点也还能接受一条都不占那就别折腾了。还有一个折中方案把适配端点做成一个独立的 Java 模块通过依赖的方式嵌入各业务服务代码只维护一份但运行时仍然在每个服务内部。这种方案兼顾了复用和隔离是我现在更倾向的做法。最后分享一个小经验协议适配最容易翻车的地方往往不是“看不懂协议”而是“以为看懂了两边协议”结果漏掉了 system 字段的位置、stream 事件的顺序、tool_use block 的多态结构这些细节。如果你也在做类似的事建议先把两边的官方示例请求和响应打印出来逐字段对照着写转换器比直接看 SDK 源码快得多。这套适配端点跑上线之后我最大的体会是别为了让代码看起来“更高级”就多加一层很多时候最简单的方式反而最省心。