litellm：打造统一多模型接入的开源LLM网关

现在很多做 AI 应用的同学尤其是那些需要同时对接多家模型服务的团队正在被一个非常琐碎的问题反复折磨每个平台都有自己的 API 格式、认证方式、限流策略和计费规则今天要在代码里兼容这个明天要适配那个。更别提团队里不同成员可能各自申请了不同的密钥月底对账的时候只能对着账单发懵。我第一次遇到这个场景是在一个需要同时跑国内和国外多个模型做效果对比的项目里当时我就在想要是能有一个统一的管道把所有模型接口都收敛到一个入口让上层应用只管发 HTTP 请求底层细节全被屏蔽掉就好了。后来我发现一套成熟的开源方案其实已经把这条路走通了那就是名为 litellm 的模型网关服务。这里先直接给结论litellm 是一个用 Python 编写的开源 LLM 代理网关它把 OpenAI、Anthropic、Google Gemini、Azure OpenAI、以及国内常见的各类兼容接口全部统一成 OpenAI 的请求/响应格式。这意味着你不需要为每家模型单独写 SDK只需要往配置里写清楚上游地址和密钥然后所有应用都请求 litellm 服务本身即可。它还额外提供了密钥管理、负载均衡、成本追踪、限流以及简单的前端面板基本上一个团队自用或者小规模生产环境所需的网关能力它都覆盖了。这篇文章我会从实际落地的角度出发先把这套网关的核心设计逻辑讲清楚再带着你把配置、部署、调用、排错走一遍。无论你是刚接触 AI 开发的初学者还是已经在生产环境维护服务的资深工程师应该都能从里面找到可以直接拿回去用的内容。文章里不会塞一堆晦涩的概念我尽量用大白话加实际踩坑经验来讲保证你看完能上手。1. 核心思路拆解一个入口接管所有模型服务1.1 为什么需要一层“中间代理”很多人最开始不理解为什么不在代码里直接换个库、改几行请求参数非要引入一个额外的服务层。我举一个非常典型的场景你的项目里先用 OpenAI 的 GPT 做文本总结后来发现另一个平台的模型在中文长文本上效果更好、价格更便宜你决定切换过来。如果没有网关你需要把工程里所有调用 OpenAI 的代码全部扒出来把请求地址改成新平台的地址把请求体里的字段名按新平台规范改一遍认证方式换掉然后测试所有链路。这一套下来一个中大型项目少说也要折腾一到两天。引入 litellm 之后这个过程变成什么样子呢你在后端部署好 litellm 服务配置里写好“模型 A”指向 GPT 的 upstream“模型 B”指向另一家平台的 upstream。上层应用实际看到的是一个 OpenAI 格式的接口需要的只是一个虚拟的模型名比如gpt-4o-custom。后续要切换模型你只需要修改网关配置文件或者直接通过 API 动态调整路由规则应用代码一行都不用动。这种方式相当于给你的应用层和模型供应商之间加了一个适配层供应商的协议差异、密钥体系、限流策略全部被隔离在这个适配层内部。还有一个隐藏得很深的价值统一网关实际上帮你做了一层审计和管控。在直接接各家 API 的时候每次调用要花多少钱、被谁调的、成功率和延迟怎么样这些数据分散在供应商后台看不全也难统计。而 litellm 作为所有请求的汇聚点天然记录了每次调用的模型、项目、用户、token 消耗、耗时和费用估算你可以在一个面板上掌握全部情况。1.2 技术架构的三层逻辑从技术上看litellm 的架构可以拆成三层来理解。第一层是北向 API 层也就是对上层应用暴露的接口。这一层的设计非常聪明它直接复用了 OpenAI 的v1/chat/completions接口格式所以你在 OpenAI Python SDK 里随便改一下base_url指向 litellm再把 API key 换成 litellm 生成的虚拟 key就能正常使用。这种设计让迁移成本降到几乎为零因为 OpenAI 的 SDK 生态是市面上最成熟的几乎所有语言都有现成封装。第二层是路由层这也是 litellm 的灵魂。它负责拿到请求之后从配置和策略里确定应该把请求转发到哪个模型供应商。路由层要处理的事情包括如果配了多个相同名称的 upstream怎么根据权重、健康状态和最大并发数动态分流如果发现某个 upstream 持续报错或者超时了怎么自动摘除并切换到备用节点以及如果模型名称对不上实际服务如何做纠错和映射。这一层把复杂的容错逻辑沉淀在了定时任务和健康检查机制里上层不需要关心任何细节。第三层是南向供应商适配层。litellm 对各家供应商的 API 差异做了大量兼容工作。它走的是动态解析 JSON Schema 的路线请求进来时先把 OpenAI 规范的请求体翻译成各供应商能识别的格式再把返回的响应翻译回 OpenAI 规范。这个翻译过程不是简单字段改名还包括处理不同平台的消息格式差异比如某些平台的 system 消息、工具调用格式不太一样、不同平台对参数默认值的理解差异等。可以说这一层才是 litellm 的核心技术壁垒。2. 核心功能解析密钥、预算、路由和可观测2.1 多密钥管理与预算控制在 litellm 里密钥管理并不是简单的“存起来给你用”它是一套完整的虚拟密钥体系。你可以理解成真实的供应商 API key 被加密存在 litellm 的配置库中称为“后端密钥”而你分发给团队成员的是 litellm 自己生成的“虚拟密钥”与后端密钥一一对应或共享某个配额池。管理员通过管理接口或面板创建一个虚拟密钥时可以指定这个 key 能调用哪些模型、每分钟/每天/每个月的最大请求数或最大花费金额、绑定到哪个团队或用户以及在什么时间段内生效。举个实际例子你公司有实习生在做测试你不想让他用你的主 key 去生产环境模型上疯狂跑给他开一个虚拟 key限制只能调用最便宜的模型月预算上限 50 块钱到期自动失效。这个流程在管理面板上两分钟就能完成意义在于让密钥使用变得可管控不会出现一个 key 泄露导致整个账户被刷爆的惨剧。实战中我强烈建议真实供应商 key 的权限越少越好如果供应商支持子账号体系就为 litellm 单独创建一个专用子账号不要用主要账号的 key 去配。因为网关存储的密钥虽然本身是加密的但任何系统都扛不住密钥泄露如果泄露的是子账号且只授权了有限模型你的损失是可控的。2.2 路由策略与负载均衡配置逻辑路由策略是一个网关最值得强调的地方。litellm 的路由不是简单的“写死一个地址转发”它支持在同一模型名下配置多个 upstream形成一组专用后端。请求到来时网关会结合你配置的权重、最近 100 次调用的平均耗时、失败率、以及每个上游当前的并发请求数来做综合决策。最常见的配置方式是同一个模型服务部署在多套供应商或区域节点比如你同时拥有标准版和低延迟版两个渠道正常情况下所有流量走标准版但标准版超时率达到预设阈值时自动切换到低延迟版。另一种常见的用法是主备模式主供应商偶尔抽风备供应商集成在你的配置里一旦主供应商 API 返回 500/429 超过设定比例litellm 会把流量切到备供应商。这个能力对生产环境至关重要因为没有任何一家模型服务商能保证 100% 的 SLA但通过网关层的自动切换你的应用可以做到对外几乎无感。我在本地测试时给两个不同的上游渠道分别设了routing_strategyusage-based-routing和routing_strategylatency-based-routing实测发现延迟策略在我们流量不均匀的场景下不太稳定因为单次调用的延迟波动受网络影响很大。后来改成simple-weight加失败自动摘除效果反而更稳。这里想说明的是路由策略不是越智能越好要看你的实际流量特征小团队用简单策略加健康检查就非常香。2.3 成本追踪和 Token 级别的数据洞察成本追踪这一块litellm 做得比较深入。每次请求结束之后网关会根据上游返回的 usage 信息prompt tokens、completion tokens、以及你在配置里为模型设定的单价计算出这次调用的估算成本写入独立的数据库表。你可以在面板上按天、按模型、按团队、按用户查看消耗趋势。对于做预算控制的人来说这个功能基本是刚需。不过要注意的是“估算成本”不一定等于“真实账单”。因为部分模型供应商对大额充值用户的折扣价、月末返点等优惠不会体现在公开单价里litellm 的计算是基于你配置的价格表。建议你在季度末用供应商后台的账单去校准一下 model 的单价配置偏差大的话手动调价这样日常成本趋势才更准确。另外litellm 会把每次请求的完整调用链信息包括请求的原始输入截断、模型输出截断、耗时、状态码、错误信息持久化存储。这意味着你可以在面板里回看某一次调用到底发了什么、模型回了什么。排查问题的时候再也不需要去翻应用日志和供应商后台空对照直接在网关里看请求日志就清楚多了。3. 实操部署全流程从配置到生产可用3.1 环境准备与基础安装litellm 对 Python 版本的要求不算苛刻3.8 以上都没问题官方接口推荐 Python 3.11。安装方式最省事的是直接通过pip安装主包它会把依赖的客户端库一并带上。这里我要提醒一句安装时不要图省事用pip install litellm然后什么都不管建议新建一个独立的虚拟环境来跑网关服务避免污染你现有的 Python 环境。我们实际部署踩过版本冲突的坑就是在原有项目的虚拟环境里直接安装结果把某个依赖库版本挤掉导致项目起不来。# 创建一个专用虚拟环境 python3.11 -m venv litellm-env source litellm-env/bin/activate # 安装 litellm生产环境建议指定版本 pip install litellm[proxy] # 查看版本确认安装成功 litellm --version装好之后最快的启动方式是使用 SQLite 作为默认存储服务会初始化一张简单的 KV 表来保存密钥和配置如果你配置了数据库连接串它也能自动建表并迁移。生产环境我建议直接接一个 PostgreSQLSQLite 在并发稍高的时候会有锁冲突影响网关性能。数据库的连接方式和标准 ORM 类似设置好 URI 环境变量即可。3.2 第一步配置接入第一个模型服务我们用最常见的 OpenAI 兼容接口来演示配置。假设你手头有一个平台它的 API 地址是https://xxx.example.com/v1模型名是my-model供应商 key 是sk-abc123。首先创建一个配置文件config.yamlmodel_list: - model_name: my-model-proxy litellm_params: model: openai/my-model api_base: https://xxx.example.com/v1 api_key: sk-abc123 rpm: 500 model_info: mode: completion然后启动服务litellm --config config.yaml --port 4000启动之后litellm 会监听 4000 端口。你本地用 curl 做一次快速连通性验证curl --location http://localhost:4000/v1/chat/completions \ --header Content-Type: application/json \ --header Authorization: Bearer sk-1234 \ --data { model: my-model-proxy, messages: [ {role: user, content: 你好请回复一句话} ] }这里有个细节要说明model字段在litellm_params里写成openai/my-model这个前缀openai/是告诉 litellm 走 OpenAI 兼容协议去解析后面跟的才是真正的模型名。如果你的上游是别的平台前缀可能变成anthropic/、gemini/、azure/等litellm 就是靠这个前缀来识别该走哪个协议适配器。这是最容易出错但又最值得理解的地方把model前缀和api_base地址分别理解成“协议类型”和“目标地址”配置文件读起来就轻松很多。3.3 打开密钥管理并生成虚拟密钥初次启动后管理接口默认没有开启。你需要在配置文件里加上master_key并指定一个管理员用户名密码这样面板和管理 API 才会被激活。这个master_key相当于整个网关的超级管理员请务必用强随机字符串并妥善保管它可以在不配置数据库的情况下管理所有虚拟密钥。加入如下配置general_settings: master_key: sk-master-strong-random-key database_url: postgresql://user:passwordlocalhost:5432/litellm管理员用户名密码在环境变量里指定export LITELLM_PROXY_ADMIN_PASSWORDadmin_secure_password litellm --config config.yaml --port 4000重启之后访问http://localhost:4000/ui进入管理面板。你可以用 master key 登录部分版本直接用 master key 作为管理员密码然后进入密钥管理页面点击生成新的虚拟 key给它绑定目标模型也就是my-model-proxy设置好预算和过期时间。生成出来的 key 形如sk-XXXXXXXXXXXXXXXX把它配到你的应用环境变量里。很多人刚开始会忽略这一步直接在应用里使用真实供应商 key 去请求 litellm。这样做不是不行但等于完全放弃了密钥管控。我建议把“应用 → litellm 虚拟 key → 真实 key”这套链路作为标配后面查问题看日志的时候你能根据虚拟 key 区分是哪个应用在调用而不是所有流量混在一起。3.4 高可用部署的关键动作当 litellm 从本地实验走向生产有几点是必须提前规划的。第一是数据库必须外置且高可用不要依赖进程内嵌的 SQLite。第二是网关本身建议跑多个副本前面挂一层负载均衡这些副本共享同一个数据库和配置文件运行时状态是粘在 PostgreSQL 里的所以多实例部署很自然。第三点很容易忽略litellm 默认的模型路由数据是存在内存里的多副本部署时每个副本只有自己内存中的健康状态。这意味着如果一个副本已经把一个上游标记为不健康另一个副本可能还在往这个上游发请求。要解决这个问题需要把健康检查状态和部分路由状态持久化到 Redis 里。官方文档提供了redis_host等配置在general_settings下加上general_settings: redis_host: 127.0.0.1 redis_port: 6379 redis_password: 这样之后多副本之间的健康状态、缓存数据就可以共享了。实践下来即使只有单副本接一个 Redis 也能让并发处理能力明显提升因为很多请求参数校验的结果会被缓存不用每次重新解析。4. 高频问题与排查经验实录4.1 模型名称映射错误请求一直 404最常见的问题集中在model前缀上。很多人把 OpenAI 的 SDK 包直接改 base_url 指向 litellm然后请求时还传model: gpt-3.5-turbo但没有在 litellm 的model_list里配置gpt-3.5-turbo这个名字于是 litellm 根本找不到匹配的路由规则直接返回 404 或者报错 “model not found”。解决办法是无论 SDK 里传什么模型名必须保证这个字符串存在于 litellm 的model_list里。如果你希望上层业务代码保持原样还是传gpt-3.5-turbo那就把配置里的model_name也命名为gpt-3.5-turbo并映射到你的真实上游。让网关的模型名和业务侧模型名保持一致是最省心的方案。4.2 请求超时和上游限流的连锁反应上游模型服务偶尔响应变慢如果 litellm 默认超时时间设得过短网关会很快放弃并返回错误给客户端。但调大超时时间又有风险并发一高网关这边堆积大量等待中的请求内存飙升最后整台机器卡死。我们遇到过最严重的一次是某个上游集体限流所有请求都在排队结果 litellm 的 worker 全部被堵住健康检查端口都无法响应。后来我们做了三个动作第一根据上游的响应特点分别设置request_timeout比如普通生成模型 60 秒重计算类模型 300 秒第二在 litellm 前方加了超时更快的网关层快速失败返回给客户端不让请求在 litellm 里无限堆积第三给 litellm 进程单独配置内存上限并设置容器级别的自动重启策略。这样即使上游彻底抽风我们的服务也只是损失部分请求不会拖垮整个应用。4.3 成本统计和实际账单有偏差成本这块前面提了一嘴这里详细说。litellm 计算成本时需要model_info块里的input_cost_per_token和output_cost_per_token不同模型肯定不一样。如果你图省事不配置这两项网关就用默认值论“百万 token 美元”来算准确率很低。而且部分模型的实际价格是累进计费超出一定 token 量单价变化litellm 内置的固定单价模型算不了这种场景偏差就更大。处理办法是在配置里尽量精确填写单价尤其是 token 密集的对话场景差一两位小数月末汇总起来误差都不小。另外litellm 的统计更适合看趋势不建议完全替代财务对账。4.4 虚拟密钥泄露后的紧急处置一旦发现虚拟 key 被人刷了第一反应应该是到管理面板立刻把该 key 删除阻断后续请求。然后查日志确认被调用的是哪些模型、量级多少、损失约多少钱。由于真实供应商 key 始终在 litellm 内部外泄的虚拟 key 即使被他人拿到能调用的也只限于你绑定给它的模型和预算额度这是虚拟密钥体系最大的好处。5. 最后再分享两个实用小技巧第一个技巧litellm 支持把多个不同的供应商 key 配成同一个model_name系统会自动把密钥分散使用起到轮询的效果。比如同样的模型你有两个账号免费额度大家都懂的原因不想一下子消耗完就可以在配置里写两个litellm_params网关会轮流切换账号调用变相提高可用容量。但这个技巧请谨慎使用务必确认服务商允许这种用法别触碰服务条款。第二个技巧如果你在做一个面向大量用户的产品可以在请求体的 metadata 里塞上用户 ID 和会话 IDlitellm 会把它们透传到日志系统。之后你想统计“哪个用户消耗了多少 token、花了多少钱”在面板日志里就能直接筛选不用自己另外打点。这个习惯建议从第一天就养成不然后期补数据会异常痛苦。最后根据我的实际经验litellm 早期配置阶段看着繁琐但一旦路由、密钥、数据库这几条主线捋顺了日常维护非常轻松。它的价值不在于帮你写业务代码而是让你把“模型接入”这件事沉淀为基础设施能力。我强烈建议但凡有多个模型渠道的团队都花半天时间把它部署起来后面真的要切模型、做灰度、控成本的时候你会庆幸自己当初做了这个决定。