拆解 Metapi 源码：OpenAI⇄Claude 格式转换与 SSE 流式代理引擎是如何工作的

拆解 Metapi 源码OpenAI⇄Claude 格式转换与 SSE 流式代理引擎是如何工作的【免费下载链接】metapi把你在各处注册的 New API / One API / OneHub / DoneHub / Veloera / AnyRouter / Sub2API 等站点 汇聚成 一个 API Key、一个入口自动发现模型、智能路由、成本最优项目地址: https://gitcode.com/cita-777/metapiMetapi 是一个多站点 API 网关把 New API、One API、DoneHub、Sub2API 等站点汇聚成一个 API Key 和一个入口。它的两大核心能力——OpenAI⇄Claude 格式转换与SSE 流式代理引擎——都集中在源码的src/server/transformers/目录里。本文带你用一篇文章读懂这套协议转换与流式代理引擎的设计请求如何被解析成通用中间格式SSE 事件如何被逐条转发与改写以及失败时如何自动切换通道。一、请求的完整路径一个 POST 请求经历了什么所有代理入口都注册在 chat.ts 中路由层极其薄只做一件事——把请求交给表面层Surface下游调用方格式路由上游真实协议OpenAI Chat/v1/chat/completionsOpenAI / Claude / Gemini …Claude Messages/v1/messages同上双向互通请求随后进入 chatSurface.ts再经过三关选通道由 DefaultProxyConductor.ts 选出目标站点通道失败时按retryPolicy决定重试、刷新鉴权还是换通道改协议把请求体从下游格式转成上游格式下文详述转发并回流发起上游请求SSE 响应边读边改写边写回客户端。整个引擎的指挥棒就是这个 Conductor 的execute()循环选通道 → 尝试 → 记录用量 → 判断失败动作终态失败 / 同通道重试 / 刷新鉴权 / 换通道对客户端完全透明。二、格式转换的核心ProtocolTransformer 契约理解 Metapi 转换层的关键是一个只有 6 个方法的接口 contracts.ts方法职责parseRequest任意格式的请求体 →Canonical 通用信封buildProtocolRequestCanonical 信封 → 目标协议的请求体normalizeFinal上游非流式响应 → 归一化响应normalizeStreamEvent上游 SSE 事件 → 归一化流事件serializeFinal归一化响应 → 下游协议响应体serializeStreamEvent归一化流事件 → 下游 SSE 文本帧这是典型的枢纽模式Hub-and-Spoke不是 OpenAI 直接翻译成 Claude 再翻译成 Gemini 的 N×N 矩阵而是所有协议先降落到统一的 Canonical 中间格式canonical/request.ts再起飞到目标协议。新增一个协议只需实现一个 Transformer转换矩阵自动扩展。归一化数据结构定义在 normalized.ts其中NormalizedUsage统一了 token 用量字段——包括缓存读写 token、推理 token、音频 token 这些各家命名不一的字段这也是计费统计proxyBilling能跨站点准确记账的基础。三、OpenAI⇄Claude 双向转换的关键映射以 Claude 侧为例请求/响应桥接都在 anthropic/messages/ 目录下核心映射关系如下OpenAI ChatClaude Messagesmessages[].contentmessages[].content[]text / image / tool_use / tool_result 块toolstool_choicetoolstool_choiceauto→any等枚举改写max_tokens默认值兜底max_tokensClaude必填缺省会 400system消息顶层system字段finish_reason: tool_callsstop_reason: tool_useusage末尾 chunkmessage_delta事件中的 usage几个容易踩坑的细节在源码里处理得很细max_tokens兜底Claude 要求必填而 OpenAI 允许缺省桥接层会自动补一个合理默认值工具调用参数OpenAI 的arguments是 JSON 字符串Claude 的input是对象streamBridge.ts 里做了JSON.parse容错——解析失败时包装成{ value: 原文 }而不是让整个流崩掉thinking 块签名Claude 扩展思考extended thinking带有signature字段Metapi 在 reasoningTransport.ts 中专门处理了签名的透传与metapi:前缀的内部标记清洗。四、SSE 流式代理引擎逐帧读、逐帧改、逐帧写流式是代理网关最考验功力的部分。Metapi 的做法是三段式管道以 OpenAI Chat 为例openai/chat/streamBridge.ts上游 SSE 帧 ──► normalizeEvent() ──► 归一化流事件 ──► serializeEvent() ──► 下游 SSE 帧 Claude/Gemini 等 翻译成中间格式 无协议差异 拼装成目标格式读帧pullSseEventsWithDone按data:行切分上游响应识别[DONE]终止标记见 streamBridge.ts 的解析逻辑翻译每个事件被归一化成NormalizedStreamEvent——内容增量、推理增量、工具调用增量、结束原因各归各位跨协议的字段差异在这里被抹平写帧serializeNormalizedStreamEvent把归一化事件拼回下游客户端认识的格式OpenAI 客户端收到data: {...}加data: [DONE]Claude 客户端收到event: message_start到message_stop的完整事件序列事件名清单见 streamBridge.ts。两个值得称道的工程设计工具调用增量合并流式工具调用的参数是一个字符一片地到达的streamBridge.ts 用WeakMap按流上下文暂存每个工具调用的 id/name/arguments 片段串流结束后自动回收既不污染全局状态也不泄漏内存非流式降级当上游只返回完整 JSON 而客户端要求流式时buildSyntheticOpenAiChunks会把整包响应拆成若干 chunk 逐帧发出保证客户端体验一致。流量落库后代理日志页可以回看每一次转发的明细五、通道调度转换引擎的保险丝格式转换解决能不能懂通道调度解决挂了怎么办。DefaultProxyConductor.ts 的主循环展示了完整的故障处置策略shouldRetrySameChannel超时、5xx 抖动 → 原通道重试shouldRefreshAuth401/403 → 触发该站点 token 刷新后继续shouldFailover换下一条健康通道并把失败通道加入排除列表isTerminalFailure鉴权彻底失效等终态 → 停止并上报。每次尝试都会通过 usageHooks.ts 记录成功/失败为路由冷却routeCooldownService和站点健康度打分提供数据。六、源码导读按这条路径读下去想理解什么从哪里读起协议转换契约src/server/transformers/contracts.tsOpenAI Chat 全链路src/server/transformers/openai/chat/Claude Messages 全链路src/server/transformers/anthropic/messages/归一化数据结构src/server/transformers/shared/normalized.ts路由与调度src/server/proxy-core/conductor/DefaultProxyConductor.ts架构与目录说明docs/project-structure.md一句话总结Metapi 用Canonical 中间格式 6 方法 Transformer 契约 三段式 SSE 管道把 N 种协议互转变成了 N 个单向适配问题再配上 Conductor 的通道故障转移构成了一个既好读又好扩展的流式代理引擎。【免费下载链接】metapi把你在各处注册的 New API / One API / OneHub / DoneHub / Veloera / AnyRouter / Sub2API 等站点 汇聚成 一个 API Key、一个入口自动发现模型、智能路由、成本最优项目地址: https://gitcode.com/cita-777/metapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考