1. 从一个真实困境说起：多模型调用的碎片化之痛
如果你做过任何跟大语言模型相关的应用开发，大概率经历过这样一个阶段：项目初期只接了一家模型服务商的API，代码写得干净利落，几十行就能跑通。但很快，产品经理跑过来说“能不能也支持另一家的模型，用户反馈那家的中文理解更好”，或者“老板说成本太高，简单任务换一个便宜的模型”。于是你开始写第二套调用逻辑，然后是第三套、第四套。每家的SDK不一样，认证方式不一样，返回结构不一样，流式输出的格式也不一样。到最后，你的代码库里塞满了各种适配层，维护成本直线上升。
这就是litellm要解决的核心问题。它本质上是一个统一的模型调用中间层，用一套OpenAI风格的接口去调用市面上几乎所有主流的大语言模型服务。你写一次代码，改一个字符串参数就能切换模型供应商，不用再为每家的SDK写适配代码。对于需要做模型对比、成本优化、多模型兜底策略的团队来说，这个东西的价值非常直接。
这篇文章适合三类人看：第一类是做AI应用开发、被多模型适配折磨过的工程师；第二类是想快速对比不同模型效果、但不想写一堆胶水代码的技术负责人；第三类是对LLM应用架构感兴趣、想了解统一调用层设计思路的开发者。我会从实际使用角度出发，把litellm的核心机制、配置细节、踩坑经验和进阶玩法都讲清楚，尽量让你看完就能上手。
2. litellm到底做了什么：统一接口的底层逻辑拆解
2.1 核心设计思路：把差异吃掉，只留一个入口
litellm最核心的设计哲学可以用一句话概括：所有模型调用都收敛到completion这个函数。不管你调的是哪家的模型，入口都是同一个函数，参数格式也基本一致。它内部做了一层映射，把你的统一请求翻译成各家API能理解的格式，拿到响应后再翻译回统一的格式返回给你。
这个思路听起来简单，但实现起来要处理的细节非常多。比如不同厂商对“系统提示词”的支持程度不一样，有的支持得很好，有的只能用用户消息模拟；有的支持function calling，有的不支持；流式输出的chunk结构也各不相同。litellm做的事情就是把这些差异全部封装在内部，对外暴露一个尽量一致的接口。
你可以把它理解成一个“翻译官”加“适配器”的组合。翻译官负责把你说的话翻译成对方能听懂的语言，适配器负责把对方的回复转换成你能理解的格式。你只需要跟翻译官打交道，不用管对面坐的是谁。
2.2 支持的模型范围与调用方式
litellm支持的模型范围相当广，覆盖了主流的商业API和大量开源模型的自部署方案。调用方式上，它遵循一个简单的命名规则：供应商前缀加模型名称。比如你想调用某家的模型，就用对应的前缀加上模型标识符，litellm会自动路由到正确的后端。
这种命名规则的好处是直观且可扩展。你不需要记每个供应商的SDK初始化方式，只需要知道前缀和模型名就行。而且这个规则是开放的，如果某个模型还没被内置支持，你可以通过自定义配置的方式接入，灵活性很高。
从实际使用体验来看，最常见的调用场景包括：文本补全、对话生成、流式输出、函数调用、嵌入向量生成。这几类操作litellm都有对应的统一接口，基本覆盖了日常开发中百分之九十以上的需求。
2.3 为什么不是简单封装：错误处理与重试机制
很多人会想，这东西不就是个HTTP请求的封装吗，我自己写个函数也能做。但真正用过之后你会发现，错误处理和重试机制才是这类工具的核心价值所在。
不同厂商的API在出错时的行为差异很大。有的返回429表示限流，有的返回503表示服务不可用，有的直接在响应体里塞一个错误码。litellm把这些错误统一映射成标准的异常类型，让你可以用同一套逻辑处理所有供应商的错误。它还内置了重试机制，当遇到限流或临时故障时，可以自动重试，并且支持配置重试次数和退避策略。
这个能力在生产环境中特别重要。我自己就遇到过某家API在高峰期频繁返回限流错误的情况，如果没有自动重试，用户的请求就会直接失败。用了litellm之后，配置好重试参数，大部分临时性错误都能被自动消化掉，用户体验好了很多。
3. 从零跑通第一个调用：环境准备与最小可用示例
3.1 安装与密钥配置的几种方式
安装litellm本身很简单，一条pip命令就能搞定。但密钥配置这块有几个细节值得注意，因为不同项目的密钥管理策略不一样。
最直接的方式是在代码里通过环境变量读取密钥。litellm会自动识别各家供应商对应的环境变量名，你只需要在运行环境里设置好就行。这种方式适合本地开发和测试，简单直接。
第二种方式是在代码中显式传入密钥参数。这种方式适合需要动态切换密钥的场景，比如多租户系统中每个用户用自己的密钥。但要注意不要把密钥硬编码在代码里提交到版本库，这是基本的安全常识。
第三种方式是通过配置文件管理。litellm支持用一个YAML格式的配置文件来定义模型列表和对应的参数，包括密钥、API地址、超时时间等。这种方式适合需要管理大量模型配置的场景，配置和代码分离，维护起来更清晰。
注意：不管用哪种方式，密钥都不要出现在日志里。litellm默认会对密钥做脱敏处理，但如果你自己打印请求参数，记得手动过滤掉敏感字段。
3.2 第一个completion调用：参数详解
跑通第一个调用只需要几行代码。核心参数包括模型名称、消息列表、温度值、最大生成token数等。这些参数的含义和OpenAI接口基本一致，如果你之前用过OpenAI的API，上手几乎没有成本。
消息列表的结构是标准的角色加内容格式，支持system、user、assistant三种角色。温度值控制输出的随机性，值越低输出越确定，值越高越有创造性。最大token数限制生成的长度，防止意外产生超长响应导致费用失控。
这里有个实际经验：初次调用时建议把超时时间设短一点，比如10到15秒。因为有些供应商的API在冷启动时响应会比较慢，如果不设超时，程序可能会卡住很久。等确认调用正常之后，再根据实际响应时间调整超时参数。
3.3 流式输出的处理方式
流式输出是对话类应用的标配，litellm对它的支持很完善。你只需要在调用时把stream参数设为True，返回的就是一个迭代器，每次产出一个chunk。每个chunk里包含增量生成的内容，你可以边接收边展示给用户。
处理流式输出时要注意一个细节：不同供应商的chunk结构虽然被litellm统一了，但结束标志的位置可能略有差异。有的在最后一个chunk里带finish_reason，有的需要你判断内容是否为空。稳妥的做法是同时检查finish_reason和内容字段，确保不会漏掉结束信号。
另外，流式输出场景下的错误处理要特别小心。因为连接是长连接，中途可能出现网络中断或服务端超时。litellm会抛出相应的异常，你需要在迭代过程中捕获并处理，给用户一个友好的提示，而不是让页面一直转圈。
4. 多模型路由与成本控制：把litellm用出生产级效果
4.1 模型路由策略的设计思路
当你支持了多个模型之后，下一个问题自然就是：什么请求该走哪个模型？这就是路由策略要解决的问题。litellm提供了几种内置的路由能力，你也可以基于它的接口自己实现更复杂的逻辑。
最简单的策略是按任务类型路由。比如代码生成任务走代码能力强的模型，创意写作走文风好的模型，简单问答走便宜的模型。这种策略实现起来直接，效果也立竿见影。
进阶一点的策略是按成本路由。你可以给每个模型配置每百万token的价格，然后根据请求的预估token数选择成本最低的模型。litellm支持在配置文件中定义模型列表和对应的成本参数，路由时自动选择最便宜的可用模型。
更复杂的策略是基于质量反馈的动态路由。比如先用便宜模型生成，如果置信度低或者用户反馈不好，再自动升级到更强的模型重新生成。这种策略需要你自己维护质量评估逻辑，但litellm的灵活接口让这种实现变得可行。
4.2 成本追踪与预算控制
多模型调用带来的一个直接问题是成本管理。不同模型的价格差异可能达到几十倍，如果不做追踪和控制，月底账单可能会让你吃惊。
litellm内置了成本追踪功能，每次调用后会返回本次请求的token消耗和预估费用。你可以把这些数据记录下来，做汇总分析。我自己的做法是在每次调用后把模型名、token数、费用写进日志，然后定期分析哪些模型消耗最多、哪些请求可以优化。
预算控制方面，litellm支持设置预算上限，当累计费用超过阈值时自动拒绝后续请求或降级到更便宜的模型。这个功能在多租户场景下特别有用，可以给每个租户设置独立的预算，防止某个租户的异常调用拖垮整体成本。
提示：成本追踪的准确性依赖于模型价格配置的及时更新。各家供应商的价格会调整，建议定期检查配置文件中的价格参数是否还是最新的。
4.3 失败降级与多模型兜底
生产环境中，任何单一供应商都可能出现故障。litellm的降级机制让你可以配置一个模型列表，当主模型调用失败时自动尝试备用模型。这个能力对于保证服务可用性非常关键。
配置降级策略时要注意几点。首先是降级链路的长度，一般两到三层就够了，太多层会导致故障时响应时间过长。其次是降级模型的兼容性，确保备用模型能处理主模型的请求格式，否则降级后可能返回不符合预期的结果。最后是降级时的用户提示，如果发生了降级，最好在响应中带上标记，方便后续排查和统计。
我自己在实际项目中的配置是：主模型用能力最强的，第一备用用同级别但不同供应商的，第二备用用便宜且稳定的。这样在绝大多数故障场景下都能保证服务不中断，同时成本可控。
5. 那些文档里不会写的踩坑记录
5.1 参数传递的隐性差异
虽然litellm尽量统一了参数格式，但不同模型对参数的支持程度还是有差异。有些模型不支持温度参数，有些对最大token数有上限限制，有些对消息角色有特殊要求。这些差异在文档里不一定写得很清楚，需要在实际调用中逐步发现。
我遇到过一个典型问题：某个模型对system消息的处理方式和其他模型不一样，它会把system消息的内容合并到第一条user消息里。这导致同样的提示词在不同模型上效果差异很大。解决办法是在提示词设计时尽量不依赖system角色的特殊行为，把关键指令放在user消息里，保证跨模型的一致性。
另一个常见问题是参数值的合法范围不同。比如温度参数，大部分模型支持0到2的范围，但有的只支持0到1。如果你传了超出范围的值，有的模型会报错，有的会静默截断。稳妥的做法是在配置文件中为每个模型定义参数范围，调用前做一次校验。
5.2 超时与重试的平衡
超时设置太短会导致正常请求被误判为失败，太长会让用户等待过久。重试次数太少无法覆盖临时故障，太多会放大故障影响。这个平衡点需要根据实际业务场景来调。
我的经验是：先统计正常请求的响应时间分布，把超时设为P99响应时间的1.5倍左右。重试次数设为2到3次，退避策略用指数退避，第一次重试等1秒，第二次等2秒，第三次等4秒。这样既能覆盖大部分临时故障，又不会在真正故障时让用户等太久。
还有一个细节：流式请求的超时设置和普通请求不一样。流式请求建立连接后是持续传输的，超时应该设置在两个chunk之间的最大间隔，而不是整个请求的总时长。litellm对这两种超时都有支持，配置时要区分清楚。
5.3 版本升级带来的兼容性问题
litellm的迭代速度比较快，新版本可能会调整接口行为或默认参数。升级时如果不注意，可能会导致现有功能异常。
我踩过的一个坑是：某个版本升级后，默认的重试次数从3次改成了1次，导致之前依赖自动重试的逻辑失效，故障率明显上升。后来在配置里显式指定了重试次数才恢复。从那以后，我养成了习惯：每次升级前先看变更日志，升级后在测试环境跑一遍核心场景，确认无误再上生产。
另外，配置文件的格式也可能随版本变化。建议把配置文件纳入版本管理，升级时对比新旧格式差异，避免因为格式不兼容导致配置加载失败。
6. 进阶玩法：把litellm嵌入到实际项目架构中
6.1 作为独立代理服务部署
litellm除了作为Python库使用，还可以作为一个独立的代理服务部署。这种方式适合多语言技术栈的团队，比如你的主服务是Java写的，但想用litellm的统一调用能力，就可以把litellm部署成一个HTTP服务，Java服务通过HTTP调用它。
代理服务的配置方式和库模式类似，通过配置文件定义模型列表和路由规则。部署后它会暴露一组OpenAI风格的HTTP接口，你的任何服务都可以调用。这种架构的好处是调用逻辑集中管理，升级和维护只需要在一个地方操作。
部署时要注意几点：代理服务本身要做高可用，至少部署两个实例避免单点故障；要做好访问控制，不要暴露在公网上；要配置好日志和监控，方便排查问题。
6.2 与缓存层的配合使用
litellm支持与缓存层集成，把相同请求的响应缓存起来，避免重复调用。这在某些场景下能显著降低成本，比如多个用户问同样的问题，或者同一个请求被重复触发。
缓存策略需要根据业务特点来设计。对于事实性问答，缓存命中率可能很高，缓存时间可以设长一些。对于创意生成类请求，即使输入相同，用户也可能期望不同的输出，这时候缓存就不太合适，或者需要把温度参数纳入缓存键的计算。
litellm支持多种缓存后端，包括内存缓存和外部缓存服务。内存缓存适合单实例部署，简单但容量有限。外部缓存适合多实例部署，可以共享缓存，但需要额外维护缓存服务。选择哪种取决于你的部署架构和缓存需求。
6.3 自定义模型接入的完整流程
虽然litellm内置支持了很多模型，但总有一些小众模型或自部署模型需要自己接入。litellm提供了自定义接入的机制，流程大致是：定义一个模型配置，指定API地址、认证方式、请求和响应的转换逻辑，然后注册到litellm中。
自定义接入的关键是请求和响应的格式转换。你需要把litellm的统一请求格式转换成目标API能理解的格式，再把目标API的响应转换回统一格式。这部分需要写一些适配代码，但litellm提供了基类和工具函数，工作量比从零写要小很多。
我自己接入过一个自部署的开源模型，整个过程大概花了一个下午。主要时间花在调试响应格式的转换上，因为那个模型的返回结构和OpenAI的标准格式差异比较大。调试通过之后，后续使用就和内置模型完全一样了，非常方便。
7. 一些实际使用中的经验体会
用litellm有一段时间了，最大的感受是它确实解决了多模型调用的核心痛点，但也不是银弹。它帮你统一了接口，但不同模型的能力差异、提示词的适配、参数的调优这些工作还是得自己做。工具能降低工程复杂度，但不能替代对模型本身的理解。
另外一个体会是，不要过度依赖自动路由和降级。这些机制在故障时能救命，但如果配置不当，可能会掩盖问题。比如降级太频繁，说明主模型可能一直有问题，应该去排查根因，而不是靠降级糊弄过去。我一般会监控降级的触发频率，如果超过某个阈值就告警，提醒去检查主模型的状态。
最后分享一个小技巧：在开发阶段，可以把litellm的日志级别调高，把每次请求的完整参数和响应都打出来。这样调试提示词和参数时非常方便，能清楚看到不同模型对同一个请求的处理差异。上线后再把日志级别调低，避免日志量过大。这个习惯帮我省了很多排查时间。
