先说结论：如果你现在正在同时对接多家大模型服务商的API，每天被各种不一样的请求格式、鉴权方式、错误码折腾得头皮发麻，那LiteLLM绝对值得你花一晚上试一下。它是一个统一接口层，让你用一套代码、一套请求格式，就能调用市面上主流的大模型服务商，还能顺带把成本统计、令牌审计、模型路由这些工程化问题一并解决。我是在一个多模型调度的模拟项目里第一次正式用它的，踩了几个坑之后，基本就把项目里所有模型调用全部收敛到了一个Python包和一行配置下面。
这篇文章没有太多虚的，就是我实际使用LiteLLM的完整记录，包括它到底怎么工作、为什么这么做、从安装到上手的每一步、进阶的代理模式，以及我踩过的一些有代表性的坑。无论你是刚接触LLM应用开发的初学者，还是已经在生产环境里维护多个模型接入的同学，这篇文章应该都能给你一些参考。
1. 项目定位：LiteLLM解决的真问题
1.1 多模型时代，调用接口有多乱
先回忆一下在没有LiteLLM的时候，接不同大模型服务商是个什么体验。每家服务商都给了自己的SDK，互相之间不兼容。有的用messages数组传对话，有的用prompt字符串；有的返回里直接带choices，有的返回里塞了个output；鉴权有的是请求头Authorization: Bearer xxx，有的又搞了个自定义头。就算你把网络请求自己封装一遍，每家API的错误码、限流字段、重试规则也完全不同。
最让人难受的是切换成本。今天想从A模型换成B模型，本以为是改一行代码的简单事，实际要动的是整个调用层的封装。遇到流式输出、工具调用这种稍微高级一点的特性，各个服务商实现差异更大，光是对齐就够你加好几天的班。我见过一个项目里，仓库上有三套独立的API封装代码，分别对应不同服务商，每套都有自己处理超时和重试的逻辑，维护成本高得吓人。
LiteLLM做的事情，说白了就是把这个烂摊子统一收编。它提供一个统一的输出格式，让你不用关心背后调用的是哪家服务商。你只需要用litellm.completion()这一个函数，传入标准化的参数，剩下的事情——协议翻译、鉴权补全、超时设置、重试策略——都由LiteLLM代劳。
1.2 统一接口背后，LiteLLM做了什么取舍
但“统一接口”这个需求，听起来简单，做一个能用的方案却不容易。LiteLLM不是简单地把所有SDK包一层壳，它做的是把各家API的核心能力抽象成一套公共范式。
它选择的抽象基准是OpenAI的请求/响应格式。也就是说，LiteLLM把你输入的数据统一转成符合OpenAI格式的样子，再把服务商返回的结果统一转回OpenAI风格的响应结构。这样做有个很实际的好处：OpenAI格式是整个行业事实上最通用的规范，很多其他服务商在设计API时也主动兼容了它。LiteLLM以它为基准，适配起来省力，用户的认知负担也最低。
这其实是一个很大的取舍。统一格式必然会丢弃某些服务商的独有参数，但换来的是“任何一个模型都能用同一套逻辑调用”的确定性。对绝大多数应用场景来说，这个取舍是完全值得的。
1.3 它究竟适合谁用
LiteLLM适合的人群，我总结下来大致三类：
第一类是正在开发LLM应用、但还没确定最终用哪个模型的团队。先用LiteLLM把接口统一，后面换模型是改配置文件的事，不是改代码的事。
第二类是想要在多个模型之间做低成本对比的开发者。同一个提示词、同一套参数，分别发给不同服务商，拿回结果对比，这个流程LiteLLM做起来非常顺手。
第三类是需要在团队内部提供统一模型入口的工程团队。用LiteLLM Proxy起一个服务，给业务方暴露一个OpenAI兼容的端点，业务方不需要知道背后有哪些模型，也不必自己申请各家密钥。
这个项目不是万能的，它不会帮你优化提示词，也不会替你做模型选型。它就是把你和各家API之间的那堆脏活累活接过去，让你能把精力放在真正重要的应用逻辑上。
2. 核心机制：一个请求如何走到目标模型
2.1 协议转换层：不同API怎么“翻译”
要做到一个函数调用所有模型，核心在于协议转换层。LiteLLM内部维护了一个关于各家服务商API规范的表，里面记录了：请求格式要怎么从标准格式转换成该服务商的格式、响应格式要怎么从该服务商的格式转换回标准格式、鉴权信息怎么填、特殊参数怎么映射。
以字符串形式的提示词为例，LiteLLM接收你传入的messages列表，如果目标服务商要求的是聊天消息格式，就直接用；如果目标服务商API更接近文本补全风格，它会把你的messages转换成一个拼接好的prompt。返回结果也是同样道理，LiteLLM会把服务商返回的文本、结束原因、令牌使用量等信息，重新打包成一个结构一致的响应对象。
这个过程我在第一次用的时候并没有感觉，因为LiteLLM把一切都封装在函数内部，我只管传参和读结果。直到有一次我调试某个模型返回的异常数据，手动打印了中间对象，才意识到协议转换层的数据映射做得有多细，连不同服务商finish_reason的叫法不一致这种细节都考虑到了。
2.2 统一格式设计：输入输出都长一个样
LiteLLM统一后的输入结构，其实和主流聊天模型的开放接口保持一致：一个messages数组，每个元素是带role和content的字典；一个model参数，用于指定目标模型；可选传temperature、max_tokens、top_p等生成参数。
关键在model参数的命名约定，LiteLLM用“服务商前缀 + 模型名”来定位到底调用谁。比如openai/gpt-4o就是用OpenAI兼容协议调用某特定型号，anthropic/claude-3就是用Anthropic协议调用对应模型。这个前缀不只是给人看的，LiteLLM会解析它来决定走哪个协议转换逻辑。
我知道刚接触的人肯定会疑惑：为什么不是只传模型名，还要带服务商前缀？这是为了避免歧义。不同服务商可能提供同名的模型，而且只有带上前缀，LiteLLM才知道该用哪一套鉴权信息、哪一套协议去通信。这个设计在后面的多模型路由中会显得尤其重要。
2.3 模型路由与密钥管理：多模型安全切换的关键
在工程化场景里，每个服务商的API密钥往往归属不同、预算独立，不能混用。LiteLLM把这个问题的解决方案也沉淀下来了。
你可以通过配置文件定义一组“模型别名”，并给每个别名绑定真实模型、密钥、超时参数。调用的时候，业务代码只用模型别名，密钥这些信息全部留在配置层。如果今天要换掉某个底层模型，改配置就够了，业务方甚至感知不到变化。
密钥管理方面，LiteLLM支持从环境变量读取，也支持在配置里显式传入。大多数情况下，我推荐用环境变量方式，避免密钥被写进代码仓库。特别是团队协作的项目里，配置文件经常要提交到Git，把密钥直接写在配置文件里基本等于裸奔。
2.4 成本控制与令牌统计：预算怎么盯住
除了调用本身，LiteLLM还提供了令牌使用统计和成本估算能力。每次调用返回的对象里都带有usage字段，包含prompt_tokens、completion_tokens和total_tokens。如果你用litellm.completion_cost()对响应做一次包装，还能拿到这次调用的估算成本。
这个能力看着不起眼，真正用起来是真香。之前我做一个对比实验，要在多个模型上跑同样的测试集，如果自己统计每个模型的消耗，要做不少额外工作。用LiteLLM做个循环，把每次的usage和cost记录下来，最后汇总对比一目了然。
成本估算背后是一张动态更新的计价表。不同型号、不同输入输出定价不一样，LiteLLM内置了常见型号的价格数据。要注意的是，估算值不等于账单准确值，尤其在有折扣、特殊渠道、缓存命中的情况下会有偏差。但这作为横向对比的依据已经完全够用了。
3. 五分钟上手：安装、配置、第一次调用
3.1 安装LiteLLM
安装没什么门槛，它就是一个普通的Python包。我建议在虚拟环境里安装，避免污染全局环境。项目初始化、依赖隔离这些习惯，遇上再简单的依赖也值得保持。
pip install litellm如果你需要代理模式，还需要安装带proxy的额外依赖：
pip install "litellm[proxy]"装完可以用一条命令快速验证是否成功：
python -c "import litellm; print(litellm.__version__)"能正常打印版本号，说明基础环境没问题。我在干净环境里安装过一次，整个过程不到一分钟，没有遇到依赖冲突的问题。担心冲突的话，用虚拟环境解决基本都能绕开。
3.2 配置服务商密钥
密钥的配置方式很直接，LiteLLM读取环境变量。不同的服务商有各自约定的环境变量名称，这个在项目文档里写得很清楚。以两家主流服务商为例：
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx" export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxx"我习惯把密钥统一放在一个.env文件里，然后用工具在项目启动时加载，而不是在代码里手动设置。这样本地方便调试，部署到服务器上时也可以换成真实环境变量而不改代码。
这里要留意一个问题：LiteLLM支持的服务商非常多，同名或相近的环境变量名偶尔会造成混淆。如果你同时配置了好多家的密钥，建议每配一个就在终端里验证一次，不要攒到最后一口气排查，不然出了问题很难分清是哪一步写错了。
3.3 第一个统一格式的调用
装好配好，接下来就是见证奇迹的时刻。忽略掉服务商差异，直接调用：
from litellm import completion response = completion( model="openai/gpt-4o-mini", messages=[ {"role": "system", "content": "你是一个技术助手。"}, {"role": "user", "content": "请用一句话介绍LiteLLM。"} ], temperature=0.7 ) print(response["choices"][0]["message"]["content"])第一次跑通这段代码的感觉是很爽的，因为我之前分别接通过各家SDK，每个都要读一遍不同的文档、处理不同的响应结构。现在所有逻辑收敛到同一个函数，返回结果里的choices结构完全一致，不需要为某个服务商单独写特判。
如果你把model参数换成：
response = completion( model="anthropic/claude-3-5-sonnet", messages=[ {"role": "user", "content": "请用一句话介绍LiteLLM。"} ], temperature=0.7 )其他代码一行都不用动，请求就直接发给了另一家服务商。这种感觉在对比模型时尤其实用，同一个测试脚本，循环跑不同模型，结果全都能统一处理。
3.4 多模型切换的代码实践
多模型切换，最简单的用法就是写个配置映射，把模型名放到外部配置里：
import os from litellm import completion model_key = os.getenv("TARGET_MODEL", "openai/gpt-4o-mini") def chat(user_input: str) -> str: response = completion( model=model_key, messages=[{"role": "user", "content": user_input}] ) return response["choices"][0]["message"]["content"] print(chat("今天天气不错，适合做点什么？"))通过环境变量控制走哪个模型，不改代码就能切换，这让模型对比和灰度验证变得特别轻松。你可以同时开几个终端进程，每个进程指定不同的TARGET_MODEL，跑同样的输入，直接观察输出差异。
流式输出也是高频需求。LiteLLM支持在调用时传入stream=True：
from litellm import completion response = completion( model="openai/gpt-4o-mini", messages=[{"role": "user", "content": "写一段300字的产品文案。"}], stream=True ) for chunk in response: delta = chunk["choices"][0]["delta"].get("content") if delta: print(delta, end="")流式响应被封装成迭代器，不管是哪个服务商，遍历方式都一样。这里有个小坑：流式模式下每个chunk里的delta可能为空，比如角色字段变化时就不带content，所以遍历时要对content做空值判断。我最初写的时候没注意，打印出来一堆None，还以为是接口出问题了。
4. 工程化落地：用代理模式统一团队入口
4.1 代理模式的思路
LiteLLM除了作为Python库嵌入应用，还能以代理服务的方式独立运行。它启动一个本地或远程的HTTP服务，对外暴露一个OpenAI兼容的API端点。业务方不用装Python包、不用知道LiteLLM底层逻辑，只需要把请求发到代理地址，就能访问所有被代理的模型。
为什么需要这个东西？因为在真实团队里，不是每个业务方都适合直接依赖LiteLLM。有些是其它语言栈，有些已经有了自己基于OpenAI协议封装的调用层，还有的压根不想碰各家密钥。代理模式相当于把模型接入能力做成了一种基础设施，业务方以标准HTTP方式调用即可。
我自己在一个跨团队协作的模拟项目中尝试过这种模式。当时多个业务模块都要调用模型，如果每个模块都自己去接服务商，那密钥管理、成本归属、限流控制全都得重复做。引入LiteLLM Proxy之后，所有模型调用统一收敛成一个服务，团队里其他人只跟这个服务打交道，干净利落。
4.2 配置文件实战：定义模型组与路由策略
代理模式的核心是配置文件。一个典型的config.yaml长这样：
model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude-sonnet litellm_params: model: anthropic/claude-3-sonnet api_key: os.environ/ANTHROPIC_API_KEY litellm_settings: drop_params: true set_verbose: true这里model_name是对外暴露的名字，业务方只用这个名字；litellm_params里的model才是LiteLLM实际解析要用的完整模型标识。api_key可以引用环境变量，也可以在配置里直接写字符串（不推荐）。
启动代理服务只需要一行命令：
litellm --config config.yaml --port 4000看到服务启动成功的日志后，你可以用curl快速验证一下端点是否正常：
curl http://localhost:4000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o", "messages": [{"role": "user", "content": "你好"}] }'因为LiteLLM Proxy暴露的是OpenAI兼容接口，所以任何基于OpenAI SDK写的客户端都能直接对接。这是它设计上的一个聪明之处：你不用给每个团队重新发明一套HTTP交互规范，所有人都按照最熟悉的OpenAI格式来。
4.3 提供标准化接口给业务方
代理服务跑起来之后，业务方的接入体验是这样的：
from openai import OpenAI client = OpenAI( base_url="http://localhost:4000/v1", api_key="sk-anything" # 代理会做鉴权，这里只需任意占位值 ) response = client.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": "请帮我总结这段文字的核心要点"}] ) print(response.choices[0].message.content)注意这个api_key，业务方不需要持有真实服务商密钥，因为真实密钥已经被代理接管了。在这里填什么值取决于你如何配置代理的鉴权。默认情况下填一个任意值也能跑通，但生产环境强烈建议开启虚拟密钥功能。
虚拟密钥机制是LiteLLM Proxy的一个亮点。管理员可以生成独立的虚拟密钥，每个密钥可以绑定某个模型或模型组、设置预算上限、限制速率。也就是说，你可以给A团队一个只能调用某款廉价模型的密钥，给B团队一个预算更高的密钥，谁用了多少、花在哪了，一目了然。这比直接把真实密钥分发下去安全得多。
4.4 部署与稳定性要点
代理服务本质上是一个普通Web服务，部署方式没太多特殊之处。可以用容器化方式跑，也可以直接用进程管理工具守护。我实际部署时倾向于用容器化方式，好处在于环境隔离、扩展方便，而且LiteLLM Proxy本来就已经打包好了镜像。
稳定性方面，我主要关心几个点：
请求超时要有兜底。代理层如果不设置超时，上游服务商的慢响应会拖垮下游接口。LiteLLM的配置里有timeout参数，建议根据业务预期设置合理的值，比如30秒。
并发数要关注。默认配置下，代理能处理的并发取决于底层模型服务商的速率限制。如果团队规模大、调用密集，建议在配置里显式设置num_workers之类的并发参数，并通过测试找到合适的值。
日志要留。代理服务自带日志能力，开启之后每次请求的模型、令牌数、耗时、状态码都有记录。排查问题时这些日志价值极大，别在生产环境里为了省日志空间把它关掉。
还有一点容易被忽略：代理服务和底层模型服务商之间的网络连通性。如果你同时对接的服务商分布在不同的网络区域，记得提前测试通不通、延迟多大、有没有间歇性丢包。这些网络层面的问题，到代理服务外面去看往往一片正常，但实际调用就是慢或者报错。
5. 踩坑记录：常见问题与排查思路
5.1 密钥与鉴权问题
最常见的问题，大概就是调用时报鉴权错误。LiteLLM报错信息里通常会带状态码，最容易遇到的是401。这种情况先检查环境变量到底有没有传入对。
我遇到过一种很隐蔽的情况：环境变量名拼写少了一个字母，结果LiteLLM回退到去读取别的同名变量，而那个变量是旧的失效值，导致明明看起来配置了密钥却一直鉴权失败。排查时不要只看有没有配置，要用print(os.getenv(...))确认加载的实际值到底对不对。
另外一个坑是多个服务商之间共用了同一个密钥变量名。你在.env里给A服务商设置的变量名，恰好被B服务商识别成了别的意思，结果A调用正常、B调用经常鉴权失败。建议每次新增服务商时，先把它单独跑一次最小调用，确认无误再进行下一步。
5.2 超时和限流问题
模型调用是典型的慢网络IO，超时几乎一定会遇到。LiteLLM默认有重试机制，但重试策略不是万能的，遇到服务商限流429时，盲目重试反而会让情况更糟。
我处理限流的方法，分三步。第一步，确认服务商限流的具体阈值，比如每分钟请求数、每分钟令牌数，不同的服务商限制维度不一样。第二步，在代码里控制调用频率，适当加一点随机抖动，避免多个线程同时打过去造成突发峰值。第三步，对重试策略做指数退避，而不是固定间隔重试。
如果你用代理模式，还要考虑代理自己会不会成为瓶颈。代理转发请求也是要消耗并发连接的，多个业务方同时打过来，代理层自身超时可能导致请求被积压。这种时候先看代理日志里有没有排队积压的迹象，再决定是否加并发数或扩容。
5.3 工具调用与参数透传问题
基础文本对话跑通之后，很多人会去试工具调用和结构化输出。这时候最容易出问题的反而不是LiteLLM本身，而是各家服务商对工具调用参数的定义不同。
LiteLLM虽然做了大量兼容工作，但工具调用这种高级特性各家实现差异实在太大，统一抽象不可能覆盖所有细节。我在一个场景里需要给模型传一个带特定格式要求的工具参数，不同服务商对参数命名、嵌套结构的解析完全不同。LiteLLM能保证的是大部分常规场景，遇到特别复杂的私有扩展参数时，还是需要对具体服务商做单独的适配。
这类问题的排查思路是：先用原生SDK跑通同样的请求，确认到底是不是LiteLLM的问题。如果原生SDK正常、LiteLLM报错，多半是参数透传或格式转换的差异；如果原生SDK也报错，那就是请求参数本身不符合该服务商的约束，跟LiteLLM无关。
5.4 流式与代理并用的缓冲陷阱
最后说一个代理模式下流式输出的坑。业务方通过LiteLLM Proxy请求一个开启流式输出的模型，代理需要把上游服务商的流式响应逐段转发给下游。如果配置不当，代理可能会先缓冲全部响应再一次性返回，流式的“实时感”就完全消失了。
如果你发现用代理走流式输出时，第一块内容要等很久才出来，或者是一下子全部出来，多半就是缓冲问题。解决方案一般是检查代理配置里是否禁用了对流式响应的缓冲，确保代理层是逐块转发而不是攒齐了再发。
这个问题排查起来不太好定位，因为从业务方视角看，请求是正常返回的，只是“感觉慢了”。但流式输出的体验恰恰就体现在“首字延迟”上，如果被缓冲破坏，那整个流式方案的意义就少了一半。
5.5 排错手段的整体建议
面对以上任何一类问题，我都建议从日志出发。LiteLLM提供了详细的调试日志，打开set_verbose=true之后，能看到每次请求内部到底发生了什么，包括用了哪个服务商、请求头是什么、映射后的URL是什么、最终返回的原始字符串是什么。
有了这些日志，排查就不再是盲猜。最节省时间的做法是：复现问题时打开详细日志，把报错前后的日志完整贴下来，然后对照配置逐项检查。很多时候问题一眼就能看出来，比如映射后的URL少了路径前缀、请求头里的认证信息是空的，等等。
调试完毕记得把set_verbose关掉，否则生产环境日志会非常啰嗦。
写在最后的个人体会
如果让我用一个词概括LiteLLM，我会说它是“标准化的搬运工”。它没发明什么高深的模型技术，但把模型调用这件事的复杂度大幅降低了。尤其是当你手里同时握着好几个服务商的账号、跑着不同的模型实验、还要向团队其他人提供稳定的模型入口时，LiteLLM带来的省心是实实在在的。
我在使用中最大的感触是：它并没有把所有东西都藏起来，遇到问题时依然能打开日志看到内部流程，这让它在“易用”和“透明”之间找到了一个不错的平衡点。凡是做过技术选型的人都明白，这两个词往往互相矛盾，LiteLLM能把它们兼顾到这种程度，已经非常难得。
最后再分享一个小经验。LiteLLM更新很频繁，各家服务商API变化后，兼容层往往也会跟着调整。我建议在正式升级版本前，先把核心调用路径在预发环境完整跑一遍，至少要覆盖文本对话、流式输出、工具调用三个场景。别在升级当天才去验证，那时候遇到兼容性变化会特别被动。总之，如果你正在被多模型接入折磨，花一个晚上试试LiteLLM，大概率能让你第二天的工作轻松很多。
