litellm这个名字，如果你这两年在搞AI应用开发，应该不陌生。我第一次注意到它，是因为要在一个内部项目里同时接入三家不同厂商的模型服务，结果发现每家SDK的调用方式、消息格式、错误码都各不相同，代码里光是适配层就写了一百多行，而且每次切换模型还要改业务逻辑。后来我意识到，这种问题的根源不是某家SDK写得不好，而是你的应用缺少一个统一的模型接入层。
litellm做的事情，简单说就是把这层适配工作全部抽出来：它用一套规范的调用格式去对接上百家LLM服务商的接口，对外暴露兼容OpenAI风格的API，让应用代码里只需要关注业务，不需要关心底层模型到底是谁家的。这篇文章我会把自己在实际项目里从接入、切换、限流到部署网关的完整过程拆开讲，里面包含具体的代码片段、配置参数，还有一些踩过之后才知道的坑，希望对正在纠结模型接入方案的朋友有帮助。
1. 为什么我最终选择用litellm统一管理模型调用
先聊聊背景。一个月前，团队接到一个需求：公司内部的知识库问答助手要升级，不仅要用原来那家模型服务商A，还要同时支持服务商B和服务商C的模型，因为不同模型在不同类型的任务上表现不一样——有的擅长长文本理解，有的代码生成质量更高。按理说，这种“多模型接入”的需求在现在的LLM应用里很常见，但真正落到代码里，你会发现事情并不简单。
服务商A的SDK是一套对象风格的调用方式，消息体里要求传messages数组、temperature参数；服务商B走的是REST风格，参数名又不一样，流式输出的格式甚至带了一层额外的包装；服务商C干脆连系统提示词的处理方式都不同。更要命的是，它们的错误码体系完全独立，超时时间、重试策略、速率限制也各有各的脾气。如果直接在业务代码里写三套调用逻辑，初期看起来还行，但后续一旦要加第四家、第五家，或者要上线一个统一的重试策略，维护成本会迅速失控。
我用litellm的核心原因就是看中了它“抽象层”的定位。它不是替你选某个模型，而是把“模型调用这个动作”本身标准化。你只需要记住一套参数格式，剩下的厂商差异——包括prompt模板组装、模型名映射、鉴权方式、流式返回格式转换——全部交给它在内部处理。官方支持的服务商数量非常多，从主流的几家大模型厂商到各类开源模型托管的服务商都有覆盖，这一点在后续扩展时尤其占优势。
另外一个实用原因是litellm的接口风格和OpenAI官方SDK高度一致。这意味着如果你以前写过OpenAI的调用，几乎不需要重新学习，只要把base_url或者api_key换成litellm网关的地址，原来的代码就能跑。对于团队里其他成员来说，上手成本极低，不需要每个人重新读一遍新SDK文档。
2. 一小时跑通核心调用链路
2.1 安装与首个调用Demo
既然目标是实用，先不讲太多理论，直接演示一个可运行的调用。litellm的安装非常简单，Python环境里直接：
pip install litellm如果你用的是Node.js技术栈，官方也提供了对应的SDK包，调用风格基本一致。我个人项目里主要用Python版本，所以下面示例都基于Python。
装完之后，最简单的调用长这样：
import litellm # 以调用某厂商的对话模型为例 response = litellm.completion( model="gpt-4o-mini", # 这里的模型名，使用litellm定义的统一名称 messages=[ {"role": "system", "content": "你是一个知识库问答助手，回答请简洁准确。"}, {"role": "user", "content": "用一句话解释什么是API网关"} ], temperature=0.2 ) print(response.choices[0].message.content)这段代码和OpenAI官方的写法几乎一样，唯一的区别是引入了litellm，而且model字段的取值空间大幅扩展了——如果你把model换成claude-3-5-sonnet，再把环境变量里的密钥换成对应服务商的密钥，代码其他部分什么都不用改，就能调用另一家服务商的模型。这个“只改一个字段就能换模型”的效果，正是我想要的。
如果你的代码里已经全局设置了OpenAI的API Key，类似：
litellm.openai_api_key = "你的密钥"那么连api_key参数都可以省略。当然，在实际项目中我更推荐用环境变量的方式管理密钥，而不是硬编码在代码文件里。
2.2 流式输出和异步调用的正确处理方式
大部分真实场景下，用户希望看到token逐个蹦出来，而不是等十几秒后一次性收到全部结果，所以流式输出是必须支持的。litellm的流式调用和OpenAINative接口差别也不大：
response = litellm.completion( model="gpt-4o-mini", messages=[{"role": "user", "content": "写一段300字左右的短文，关于海边的早晨。"}], stream=True ) for part in response: delta = part.choices[0].delta.content if delta: print(delta, end="", flush=True)对于需要并发的场景——比如你的服务同时处理多个用户的请求——建议使用异步接口：
import asyncio import litellm async def call_model(user_message): response = await litellm.acompletion( model="gpt-4o-mini", messages=[{"role": "user", "content": user_message}] ) return response.choices[0].message.content async def main(): results = await asyncio.gather( call_model("你好"), call_model("介绍一下你自己"), call_model("今天天气如何") ) print(results) asyncio.run(main())我测试过在同一个进程里跑上百个异步请求，吞吐表现不错，也没遇到线程安全问题。有一点要提醒：如果在gather里同时调用不同服务商的模型，请确保各自的API密钥都已在环境变量里正确配置，否则某个请求会抛认证错误。
2.3 响应格式统一的背后逻辑
很多人第一次用litellm会留意到一个细节：无论底层是哪个服务商的模型，返回结构看起来都差不多，都是choices数组、message.content、usage.prompt_tokens这些字段。这种统一并不是巧合，而是框架在内部做了响应标准化。
具体来说，各家模型的返回格式确实有差异。有的服务商默认把内容放在candidates字段里，有的把token统计放在单独的响应头里，还有的流式消息要拼接多个事件才能得到完整内容。litellm的做法是，在拿到原始响应之后做一层映射，把不同厂商的不同字段统一转换成一棵符合规范的响应树。这样做的好处是：上层业务代码不需要为每个厂商写一个解析器，出问题的时候排查路径也是单条的。
不过在使用中也要理解，标准化针对的是常见字段。如果某个模型发布了独有的新特性（比如某种推理过程字段、某种特殊的工具调用元数据），而这些字段没有纳入通用的响应结构，你可能仍然需要从原始返回里取值。litellm通常会把原始响应中的一部分信息保留，必要时可以直接读取response.choices[0].message里额外的属性。
3. 从“能跑”到“好用”：模型切换、路由与容错
3.1 只改一个字段真的能切换模型吗
前面说“只改model字段就能换模型”，这句话在实际使用中要稍微兜个底：切换模型后，确实不需要改调用结构，但你要对目标模型的参数习惯有基本认知。比如某个模型对temperature范围限制比较严格，你把0.8传给了一个只支持0到0.5的模型，虽然服务商不一定会报错，但生成效果可能就不是你预期的。又比如有的模型原生支持response_format加固，有的并不支持，强行传参在某些服务商那里会返回参数无效的异常。
所以我的习惯是：每个模型的参数设置单独抽成一份配置，放在一个字典里，按模型名索引。切换模型时，对应切换整套参数，而不是只换一个名字。litellm在这块也提供了可选的自定义参数透传，你可以通过additional_parameters把厂商特有的参数传进去。框架尽量做到通用，但具体模型的“个性”，还是要使用方自己管理。
3.2 失败重试与回退机制
现实生产环境里，没有哪家服务商敢说自己100%稳定。我们遇到比较多的情况是：请求超时、限流返回429、临时过载返回5xx。如果代码不做容错，一次抖动就会让用户看到一个刺眼的报错页。
litellm原生支持fallback参数。它的思路是：指定一批备用模型，当主模型调用失败时，自动把请求转给备用模型。示例：
import litellm # 定义一个回退列表 fallback_list = [ "gpt-4o-mini", "claude-3-5-haiku", "gemini-1.5-flash" ] # 主要调用某个模型，失败时按顺序尝试备用 response = litellm.completion( model="gpt-4o", messages=[{"role": "user", "content": "介绍一下量子计算的基本概念。"}], fallbacks=fallback_list )使用fallbacks之后，主模型正常时一切照旧；主模型不可用时，框架会自动尝试列表中下一个可用的模型。这里有一个细节：回退条件默认针对特定类型的异常（连接错误、超时、限流等）。如果你调用时传入了非法参数导致校验类错误，这类错误不会触发回退，因为它不是“服务不可用”的问题，而是“请求本身有问题”，重试另一家模型也一样会失败。
需要特别说明一点：fallbacks这个参数的具体可用形式可能随版本更新而调整，我第一次使用时翻了不少文档才确认当前版本的正确写法。建议无论在哪个版本下，都先在一个测试脚本里验证一下主模型不可用时回退是否真的生效，而不是直接相信配置写完就万事大吉。
3.3 负载均衡与本地模型优先策略
当一个项目的请求量上来之后，单一路由就不够用了。litellm可以在代理模式下配置多个同样的模型实例，并把请求分发到不同的上游。它内置了多种路由策略，常见的有：
simple-shuffle：在健康实例之间随机选择。least-busy：选择当前排队请求数最少的实例。usage-based-routing：按模型的花费/速率限制进行估算后分配。
如果你同时接了云端API和本地部署的开源模型，也可以把“本地模型优先”作为一种降本策略：请求先走本地实例，本地压力过大或服务不可用时再转向云端。这种混合路由在成本预算敏感的项目里价值很高，因为本地模型的单次请求成本接近于零，只是需要维护硬件资源和管理推理服务。
4. 把每一笔费用和令牌数都算明白
4.1 为什么要关心token级别的统计
LLM调用和普通HTTP接口不一样：你没法提前精确知道一次请求要花多少钱，因为费用取决于模型、输入token数、输出token数以及缓存命中情况。如果不做记录，月底看到账单的那一刻往往是最刺激的。
litellm在每次调用后都会返回usage对象，里面包含prompt_tokens、completion_tokens、total_tokens这样的基础数据。此外，它还有一个非常有用的能力：通过callbacks把每次调用的耗时、token数、费用估算推送到自己的日志系统或者监控服务。
比如我需要把调用记录打进自定义的美化日志里，可以这样注册回调：
import litellm def my_usage_callback(user_model, user_messages, response, *args, **kwargs): usage = response.get("usage") or {} cost = litellm.completion_cost( model=response.get("model", ""), prompt_tokens=usage.get("prompt_tokens", 0), completion_tokens=usage.get("completion_tokens", 0) ) print(f"模型: {user_model} | 输入token: {usage.get('prompt_tokens')} | 输出token: {usage.get('completion_tokens')} | 估算费用: ${cost}") litellm.success_callback = [my_usage_callback]这里用到了litellm.completion_cost()这个方法，它内部维护了不同模型的价格表，能根据token数估算花费。对于支持的模型，估算结果基本能和大盘账单对得上。
4.2 防止预算失控的两个硬手段
第一是令牌数上限。模型本身有上下文窗口上限，但我们应在代码层再设一层自己的上限。litellm请求时可以设置max_tokens，控制单次输出的最大token数，避免因为一个异常指令导致模型一直生成直到把额度耗尽。
第二是总体预算封顶。litellm的代理模式支持设置预算字段，比如按虚拟密钥维度限制一个项目一个月的最高消耗，超过之后网关直接拒绝新请求。团队里给不同业务线发不同key时，这种管控尤其有用。每个人看到自己的额度提醒，自己心里有数。
4.3 缓冲、缓存与重复请求的省钱套路
在成本敏感的场景下，个人建议把“语义缓存”也一并考虑。如果频繁请求相似的查询，比如很多人问知识库里的同一个问题，每次都完整走一遍模型推理，既慢又贵。可以先在前置层做一次向量相似检索，如果已经存在高度相似的历史问答，直接返回缓存结果，不触发模型调用。litellm本身也有基于精确匹配的缓存能力，但业务层的语义缓存通常效果更明显，因为用户问法再怎么变，意思类似的还是挺多的。
5. 团队协作阶段：把它部署成一个代理网关
5.1 为什么需要网关而非直连SDK
当项目进入稳定期，并且是多人协作开发时，继续让每个开发者在代码里直接调litellm的Python包就不太合适了。原因有三点：一是不同服务商的密钥散落在各人本地环境里，管理混乱；二是调用记录散落在各台开发机上，没法统一追溯；三是如果有人误写了循环调用，直接把预算刷爆，你可能直到月底对账时才发现。
litellm的解决方案是启动一个代理服务，它本身是一个独立的HTTP服务，运行在服务器上。开发者客户端只需要把base_url指向这个网关，把api_key换成网关下发的虚拟Key，代码里甚至不需要安装litellm——直接使用任何兼容OpenAI风格的SDK即可。
5.2 用一条命令启动服务
启动代理网关非常轻量，本地测试只需要：
litellm --model gpt-4o-mini --port 4000但实际项目里我更推荐用配置文件的方式，因为模型列表、密钥、路由策略、预算限制都可以集中写在配置里，方便走版本管理。一个简化版配置长这样：
model_list: - model_name: gpt-4o-mini litellm_params: model: gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: claude-3-5-sonnet litellm_params: model: claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY litellm_settings: drop_params: true set_verbose: true general_settings: master_key: sk-网关主密钥 database_url: postgresql://user:password@localhost/litellm_tracing然后启动：
litellm --config ./config.yaml网关起来之后，团队里的成员拿一个虚拟Key，把代码里的base_url指向http://服务器IP:4000，就能开始用了。原来的业务代码不用大改，这一点让很多同事觉得很省事。网关内部会做密钥代管、token统计、请求日志和预算限制，相当于把之前散落在各处的关注点集中到了一处。
5.3 生产部署时的几个补充点
生产环境部署网关时，我习惯再检查三件事：
- 数据库配置：如果要在网关层持久化调用日志和虚拟密钥数据，需要提前准备一个PostgreSQL之类的数据库，而不是用默认的本地存储。生产环境重启服务器太常见了，状态不能丢。
- 身份认证：网关本身有
master_key用来管理下游虚拟密钥。要确保这个master key足够复杂，最好由密钥管理系统生成和存储。 - 健康检查与监控：给网关单独配一个健康检查接口，并入现有的监控告警体系。网关一旦出问题，所有模型请求都会挂，这个事实要在架构设计里被严肃对待。
跑通网关之后，团队里基本可以做到：新业务接入AI能力时只申请一个虚拟Key，后端开发和模型供应商完全解耦。后续某个模型涨价或下线，只需要在网关配置里修改对应条目，业务侧无感切换。
6. 实际开发中容易被忽略的几个细节与坑
6.1 关于“模型名支持范围”的想当然
这是我初期最容易踩的坑：看到文档里写着“支持各大服务商模型”，就以为任何模型名都默认支持。实际上litellm的模型名映射规则比较严谨，你在配置文件里写的model_name是别名，真正的模型名要和上游服务商的模型标识精确匹配。
遇到modelnot found或Invalid model这类报错时，不要只怀疑网络或密钥，先去核对一下模型名是否完全一致、版本号是否还可用。我在一次排查时浪费了不少时间，最后发现问题只是服务商把某一个旧模型标识下线了。框架不会替你修正拼写，它只会照原样传给上游。
6.2 超时和重试参数的“厂商差异”
不同服务商对超时报错的反应差别很大。有些公共云模型在高峰期排队可能长达几分钟，一旦客户端提前断开了连接，服务端可能还会继续计费；有些服务商则是快速失败风格，几秒内就返回429。我在一次线上事故中发现，统一设置60秒超时对A厂商没问题，但对B厂商就很尴尬——B厂商正常响应是40秒，但偶发排队时要90秒，导致频繁超时。
建议的做法是：在网关路由配置里，对不同模型设置不同的timeout和max_retries，不要图省事一把梭。判断超时的首要标准不是“大家都这么设”，而是“这个模型服务商分位响应时间是多少”。
6.3 流式响应的完整性校验
流式响应好用，但也更容易出怪问题。我遇到过一种情况：请求成功返回了，流也确实推完了，但业务侧发现内容不完整——最后几个字被截掉了。排查的时候发现，是代理层提前判定了流结束，而底层的最终内容事件还没处理完。
当时解决问题的思路是：测试时把所有流式事件打印出来，观察是否存在finish_reason和预期不符的现象。如果经常出现截断，可以考虑在业务环节对内容格式做一次结束标记校验，或者调大空闲超时时间。这个坑不一定每个人都会踩，但一旦踩到，很不好查，因为服务商侧看起来一切正常。
6.4 不要忽略输入侧的“长度压缩”策略
最后提一个容易被忽略的成本策略：请求文本越长，token消耗越贵，这大家都懂。但实际做的时候很多团队并没有把“压缩用户输入”当成一个优化点。例如知识库助手场景里，用户粘贴一大段文档进来，很多内容其实是噪音。我们后来加了轻量的前置摘要模块，过长输入先让一个小模型做关键信息抽取，再喂给主模型，成本降了大约三成，对最终回答质量影响很小。这个思路虽然和litellm本身功能无关，但既然做模型接入，控制输入规模这件事值得同时考虑。
最后再分享一个小经验：框架类工具更新速度普遍快，litellm的版本迭代尤其频繁，每次升级大版本前，一定要先看变更日志。有些配置参数是旧的沿用，有些则是悄悄废弃或改名。我踩过几次升级后配置不生效的坑，后来定了一个规矩：生产环境锁定版本号，测试环境确认新版本没问题后再统一升级。工具再强大，管理手段也得跟上，这套组合用下来，项目在模型接入层的稳定性一直保持在可控范围内。
