2. 多模型切换的真实痛点：不引入LiteLLM之前我经历了什么
这两年LLM接入的项目做得多了，最让我头疼的从来不是某个模型本身的效果问题，而是API格式的差异。今天业务方说"换个模型试试"，听起来一句话的事，落到代码里就是重写一遍客户端、改鉴权方式、调参数映射、解决那些奇奇怪怪的报错字段。几个项目叠下来，我的代码库里堆了至少三套不同的SDK封装，维护成本越来越高。
直到我用上了LiteLLM，这个问题才算是被彻底解决。它的思路很直接：把几乎所有主流大模型厂商的API接口，统一转换成OpenAI风格的接口。也就是说，你只需要用OpenAI SDK的写法，就能调用Anthropic、Google、Azure、AWS Bedrock等等不同平台的模型，底层的格式差异全由LiteLLM帮你抹平。
这篇文章我就结合自己实际接入项目的经历，从痛点、安装、调用、部署到踩坑，完整捋一遍。适合谁看？正在做LLM应用开发、被多模型切换折磨过的开发者；想搭一个统一的模型网关供团队内部使用的后台工程师；以及技术上想搞明白"API统一层到底值不值得引入"的技术负责人。本文所有代码均基于常见的Python环境，LiteLLM当前主版本为v1.x，如果你拿到的版本更新，个别参数可能需要微调。
先说清楚一件事：LiteLLM不是用来"绕过"或"替换"各家模型的工具，它是站在你和大模型提供商之间的一层适配器。你要的模型能力还是来自各厂商，但你和厂商之间的对话方式，被LiteLLM规整成了同一套语言。这层"统一"的价值，在实际工程里远比你想象的大。
2.1 换一次模型重写一次客户端的日子
我给自己做过一个统计：最早做的一个问答机器人项目，最初只接了一家模型提供商的API。后来因为成本考虑要切换服务商，光是改造调用层就花了将近两天。不是改代码逻辑，而是改那些"看似简单但处处是坑"的接口差异。
举几个最典型的例子。各家超参数的名字完全不一样，有的叫temperature，有的叫top_p，还有的叫nu，同一个概念换个平台就换个叫法；鉴权方式更是各搞一套，有的是Bearer Token，有的是API-Key放在自定义Header里，有的要走签名流程；返回结构也天差地别，有的把对话内容嵌在好几层嵌套字段里，有的直接给你一个choices[0].message.content，你以为都是这样写的，结果换一家发现字段路径完全对不上。
更麻烦的是流式输出的格式。同样是打字机效果，有的平台输出data: {json}带特定前缀，有的平台直接吐字符串，有的还会在流中间插入心跳包。这些细枝末节一旦对接过，就知道有多浪费时间。每换一次模型，就要把这些坑重新踩一遍。
2.2 我一查，市面上还真没有更好的解法
被折腾几次之后，我认真找过替代方案。当时有几个思路：一个是自己写一层抽象接口，把所有厂商API都封装成自己的统一格式。想法挺好，但维护量巨大——厂商一更新接口，你就得跟着改。而且每家SDK的依赖冲突、版本兼容问题，都得自己扛。
另一个思路是直接用各厂商自家的SDK，然后在上层做适配。但这样代码里还是会混着各种SDK的调用方式，团队新成员上手成本高，排查问题时候也得在多个SDK文档之间来回跳。
LiteLLM能胜出的原因很简单：它把"适配"这个苦力活做成了标准化模块。你不必自己维护一堆适配器，也不必关心各家SDK的版本演进，LiteLLM社区在不断跟进更新。你只需要对着OpenAI风格的接口写代码，底层的事交给它。这对于小团队和独立开发者来说，省下的不是一点点功夫。
3. LiteLLM核心用法：从零开始用OpenAI写法调用各家模型
LiteLLM的用法几乎不需要额外学习成本。只要你会用OpenAI的Python SDK，你就能用LiteLLM调用几乎所有主流模型。它的设计哲学非常明确：把所有模型的调用方式收敛为OpenAI格式。
3.1 安装与环境准备
安装没什么特殊的，直接pip装就行：
pip install litellm如果你打算运行带UI的代理服务（后面会讲），可能还需要另外装一些额外依赖，比如用于密钥管理的数据库模块。具体看官方文档即可，我这里只讲最核心的用法。
装好之后，建议先验证一下是否正常：
python -c "import litellm; print(litellm.__version__)"能看到版本号就说明安装成功了。注意LiteLLM的版本更新很快，用最新版通常不会错，但升级前要留意breaking change，这个我在踩坑章节会细讲。
3.2 三步完成第一次跨模型调用
接下来是重头戏。假设我要用OpenAI的GPT模型，只需要这样：
import litellm response = litellm.completion( model="gpt-4o-mini", messages=[{"role": "user", "content": "你好，请介绍一下你自己"}] ) print(response.choices[0].message.content)熟悉吧？这就是OpenAI SDK的写法。那我要切换到Anthropic的Claude模型呢？只需要改model参数：
response = litellm.completion( model="claude-3-5-sonnet-20240620", messages=[{"role": "user", "content": "你好，请介绍一下你自己"}] )其他代码一行都不用动。这就是LiteLLM最吸引人的地方：业务层代码对模型是"无感"的。你今天用GPT，明天换Claude，后天换Gemini，调用层只需要改一个字符串。
当然，要使用各家模型，你得先在环境变量里配置好对应的API密钥。比如：
export OPENAI_API_KEY="sk-..." export ANTHROPIC_API_KEY="sk-ant-..." export GEMINI_API_KEY="AIza..."这些密钥LiteLLM会自动从环境变量读取，当然你也可以在代码里显式传入api_key参数。
3.3 异步调用和流式输出，这两件事是生产级的命门
真实项目里几乎没有同步调用的场景。在线接口动辄几秒钟延迟，同步等着会阻塞线程池。LiteLLM提供了一整套异步接口，写法也很贴合现有的异步生态：
import asyncio import litellm async def main(): response = await litellm.acompletion( model="gpt-4o-mini", messages=[{"role": "user", "content": "给我讲个笑话"}] ) print(response.choices[0].message.content) asyncio.run(main())把completion换成acompletion，同步变异步，就这么简单。这个设计对FastAPI这类异步框架尤其友好，可以直接在async路由函数里调用，不会阻塞事件循环。
流式输出也是生产环境的刚需。用户看到的"打字机效果"，本质上就是流式响应。LiteLLM的流式调用同样对齐了OpenAI的用法：
response = litellm.completion( model="claude-3-5-sonnet-20240620", messages=[{"role": "user", "content": "写一段100字左右的科技短文"}], stream=True ) for chunk in response: content = chunk["choices"][0]["delta"].get("content", "") print(content, end="", flush=True)注意看，即使是Anthropic的模型，stream=True之后返回的chunk结构也是OpenAI风格的choices[0].delta.content。所有底层厂商的流式格式差异在这里都被隐藏掉了。这一点在实际工程里价值极高——你不用再为不同厂商写不同的流式解析逻辑。
3.4 提前帮大家避一个坑：消息格式的统一处理
用过OpenAI的开发者都知道，messages参数是一个列表，里面有role和content字段。但不同模型对role的支持其实不一样。比如有些模型不支持system角色，有些模型对多条历史消息的长度有限制。LiteLLM虽然做了很多自动映射，但遇到复杂的消息格式时还是可能出现偏差。
我的建议是：始终按OpenAI的消息格式写，这是最通用的。role字段在system、user、assistant之间切换基本不会出错。如果换了模型后出现报错，优先检查是不是你传入的消息里有特殊字段（比如某些模型支持tool_calls，另一些不支持）。这一块LiteLLM帮你处理了大部分，但边界情况还是得靠经验去填。
4. 把它当成网关用：搭建LiteLLM Proxy做多模型路由与API密钥管理
在单机脚本里直接用LiteLLM很方便，但在团队协作或者生产环境里，你迟早需要一个"统一入口"。LiteLLM Proxy就是干这个的：它把LiteLLM变成一个独立部署的服务，你的应用只需要访问这个服务的HTTP接口，让服务去负责调用各家模型。
4.1 Proxy模式到底解决了什么问题
想象一个场景：你的团队里有好几个后端服务，每个服务都要调用大模型API。没上Proxy之前，每个服务里都要配置各家厂商的API密钥，都要写一遍调用逻辑。密钥散落各处，安全风险高；出问题了也不知道是哪个服务在疯狂调用消耗费用。
上了Proxy之后，所有服务只需要访问同一个HTTP地址，密钥只存在Proxy配置里。你想在多个模型之间做负载均衡、切换主模型、限制每个服务或每个用户的调用量，改配置文件就行，不用动业务代码。这就是网关的价值。
4.2 最快搭建方式：一份config.yaml加一条命令
搭建Proxy非常简单。你先写一个配置文件，比如叫config.yaml：
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-20240620 api_key: os.environ/ANTHROPIC_API_KEY这里每个条目定义了"对外暴露的模型名"和"实际调用的模型规格"。你可以在model_name字段里起一个自己的别名，比如统一叫gpt-4o-mini，但实际上背后指向的是某个Claude模型。这样前端应用根本没有感知，后端换了哪个厂商的模型，前端代码都不用改。
然后一行命令启动服务：
litellm --config config.yaml --port 4000默认情况下，服务会启动在localhost:4000。你的应用就可以用OpenAI SDK的姿势来请求它了，只不过把base_url指到本地：
from openai import OpenAI client = OpenAI( api_key="sk-anything", base_url="http://localhost:4000" ) response = client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": "你好"}] )看到没有，你的应用代码可以完全不感知LiteLLM的存在，它以为自己只是在跟OpenAI对话，但实际上背后是Proxy在代替它做模型路由。这个兼容性设计非常巧妙。
4.3 团队协作视角：API密钥管理不再是头疼的事
多个人共用一个Proxy时，单独给每个人发厂商密钥显然不合适。LiteLLM Proxy提供了自己的虚拟密钥机制——你可以生成多个"虚拟密钥"，分发给不同的团队成员或不同服务，每个虚拟密钥可以挂不同的模型访问权限和预算限制。
生成方式也很简洁。在启动Proxy后直接调用HTTP接口生成虚拟密钥：
curl -X POST "http://localhost:4000/key/generate" \ -H "Authorization: Bearer sk-1234" \ -H "Content-Type: application/json" \ -d '{ "models": ["gpt-4o-mini"], "max_budget": 10 }'得到一串以sk-开头的虚拟密钥。然后你就可以把这把钥匙给某个同事或某个服务用。他以为自己在用OpenAI的密钥，但实际上使用的是你的Proxy生成的受限密钥——不能直接访问厂商，只能通过你的网关调用。
这一套机制对团队管理特别有用：谁用了多少额度、哪个模型被频繁调用，全都一目了然。结合管理后台界面，你能直观地看到每个虚拟密钥的调用量、花费情况，甚至能实时撤销某把钥匙。
4.4 多个模型之间怎么做负载均衡
很多项目里，同一个模型会有多个部署（比如同一个模型在多家云厂商都有部署），或者你需要把流量分摊到不同模型上以降低成本。LiteLLM Proxy配置文件里的model_list和router_settings就派上用场了。
一个简单的配置示例：
model_list: - model_name: gpt-4o-mini litellm_params: model: gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: gpt-4o-mini litellm_params: model: azure/gpt-4o-mini api_key: os.environ/AZURE_API_KEY api_base: os.environ/AZURE_API_BASE两个条目都用了model_name: gpt-4o-mini，但背后一个指向OpenAI官方，一个指向Azure上的OpenAI模型。当你的应用请求gpt-4o-mini时，LiteLLM会按照负载均衡策略在两个上游之间分发请求。如果你配置了router_settings里的routing_strategy="least-busy"，它会优先选择当前负载更低的上游，实测下来在高峰期确实能明显降低响应时延。
5. 预算控制、限流、重试优化这些生产级细节值得稳扎稳打
对一个个人项目来说，能调通LiteLLM已经够了。但如果是在企业环境或者高并发场景，你还需要考虑预算、限流、错误重试这几件事。LiteLLM在这些方面同样提供了相对完善的机制。
5.1 给虚拟密钥绑定预算，让每个业务方都量化
我在前面的/key/generate示例里已经传了max_budget参数。这个参数是按美元计算的。你可以给一台开发用的测试密钥设置max_budget=5，当月度消费达到5美元后，这把钥匙直接失效，请求返回403。
更细的预算粒度也有。你可以在config.yaml里给某个模型设置预算上限、给某个API Key设置每日/每周/每月限额。它们会组合生效。这意味着你可以在团队维度、项目维度、甚至模型维度上都建立量化的成本控制。
我的经验是：把预算控制明确到个人或项目级别。很多公司是用一个共享的公司账户在调用模型，一旦某个人在调试时候产生失控循环调用，整个团队的成本都在涨。给每把虚拟密钥设好上限，相当于上了一层保险丝。出问题时候，只是某一把钥匙失效，不会波及整个账户。
5.2 限流配置：防止单模型被打爆
限流在多模型网关里尤其重要。有些模型提供方对单账号有严格的每分钟请求数（RPM）和每分钟Token数（TPM）限制，一旦超限会导致大量429错误，而且某些厂商的429报错会重重打断你的使用体验。
LiteLLM Proxy支持限流配置，可以在router_settings里做请求级别的控制。例如：
router_settings: rpm_limit: 500 tpm_limit: 100000 max_parallel_requests: 50rpm_limit限制每分钟请求数，tpm_limit限制每分钟消耗的Token总量，max_parallel_requests限制同时处理的并发请求数。如果有上游频繁报429，我建议把max_parallel_requests调小，同时打开重试机制（下一节细说），这样比硬扛流量更稳。
5.3 重试机制：让抖动不再直接打到用户脸上
大模型API的抖动是常态，尤其是高峰期，各家厂商都偶尔会返回5xx或者429。LiteLLM内置了重试机制，默认情况下会在遇到特定错误码时自动重试。你也可以手动配置：
import litellm litellm.num_retries = 3 litellm.retry_after = 5 # 重试间隔（秒） litellm.allowed_fails = 2 # 连续失败几次后放弃这里有个小技巧：重试的间隔最好设置成递增的，而不是固定值。因为上游报429说明它真的忙，固定间隔重试很容易在恢复瞬间继续撞到限流。LiteLLM虽然没有直接暴露指数退避参数，但retry_after配合num_retries，再结合你根据自己的调用历史调整间隔，就能得到不错的效果。
另一个容易被忽略的点是：流式请求的重试比普通请求更麻烦。因为流式请求可能已经吐了一半内容才报错，这时候重试会导致用户看到重复内容。我建议对线上流式请求做两层保护：一是LiteLLM的自动重试要设置较短的重试上限；二是业务层自己记录已发送的token数，流式中断后提示用户重试而不是自动拼接。这个坑我在实际项目中踩过，现在说出来也是希望大家少走弯路。
5.4 降级策略：主模型挂了，备胎模型顶上
最后说说降级。LiteLLM支持把多个模型配置成"同组"，当一个模型不可用时，自动切换到另一个。这在稳定性要求高的场景很管用。
配置方式也简单，在config.yaml里给多个模型打相同的路由组标签。比如：
model_list: - model_name: gpt-4o-mini litellm_params: model: gpt-4o-mini model_info: mode: completion - model_name: gpt-4o-mini litellm_params: model: claude-3-5-sonnet-20240620 model_info: mode: completion虽然名字都叫gpt-4o-mini，但实际一个指向GPT，一个指向Claude。调用时候，LiteLLM会按配置顺序尝试，第一个失败就切到第二个。这个方案在某些场景下会带来一定体验差异（毕竟不同模型输出风格不同），但总比服务宕机强太多。
6. 我踩过的坑和最后的几条建议
LiteLLM功能确实强大，但也不是完全无坑。这一章写写我在使用过程中遇到的典型问题，以及解决问题的心得。
6.1 版本更新较快，小心breaking change
LiteLLM迭代速度很快，有时候小版本更新就会改掉某些方法签名。我之前在一个项目里用了一个比较旧的版本，配置里写的参数在新的v1.x版本里已经更名为其他说法，启动时直接报错。
解决方式很简单：上线前固定版本号。在requirements.txt或者Dockerfile里写死版本，不要用litellm或litellm==*这种开放式约束。每次要升级时，先在测试环境跑一遍完整的回归用例，再决定是否更新。
6.2 各模型对参数的支持程度不一样，不能无脑透传
LiteLLM的定位是"统一接口"，但各家模型的能力边界还是不同的。比如response_format={"type": "json_object"}，并不是所有模型都支持。你传了某些模型不支持的参数，LiteLLM虽然不会报错，但参数会被悄悄忽略。看起来一切正常，实际模型并没有按你的要求输出JSON。
我的处理方法是：在业务层对模型能力做一份额外清单，按模型名判断是否支持某些高级参数。虽然这么做稍显繁琐，但能避免"你以为传了、实际没传"的隐蔽问题。
6.3 用Docker部署时，环境变量别写在镜像里
这点也是老生常谈，但确实是生产环境最常见的失误。config.yaml里引用了os.environ/OPENAI_API_KEY这样的写法，意味着服务启动时必须从环境变量里读。很多人图省事，直接把密钥写死在镜像里，结果镜像一旦外泄，密钥就全泄露了。
我用的方案是：密钥统一放在部署平台的安全配置项里，比如Kubernetes的Secret或者Docker的--env-file参数，镜像本身保持无密钥状态。这样不管镜像分发到哪，密钥都不会跟着走。另外，虚拟密钥的管理也是同理，不要写死在配置仓库里。
6.4 最后说点实在话
LiteLLM解决了我将近两年的多模型适配问题。它不是一个非常复杂的组件，但它在工程上的意义很大——把"模型提供商"和"应用代码"彻底解耦开。哪怕你目前只用了单一的模型，我也建议从第一天起就用LiteLLM做接入层，因为需求说变就变，技术债越早还不越痛。
个人经验是，小型项目直接引入LiteLLM成本很低，收益立竿见影；中大型项目用Proxy模式统一入口、控制预算，团队协作效率会明显提升。如果你正在被多模型API差异折磨，建议照着本文的步骤先跑通一个最小案例，剩下的事，水到渠成。
