Awesome Architecture

简体中文

English

简体中文

English

外观

AI 中转站 / AI 网关 架构模板 ​

代表产品:One API、New API、LiteLLM、Helicone、Portkey、OpenRouter、Cloudflare AI Gateway 一句话定位:在你的应用和众多大模型供应商之间,架一个统一的「中间层」——用一套(通常是 OpenAI 兼容的)接口接入所有模型,并集中做鉴权、计费、限流、负载均衡、故障转移、缓存与可观测。

1. 一句话定位 ​

AI 网关 = LLM 时代的 API 网关 + 反向代理。它本身不产生任何智能,价值全在「治理」:把原本散落在各处、直连各家模型的调用,收拢成一个可统一管控的入口。

它解决的问题特别朴素:当你的代码里到处是「调 OpenAI」「调 Claude」「调 DeepSeek」,各家接口不同、各家会挂、花了多少钱没人说得清——这时你需要一个中间层,把这些横切关注点(鉴权、限流、计费、容错、观测)一次性收编。

它就是 04 · 架构模式 里 BFF / 网关和代理思想,套在「调大模型」这件事上的产物。

2. 业务本质:它在解决什么问题 ​

它有两种典型用途,对应两种业务本质:

  • (A)企业内部治理:团队里几十个应用都要调模型,需要统一管 key、统一限额、统一看账单、一家供应商抖动能自动切换。网关让「调模型」变得可管、可控、可审计。
  • (B)「中转站」分发模式:运营方聚合上游(可能是多个账号、多个供应商),对下游用户按量计费、二次分发 key。它卖的是「省心 + 聚合 + 计费」——下游不必各自注册各家、不必管理多个 key,用一个接口、一个账户就能用上所有模型。

不论哪种,它的核心都是「把调用大模型这件事产品化、可治理化」。它不替你思考,它替你收银、调度、兜底、记账。

3. 核心需求与约束 ​

功能性需求:

  • [ ] 统一接口(通常 OpenAI 兼容),屏蔽各供应商差异
  • [ ] 多供应商 / 多模型路由
  • [ ] key 管理与分发、按用户 / 团队计费与配额
  • [ ] 限流、负载均衡、故障转移(重试 / 切换上游)
  • [ ] 缓存(省钱)、用量日志与可观测
  • [ ] (可选)内容审核 / 护栏

非功能性需求 / 质量属性:

质量属性目标为什么对这类系统重要
附加延迟极低(毫秒级)网关夹在关键路径上,自己绝不能拖慢请求
可用性极高它是单点,挂了 = 所有模型调用全挂
流式透传必须LLM 是流式输出的,网关要原样转发,不能缓冲
成本可见精确到 token计费 / 配额的根基

关键约束(不可逾越的边界):

  • 🔴 它是关键路径上的单点:必须无状态、可水平扩、配置可热更新,否则就是全局故障点。
  • 🔴 响应是流式的:必须边收边转(SSE 透传),不能等模型生成完再返回。
  • 🔴 上游不可靠且各异:各家会限流、会抖动、价格和能力都不同。
  • 🔴 上游 key 就是钱:绝不能泄露给下游或日志。

4. 架构全景图 ​

   你的应用 / 下游用户(用统一的 OpenAI 兼容接口)
        │  一个 base_url + 一个 key
        ▼
┌──────────────────────────────────────────────────────────────┐
│  AI 网关(无状态,可水平扩)                                       │
│  ① 鉴权 + 配额检查      ② 限流                                   │
│  ③ 路由 / 负载均衡:按价格 / 延迟 / 健康度选一个上游               │
│  ④ 缓存:命中则直接返回(省一次调用)                             │
│  ⑤ 调上游,失败则【故障转移】到下一个上游                         │
│  ⑥ 流式透传 token  ⑦ 解析 usage → 记账扣费                       │
└───┬───────────────────────────────────────────┬──────────────┘
    │ 转发(并原样回传流)                          │ 旁路异步
    ▼                                             ▼
┌───────────────────────────────┐      ┌──────────────────────┐
│ 上游 LLM 供应商(多家、多 key)  │      │ 用量 / 日志 / 计费存储  │
│ OpenAI / Claude / Gemini / 自建│      │ (可观测、出账单)       │
└───────────────────────────────┘      └──────────────────────┘

灵魂在于:网关自己什么模型都不跑,它是个「聪明的收费站」——所有车(请求)都从这过一道,被鉴权、计价、限速、必要时改道,但车还是开向上游的模型。

5. 组件职责 ​

  • 统一接入层:对外暴露一套(OpenAI 兼容)接口,内部用适配器把它翻译成各家上游的协议。为什么需要:让下游「写一次,调所有」,屏蔽供应商差异——这是适配器模式的经典应用。
  • 鉴权与 key 管理:校验下游 key、管理上游 key 池、做二次分发。为什么需要:上游 key 是钱,必须由网关托管、绝不外泄。
  • 路由 / 负载均衡 / 故障转移:在多个上游 / 多个 key 间选择,失败自动重试或切换。为什么需要:别把鸡蛋放一个篮子,单家挂了不能全挂。
  • 限流与配额:按用户 / 团队限速、限额。为什么需要:防滥用、防超支(每个 token 都是钱)。
  • 缓存:相同(或相似)请求直接返回缓存结果。为什么需要:LLM 调用又贵又慢,缓存是最大的省钱杠杆之一。
  • 计量与计费:解析每次响应的 token 用量,记账扣费。为什么需要:没有计量就既管不住成本、也出不了账单。
  • 可观测 / 日志:每一笔调用的延迟、成本、成败。为什么需要:看不见就管不了。

6. 关键数据流 ​

场景一:一次普通转发(网关的日常)

1. 下游带 key 发请求 ──▶ 网关:鉴权 + 查配额(够不够额度?)
2. 限流通过 ──▶ 查缓存:命中则直接返回(省一次上游调用)
3. 未命中 ──▶ 路由选一个健康的上游 ──▶ 转发请求
4. 上游开始流式吐 token ──▶ 网关【边收边原样转发】给下游(SSE 透传)
5. 流结束 ──▶ 解析 usage(prompt/completion token 数)──▶ 异步记账扣费

第 4 步是关键:网关绝不能等上游把整段生成完再转,否则流式体验全毁。它必须是「透明管道」。

场景二:上游故障转移

路由选中的上游返回 429(限流)或 5xx / 超时:
  ──▶ 网关按【故障转移链】切到下一个上游(或换一个 key)
  ──▶ 重试(指数退避)
  ──▶ 全部上游都失败,才向下游返回错误
  ── 下游全程无感:它只知道「我调了一次,拿到了结果」

7. 数据模型与存储选择 ​

核心实体:下游用户 / key / 配额;上游供应商 / key 池;用量流水(token、费用、延迟);路由配置;缓存。

数据存储类型为什么
用户 / key / 配额关系型要事务、强一致(扣额度不能错)
路由 / 模型配置关系型 + 内存缓存频繁读、要可热更新
用量 / 计费流水时序 / 列存海量追加、按时间和用户聚合出账单
响应缓存内存级 KV命中要快,有 TTL
限流计数内存级 KV高频读写、滑动窗口

8. 关键架构决策与权衡 ⭐ ​

决策 1:流式响应,透传还是缓冲?(网关的红线)⭐

  • 缓冲:等上游生成完整再返回——实现简单,但下游要干等十几秒,流式体验荡然无存。
  • 透传:边收边转(SSE 逐块转发)。
  • 取向:必须透传。代价是连接管理、错误中途恢复更复杂,但这是 LLM 网关的基本素养。

决策 2:自建部署,还是用托管?(不同阶段的关键选型)⭐

  • 托管(如 OpenRouter、Cloudflare AI Gateway):零运维、开箱即用,但有第三方依赖、数据要经过它、定制有限。
  • 自部署(如 One API、LiteLLM):完全可控、数据自留、可深度定制,但要自己保高可用、自己运维。
  • 取向:个人 / 起步用托管或单机自部署够了;团队 / 平台级要自部署并做高可用。详见第 12 节。

决策 3:缓存——精确缓存还是语义缓存?⭐

  • 精确缓存:请求完全相同才命中,安全但命中率低。
  • 语义缓存:请求「语义相似」就返回缓存——命中率高、更省钱,但有答非所问的风险(相似 ≠ 等价)。
  • 取向:默认精确缓存;语义缓存只在容忍度高的场景谨慎开启,且要能配相似度阈值。

决策 4:负载均衡 / 路由策略怎么定?

  • 轮询:简单均摊。按价格:优先便宜的上游。按延迟 / 健康度:优先快的、活的。
  • 取向:多数用「健康度优先 + 故障转移链」打底,叠加价格 / 延迟权重。核心是别把所有流量压在一家上。

9. 规模化与瓶颈 ​

  • 第一个瓶颈:网关自身吞吐。 → 破解:网关无状态,直接水平扩 N 份 + 前置负载均衡。
  • 第二个瓶颈:上游限流(各家都有 RPM/TPM 上限)。 → 破解:多账号 / 多 key 轮换、请求排队、按配额削峰。
  • 第三个瓶颈:计费写入量大。 → 破解:用量记账异步化(先转发,再落账),别挡在关键路径上。
  • 第四个瓶颈:配置 / 限流状态的一致性(多个网关实例)。→ 破解:用共享的内存级存储(集中式限流计数与配置)。

10. 安全与合规要点 ​

  • 🔴 上游 key 绝不外泄:它是钱。下游只持有网关发的下游 key,永远看不到上游 key;日志也要脱敏。
  • 多租户隔离:不同下游用户 / 团队的额度、数据、日志严格隔离。
  • 防滥用:限流、异常用量告警、key 泄露检测。
  • 内容合规:作为流量必经之地,可在此统一接内容审核 / 护栏。
  • 提示注入:网关透传的是用户内容,本身不解释它,但要意识到下游模型面临注入风险(见 AI 对话产品模板 第 10 节)。

11. 常见误区 / 反模式 ​

  • ❌ 缓冲完整响应再返回 → ✅ 流式透传,网关是透明管道。
  • ❌ 把网关做成有状态、难扩的单点 → ✅ 无状态 + 水平扩 + 共享状态外置。
  • ❌ 不解析 token、不计量 → ✅ 按 usage 记账,否则成本失控、出不了账单。
  • ❌ 滥用语义缓存导致答非所问 → ✅ 默认精确缓存,语义缓存谨慎开。
  • ❌ 把上游 key 暴露 / 打进日志 → ✅ 上游 key 由网关独占托管、脱敏。
  • ❌ 只接一家上游,它一挂全挂 → ✅ 多上游 + 故障转移链。

12. 演进路线:MVP → 成长期 → 成熟期(不同阶段怎么设置) ​

阶段规模量级怎么设置(具体)此时该操心什么
MVP / 个人单应用、少量调用直接用托管(OpenRouter / Cloudflare AI Gateway),或单机起一个 One API / LiteLLM,接 1–2 个上游就够别过度建设,先跑通「统一接口 + 看得到花了多少钱」
成长 / 团队多应用、多团队自部署 LiteLLM / One API:配多供应商路由 + 故障转移、按团队配额限流、加一层内存级缓存、用关系库存用量容错、配额、缓存命中率、把单 token 成本压下来
成熟 / 平台对外分发 / 大规模网关多副本高可用 + 集中式限流;接入专业可观测(如 Helicone);精细计费与多租户隔离;按需开语义缓存与护栏高可用、精确计费、合规、滥用治理

13. 可复用要点 ​

  • 💡 网关 / 中间层是「把横切关注点集中化」的经典手法。 鉴权、限流、计费、观测、容错——与其在每个应用里重写一遍,不如收编到一个入口。
  • 💡 适配器模式屏蔽供应商差异:对外一套接口,对内 N 个适配器。「写一次,调所有」适用于任何「对接多个异构第三方」的场景。
  • 💡 故障转移 = 别把鸡蛋放一个篮子。 任何强依赖外部、且外部会挂的系统,都该有「主挂了切备」的链路。
  • 💡 缓存是 LLM 系统最大的省钱杠杆之一——这一点和 AI 对话产品、模型推理服务 的 prompt / 前缀缓存一脉相承。

🎯 随堂检验 ​

🤔AI 网关 / 中转站的核心价值是?
  • A它自己跑大模型
  • B用一个统一入口集中做鉴权、计费、限流、容错、缓存
  • C负责训练模型

参考原型与延伸阅读 ​

本模板基于以下真实开源项目与公开文档的架构理念整理。想深入,直接读它们的代码与文档——比任何二手讲解都可靠。

🔧 开源原型(可直接读代码):

  • songquanpeng/one-api — 最流行的中文 LLM API 管理 & 分发系统,统一接口 + key 管理 + 二次分发,「中转站」的典型实现。
  • BerriAI/litellm — 用 OpenAI 格式调用 100+ 模型的网关 / 代理,内置成本追踪、负载均衡、故障转移、限流。
  • Helicone/ai-gateway — Rust 写的高性能开源 AI 网关,主打负载均衡、缓存、限流、可观测。
  • Portkey-AI/gateway — 极轻量(<1ms 附加延迟)的开源 AI 网关,路由 + 护栏 + 多供应商。

📖 工程文档 / 资料:

📌 一句话记住 AI 网关:它不跑任何模型,它是「调用大模型」这件事的收费站与调度台——所有设计都在回答『怎么用一个统一入口,把鉴权、计费、限流、容错、缓存、观测一次性管好』。