~/notes/omnigate-protocol-gateway-and-console-pagination.md1291 字

项目实战Omnigate 网关开发学习笔记 · 01/03

Omnigate(一):用 CIR 中间表示拆开协议转换

从 CIR 流式事件和 dialect/vendor 的职责分界入手,理解多协议 LLM 网关如何控制适配组合的复杂度。

目录 4 节

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 表达共用语义,方言代码处理格式差异,服务配置表达同一种方言下的来源差异。中间层有明确边界,新增来源时才能判断应该加配置还是扩展代码。

本系列对应仓库目前为私有,代码片段取自已核对的实现;删去的字段或流程已在相关段落注明。

系列阅读

下一章:Omnigate(二):流式响应的提交点与账号健康状态

  1. Omnigate(一):用 CIR 中间表示拆开协议转换
  2. Omnigate(二):流式响应的提交点与账号健康状态
  3. Omnigate(三):游标分页如何保持明细与汇总一致