Omnigate 是我用 Rust 写的多协议 LLM API 网关。客户端使用熟悉的入口协议,网关负责选择上游、转换请求,再把结果渲染成客户端能够接收的格式。
本系列从已经实现的代码整理学习笔记。第一篇只讨论协议适配:为什么需要规范化中间表示 CIR,以及为什么服务品牌和协议方言要分开维护。流式重试和控制台分页分别放到后两篇。
一、协议转换为什么需要一层中间表示
如果直接为每个客户端协议和上游方言写转换逻辑,路径数量会随着组合增长。
例如,假设有 4 种入口协议、5 种出站方言,逐对实现就可能出现 20 条转换路径。新加一种入口,还要继续补齐它与所有上游的组合。工具调用、流式输出和用量统计一旦各写一遍,维护成本会比普通文本请求高得多。
Omnigate 把这件事拆成两步:入口协议先解析成 CIR,也就是规范化中间表示;上游适配器再从 CIR 构造实际请求。响应沿相反方向返回。
客户端请求 → 入口协议解析 → CIR → 上游适配器 → 上游服务
客户端响应 ← 入口协议渲染 ← CIR ← 上游响应解析 ← 上游服务
这样,新增入口主要扩展入口解析和响应渲染,新增出站方言主要扩展上游适配。上面的示例从 20 种组合收敛为 4 个入口适配和 5 个上游适配。
当然,中间表示不会自动消除协议差异。某个上游不支持工具调用、图片或特定输出约束时,仍然需要做能力协商。项目把能力缺口分成丢弃、模拟和拒绝三类,让处理策略在请求发出前就明确下来。
我更看重的是:协议差异有了集中的表达位置,不会散落在每一对转换路径里。
看 crates/og-core/src/cir/event.rs 时,可以先抓住下面几类事件。这段类型结构删去了部分变体与字段:
pub enum CirEvent {
ContentBlockStart { index: u32, start: BlockStart },
ContentBlockDelta { index: u32, delta: Delta },
ContentBlockStop { index: u32 },
MessageStop,
Error { kind: ErrorKind, message: String },
}
index 把内容块的开始、增量和结束关联起来;Delta 则区分文本、思考内容与工具参数片段。工具参数的片段还不一定是完整 JSON,要等内容块结束后再按完整参数处理。
学习这段代码时,可以先画出一个工具调用的事件顺序:开始块声明工具名称与 ID,多个增量传递参数片段,结束块标记参数接收完成。随后再看各协议适配器如何投影这条事件序列,比直接对照两份 JSON 更容易找到语义差异。
二、服务品牌和协议方言分开维护
另一个容易把代码写大的地方,是把每个服务商都实现成一个独立适配器。
实际接入时,不少来源使用相同的 OpenAI 兼容格式,区别主要在地址、鉴权、模型目录和少量参数约定。如果只是换了地址和服务名称,也复制一套请求解析器,后面修一次公共问题就要同步改很多份。
Omnigate 因此区分两个概念:
| 概念 | 负责什么 | 主要维护方式 |
|---|---|---|
方言 dialect |
请求和响应的实际结构 | 代码适配 |
服务类型 vendor |
地址、鉴权和服务特性 | 配置数据 |
对使用已有方言的新来源,优先增加配置。只有格式和交互方式确实发生变化,才增加协议代码。
控制台也需要遵守这个区分。内部 vendor 用于路由和计价,普通列表则显示账号配置的“来源服务”名称。否则,两个分别配置的中转服务可能显示成同一个品牌,用户看日志时反而无法判断请求去了哪里。
三、沿着事件结构读适配代码
读实现时,可以先打开 crates/og-core/src/cir/event.rs,再跟进 cir/content.rs 中的内容块和增量类型。先建立“内容块开始、参数增量、内容块结束”的关系,然后再看入口与上游适配器分别如何处理这些事件。
这篇最需要记住的是职责划分:CIR 表达共用语义,方言代码处理格式差异,服务配置表达同一种方言下的来源差异。中间层有明确边界,新增来源时才能判断应该加配置还是扩展代码。
本系列对应仓库目前为私有,代码片段取自已核对的实现;删去的字段或流程已在相关段落注明。