做应用开发的朋友应该都有这种经历：项目里接了好几个模型服务商的API，代码里写满了不同的请求格式、不同的鉴权方式，每换一家厂商就得改写一版调用层；密钥散落在代码和环境变量里，月底对账的时候得翻聊天记录找谁用了多少个Token；更麻烦的是想给模型调用统一加缓存、限流、预算控制，发现每个厂商的接口控制方式都不一样。litellm就是专门解决这一堆问题而生的统一网关项目。

它本质上是一个Python库，同时也自带一个可独立部署的代理服务。你只需要用一套统一的接口调模型，剩下的事——到底请求哪家服务商、要不要重试、要不要缓存、这次调用花了多少钱——都由litellm来处理。适合正在做AI应用开发、需要在多个模型供应商之间切换、或者想把模型调用的成本和管理收拢到一处的人参考。

1. litellm到底解决什么问题：拆掉模型厂商之间的“接口围墙”

1.1 为什么需要统一网关

先说一个我自己的真实感受。两三年前接模型服务还是一件很纯粹的事，选一家厂商，读它的文档，按它的格式拼请求，跑通就完事了。但现在的项目普遍是混合策略：日常问答用一个性价比模型，复杂推理用一个更强的模型，偶尔还要用开源模型做私有化部署。这样一来，业务代码必须同时维护好几套请求协议，每一家的消息格式、鉴权字段、超时语义、错误码都不一样，甚至同一家的新旧版本接口都可能不兼容。最典型的结果就是：换个模型，牵一发而动全身，测试用例要改，异常处理要改，计费逻辑也要跟着改。

用生活里的例子类比一下。每个模型服务商就像一家餐厅，接口就是它家的菜单和点菜规矩。你自己一家一家去点菜，就得记住每家的规矩。litellm相当于一个专属代点餐管家，你只需要告诉他“我要一份单人餐”，他负责把需求翻译成各家能听懂的话，送到对应的餐厅，再把结果端回你面前。你根本不用关心这道菜是哪个厨房做出来的。

所以从本质上看，litellm解决的是模型接入层的“接口碎片化”问题。它把多变的需求收敛成一个稳定入口，业务代码只依赖这个入口，模型服务商怎么变、接口怎么改，都被隔离在适配层之外。这和你用统一数据库访问层屏蔽MySQL和PostgreSQL的差异是一个道理，只不过这次屏蔽的是各家大模型API。

1.2 SDK模式和代理服务模式，各自该在什么时候用

litellm提供了两种接入方式，很多人第一次接触时会纠结选哪个，我直接说结论。

SDK模式是把它当普通Python库用，代码里直接import litellm，调用统一函数完成请求。这种方式最轻量，适合单个服务、快速原型、或者团队里只有少数几个项目使用。好处是零额外部署，跟着应用一起跑，坏处是每个接入的项目都要装这个库，密钥和配置还是分散在各处的。

代理服务模式则是用一个命令启动一个独立的HTTP网关服务，所有模型请求都发给这个网关，由它再去转发给真正的模型服务商。业务代码不再需要安装litellm，只需要按标准HTTP接口调用网关地址即可。这种方式适合多团队共享、多语言异构、需要集中管控密钥和费用、或者想把限流缓存这类横切能力统一收口到网关的场景。

我用一个简单的对比表格帮你理解：

我的建议是，如果你一开始不确定，先用SDK模式跑通流程，跑起来之后再把同样的配置迁移到代理服务模式。litellm的设计让这两种模式共用同一套配置概念，迁移成本很低，不用推倒重来。

1.3 除了转发请求，它还在背后做了什么

litellm的另一大价值在“转发之外”的事情上。大多数网关类项目只解决协议统一，但litellm把生产环境需要的周边能力也一并做了，这一点在我实际用下来之后体会特别深。

第一是自动重试。模型服务商的接口经常会因为限流、瞬时抖动、网络波动返回错误，litellm支持配置重试次数和重试退避策略，应用层不需要自己写循环。

第二是缓存。对很多客服、知识库问答场景来说，用户的问题高度重复，同样的请求打给模型服务商不仅花冤枉钱，延迟还高。litellm支持本地内存缓存和Redis缓存，网关层直接把结果挡回去。

第三是费用追踪。它会把每一次请求的模型名、Token用量、预估费用记录到日志或数据库里。配合预算限额，你可以设置一个月度总预算，超过阈值之后自动拒绝新的请求。这种能力在没有网关的时候几乎是手工活——要么自己写埋点，要么在服务商后台一个一个对账单。

第四是虚拟密钥管理。代理模式下，你可以给不同业务线、不同环境签发不同密钥，每个密钥绑定不同的模型范围和预算额度。比如给内部测试环境一个每天只有10元额度的密钥，给线上环境一个更宽松的密钥，出了问题也能快速定位是哪个团队在用。

这些能力单独看都不算新奇，但组合在一起，并且能通过一个配置文件统一声明，才是litellm真正值钱的地方。

2. 安装部署与基础配置：从零跑通第一次调用

2.1 环境准备与pip安装

litellm对Python版本的要求不算苛刻，我建议用3.9以上环境，顺手把虚拟环境也建好。安装命令很简单：

pip install litellm

装完之后可以用一个很直白的方式验证是否成功：

python -c "import litellm; print(litellm.__version__)"

能打印出版本号就说明基础安装没问题。需要注意的是，litellm的依赖项比较多，因为它要同时适配几十家模型服务商的SDK和协议，装一次会把一整套适配器相关依赖都带下来。如果你的项目对依赖体积特别敏感，可以考虑用代理服务模式把它独立部署在单独的虚拟环境里，不要和业务服务搅在一起。

2.2 SDK模式的最小调用示例

先看一段最朴素的代码：

import litellm response = litellm.completion( model="provider_a/fast-chat-model", messages=[ {"role": "user", "content": "你好，请简单介绍一下你自己"} ], api_key="你的provider_a密钥" ) print(response.choices[0].message.content)

看到没有，整个调用过程就是函数、模型名、消息列表、密钥四个要素。真正让这段代码具备通用性的关键是model参数里的provider_a这个前缀。litellm拿到前缀后，会自动路由到对应的服务商适配器，然后把统一格式的输入转换成那家服务商真正需要的请求结构。你不需要关心那家的鉴权头怎么写、消息结构怎么组织、返回内容怎么解析，适配器全包了。

如果你用的是异步框架，比如FastAPI，那用异步版本更合适：

import asyncio import litellm async def main(): response = await litellm.acompletion( model="provider_a/fast-chat-model", messages=[{"role": "user", "content": "异步测试"}], api_key="你的provider_a密钥" ) print(response.choices[0].message.content) asyncio.run(main())

从同步切换到异步，只换了一个函数名。这种一致性设计对重构很友好，你不需要为同步异步维护两套调用逻辑。

2.3 代理服务模式：一条命令启动网关

SDK模式跑通之后，体验一下代理模式。先准备一个配置文件config.yaml，内容大致长这样：

model_list: - model_name: fast-chat-model litellm_params: model: provider_a/fast-chat-model api_key: os.environ/PROVIDER_A_API_KEY - model_name: big-reasoning-model litellm_params: model: provider_b/big-reasoning-model api_key: os.environ/PROVIDER_B_API_KEY

注意这里的细节：model_name是给你自己业务用的逻辑别名，你可以随便起，业务代码请求时填的就是这个；litellm_params里的model才是服务商规定的真实模型标识，必须和对方控制台里的名字严格一致。api_key这里用了os.environ语法，意思是网关启动时从环境变量里读取密钥，而不是明晃晃写在配置文件里。这比把密钥直接写进config文件安全得多。

然后启动网关：

litellm --config config.yaml --port 4000

看到日志里出现服务地址后，你就可以用标准的HTTP请求来调用模型了：

curl http://localhost:4000/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-your-virtual-key" \ -d '{"model": "fast-chat-model", "messages": [{"role": "user", "content": "你好"}]}'

这里有个容易被忽略的点：代理暴露的接口格式和主流模型服务商的REST风格保持一致，所以如果你的业务代码原本就是按这种通用格式写的，现在只需要把base_url从服务商官方地址改成http://localhost:4000，其他基本不用动。这是代理模式最吸引人的地方——对存量代码的侵入性非常小。对于还在用各家SDK的老代码，也可以在这里配一个轻量的适配层，逐步把流量切换到网关。

2.4 多模型配置与密钥管理

生产环境不会只有一个模型，所以配置文件的管理要从一开始就规范化。我的习惯是在config里维护一份清晰的模型清单，每个模型一小段，用yaml的缩进把逻辑关系表达清楚。随着模型数量增加，一个最容易踩坑的地方是：model_name重复。litellm遇到重名会启动报错或路由混乱，所以在给别名起名时，最好用业务语义而不是模型性能描述，比如客服机器人和代码助手，分别定义成support-bot和code-assistant，以后调整背后的真实模型时，业务代码完全不用改。

密钥管理的核心原则是：不要让业务环境接触明文密钥。在代理模式下，所有密钥集中在网关配置里，通过环境变量引用。具体操作是先把密钥写进网关所在的服务器环境变量，然后在config里用os.environ/变量名引用。如果你的团队上了密钥管理服务，也可以在启动脚本里动态注入环境变量，然后启动litellm进程，这样密钥连服务器磁盘上的明文文件都不会有。

3. 生产环境进阶玩法：路由、重试、缓存与预算控制

3.1 多模型路由与故障转移策略

网关的意义不只是转发，还可以让请求按策略自动分流。litellm在模型列表里支持配置fallbacks，也就是主模型失败后自动降级到备选模型。举一个很常见的配置例子：

model_list: - model_name: support-bot litellm_params: model: provider_a/fast-chat-model api_key: os.environ/PROVIDER_A_API_KEY model_info: supports_function_calling: true - model_name: support-bot-fallback litellm_params: model: provider_b/cheap-chat-model api_key: os.environ/PROVIDER_B_API_KEY router_settings: fallbacks: support-bot: - support-bot-fallback

这样配置之后，当provider_a因为限流、额度不足或者瞬时故障拒绝请求时，网关会自动把请求转向provider_b的备用模型。业务方完全无感，只知道自己请求最终成功了。这个能力在线上服务稳定性上非常关键，模型服务商出现故障并不罕见，如果没有这层自动切换，你的应用就会跟着一起宕机。

在路由层面我给你的建议是：别把鸡蛋放在一个篮子里。即使你最喜欢某一家模型，也至少配置一个不同服务商的备用模型。这样既能在出故障时兜底，也能在做模型选型对比时有真实流量数据做支撑。

3.2 缓存机制的选择与命中率调优

缓存是一个让你又爱又恨的东西。爱的是它省成本、降延迟，恨的是配置不当会拿到过时结果。litellm的缓存思路比较清晰：你可以按请求内容做完全相同的幂等缓存，也可以设置缓存过期时间。最简单的理解就是同一段messages进来，缓存里有就直接返回，不重复打模型。

配置缓存相当简单。本地缓存适合单机部署：

cache: true

如果要支持多节点网关共享缓存，上Redis：

cache: type: redis host: localhost port: 6379 ttl: 3600

这里的ttl单位是秒，3600就是1小时。我在配置的时候会刻意区分场景：如果是产品介绍、固定规则说明这类短时间不变的问答，可以设置较长ttl；但如果是实时数据查询、需要个性化回答的场景，干脆就不要开缓存，或者把ttl压得非常短，比如30秒。否则用户问一句“今天天气怎么样”，你会把一个小时前的晴天答案缓存给他。

还有一个容易被忽略的细节：缓存键默认包含完整请求内容。如果请求参数里带了随机数、时间戳这类动态字段，每次键值都不同，缓存命中率会接近于零。排查缓存不生效时，先看请求内容是否每次都完全一致。

3.3 预算管理、速率限制与成本追踪

预算控制是我认为litellm最值得长期使用的功能点之一。它内置了max_budget参数，可以为整个网关、某个团队、某个虚拟密钥分别设置预算上限。达到阈值后的表现可以配置为直接拒绝请求，也可以只记日志不阻断，方便你做灰度观察。做一个最小示例：

general_settings: master_key: sk-master-key max_budget: 100 budget_duration: 30d

这段配置的意思是网关整体30天内的模型调用预算上限为100元，一旦快用完，后续请求会被拦下来。这种硬性约束对防止失控调用特别有用，尤其是你开放API给多个团队使用时，能避免某个试验脚本一晚上烧掉半个月预算的情况。

速率限制同理。litellm支持配置每分钟请求数rpm和每分钟Token数tpm：

model_list: - model_name: support-bot litellm_params: model: provider_a/fast-chat-model api_key: os.environ/PROVIDER_A_API_KEY rpm: 60 tpm: 100000

这里rpm是每分钟最多60次请求，tpm是每分钟最多10万Token。一旦超出限额，网关返回限流错误，不会真的把请求打到服务商那里，既保护了服务商侧的配额，也避免业务方无感知地拖垮依赖接口。

至于成本追踪，litellm默认会把每次请求的花费记录到本地数据库。你可以在管理界面或日志里看到每一次调用用的什么模型、输入输出各多少Token、花了多少钱。这种细粒度数据哪怕不用来管控，光是月底出个报表给财务就很省心。

3.4 流式输出与超时控制

大模型回答通常很长，如果等完整结果一次性返回，用户会盯着一个转圈圈好几秒。流式输出是提升体验的标配做法。在代理模式下，业务端正常发HTTP请求，只要在请求体里加上stream参数：

{ "model": "support-bot", "stream": true, "messages": [{"role": "user", "content": "讲个短故事"}] }

网关就会以流式方式持续下发数据块，业务端一边收一边渲染，用户的感知就是“字在慢慢蹦出来”，比干等好几秒强得多。如果你用的是SSE协议，在客户端解析事件流时需要处理心跳包，这部分逻辑不能省，否则长连接容易因为空闲被中间网络设备断开。

超时控制是另一个容易被忽视的地方。不同服务商响应速度差异很大，有的几秒钟出结果，有的复杂推理模型需要先运筹帷幄三十秒。建议你针对不同模型分别设置超时时间，而不是全局一刀切。把首字节超时和整体超时分开理解：首字节超时关注的是请求发出去后多长时间没开始返回内容，整体超时关注的是整个对话最长允许跑多久。遇到“等了好久什么都没返回”的问题，先判断到底是一直没连接上，还是服务商正在思考但还没输出，两者处理策略完全不同。

4. 常见问题与排查实录：我踩过的那些坑怎么解

4.1 密钥配置不生效

这是新手遇到最多的问题，现象是请求报401或403，根本原因通常不是密钥错了，而是密钥没被正确读到。

排查思路很简单。如果你用SDK模式直接传了api_key参数，先确认这个参数确实传进去了；如果你用的是环境变量加载，先确认环境变量真的存在：

import os print(os.environ.get("PROVIDER_A_API_KEY"))

如果是代理模式，检查config里是不是写了os.environ/PROVIDER_A_API_KEY，但启动litellm的终端里并没有导出这个变量。记住一句话：进程读环境变量的时间是启动那一刻，你改完系统环境变量后必须重启网关进程，不是刷新页面就行的。

还有一个容易被忽略的情况：账户层面没有余额或权限不足。密钥格式看着没问题，请求也成功鉴权了，但对方服务商会返回一个额度不足或模型无权限的错误。这种问题从报错信息上很容易误解成密钥问题，实际上去服务商控制台看一眼就明白了。

4.2 模型标识写错

模型路由不到目标服务商、404找不到模型、或者返回了完全不是你预期的那款模型，大概率是模型标识写错了。

litellm的模型名格式是服务商前缀+斜杠+模型标识。前缀对应服务商适配器，这部分属于固定的路由信息；斜杠后面的部分必须和服务商文档页面里的模型名称完全一致。这里的大小写、点号、连字符、版本号都算作名称的一部分，差一个字符就找不到。

我自己的习惯是：每接一个模型服务商，先去服务商的控制台看一次能用哪些模型，而不是凭记忆或旧文档写。模型服务商经常更新模型标识，旧标识可能保留但不再对新用户开放。如果发现请求返回模型不存在，打开debug日志，网关会把它最终拼出来的模型名称打印出来，对照一下官方页面便知是否一致。

4.3 网关超时、并发处理不当

代理模式跑起来之后，另一个高频问题是网关自身超时或崩溃。这里要先想清楚瓶颈在哪。如果是你的业务服务并发太高，每个请求都要经过网关转发，网关进程自身可能成为瓶颈。这时可以在部署层面做水平扩展——litellm网关是无状态的，前面挂负载均衡器，后面多开几个实例。

如果某个模型服务商响应特别慢，占满了网关节点的连接池，其他请求全被堵住，就得在模型配置里单独给它设置更短的超时时间，同时把这类慢模型和快模型放在不同的网关实例上隔离。这有点像厨房里炒菜：一个灶台能同时开三道菜，但其中一道特别慢，三道一起堵着，其他桌全饿着。给慢菜配一个单独的灶台是最直接的解法。

4.4 日志、监控与debug模式

线上环境最忌讳“黑盒运行”。litellm提供了比较详细的日志能力，你可以设置环境变量打开debug日志：

export LITELLM_LOG=DEBUG

开启之后，网关会打印每一次请求的路由去向、模型映射、缓存命中情况、Token花费等细节。问题排查时看日志是第一动作，不要凭感觉猜。

如果团队已经有一套日志聚合和监控告警体系，建议把网关注入其中，重点盯几个指标：请求成功率、平均和P95延迟、缓存命中率、预算消耗速度。这几个指标能让你在服务商侧出问题之前就提前感受到异常。我见过太多团队只在出故障后才去翻网关日志，其实这些问题在指标曲线上早就该被预警了。

5. 实战心得与个人建议：我现在的用法和想叮嘱的事

5.1 先小范围试点，再平滑切换到代理模式

如果你正打算在项目里用litellm，我的建议是别一上来就搞大动作。先用SDK模式把一个低风险模块接进去，比如某个内部工具的后台问答，把调用链路跑通，观察几天日志和费用数据。这个小试点能帮你确认模型映射、密钥配置、返回解析这些基础环节都没问题。

试点稳定之后，再上代理模式。配置可以复用，只需把原来代码里的模型请求地址指向本地网关接口。切换时可以把流量按比例放量：先让10%的请求走网关，确认稳定后再逐步提高到100%，整个过程业务无感，也方便回滚。

5.2 什么时候值得上统一网关

我个人的判断标准很简单：如果你只需要固定调用一个模型，而且没有成本分摊、限流、多人共享这些诉求，那直接用官方SDK就行，不需要引入额外组件。一旦出现下面任一情况，就值得上litellm这类网关：

• 项目里同时接了两家以上模型服务商，或者准备随时切换
• 多个团队或服务共享同一批模型密钥，需要分租户管理
• 需要对模型调用做月度预算控制，防止费用失控
• 想给模型层加缓存、重试、限流，但又不想在每个服务里重复实现

技术选型最怕的不是多引入一个工具，而是为一个用不上的功能付出不必要的维护成本。litellm能不能带来收益，关键看你的团队是否真的面临上述问题。

5.3 一个小技巧：用模型名切换做AB对比测试

最后分享一个我自己经常用的小技巧。做模型选型时，不要写两套代码去分别调不同服务商，用litellm只需改一个配置里的model_name映射即可。同一套业务代码、同样的输入问题，把fast-chat-model从模型A切到模型B，侧面验证一下模型B的效果。因为业务代码根本不关心底层用的是什么，它只认识别名，所以你可以在一天之内完成多种模型的对比测试，把结果记录下来再决定保留哪个。

这招对产品经理尤其友好。他们想试试新模型在业务里的效果，不再需要拉着研发改代码、发版本，研发在网关配置里加一行映射就完事了。把模型当配置项来管理，而不是当代码逻辑来管理，是我用litellm过程中最大的感受转变。