litellm：大模型统一接入层，一套API搞定多模型切换

最近这半年，我一直在折腾自己维护的AI应用项目，折腾来折腾去发现最耗时的不是模型选型，而是模型接口对接。今天想认真聊聊我最后定下来的方案：litellm。它可以理解成一个大模型调用的统一接入层——既能让你在代码里用一套API切换多家模型服务，也能部署成独立网关给整个团队共用，顺带把超时、重试、缓存、成本统计这些脏活一起接了。如果你和我一样不想在每家模型服务商之间来回改代码，或者正在给团队规划统一模型入口，这篇文章应该值得你花几分钟看完。

1. 为什么说模型接入层是后端项目的隐形债

1.1 各家模型API表面上相似，实际处处是坑

很多刚开始接大模型API的同学会觉得，不就是拼个prompt、发个HTTP请求、解析返回结果吗？真到了生产环境，事情远没有这么简单。我当初做过一个内部的知识库问答功能，最初只用了A厂商的接口，后来因为效果和成本原因想换成B厂商，结果一改就是大半天：请求路径不一样，鉴权header不一样，消息里system、user、assistant的字段拼法不一样，连流式返回的格式都不同。最头疼的是错误码，A家429代表限流，B家429可能只是"暂时繁忙"，C家失败时返回200但body里带一个error字段，不仔细读body根本发现不了。

这些差异的杀伤力在平时看不出来，一旦遇到上游服务不稳定、需要快速切换供应商的时候，就会变成灾难。我见过一个同事在线上紧急切模型，因为忘了改stop参数的字段名，生成结果里全是截断的碎句子，用户反馈直接炸了。技术债就是这样一点点累积起来的——每个模型服务商都像一套方言，光靠复制粘贴终究要还的。

1.2 litellm真正做的事：把"方言"翻译成"普通话"

litellm本质上是一个翻译层，它把所有主流大模型API的请求和响应统一成一种规范格式。你可以把它想象成一个万能遥控器，各家电视的按键逻辑不一样，但它用一个面板帮你搞定；也可以理解成电源转换头，欧洲、英标、美标插头都能接你的设备。

它在两种场景下工作：第一是作为Python库，直接在代码里调用，适合单个服务内部使用；第二是作为代理网关，起一个独立服务，把内部统一接口再转发给各个模型厂商，适合团队或多服务共享。无论哪种模式，对外暴露的格式基本一致，这带来的好处是：业务代码只需要写一次，后面换模型只是换一个字符串的事。

1.3 它在模型生态里的确切位置

要理解litellm，得先分清它不是什么。它不训练模型，不托管数据，不负责生成内容，也不绑定某个特定厂商。它处在"上层业务应用"和"底层模型服务商API"之间，是一个纯粹的桥接层。当前它支持的模型数量非常多，覆盖了主流闭源模型、开源模型、多模态模型和各家云平台托管模型。你甚至可以用它对接本地部署的推理服务，只要目标服务提供兼容的HTTP接口就行。所以从架构视角看，litellm扮演的是服务网关+协议适配器这两个角色，而不是一个模型商店。

2. 最基础的用法：在代码里把litellm当成统一SDK用

2.1 安装和第一个请求

litellm的安装非常简单，一个pip命令搞定：

pip install litellm

装好之后，直接import进来就能用。下面是最简单的一个调用：

import os from litellm import completion os.environ["ANTHROPIC_API_KEY"] = "你的Claude风格接口密钥" response = completion( model="claude-3-5-sonnet-20241022", messages=[ {"role": "system", "content": "你是一个简洁的助手。"}, {"role": "user", "content": "用一句话解释什么是消息队列。"} ], temperature=0.7, ) print(response.choices[0].message.content) print(response.usage)

我在第一次使用的时候，最大的感受是"这不就是OpenAI SDK吗"。它返回的response.choices[0].message.content结构、usage字段里的token统计，还有model字段，都是大家熟悉的那套风格。也就是说，如果你项目里已经把OpenAI兼容格式的调用写好了，换成litellm的改动成本接近于零。

2.2 model参数才是最容易出错的地方

litellm的model参数看起来是一个字符串，但这里藏着整篇文章最关键的规则：建议写成厂商名/模型名的格式，例如anthropic/claude-3-5-sonnet-20241022、openai/gpt-4o-mini、gemini/gemini-1.5-pro。如果你只写模型名，litellm会靠内部映射去猜厂商，猜错的时候请求会打到错误的服务上，返回的报错信息容易让人摸不着头脑。

我踩过一次这样的坑：当时写model="gpt-4o-mini"没问题，后来换成某个开源模型，直接写了不带前缀的模型名，结果litellm把它识别成了另一家服务商的同名模型，白白消耗了调次数。所以从第一天开始就养成写完整前缀的习惯，能省掉后面大量排查时间。

2.3 通用参数是怎么被翻译到各家平台的

不同服务商的参数名称和语义并不统一，litellm会在内部做映射。比如统一传入max_tokens，它会自动转换成Claude风格接口需要的max_tokens_to_sample，也会转换成其他厂商内部对应的字段。常用的映射对照如下：

这个映射机制看着简单，实际很关键。比如stop参数，有些平台要求字符串，有些平台要求数组，litellm会自动归一化。如果你在业务代码里全是统一写法，将来换供应商时，就不用在每个分发逻辑里再补一次参数转换。

2.4 异常体系也是统一过的

比参数映射更重要的是异常处理。各家API的失败返回差异很大，有返回HTTP 200但业务错误的，有抛出JSON解析异常的，还有在流式传输一半时断开的。litellm把常见的失败场景整理成了一套Python异常，比如AuthenticationError、RateLimitError、TimeoutError、APIError等。所以业务代码里可以放心地做统一捕获：

from litellm.exceptions import RateLimitError, TimeoutError try: response = completion(model="...", messages=messages) except RateLimitError: # 走限流后的降级策略 pass except TimeoutError: # 改走备选模型 pass

这一点在写重试和降级逻辑的时候特别舒服，不用为每个厂商写一套错误判断分支。

3. 流式、超时、重试：调用大模型前必须想清楚的三件事

3.1 流式输出也要用统一方式处理

聊天类应用基本都会用流式，因为用户等不了一个模型把整段话生成完。litellm对流式的处理非常友好，开启方式就是在参数里加stream=True：

response = completion( model="claude-3-5-sonnet-20241022", messages=messages, stream=True, ) for chunk in response: delta = chunk.choices[0].delta.content if delta: print(delta, end="", flush=True)

我实际用下来发现，不同厂商的流式行为差异比非流式更大：有的厂商会先发一个空的meta包，有的在结束时发[DONE]标记，有的发完内容还会多发一个空块。litellm帮你把这些差异都消化掉了，外层拿到的永远是比较规整的OpenAI风格的chunk。如果你是自己手写适配层，这种细节很容易漏，而且漏一次就是一次线上事故。

3.2 超时和重试的推荐配置

大模型接口天然比普通HTTP接口慢，所以超时设置不能照搬后端常规经验。我的建议是给litellm设置一个全局请求超时，再配合少量重试：

import litellm litellm.timeout = 60 # 总请求超时 litellm.num_retries = 3 litellm.retry_policy = { "timeout": True, "429": True, "500": True, "503": True, }

经验数据是这样的：连接阶段超时给10秒左右，因为网络问题通常会在连接期暴露；生成阶段则要看业务，一般30到120秒比较合理。重试一定要用指数退避，比如第一次等1秒，第二次等2秒，第三次等4秒。我见过有人把重试调成固定1秒连打，结果上游限流还没恢复，反而把429打得更严重了。

此外要注意400错误不要重试，那是参数问题，重试一百万次也不会成功；可以重试的是409、429、500、503这些服务端或限流性质的错误。

3.3 token和成本控制要在一开始就做

很多人只关心"调用成功没有"，不关心一次调用烧了多少钱。但模型应用上生产之后，最大的意外往往来自成本失控。litellm提供了一套成本计算方法，能根据模型参数和用量直接算出费用：

from litellm import completion, completion_cost response = completion(model="gpt-4o-mini", messages=messages) cost = completion_cost(completion_response=response) print(f"这次调用消耗: ${cost}")

不过光算账还不够，必须从源头控制。我强烈建议所有调用都显式传入max_tokens，否则部分服务商的默认生成上限非常宽松，一次长对话可能产生巨额费用。我的做法是先用小流量测出常见的输出长度分布，取P95再加一点余量，把它设成max_tokens。这样既不会频繁截断，也不会给成本失控留口子。

4. 把litellm跑成团队网关：配置、路由与多租户

4.1 为什么业务多了之后要上独立网关

如果只是自己一个服务在用，直接用SDK模式就够了。但当团队里同时有三四个服务都在调大模型，每个服务各自配密钥、各自写一套调用逻辑时，问题就来了：密钥散落在各个机器上，数据量和费用没法统一统计，要切换某个模型得通知所有人改代码。这时候把litellm部署成一个独立的代理服务，业务方谁都不用管密钥和供应商，只需要请求网关暴露的统一接口，我这边统一管理路由、限流和审计，省心非常多。

网关模式的另一个好处是，业务方完全不用装litellm的Python包，因为网关暴露的是一个OpenAI兼容的HTTP端点，任何语言只要会发HTTP请求就能用。这相当于把模型接入能力做成了团队内的一种基础设施。

4.2 一份能直接跑起来的最小配置文件

litellm网关的玩法是配置文件驱动，官方默认读取config.yaml。我先给出一份最小可用的配置：

model_list: - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: claude-3-5-sonnet litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY max_tokens: 4096 litellm_settings: num_retries: 3 request_timeout: 60 general_settings: master_key: sk-master-123456

启动命令更简单：

litellm --config ./config.yaml --port 4000

启动之后，网关默认监听4000端口，暴露的地址是http://localhost:4000/v1/chat/completions，请求格式完全兼容OpenAI。这里要解释一下配置文件里的关键逻辑：model_name是给客户端看的别名，客户端请求里带model: gpt-4o-mini；litellm_params里的model才是真正要打到哪个厂商哪个模型，两者可以是完全不同的名字。general_settings里的master_key是管理员密钥，后面管理虚拟key会用到。

4.3 路由策略与多模型降级

同一个model_name底下可以挂多个litellm_params，比如挂两家不同的模型服务，实现负载均衡和自动容错。效果上就是，同一个模型别名，请求会轮流打到不同后端，某个平台挂了，网关会把流量自动切到另一个可用的后端上。

配置一个带权重和备选模型的路由也很直观：

model_list: - model_name: chat-main litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY model_info: mode: default weight: 7 - model_name: chat-main litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY model_info: mode: fallback weight: 3

这样配置后，主请求走便宜的gpt-4o-mini，当主请求连续失败时，部分流量会切到更强的gpt-4o作为兜底。要注意的是，故障转移不等于把num_retries加到很大，重试只能解决瞬时抖动，真正该做的是不同后端之间的快速切换。我在生产里一般把单后端的重试控制在1到2次，剩下的交给fallback逻辑。

4.4 虚拟key、预算和团队隔离

网关模式下最重要的管理能力是虚拟key。master key不适合发给所有业务方，应该用它去创建一批带限额的虚拟key，每个业务线一把。用curl就能生成：

curl --location --request POST 'http://localhost:4000/key/generate' \ --header 'Authorization: Bearer sk-master-123456' \ --header 'Content-Type: application/json' \ --data '{ "models": ["gpt-4o-mini"], "max_budget": 100, "info": {"team": "search-service"} }'

返回结果里会带一串新的虚拟key，把它交给对应团队使用。虚拟key可以做三件很实用的事：限定能用哪些模型、限定预算上限、限定每分钟请求数。这样多团队共用网关时，不会出现一个团队把预算烧完导致另一个团队不可用的情况。

我想额外提醒的一点是：预算统计通常不是实时的，它是按每次调用完成后回写用量来累积的，所以不要把它当成银行账户来依赖，它是防止失控的护栏，不是精确到秒的计量系统。

5. 生产环境的真实坑：缓存、故障排查与避坑清单

5.1 响应缓存，省钱是表面，稳定才是核心

给重复请求加一层响应缓存，是litellm网关最实用的功能之一。配置里把它打开即可：

litellm_settings: cache: true cache_params: type: redis host: localhost port: 6379

表面上看，缓存最直接的效果是省钱，因为相同prompt不用反复调用付费模型。但我的体会是，缓存真正的价值是把高延迟接口变成了低延迟接口，尤其在模型服务商抖动的时候，命中缓存的请求完全不受影响，能扛住不少压力。缓存适合用在摘要生成、文本分类、信息抽取这种幂等场景；但聊天、多轮对话这类上下文相关的请求，不要全量开缓存，非常容易把上一个用户的内容返给下一个人，事故就是这么来的。

5.2 我经历的一次线上排查链路

有一回我们线上问答服务的成功率突然掉到92%，p99延迟从2秒涨到15秒。一开始业务方反馈"模型变慢了"，我接手排查后没有直接去看模型，而是先打开litellm的日志，按时间倒序看网关记录的错误类型。结果发现大量请求都在同一个后端模型上返回429限流，其他模型完全正常。

定位到这一步，我做了三件事：第一，确认所有失败请求都指向同一个下游供应商，并且时间窗口和对方服务状态页的公告吻合，基本断定是上游限流；第二，把核心链路的fallback参数临时切到另一个可用模型，让新流量走备选模型；第三，下调了该供应商对应虚拟key的每秒请求数，同时把重试间隔调大。半小时后成功率恢复到98%以上。

事后我总结出这个排查链路供参考：先看网关日志里的provider错误，确认失败的模型和错误码；再看限制是否集中在某个上游；最后决定是调路由策略还是做降级。litellm日志里的model字段会记录实际命中的后端模型，usage和cost字段能帮你判断影响面有多大，这些数据平时没什么存在感，出故障时就是救命的信息。

5.3 避坑清单，直接抄作业

5.4 网关层的高并发与连接池注意点

很多人在自测时一切正常，一上生产并发稍微高一点就开始大量超时，问题往往不在模型端，而在Python进程的HTTP连接池上。litellm默认会复用连接，但如果并发上来后连接池打满，新请求就要排队等连接释放，最终表现为timeout。遇到这种情况，先看网关的并发数是否接近默认连接上限，再决定是否需要调大连接池、增加网关实例，或者改用异步调用。

异步模式下，代码可以写成这样：

from litellm import Router router = Router(model_list=[{...}]) async def call_model(messages): response = await router.acompletion( model="chat-main", messages=messages, ) return response

异步配合网关部署，比同步阻塞式调用能扛的并发高不少。如果你们的并发量再往上走，就考虑在litellm网关前再挂一层负载均衡，把流量分散到多个网关实例上。

6. 从能用走向好用：生态定位与我的总体感受

6.1 和编排框架不是竞争关系

经常有人纠结"用了langchain还要不要用litellm"。我的理解是，这两个东西根本不在同一层：编排框架负责的是"把多个步骤串起来、决定何时调用工具、如何管理记忆"，而litellm负责的是"把一次模型调用发出去并拿回结果"。用编排框架完全不耽误同时用litellm，反而是一个合理的组合。我自己倾向于在编排框架内部把LLM客户端统一替换成litellm，这样既保留了框架的编排能力，又在模型切换这件事上保留了自由度。

6.2 对模型接入层的一些建议

如果你正在设计团队的模型接入层，我的建议是不用重复造轮子，但要在配置和监控上多花心思。配置文件建议纳入版本管理，模型切换要像发布代码一样走评审和灰度。同时在litellm网关前面接好监控，至少要看四个指标：请求量、成功率、延迟分位值、单次成本。这些数据平时不起眼，等要决策"是不是该换一家模型"的时候，它们就是你唯一的依据。

说到不重复造轮子，我也想说一下litellm的局限。它虽然覆盖的模型很多，但各家新出的独特功能往往需要一点时间才能支持，某些厂商自定义的response字段可能不会完整透传。所以在选型时要有个预期：它不是所有边缘功能都能100%覆盖，但作为主流场景的统一入口已经非常成熟。

6.3 我实际用下来的几点体感

用了一段时间之后，我对litellm最大的好感其实不是它"多好用"，而是它帮我省掉了"切换成本"。模型这个领域变化太快，今天效果最好的模型下个月可能就被超越，如果没有一个统一的接入层，每次技术选型更新都是一次伤筋动骨的迁移。有了它之后，换模型变成了改一行配置、跑一轮回归的事，团队里再也没有人因为"改模型调用"而加班到深夜了。

如果你现在也在为多模型接入头疼，我建议从最小的demo开始：先在自己的Python服务里试试SDK模式，把现在正在用的模型通过litellm调通；跑顺之后再考虑部署网关，用虚拟key分给团队测试。这个过程不需要一开始就设计得很宏大，先把"切换模型"这个最核心的价值拿到手，后面再逐步加缓存、预算和监控，你会发现整个模型调用链路会清爽很多。