1. 从一个真实困境说起多模型调用的碎片化之痛如果你正在做AI应用开发大概率遇到过这样的场景项目初期用某一家的大模型API跑通了原型效果不错上线后想加一个备用模型做容灾或者想针对不同任务切换不同模型来优化成本结果发现——每家的SDK不一样、参数命名不一样、返回格式不一样、流式输出的处理方式也不一样。光是写适配层就够喝一壶的。我最早接触litellm就是在这样一个节点上。当时手头有一个需要同时对接多个模型供应商的服务代码里充斥着各种if-else分支每接一家新模型就要改一遍调用逻辑测试用例也要跟着重写。后来同事推荐了litellm说它能用一套OpenAI格式的接口调所有主流模型。半信半疑试了一下确实把原来几百行的适配代码压缩到了几十行。litellm本质上是一个统一的LLM调用层。它做的事情可以用一个生活化的类比来理解就像万能充电头不管你手里是哪个品牌的设备插上去就能充。你只需要按照OpenAI的接口格式写代码litellm在底层帮你翻译成对应供应商的原生请求再把返回结果统一成OpenAI格式吐回来。这篇文章适合以下人群正在做AI应用但被多模型适配困扰的开发者、想快速对比不同模型效果的技术选型人员、需要给现有系统加模型容灾能力的后端工程师以及任何想用一套代码搞定多家模型调用的朋友。我会从核心机制、实操步骤、踩坑经验、进阶用法几个维度展开尽量把我在实际项目中积累的经验都倒出来。2. litellm到底解决了什么问题拆开统一接口的黑盒2.1 没有litellm之前多模型调用有多麻烦先说说不用litellm时对接多家模型的真实体验。假设你要同时支持三家供应商的对话模型每家都有自己的Python SDKA家的调用方式是client.chat(modela-large, messages[...])返回对象里取内容要用response.output.textB家的调用方式是client.generate(prompt..., max_tokens...)注意它收的是拼接好的字符串而不是消息列表返回是result.choices[0].textC家的调用方式是client.completions.create(engine..., prompt...)参数名又不一样返回结构也自成一套。这还只是最基本的文本生成。一旦涉及流式输出、函数调用、多模态输入、token计数每家的差异会成倍放大。你写一个业务逻辑可能要维护三套代码路径测试要写三遍文档要查三份。更头疼的是某家供应商改了API版本你的适配代码就得跟着改。2.2 litellm的核心思路一次编写到处调用litellm的做法是定义一个中间层抽象。你只写OpenAI格式的请求litellm负责参数映射把你传的model字段解析出供应商信息把统一的参数名翻译成目标供应商认识的参数名请求转发用对应供应商的SDK或HTTP接口发出请求响应归一把不同格式的返回统一成OpenAI的ModelResponse对象异常统一把各家的错误码和异常类型映射成统一的异常体系。这意味着你的业务代码只需要面向一套接口编程。切换模型时改一个字符串就行不用动其他逻辑。2.3 模型命名规则litellm如何知道该找谁litellm通过模型名称的前缀来识别供应商。基本格式是provider/model-name。比如模型标识对应供应商说明openai/gpt-4oOpenAI标准OpenAI模型anthropic/claude-sonnet-4-20250514AnthropicClaude系列gemini/gemini-2.0-flashGoogleGemini系列deepseek/deepseek-chatDeepSeek深度求索ollama/llama3Ollama本地部署模型azure/my-deploymentAzure OpenAIAzure上的部署如果你只写模型名不带前缀litellm会尝试根据名称特征猜测供应商。但我的建议是始终写全前缀避免歧义。特别是在多环境部署时明确的供应商前缀能省掉很多排查时间。2.4 支持的调用方式不止是Python SDKlitellm提供了多种使用方式适应不同场景Python SDKpip install litellm后直接import使用最灵活代理服务器Proxy启动一个HTTP服务暴露OpenAI兼容的接口任何能调OpenAI的客户端都能接LangChain集成作为LangChain的LLM后端使用原生HTTP调用通过代理模式用curl或任何HTTP客户端调用。对于快速验证Python SDK最方便。对于团队协作或需要统一管理密钥的场景代理模式更合适。后面我会分别展开。3. 环境搭建与第一个可运行示例3.1 安装与密钥配置的几种方式安装本身很简单pip install litellm但密钥管理是个容易踩坑的地方。litellm支持多种密钥传入方式我按推荐程度排序方式一环境变量推荐用于开发环境export OPENAI_API_KEYyour-key-here export ANTHROPIC_API_KEYyour-key-herelitellm会自动读取对应供应商的标准环境变量名。这种方式的优点是代码里不出现密钥不容易误提交到代码仓库。方式二代码中显式传入适合多密钥切换场景import litellm response litellm.completion( modelopenai/gpt-4o, messages[{role: user, content: 你好}], api_keyyour-key-here )方式三配置文件适合代理模式代理模式下可以用YAML配置文件管理多个模型的密钥和参数后面会详细说。注意不管用哪种方式密钥都不要硬编码在业务代码里。我见过有项目把密钥写在settings.py里然后提交到了公开仓库后果可想而知。3.2 最简调用三行代码跑通第一个请求环境配好后最简单的调用长这样from litellm import completion response completion( modelopenai/gpt-4o, messages[{role: user, content: 用一句话解释什么是统一接口}] ) print(response.choices[0].message.content)返回的response对象结构和OpenAI原生SDK的返回一致有choices、usage、model等字段。这意味着如果你之前用OpenAI SDK写的代码迁移过来几乎不用改。3.3 切换模型改一个字符串的事现在把上面的model参数换成另一家response completion( modelanthropic/claude-sonnet-4-20250514, messages[{role: user, content: 用一句话解释什么是统一接口}] )其他代码一行不用动。这就是litellm最核心的价值——调用逻辑与供应商解耦。3.4 流式输出处理方式与原生一致流式输出是很多应用场景的刚需litellm的处理方式和OpenAI一致response completion( modelopenai/gpt-4o, messages[{role: user, content: 写一段200字的短文}], streamTrue ) for chunk in response: content chunk.choices[0].delta.content if content: print(content, end, flushTrue)不同供应商的流式返回格式差异很大但litellm统一成了OpenAI的chunk格式。你只需要处理一种数据结构。3.5 验证清单确认环境真的配好了在正式接入业务之前建议跑一遍这个检查清单基础调用是否返回正常内容流式输出是否逐字返回token计数是否准确对比供应商控制台错误场景是否抛出可识别的异常比如故意传错密钥超时设置是否生效。这五步走完基本可以确认环境没问题了。4. 代理模式把litellm变成团队共用的模型网关4.1 为什么需要代理模式Python SDK适合个人开发但团队协作时会遇到几个问题密钥散落在每个人本地、模型配置不统一、没法做统一的用量统计和限流。代理模式就是来解决这些问题的。代理模式下litellm启动一个HTTP服务对外暴露OpenAI兼容的接口。团队成员不需要安装litellm用任何OpenAI客户端指向这个服务就行。密钥统一在服务端管理用量统计、限流、缓存也都在服务端做。4.2 配置文件怎么写代理模式的核心是一个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-sonnet-4-20250514 api_key: os.environ/ANTHROPIC_API_KEY general_settings: master_key: sk-your-master-key database_url: sqlite:///litellm.db几个关键点model_name是对外暴露的名称客户端调用时用这个litellm_params.model是实际的模型标识api_key用os.environ/前缀表示从环境变量读取避免明文写在配置里master_key是代理服务的访问密钥客户端需要带上它才能调用。4.3 启动服务与客户端接入启动命令litellm --config config.yaml --port 4000服务起来后客户端这样调用from openai import OpenAI client OpenAI( api_keysk-your-master-key, base_urlhttp://localhost:4000 ) response client.chat.completions.create( modelgpt-4o, messages[{role: user, content: 你好}] )注意这里用的是原生OpenAI SDK不是litellm。因为代理暴露的就是OpenAI兼容接口任何OpenAI客户端都能接。这个设计很聪明意味着你现有的基于OpenAI SDK的代码可以零改动迁移。4.4 用量统计与成本追踪代理模式自带用量记录功能。配置了database_url后每次调用的token数、耗时、模型名都会记录到数据库。你可以通过管理接口查询也可以直接查数据库。这个功能在实际项目中非常实用。我们之前做模型选型时就是靠这个数据来对比不同模型的性价比——同样的任务哪个模型token消耗少、响应快、成本低一目了然。4.5 多实例部署时的注意事项如果代理服务要部署多个实例做负载均衡有几个点要注意数据库要换成共享的比如PostgreSQL不能用SQLite缓存也要用共享的比如Redis否则各实例的缓存不一致master_key要统一否则客户端请求会随机失败。这些在litellm的文档里都有说明但初次部署时容易忽略。5. 那些文档里没写清楚的坑5.1 参数透传的边界哪些参数会被过滤litellm在转发请求时会过滤掉目标供应商不支持的参数。这个设计本意是好的——避免因为多传了一个参数导致请求失败。但有时候会带来困惑你明明传了某个参数但目标供应商没收到。比如你传了top_k给一个不支持这个参数的供应商litellm会静默丢弃它不会报错。如果你依赖这个参数来控制输出就会发现行为不符合预期。我的建议是在切换模型时先查一下目标供应商支持哪些参数。litellm的文档里有各供应商的参数支持矩阵花五分钟看一下能省掉很多调试时间。5.2 不同供应商的token计数差异token计数是个容易被忽视的坑。不同供应商对同一段文本的token计数可能不一样因为分词方式不同。litellm返回的usage字段是目标供应商返回的原始数据所以同一个请求发给不同模型token数可能不同。这在成本核算时要注意。如果你按token数做预算要针对每个模型分别估算不能用一个统一的换算比例。5.3 超时与重试的默认行为litellm有默认的超时和重试机制。默认超时是600秒重试次数是0不重试。这个默认值在生产环境可能不合适——600秒太长了用户等不了那么久不重试意味着网络抖动就会导致请求失败。建议在调用时显式设置response completion( modelopenai/gpt-4o, messages[...], timeout30, num_retries2 )timeout是单次请求的超时时间num_retries是失败后的重试次数。重试时会自动做指数退避不用自己实现。5.4 错误处理的统一与差异化litellm把各家的异常统一成了自己的异常体系比如AuthenticationError、RateLimitError、ContextWindowExceededError等。但有些供应商特有的错误可能没有被完全映射会以原始异常的形式抛出。处理建议先捕获litellm的标准异常再用一个通用的Exception兜底。这样既能处理常见错误又不会漏掉特殊情况。from litellm import completion from litellm.exceptions import AuthenticationError, RateLimitError try: response completion(...) except AuthenticationError: # 密钥问题 pass except RateLimitError: # 限流可以等一会儿重试 pass except Exception as e: # 其他错误 print(f未预期的错误: {e})5.5 本地模型接入的特殊处理接入Ollama等本地模型时有几个特殊点需要确保Ollama服务已经启动并且模型已经pull下来本地模型的响应速度取决于硬件超时时间要设长一些某些高级功能如函数调用本地模型可能不支持需要提前确认。response completion( modelollama/llama3, messages[{role: user, content: 你好}], api_basehttp://localhost:11434 )api_base指向Ollama的默认端口。如果Ollama跑在别的机器上改成对应的地址就行。6. 进阶用法让litellm发挥更大价值6.1 模型路由与负载均衡litellm支持在代理模式下配置多个同名的模型实例请求会自动做负载均衡model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY_1 - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY_2两个实例都叫gpt-4olitellm会轮流使用。这在有多个密钥需要轮换时很有用也天然实现了容灾——一个密钥出问题请求会自动切到另一个。6.2 回调与可观测性集成litellm支持多种回调可以把调用数据发送到外部系统做监控和分析import litellm litellm.success_callback [langfuse] litellm.failure_callback [langfuse]配置后每次调用的输入输出、token数、耗时都会自动上报。对于需要做效果分析和成本优化的团队这个功能能省掉自己埋点的工作。6.3 缓存策略省钱又提速litellm支持多种缓存后端包括内存、Redis、磁盘等。开启缓存后相同的请求会直接返回缓存结果不消耗tokenimport litellm litellm.cache litellm.Cache(typeredis, hostlocalhost, port6379)缓存对开发调试特别有用——反复测试同一个prompt时不会每次都消耗token。生产环境则要评估缓存命中率和数据新鲜度的平衡。6.4 函数调用与结构化输出litellm支持OpenAI格式的函数调用并且会把它翻译成目标供应商支持的格式response completion( modelopenai/gpt-4o, messages[{role: user, content: 北京天气怎么样}], tools[{ type: function, function: { name: get_weather, parameters: { type: object, properties: { city: {type: string} } } } }] )不同供应商对函数调用的支持程度不同litellm会尽量做兼容。但复杂场景下还是建议先做验证。6.5 多模态输入的处理litellm支持图片、音频等多模态输入格式遵循OpenAI的标准response completion( modelopenai/gpt-4o, messages[{ role: user, content: [ {type: text, text: 这张图里有什么}, {type: image_url, image_url: {url: data:image/jpeg;base64,...}} ] }] )不是所有模型都支持多模态调用前要确认目标模型的能力。7. 实际项目中的经验与建议7.1 模型选型的实用方法有了litellm切换模型变得很容易但选哪个模型仍然是个问题。我的做法是先用litellm搭一个简单的对比脚本用同一批测试数据跑几个候选模型从三个维度评估——输出质量、响应速度、token成本。质量评估可以人工打分也可以用一个更强的模型来做自动评估。速度和成本litellm的返回里都有数据。跑完一轮基本就能做出决策了。7.2 生产环境的稳定性考量生产环境用litellm有几个稳定性相关的点要注意超时设置根据业务场景设置合理的超时不要用默认的600秒重试策略对幂等的请求开启重试非幂等的要谨慎降级方案配置备用模型主模型不可用时自动切换监控告警对错误率和延迟做监控异常时及时告警。7.3 成本控制的几个抓手litellm本身不直接做成本控制但它提供了做成本控制所需的数据和灵活性。几个实用的抓手用缓存减少重复请求用便宜的模型处理简单任务贵的模型处理复杂任务设置max_tokens避免模型输出过长定期分析用量数据找出成本大头。7.4 版本升级的注意事项litellm迭代比较快升级时要注意先看changelog确认有没有breaking change在测试环境验证后再上生产锁定版本号避免自动升级到不兼容的版本。我一般会在requirements.txt里写死版本号比如litellm1.50.0需要升级时手动改。7.5 社区生态与扩展性litellm的社区比较活跃支持的模型供应商在持续增加。如果你用的供应商还没被支持也可以自己写适配器。它的架构设计得比较开放扩展起来不算复杂。另外litellm和LangChain、LlamaIndex等框架的集成也做得不错如果你在用这些框架可以直接把litellm作为LLM后端接进去。8. 写在最后litellm这个工具我用了大半年最大的感受是它把多模型调用这件事的复杂度从O(n)降到了O(1)。以前每接一家新模型都要改代码、写测试、调参数现在只需要改一个字符串。省下来的时间可以花在真正重要的地方——prompt优化、效果调优、业务逻辑。当然它也不是银弹。参数透传的边界、token计数的差异、错误处理的细节这些还是需要开发者自己留意。但总体来说它解决的是一个真实存在的痛点而且解决得比较优雅。如果你正在被多模型适配困扰建议花半小时试一下。从最简单的Python SDK调用开始跑通了再考虑代理模式。踩坑是难免的但坑不算深社区文档和issue里基本都能找到答案。