1. 从一个真实困境说起：多模型调用的碎片化之痛
如果你做过任何跟大语言模型相关的应用开发，大概率经历过这样一个阶段：项目初期只接了一家模型服务商的API，代码写得干净利落，几十行就能跑通。但很快，产品经理跑过来说“能不能加个备用模型，万一这家挂了我们要能切换”，或者“Claude在某些任务上效果更好，能不能让用户自己选”。于是你开始写第二套调用逻辑，然后是第三套、第四套。每家的SDK不一样，参数命名不一样，返回结构不一样，流式输出的格式不一样，错误码更是各玩各的。到最后，你的代码里塞满了if provider == "xxx"这样的分支判断，维护成本直线飙升。
这就是litellm要解决的核心问题。它本质上是一个统一的LLM调用中间层——用一套OpenAI风格的接口，去调用市面上几乎所有主流的大语言模型服务。你写一次代码，改一个字符串参数就能从一家模型切到另一家，不用改任何调用逻辑。对于需要做模型对比、多模型路由、成本优化、故障降级的团队来说，这个东西的价值非常直接。
这篇文章适合谁看？如果你正在做AI应用的后端开发，或者负责模型接入层的架构设计，又或者你只是想让自己的脚本能灵活切换模型而不想重写代码，那接下来的内容应该对你有用。我会从它解决什么问题讲起，然后拆解核心机制，再给出一套可以直接抄的实操方案，最后聊聊我在实际使用中踩过的坑和总结出来的经验。
2. 拆解litellm的核心机制：它到底在中间做了什么
2.1 统一接口的本质是一次“协议翻译”
很多人第一次接触litellm，会觉得它就是个“包装库”，把各家的SDK包了一层。这个理解不算错，但太浅了。litellm真正做的事情，是定义了一套标准化的请求与响应协议，然后在中间做双向翻译。
你发给litellm的请求，用的是OpenAI的格式：model、messages、temperature、stream这些字段。litellm拿到之后，会根据model参数里的前缀（比如claude-、gemini/、ollama/）判断目标服务商，然后把你的请求翻译成那家服务商能理解的格式。返回的时候反过来，把各家的响应统一成OpenAI风格的choices[0].message.content结构。
这个设计的好处在于：你的业务代码只依赖一套接口，模型切换变成了配置层面的事情。我试过在一个项目里同时接四家模型，用litellm之后，切换逻辑从原来的两百多行缩减到了不到二十行。
2.2 模型路由的命名规则与优先级
litellm识别目标服务商靠的是模型名称的前缀约定。这个设计看起来简单，但实际用起来有几个细节值得注意。
| 模型名称写法 | 目标服务商 | 需要的环境变量 |
|---|---|---|
gpt-4o | OpenAI | OPENAI_API_KEY |
claude-3-5-sonnet-20241022 | Anthropic | ANTHROPIC_API_KEY |
gemini/gemini-1.5-pro | GEMINI_API_KEY | |
ollama/llama3 | 本地Ollama | OLLAMA_API_BASE |
deepseek/deepseek-chat | DeepSeek | DEEPSEEK_API_KEY |
openrouter/anthropic/claude-3.5-sonnet | OpenRouter | OPENROUTER_API_KEY |
这里有个容易踩的坑：不同服务商的模型名称可能有冲突。比如某两家都叫chat或者pro，如果你不加前缀，litellm可能会路由到错误的服务商。我的习惯是，只要不是OpenAI官方的模型，一律加前缀，宁可多打几个字符，也不要让路由出问题。
另外，litellm支持通过api_base参数手动指定端点。这个在自建代理或者私有部署的场景下非常有用。你可以把api_base指向自己的网关地址，litellm照样能正常工作。
2.3 流式输出的统一处理
流式输出是LLM应用里绕不开的需求。各家服务商的流式格式差异很大：有的用SSE，有的用chunked transfer，返回的JSON结构也各不相同。litellm在这一层做了统一，你只需要设置stream=True，拿到的就是一个标准的迭代器，每个元素都有choices[0].delta.content字段。
但这里有个细节：不同服务商的流式结束标志不一样。有的用[DONE]，有的用特定的finish_reason。litellm在中间做了归一化处理，你不需要关心这些差异。不过我在实际使用中发现，某些小众服务商的流式实现不太规范，偶尔会出现最后一个chunk丢失的情况。如果你的应用对完整性要求很高，建议在流式结束后做一次校验，或者对关键请求使用非流式模式。
2.4 异常体系与重试机制
litellm定义了一套统一的异常类型，比如AuthenticationError、RateLimitError、ContextWindowExceededError等。这些异常在不同服务商之间的映射关系是litellm维护的，你只需要捕获litellm的异常类型就行。
重试机制方面，litellm内置了指数退避的重试逻辑。你可以通过num_retries参数控制重试次数。我一般会设置num_retries=3，配合timeout参数使用。但要注意，不是所有错误都适合重试。比如认证失败、参数错误这类问题，重试多少次都没用，反而会浪费时间。litellm默认只对可重试的错误类型进行重试，这个策略是合理的。
3. 环境搭建与最小可运行示例
3.1 安装与依赖管理
litellm的安装非常直接：
pip install litellm如果你需要用到某些特定服务商的SDK，litellm会自动处理依赖。但我的建议是，显式安装你需要的服务商SDK，避免litellm在运行时动态导入时出现意外。比如你要用Anthropic，就额外装一下：
pip install anthropic版本管理方面，litellm的迭代速度很快，不同版本之间的API可能有细微变化。生产环境建议锁定版本号，不要用pip install litellm直接拉最新版。我一般会在requirements.txt里写死版本，比如litellm==1.52.0，然后在测试环境验证后再升级。
3.2 API Key的配置方式
litellm读取API Key的方式有两种：环境变量和参数传入。环境变量是最省事的方式，每个服务商对应一个固定的变量名。你可以在.env文件里统一管理：
OPENAI_API_KEY=sk-xxxxxxxx ANTHROPIC_API_KEY=sk-ant-xxxxxxxx GEMINI_API_KEY=xxxxxxxx DEEPSEEK_API_KEY=sk-xxxxxxxx然后在代码里用python-dotenv加载：
from dotenv import load_dotenv load_dotenv() from litellm import completion response = completion( model="gpt-4o", messages=[{"role": "user", "content": "用一句话解释什么是统一接口"}] ) print(response.choices[0].message.content)如果你不想用环境变量，也可以在调用时通过api_key参数传入。但这种方式在团队协作中不太推荐，容易把密钥硬编码到代码里。
3.3 第一个跨模型调用示例
下面这段代码演示了如何用同一个函数调用三家不同的模型：
from litellm import completion def ask(model: str, question: str) -> str: response = completion( model=model, messages=[{"role": "user", "content": question}], temperature=0.7, max_tokens=500 ) return response.choices[0].message.content # 调用OpenAI print(ask("gpt-4o", "什么是向量数据库？")) # 调用Anthropic print(ask("claude-3-5-sonnet-20241022", "什么是向量数据库？")) # 调用DeepSeek print(ask("deepseek/deepseek-chat", "什么是向量数据库？"))这段代码里，ask函数的逻辑完全一样，唯一的区别就是model参数。这就是litellm的核心价值——把模型差异收敛到一个字符串参数上。
3.4 验证安装是否成功的检查清单
在正式接入业务之前，建议先跑一遍检查清单，确认环境没问题：
pip show litellm确认版本号符合预期- 逐个测试每个服务商的API Key是否有效
- 测试流式和非流式两种模式
- 测试异常场景（比如故意传一个错误的Key，看是否抛出正确的异常类型）
- 测试超时和重试逻辑
我见过不少团队跳过这一步，结果上线后才发现某个服务商的Key配置错了，或者某个模型的名称写错了。提前花十分钟验证，能省掉后面很多麻烦。
4. 进阶用法：路由、降级与成本控制
4.1 用Router实现多模型负载均衡
litellm提供了一个Router类，专门用来管理多个模型的路由策略。你可以定义一组模型列表，然后设置路由规则：
from litellm import Router router = Router( model_list=[ { "model_name": "primary", "litellm_params": { "model": "gpt-4o", "api_key": "sk-xxx" } }, { "model_name": "backup", "litellm_params": { "model": "claude-3-5-sonnet-20241022", "api_key": "sk-ant-xxx" } } ], routing_strategy="least-busy", num_retries=3 ) response = router.completion( model="primary", messages=[{"role": "user", "content": "测试路由"}] )routing_strategy支持几种模式：simple-shuffle（随机）、least-busy（最少繁忙）、usage-based-routing（基于用量）。我一般用least-busy，在并发场景下表现比较均衡。
4.2 故障降级的配置思路
故障降级是多模型架构的核心价值之一。litellm的Router支持fallbacks参数，你可以定义一组降级链：
router = Router( model_list=[...], fallbacks=[{"primary": ["backup"]}] )当primary模型连续失败达到阈值时，Router会自动切换到backup。这个机制在服务商出现大面积故障时特别有用。我经历过一次某服务商API持续返回500错误的情况，因为配置了降级链，业务几乎没有感知。
但要注意，降级不是万能的。如果降级后的模型在能力上有明显差距，可能会导致输出质量下降。我的做法是，在降级发生时记录日志并触发告警，让团队知道当前处于降级状态，而不是默默切换。
4.3 成本追踪与预算控制
litellm内置了成本计算功能。每次调用后，响应对象里会包含response_cost字段，告诉你这次调用花了多少钱。你可以把这个数据收集起来，做成本分析。
response = completion(model="gpt-4o", messages=[...]) print(f"本次调用成本: ${response._hidden_params.get('response_cost', 0)}")更进阶的用法是结合max_budget参数做预算控制。你可以给每个用户或每个项目设置预算上限，超过之后自动拒绝请求。这个功能在多租户场景下非常实用。
| 成本控制手段 | 适用场景 | 实现方式 |
|---|---|---|
| 单次调用成本记录 | 成本分析 | 读取response_cost字段 |
| 用户级预算 | 多租户SaaS | max_budget+ 用户标识 |
| 模型级限流 | 防止滥用 | Router的rpm/tpm参数 |
| 降级到低价模型 | 成本优化 | fallbacks配置低价模型 |
4.4 缓存策略的取舍
litellm支持多种缓存后端：内存、Redis、磁盘等。开启缓存后，相同的请求会直接返回缓存结果，不再调用模型API。这在开发调试阶段特别有用，能省下不少调用费用。
import litellm litellm.cache = litellm.Cache(type="redis", host="localhost", port=6379) response = completion( model="gpt-4o", messages=[...], caching=True )但缓存有个明显的副作用：对于需要实时性的场景，缓存可能导致返回过时信息。我的建议是，只在开发和测试环境开启缓存，生产环境根据具体业务场景决定。对于FAQ类应用，缓存命中率高，收益明显；对于实时对话类应用，缓存的价值有限。
5. 实际项目中踩过的坑与排查过程
5.1 模型名称前缀写错导致的路由失败
有一次我在配置里写了claude-3.5-sonnet，注意这里用的是点号而不是横杠。litellm没有报错，而是把它当成了一个未知模型，尝试用OpenAI的接口去调用，结果返回了一个莫名其妙的错误。排查了半天才发现是模型名称写错了。
这个坑的教训是：litellm的模型名称匹配是精确匹配，不会做模糊纠正。你写的名称必须和服务商文档里的完全一致。我的做法是，把常用的模型名称整理成一个常量文件，所有地方都引用常量，避免手写出错。
5.2 流式模式下超时参数的陷阱
在流式模式下，timeout参数的含义和非流式模式不太一样。非流式模式下，timeout是整个请求的超时时间；流式模式下，timeout是两个chunk之间的最大间隔时间。如果你设置得太小，比如5秒，而模型在思考复杂问题时超过了5秒没有输出下一个chunk，连接就会被断开。
我一开始没注意到这个差异，设了个10秒的超时，结果在处理长文本生成时频繁断连。后来改成60秒，问题就消失了。这个细节在官方文档里写得不太显眼，但实际影响很大。
5.3 不同服务商的token计算差异
litellm提供了token_counter函数来估算token数量，但不同服务商的tokenizer不一样，估算结果会有偏差。比如同一段中文文本，用OpenAI的tokenizer和用Anthropic的tokenizer算出来的token数可能差20%以上。
这个差异在成本预估和上下文长度控制时会造成困扰。我的做法是，对于关键场景，直接使用目标服务商提供的token计算工具，而不是依赖litellm的通用估算。litellm的估算适合做粗略判断，不适合做精确控制。
5.4 并发场景下的连接池问题
在高并发场景下，litellm默认的HTTP连接池配置可能不够用。我遇到过一次线上问题：QPS上去之后，大量请求报连接超时。排查后发现是连接池太小，请求排队等待可用连接。
解决方案是调整litellm.client_session的参数，增大连接池大小：
import litellm import httpx litellm.client_session = httpx.Client( limits=httpx.Limits(max_connections=100, max_keepalive_connections=20) )这个配置需要根据你的实际并发量来调整。我的经验是，max_connections设置为预期峰值QPS的1.5倍左右比较稳妥。
5.5 异常处理中的信息丢失
litellm在把各家异常统一成自己的异常类型时，有时会丢失原始的错误信息。比如某个服务商返回了一个详细的错误描述，但litellm包装后只剩下一个通用的错误消息。这在排查问题时很不方便。
我的应对方法是，在捕获litellm异常时，同时打印exception.__cause__和exception.__context__，这两个属性里可能保留了原始异常的信息。另外，开启litellm的debug日志也能看到更详细的请求和响应内容。
6. 把litellm用好的几个关键习惯
6.1 建立模型配置的单一数据源
不要把模型名称、API Key、超时参数散落在代码各处。我习惯用一个YAML文件统一管理所有模型配置，代码启动时加载。这样切换模型或者调整参数只需要改一个地方，也方便做环境隔离（开发、测试、生产用不同的配置文件）。
6.2 为每次调用打上可追踪的标签
litellm支持通过metadata参数传递自定义标签。我会把用户ID、会话ID、请求来源等信息放进去，方便后续做成本分析和问题追踪。这个习惯在用户量上来之后会非常有价值。
6.3 定期做跨模型的一致性测试
不同模型对同一个prompt的响应可能有很大差异。我建议定期跑一组标准测试用例，对比各模型的输出质量、响应时间、成本。这样在需要切换模型时，你有数据支撑，而不是凭感觉做决定。
6.4 不要过度依赖单一抽象层
litellm虽然好用，但它毕竟是一层抽象。某些服务商的特有功能（比如特定的function calling格式、特殊的系统提示词处理）可能无法通过litellm完全表达。遇到这种情况，不要硬套litellm的接口，直接在业务代码里做特殊处理。抽象层是为了提高效率，不是为了限制能力。
6.5 关注版本更新日志
litellm的迭代节奏很快，几乎每周都有新版本。新版本可能修复了你正遇到的bug，也可能引入了不兼容的变更。我的做法是，订阅它的release notes，每次升级前在测试环境跑一遍回归测试。不要盲目追新，也不要长期不升级。
7. 关于选型的一点个人判断
litellm不是唯一的选择，市面上还有类似的统一调用层方案。但我在几个项目里用下来，litellm的覆盖范围、更新速度和社区活跃度是比较突出的。它的代码结构清晰，遇到问题可以直接读源码定位，这一点对开发者很友好。
当然，它也不是没有缺点。文档虽然全面但组织得有点乱，某些高级功能的示例不够详细。另外，作为一个快速迭代的开源项目，偶尔会遇到版本升级导致的兼容性问题。但总体来说，如果你需要在一个项目里调用多家模型服务，litellm能帮你省掉大量重复的适配工作。
我在实际使用中最大的体会是：统一调用层的价值不在于“少写代码”，而在于“把模型选择变成一个可配置、可观测、可优化的决策”。当你能够用数据回答“哪个模型在哪个任务上性价比最高”这个问题时，litellm的价值才真正体现出来。
