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

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

---

## 1. 一句话定位

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

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

> 它就是 [04 · 架构模式](../../tutorial/04-十大核心架构模式.md) 里 **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 对话产品模板](../ai-chat-product/README.md) 第 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 对话产品](../ai-chat-product/README.md)、[模型推理服务](../inference-serving/README.md) 的 prompt / 前缀缓存一脉相承。

## 🎯 随堂检验

<Quiz
  question="AI 网关 / 中转站的核心价值是?"
  :options="['它自己跑大模型', '用一个统一入口集中做鉴权、计费、限流、容错、缓存', '负责训练模型']"
  :answer="1"
  explanation="它本身不跑任何模型,价值全在『治理』——把横切关注点收编到一个入口,是网关 / 中间层的经典手法。"
/>

---

## 参考原型与延伸阅读

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

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

**📖 工程文档 / 资料:**
- [Cloudflare AI Gateway 文档](https://developers.cloudflare.com/ai-gateway/) — 托管型 AI 网关:缓存、限流、重试、可观测,理解「托管方案怎么设计」。
- [jasonkuperberg/ai-gateway-resources](https://github.com/jasonkuperberg/ai-gateway-resources) — AI 网关选型与集成资料汇总(OpenRouter / LiteLLM / Portkey / Kong / Cloudflare)。

---

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