如果你接过多模型平台的需求大概率见过这类代码架构一个独立的网关服务前面接N个AI厂商后面接业务方配置里写满路由规则、密钥池、限流策略。表面看很干净但实际跑起来排障、迭代、测试的成本高得让人头疼。这个项目标题其实点破了一个关键问题很多人把“协议适配”误做成了“网关”而正确的做法往往是直接在 Java 应用里自建 OpenAI / Anthropic 兼容端点。这篇文章不聊 Kubernetes 部署也不聊 API 网关产品选型就聚焦一件具体的事如何在 Java 服务内部实现一个协议适配端点把 OpenAI 和 Anthropic 这两套差异巨大的 API 协议统一收敛成一套你自己的契约同时保留各自的能力边界。内容适合正在做 AI 应用集成、多模型接入、私有化模型网关的同学参考我会把协议差异、数据模型设计、流式转换、鉴权隔离这些关键点全部拆开讲。1. 为什么是“适配端点”而不是“网关”1.1 网关架构的四个隐藏成本把 OpenAI 和 Anthropic 的协议转换做成独立网关表面上隔离了上游和下游实际会引入四个隐蔽问题。第一多一跳就是多一个故障点。网关进程挂了所有 AI 能力全挂网络抖动时调用方无法区分是上游超时还是网关超时。我做过的项目里有一次线上故障排查了三个小时最后发现是网关进程的线程池被慢调用打满而上游模型响应其实一直正常。第二鉴权链路被割裂。业务方的 token、上游厂商的 API Key、网关自身的身份认证三套凭证混在一起。日志里只能看到网关和上游之间的调用业务方的原始请求上下文经常丢失出事之后很难追溯到底是哪个租户、哪个应用触发了这次调用。第三协议版本对齐难。OpenAI 的 chat/completions 接口和 Anthropic 的 /v1/messages 接口都在快速迭代网关只要慢半拍下游就会拿到奇怪的报错。比如 Anthropic 新加了 tool_choice 的 auto 模式而网关的映射层还停留在旧版本请求发过去就会收到 does not look like an anthropic model 之类的误导性错误。第四配置模型不可测试。网关的路由规则、模型映射、超时配置散落在 YAML 里本地没法单测只能联调时靠运气。而协议适配如果写在应用内部就是一个普通 Java 类JUnit 可以直接覆盖。1.2 端内适配的本质把协议当成接口契约在应用里自建端点并不是让你重新实现一个 HTTP server 去代理请求而是复用你现有的 Web 框架Spring Boot、JAX-RS 都行把 OpenAI 格式的请求和 Anthropic 格式的请求当作两种不同的入站协议在 Controller 层就完成归一化。这个思路的核心是你不需要一个独立的“翻译服务”你需要的是一个“翻译层”。这个翻译层长在业务进程内部调用方仍然按照你定义的统一协议来调用而上游到底是 OpenAI 还是 Anthropic对业务方完全透明。这样做的直接好处是你可以用业务代码里现成的依赖注入、配置管理、监控埋点来管理上游连接网关该有的功能一个不少但复杂度降了一个量级。1.3 什么时候仍然应该用网关端内适配不是银弹。如果你的场景是多个团队共享一套模型接入能力且他们各自独立部署服务那独立网关是合理的。但如果你只是在自己的应用里接了两家模型或者在做私有化交付的 AI 产品把适配逻辑塞进应用里能少维护一套服务少排查一类网络问题迭代速度会快很多。2. OpenAI 与 Anthropic 协议差异拆解2.1 端点与鉴权体系对比做适配之前先把两家协议的根本差异理清楚。我整理了一个对比表维度OpenAIAnthropic请求端点POST /v1/chat/completionsPOST /v1/messages鉴权方式Authorization: Bearerx-api-key: anthropic-version 请求头系统提示词messages 数组中的 system 角色独立的 system 顶级参数消息内容content 可以是字符串或对象数组content 一定是对象数组工具调用消息中包含 tool_calls 字段消息中包含 tool_use / tool_result 块流式结束标记最后一行 data: [DONE]流通过 message_stop 事件结束最大 token 参数max_tokens 或 max_completion_tokensmax_tokens图像输入content 数组中的 image_url 对象content 数组中的 image 对象base64 格式这些差异就是你在 Java 里要处理的全部关键点。别小看这些区别任何一个不理解到位都会在联调时踩坑。2.2 OpenAI 协议的 Java 模型映射OpenAI 的请求体在 JSON 层面比较好处理content 字段既能是纯文本也能是数组。对于这种“一会儿是 String一会儿是 List”的字段Java 里最稳的做法不是定义一个 Object 类型到处强转而是用 JsonNode 处理或者定义成自定义的反序列化类。我这边常用的做法是这样public record OpenAiMessage( String role, JsonNode content, ListOpenAiToolCall toolCalls, String toolCallId ) {}content 用 JsonNode 接收天然兼容字符串和数组两种形态。解析时判断content.isTextual()还是content.isArray()就可以分流。注意 OpenAI 的工具调用在 assistant 消息里是tool_calls字段数组里的每一项有id、type、function三个字段function里又有name和arguments。arguments 是字符串化的 JSON需要再解析一层。2.3 Anthropic 协议的 Java 模型映射Anthropic 的 content 字段永远是数组数组里可能是 text 类型也可能是 image 类型还可能是 tool_use 和 tool_result 类型。Java 模型我建议用接口加实现类的方式public sealed interface AnthropicContentBlock permits AnthropicTextBlock, AnthropicImageBlock, AnthropicToolUseBlock, AnthropicToolResultBlock { } public record AnthropicTextBlock(String type, String text) implements AnthropicContentBlock {} public record AnthropicImageBlock(String type, ImageSource source) implements AnthropicContentBlock {} public record AnthropicToolUseBlock(String type, String id, String name, JsonNode input) implements AnthropicContentBlock {} public record AnthropicToolResultBlock(String type, String toolUseId, String content, Boolean isError) implements AnthropicContentBlock {}Java 17 的 sealed interface 在这里特别好用编译期就能保证只有这四种类型switch 的时候也不用写一堆 default 分支。Anthropic 的 system 参数是顶层的当 OpenAI 请求里有多条 system 消息时需要把它们的 text 用\n拼起来作为 Anthropic 的 system 字段反过来Anthropic 应答里的 system 相关信息要拼回 OpenAI 格式时注意不能把系统提示词放进对话消息里否则上下文会混乱。2.4 模型名称的虚拟化映射适配端点里最容易被忽略的是模型名称映射。OpenAI 的gpt-4o和 Anthropic 的claude-3-5-sonnet-latest不应该是同一个逻辑模型。我推荐的做法是配置一层虚拟模型名model-aliases: chat-smart: openai: gpt-4o anthropic: claude-3-5-sonnet-latest chat-cheap: openai: gpt-4o-mini anthropic: claude-3-5-haiku-latest调用方传入chat-smart适配层根据你在配置里选择的上游厂商翻译成真正的模型名。这样业务方永远不会感知到上游模型变化换模型只需要改配置不需要改代码。很多报错比如热词里那个expected a gateway model route reference本质就是路由配置里的模型名写错或者压根没做别名映射直接把上游模型名透传了。3. 在 Java 里设计统一端点3.1 定义一个协议无关的内部模型端内适配的关键是不要让你的业务代码依赖任何一种厂商协议。我先定义一个 DCOMDomain Chat Object Model所有上游协议的差异到这里就结束了public record ChatRequest( String model, ListChatMessage messages, Double temperature, Integer maxTokens, ListChatTool tools, MapString, Object extraParams ) {} public record ChatMessage( ChatRole role, String text, ListChatContentPart contentParts, ListChatToolCall toolCalls, String toolCallId ) {} public sealed interface ChatContentPart permits TextPart, ImagePart, ToolUsePart, ToolResultPart {} public record ChatToolCall(String id, String name, String arguments) {}这个模型有几个关键设计。第一文本和富内容分开存text 字段作为纯文本的快捷方式contentParts 用来承载多模态内容。第二工具调用相关字段被显式建模因为后续做响应转换时要频繁判断这两个字段。第三extraParams 兜底各家协议的独特参数比如 OpenAI 的response_format和 Anthropic 的thinking参数避免为了适配把模型搞得过度膨胀。3.2 入站请求归一化两种协议收进来入站这一侧我直接在 Controller 层做了协议识别。如果调用方的 Content-Type 是application/json同时路径是/v1/chat/completions就走 OpenAI 解析器如果路径是/v1/messages就走 Anthropic 解析器。两个解析器都返回上面的ChatRequest。以 Anthropic 解析器的核心逻辑为例ChatRequest parseAnthropicRequest(AnthropicRequest req) { ListChatMessage messages req.messages().stream() .map(msg - { if (msg.role().equals(user) || msg.role().equals(assistant)) { return new ChatMessage( ChatRole.valueOf(msg.role().toUpperCase()), extractText(msg.content()), extractContentParts(msg.content()), extractToolCalls(msg.content()), null ); } // system 角色在 Anthropic 里是顶层字段, 这里不能直接映射 throw new IllegalArgumentException(Unsupported role: msg.role()); }) .collect(Collectors.toList()); // 把顶层 system 拼成一条 system 消息放在最前面 if (req.system() ! null !req.system().isBlank()) { messages.add(0, new ChatMessage(ChatRole.SYSTEM, req.system(), List.of(), List.of(), null)); } return new ChatRequest(req.model(), messages, req.temperature(), req.maxTokens(), parseTools(req.tools()), Map.of()); }注意这里有个坑Anthropic 的消息里没有 system 角色但用户传进来的 prompt 里可能已经写了 “System: xxx” 这种前缀。如果直接把这个字符串塞给 OpenAI 的 system 角色没问题如果反向转换从 OpenAI 的 system 消息转成 Anthropic 的顶层 system要注意把多条 system 合并的顺序先出现的 system 消息应该排在前面。3.3 上游调用抽象两个 Adapter 做到极致入站解析完成之后ChatRequest就要交给上游适配器去调用真实模型。我定义一个接口public interface ChatUpstreamAdapter { ChatCompletion call(ChatRequest request); StreamChatCompletionChunk stream(ChatRequest request); String providerName(); }OpenAiUpstreamAdapter和AnthropicUpstreamAdapter分别实现这个接口。因为内部模型已经统一了这两个 Adapter 反而很薄主要工作是调用各自的 HTTP 客户端再把响应转换回ChatCompletion。这时候 Spring 的依赖注入就派上用场了你可以根据配置给每个虚拟模型绑定一个 provider运行时自由切换。Service public class ModelRouter { private final MapString, ChatUpstreamAdapter adapters; public ModelRouter(ListChatUpstreamAdapter adapterList) { this.adapters adapterList.stream() .collect(Collectors.toMap(ChatUpstreamAdapter::providerName, a - a)); } public ChatUpstreamAdapter route(String virtualModelName) { // 从配置读取 virtualModelName 绑定的 provider String provider modelAliasProperties.getProvider(virtualModelName); return adapters.get(provider); } }3.4 出站响应归一化统一协议吐出去出站侧我默认暴露的是 OpenAI 兼容协议。为什么是这个方向因为 OpenAI 协议生态太成熟了LangChain4j、Spring AI、各类客户端工具都在优先兼容它。你的内部调用方只要按 OpenAI 的格式来就行不需要为 Anthropic 单独写一套客户端。把 Anthropic 响应转换为 OpenAI 响应时核心逻辑是这样的OpenAiChatCompletionResponse toOpenAiResponse(AnthropicResponse response, String openAiModelName) { ListOpenAiChoice choices response.content().stream() .filter(block - block instanceof AnthropicTextBlock) .map(block - new OpenAiChoice( 0, new OpenAiMessage(assistant, ((AnthropicTextBlock) block).text(), null, null), response.stopReason() ! null ? response.stopReason().replace(end_turn, stop) : stop, null )) .collect(Collectors.toList()); return new OpenAiChatCompletionResponse( response.id(), chat.completion, response.model(), choices, usageToOpenAi(response.usage()) ); }注意 Anthropic 的 stop_reason 是end_turn、stop_sequence、tool_use之类的值OpenAI 的 finish_reason 是stop、length、tool_calls。这里要做一次穷举映射。Anthropic 的 usage 里 input_tokens 对应 OpenAI 的 prompt_tokensoutput_tokens 对应 completion_tokens这个不转换的话下游做 token 统计会差很多。4. 流式响应的适配细节4.1 SSE 格式差异流式是协议适配里最容易翻车的部分。OpenAI 的流式响应是纯 SSE 格式每一行是data: {json}最后一行是data: [DONE]。Anthropic 的流式响应则是事件驱动的每一行是event: xxx紧接着是data: {json}最后是message_stop事件。Java 里用 WebClient 或者 Spring WebFlux 接收时框架一般会帮你把 SSE 按行切分但切的粒度对 Anthropic 不友好因为它的事件和数据是两行要自己拼装。4.2 用 Flux 做事件流转换我用 Spring WebFlux 的 Flux 处理这块非常顺手。核心思路是把上游的 SSE 流映射成统一的事件对象再按目标协议的格式重新编码。下面这段是核心转换逻辑的核心FluxString toOpenAiSse(FluxAnthropicStreamEvent anthropicEvents) { return anthropicEvents.flatMap(event - { if (event.type().equals(content_block_delta)) { if (event.delta().type().equals(text_delta)) { return Flux.just( data: openAiChunk(event.delta().text()) \n\n ); } if (event.delta().type().equals(input_json_delta)) { // 工具参数的增量片段 return Flux.just( data: openAiToolCallChunk(event.delta().partialJson()) \n\n ); } return Flux.empty(); } if (event.type().equals(message_delta)) { return Flux.just( data: openAiFinishChunk(event.delta().stopReason()) \n\n ); } if (event.type().equals(message_stop)) { return Flux.just(data: [DONE]\n\n); } return Flux.empty(); }); }关键点是Anthropic 的文本增量是content_block_delta里的text_delta工具调用参数增量是input_json_delta这两类增量要映射成 OpenAI 的不同 delta 结构。OpenAI 的delta.content对应文本增量delta.tool_calls对应工具参数增量而且工具参数增量在大模型流式输出时通常会是碎块需要每一块都封装成完整的tool_calls结构返回给调用方。4.3 反向流式转换的另一个方向如果你内部统一的是 Anthropic 协议反向转换也不复杂。唯一的陷阱是 OpenAI 的流式没有事件名只有data:你需要在解析侧维护一个状态机记录当前是否已经发送过message_start在第一条数据进来时先补发事件头。我实际项目中没走这个方向但提这个陷阱是想说明一点无论哪种方向流式转换的单元测试必须覆盖“跨 packet 边界拆分”的场景也就是一个完整 JSON 被拆成两个 TCP 包的情况。用 WebClient 做了一行一行解析后这个场景基本不会出问题但不要依赖框架自动处理。5. 鉴权、超时与多租户隔离5.1 调用方鉴权与上游密钥分离端内适配不是把密钥透传给调用方。调用方访问你的端点时应该使用你自己的鉴权机制比如 JWT 或者内部服务账号体系而 OpenAI 和 Anthropic 的 API Key 只存在于适配层由后端服务持有。我建议把上游密钥放在环境变量或配置中心适配层通过两个独立的配置类读取ai.provider.openai.base-urlhttps://api.openai.com/v1 ai.provider.openai.api-key${OPENAI_API_KEY} ai.provider.anthropic.base-urlhttps://api.anthropic.com ai.provider.anthropic.api-key${ANTHROPIC_API_KEY} ai.provider.anthropic.version2023-06-01这么做的好处是调用方拿不到任何一家上游的密钥你的多租户隔离只需要在内部完成。业务方 A 传进来的 prompt不可能直接构造一个请求去调用你的上游账户因为它没有验证凭证。5.2 超时与重试的差异化配置OpenAI 和 Anthropic 的超时行为差异很大。Anthropic 的长上下文模型响应时间明显更久而 OpenAI 的某些模型在开启 reasoning 后也可能等很久。如果统一设置 30 秒超时一定会误杀正常请求。我常用的配置方式是按 provider 设置三个超时连接超时、读超时、流式空闲超时。Provider连接超时读超时流式空闲超时OpenAI5s60s120sAnthropic5s120s300s流式场景下读超时不能简单用连接池的 socketTimeout因为流式连接是长时间打开的。更好的做法是用 Apache HttpClient 或者 JDK 的 HttpClient 配合响应式超时操作符每个元素之间的空闲间隔超过阈值才判超时而不是整个流的总时长超时。5.3 多租户维度模型路由与配额做了多租户就要在虚拟模型名之外再加一个租户维度。比如租户 A 可以调用chat-smart租户 B 不能调用。这个逻辑放在适配层里其实就是一个轻量级的授权判断。我更推荐的做法是把租户和上游账户绑定。比如租户 A 走公司主账户租户 B 可能用你自己的测试账户。这样适配端点内部维护一个tenant - provider - apiKey的三级映射实际调上游时动态选择密钥。密钥轮换时不需要重启服务从配置中心拉取更新即可。6. 常见问题与排查技巧6.1 从报错信息定位协议问题做这类项目时我收集了一批高频率报错整理成速查表报错现象根因处理方式doesnt look like an anthropic model模型名没映射透传了 OpenAI 模型名检查虚拟模型名映射确认调用时传入的是别名expected a gateway model route reference路由配置缺失或模型名拼写错误检查 model-aliases 配置确认大小写unable to connect to anthropic services网络层不通检查域名解析、防火墙、超时配置content must be an arrayOpenAI 的字符串 content 直接塞给 Anthropic入站转换时确保 content 转成数组tool_use id is requiredtool_result 缺少关联的 tool_use_id转换 tool result 时确认从原始 tool_call 携带了 idfinish_reason expected one of stop, length...Anthropic stop_reason 未映射添加 end_turn/tool_use/stop_sequence 到 OpenAI finish_reason 的映射每一条我都实际踩过。特别是第一条如果你用 LangChain4j 的ChatModel直接配 Anthropic 上游它内部可能默认要求 model 名称带claude前缀但你没有映射当然报错。6.2 解析 JSON 时如何应对 content 类型漂移OpenAI 的 content 字段是最容易出类型问题的。用户请求里 content 是纯字符串模型返回时 content 偶尔变成数组数组里还有 type 字段。如果你的 Java 模型只定义了 String content反序列化时遇到数组就直接抛异常。我应对这个问题的方案是前文提到的 JsonNode。但在响应转换时还有一个隐藏问题OpenAI 新版模型如果开了 reasoningcontent 可能带reasoning_content字段Java 模型里没有这个字段不会报错但 Jackson 默认配置下会忽略未知字段导致你的日志里看不到推理过程。排查问题时建议把FAIL_ON_UNKNOWN_PROPERTIES打开一段时间你会发现很多意外字段。6.3 工具调用循环的实现差异工具调用function calling是协议适配里工作量最大的部分。OpenAI 一套流程是发起请求带 tools → 模型返回 tool_calls → 业务方执行工具 → 追加 tool 角色消息 → 再次请求。Anthropic 的流程类似但消息格式完全不同模型返回 tool_use 块 → 业务方执行 → 追加 user 角色消息content 里带 tool_result 块。这里最容易出错的是多轮工具调用时的消息顺序。OpenAI 要求 assistant 消息携带 tool_calls紧接着的 user 或 tool 角色消息必须带对应的 tool_call_id顺序错乱会 400。Anthropic 要求 assistant 消息里的 tool_use 块和后续 user 消息里的 tool_result 块通过tool_use_id关联如果中间插入了别的文本内容也要保持顺序。我在适配层里专门做了一个ToolCallSession对象用来维护当前对话轮次里的工具调用上下文这样即使用户并发发来多个请求也不会串 context。6.4 日志与追踪的排障思路排障效率低多半是日志里没有请求 ID。OpenAI 和 Anthropic 的响应头里都有各自的请求 IDOpenAI 是x-request-idAnthropic 是request-id。适配层里应该把它们和外部请求 ID 关联起来。我的做法是在响应头的统一位置返回一个X-Trace-Id它的值取自调用方传的 traceId同时在适配层内部记录一份externalRequestId - providerRequestId的映射。出问题时顺着这条链就能定位到具体是哪个上游、哪个请求失败了。这个方法很土但比任何 APM 都管用。7. 端内适配的可测试性设计7.1 用 MockWebServer 模拟上游自建端点最大的优势就是可测试。不用启动真实的模型服务我用 OkHttp 的 MockWebServer 或者 JDK 的 HttpServer 模拟一个假的 OpenAI / Anthropic 服务端往适配层发固定的 JSON 响应验证转换逻辑是否正确。这样协议映射的每一条分支都能在 CI 里跑一遍。测试流式响应时MockWebServer 可以慢慢吐数据还可以故意模拟断包、延迟、半路 EOF 的场景比拿真实模型压测要精准得多。这也是我反对网关架构的一个重要理由——网关的协议转换逻辑想这么测得先起一个测试网关再配置上下游麻烦多了。7.2 契约测试锁定行为我在项目里引入了一个轻量级的契约测试把 OpenAI 和 Anthropic 的样例请求/响应保存成 JSON 文件每次修改代码后跑一遍确保老的映射行为不被破坏。这个测试不需要网络纯内存跑几秒钟就完事。它锁定的不是具体某个库的行为而是两家厂商协议之间的转换约定。这个约定定了以后升级 HTTP 客户端、改 Jackson 版本都不容易悄悄改变行为。8. 我的工程落地体会这个项目做了几轮迭代之后我最大的体会是协议适配的本质是数据翻译不是网络转发。很多人一听到“适配多个 AI 厂商”第一反应是上一套 BFF 或者 API 网关把问题复杂化了。实际上在 Java 应用里自建一个适配端点把协议差异收敛到一层清晰的数据映射上开发、测试、排障的体验都会好很多。实际操作中我个人还有一个习惯不管面向哪个厂商先把统一的 DCOM 模型做到稳定再去做具体的 Adapter。模型稳定了后面接新厂商比如 Google Gemini、本地 vLLM就是多写一个 Adapter 的事核心端点和业务代码一行都不用动。最后再分享一个小细节在端点层校验入参时一定要做 protocol-aware 的错误提示。调用方传了 Anthropic 风格请求到 OpenAI 端点时不要只抛一个“参数错误”应该明确提示“使用了 x-api-key 鉴权头但访问的是 OpenAI 兼容端点”。这个细节能帮联调同事省下大量反复确认的时间。如果后续要把这个项目扩展成支持更多模型可以考虑把虚拟模型名改成模型组的概念再加一个“按租户分配权重”的维度那就是一个轻量级但够用的模型路由中心了。但那是后话先把当前这层协议适配做到扎实才是正经事。