LiteLLM 架构拆解：请求如何穿过 AI 网关抵达 100+ 模型

LiteLLM 是一个开源 AI 网关，用一个统一的 OpenAI 格式接口，把应用和 100 多家模型提供商隔开。应用只跟它说话，它负责鉴权、路由、翻译、计费和记账。这篇文章沿着一次真实的 Hello! 请求，拆解它内部每个环节的设计与代价。

LiteLLM 是什么：公司里的邮件收发室

LiteLLM 的定位可以概括为一句话：它是一个开源网关，所有 AI 请求都从它这里经过，再被转发到真正的模型服务商，比如 OpenAI、Anthropic、Gemini、Bedrock 和 Azure。

它提供两种形态：一是 Python SDK，直接在你自己的代码里调用；二是网关，也叫 proxy，由团队或公司共享部署。根据项目仓库中的 ARCHITECTURE.md，网关内部用的就是 SDK，在此之上增加了身份校验、用量限额、预算和路由能力。下文讨论的是网关形态。

一个形象的类比是公司邮件收发室：收发员核对寄件人，选择快递公司，按对方的要求重新打包，最后记录邮费。楼上的业务部门不需要学习每家快递公司的规则。

一次请求的完整旅程

假设应用通过网关向 gpt-4o 发送一句 Hello!，整个过程可以拆成"进来什么、谁干活、留下什么、出去什么"四条线来看。

进来什么

应用像调用 OpenAI 一样调用网关，比如访问 4000 端口的 /chat/completions。Authorization 头里带的是一个虚拟密钥——网关为团队或应用生成的密钥，真实的厂商密钥被隐藏在后端。

另外两个输入同样关键：启动时读入的公开价格表，以及 config.yaml 配置文件。后者把每个模型名映射到一个模型组，组内可以包含多个 deployment，每个 deployment 代表模型运行的一个具体位置，比如另一把密钥、另一个区域或另一家厂商。

谁干活

第一步是取出密钥和预算。它们从内存或 Redis 缓存中读取，只有缓存未命中时才查数据库。接着是限流：对请求数和 token 数分别设上限，作用范围覆盖服务器、密钥、用户和团队四个层级。

然后是路由器从模型组里挑一个 deployment，默认策略是简单的随机打散。最后，针对该厂商的翻译文件把 OpenAI 格式转成厂商格式，再把返回结果转回 OpenAI 格式。

虚拟密钥（Virtual Key）与 deployment

虚拟密钥是网关自己签发的一把 key，格式通常仍是 sk-...，但它的值存储在 Postgres 中，并关联到一个团队、用户或预算对象。应用拿这把钥匙请求网关，网关查表后才知道该请求最终用哪一把真实厂商密钥去调用上游，真实密钥永远不出现在客户端。这带来两个直接好处：一是换厂商密钥不用重新分发客户端配置，二是可以单独吊销某把虚拟密钥而不影响其他调用方。

deployment 指的是同一个模型在物理上的一个具体落点：同一家厂商的另一把密钥、另一个区域端点，或者干脆是另一家厂商提供的等价模型。模型组是逻辑名（如 gpt-4o），组内的 deployment 是可替换的实例。路由器只面对 deployment 做选择，因此"同一个模型名"在网关内部其实是一组候选后端。

回答之后：成本、日志与记录

在响应发出之前，网关先算钱：输入输出 token 数乘以价格表里的单价。ARCHITECTURE.md 显示，这个成本会通过名为 x-litellm-response-cost 的响应头返回给应用。

出去什么、留下什么

应用拿到的是 OpenAI 格式的应答。日志在后台发往 Langfuse、Datadog 这类可观测工具，管理后台则展示密钥、团队和花费。

持久化方面，Postgres 存储密钥、团队、预算和消费日志，表结构用 Prisma 定义。Redis 是可选的，存在时用来放缓存、限流计数器和消费缓冲。

一句 Hello! 的消费会先进队列，由后台任务批量写入 Postgres，默认每 10 到 15 秒一批。这意味着请求链路上没有任何数据库写入。

消费缓冲队列（Spend Buffer）

这里的队列不是消息中间件，而是网关进程内（或 Redis 中）维护的一批待写入记录。请求结束时，网关只把这次调用的 token 数、成本、密钥 ID 追加到缓冲里，然后立刻返回响应；一个后台异步任务按固定间隔把整批记录一次性写进 Postgres。批量写入把 N 次请求变成 1 次数据库事务，显著降低连接开销和写放大。

代价是可见性延迟：刚发出的请求在管理后台的消费报表里要等一个刷新周期才出现。对账场景需要把这一点考虑进去，比如在查询时用时间窗口而非"立刻可见"来核对。

四个关键取舍，以及各自的代价

LiteLLM 的架构不是免费的午餐，每个设计选择背后都有明确的代价。

统一用 OpenAI 格式。 不做各家 SDK 的适配层，好处是换厂商只需改一个模型名，不用改代码；代价是某家厂商有而 OpenAI 格式没有的能力，需要靠额外参数来补。

把数据库挡在请求之外。 网关挡在每个调用前面，绝不能增加等待时间；代价是数据库里的消费总额有延迟，预算检查依赖共享的实时计数器，多副本之间只能靠 Redis 同步。

价格作为公开文件。 模型价格放在仓库里一个 JSON 文件中，安装包里也有一份副本。选文件而非定价服务或厂商账单 API，是因为任何人都能读、能改、能复用。代价像一份早上打印的菜单：厨房中午涨价，桌上的菜单还是旧价，直到有人重新打印。运行中的 proxy 会一直用启动时加载的价格，除非管理员手动重载或设置定时任务，所以成本可能漂移。

只在横向扩展时才需要 Redis。 单副本把缓存和计数器放在内存里，不需要额外组件；代价是没有 Redis 时，限额和缓存都是每个副本各算各的。

规模扩大十倍会发生什么

设想负载均衡后面挂了十个网关副本。限流和缓存迁移到 Redis，各副本对每个密钥的用量达成一致；消费更新也可以先落在 Redis，再批量写入。仓库里的 Terraform 模块走得更远，会把网关和管理后台拆成两个独立服务部署。

那厂商宕机怎么办？类比打电话：一个店员忙，就转给同一家店的其他店员；整家店关门，才打下一家店。在 LiteLLM 里，retry 是向同一个模型组再要一次，可能落到另一个 deployment；fallback 则是在第一个模型组持续失败时，切到配置里的下一个模型组。

retry 与 fallback 的区别

retry 发生在同一个模型组内部：某次调用失败（超时、5xx、限流）后，网关按配置的次数重试，路由器的选择可能落到组内另一个 deployment，因此重试天然带有"换一个后端再试"的含义。fallback 则跨越模型组：当第一个模型组重试耗尽仍然失败，网关按 config.yaml 中的 fallback 列表切到下一个模型组，可能换厂商、换模型。

两者都会带来额外延迟和潜在重复计费风险，因此实践中通常给 retry 设较小的次数，并对幂等性敏感的写操作谨慎使用 fallback。

自己动手验证

按 README 的步骤，在本地就能看到这套机制。

用 uv tool install 'litellm[proxy]' 安装网关，把 OpenAI 密钥放进 OPENAI_API_KEY，然后执行 litellm --model gpt-4o 启动。把任意 OpenAI 客户端指向本机 4000 端口（README 用的是 0.0.0.0:4000）发送 Hello!；用 curl 的话，请求 /v1/chat/completions 并打印响应头。

找到 x-litellm-response-cost 头，那就是网关算出的这次调用成本。再打开仓库里的 model_prices_and_context_window.json，找到你的模型，用单价乘以应答 usage 里的输入输出 token 数。如果两个数字对不上，先检查价格文件是否在网关加载之后被改过。

一个值得注意的运维细节

从工程角度看，LiteLLM 把"不阻塞请求"当作第一优先级，这个选择贯穿了鉴权、计费和限流三条路径。它换来的代价也很具体：消费数据有 10 到 15 秒的延迟窗口，价格表可能过期，多副本部署必须引入 Redis。

对于单机或小团队场景，这些代价几乎可以忽略；但当日志需要和财务对账、当预算控制要求强一致时，价格漂移和消费延迟就成了需要额外工具兜底的地方。原作者也正是因此做了一个浏览器端的对账工具，用每日价格去核对网关的消费日志。