1. 从一个真实痛点说起：多模型调用为什么让人头疼
如果你最近半年在折腾大模型应用，大概率会遇到这样一个场景：项目一开始只用了某一家的大模型接口，代码写得挺顺。结果产品经理跑过来说，能不能加个备用模型，万一主模型限流了自动切换？或者老板说，这个月预算超了，把一部分请求切到便宜点的模型上去。再或者你自己想做个对比测试，看看同一个提示词在不同模型上的表现差异。
这时候问题就来了。每家模型的接口地址不一样，认证方式不一样，请求体格式不一样，返回结构不一样，连错误码的定义都不一样。你原本干干净净的业务代码里，开始塞满了各种 if-else 判断、各家 SDK 的 import、格式转换的适配层。改到后面，你自己都不想看那段代码。
LiteLLM就是冲着这个痛点来的。它的核心定位非常明确：用一套统一的 OpenAI 格式接口，去调用市面上几乎所有主流的大模型服务。你只需要把原来调 OpenAI 的那几行代码里的 base_url 和 api_key 换一下，就能无缝切换到别的模型上。对于需要管理多个模型供应商的团队来说，这东西能省掉大量重复的适配工作。
这篇文章我会从实际使用的角度，把 LiteLLM 的核心设计思路、关键配置细节、完整实操流程、以及我踩过的坑，全部拆开讲一遍。不管你是刚接触大模型 API 调用的新手，还是已经在做多模型调度的老手，应该都能从中找到有用的东西。
2. 核心设计思路拆解：它到底解决了什么问题
2.1 统一接口层的价值在哪里
要理解 LiteLLM 的价值，先得理解现在大模型 API 调用的碎片化程度有多严重。
假设你手头有三个模型需要调用：一个 OpenAI 系列的、一个 Anthropic 系列的、一个国内某厂商的。如果不做任何封装，你的代码大概长这样：
# 调用 OpenAI import openai client = openai.OpenAI(api_key="sk-xxx") resp = client.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": "你好"}] ) # 调用 Anthropic import anthropic client = anthropic.Anthropic(api_key="sk-ant-xxx") resp = client.messages.create( model="claude-3-5-sonnet-20241022", max_tokens=1024, messages=[{"role": "user", "content": "你好"}] ) # 调用国内某厂商 import some_sdk client = some_sdk.Client(api_key="xxx") resp = client.chat(model="xxx", prompt="你好")三套 SDK，三种调用方式，三种返回格式。你的业务逻辑里如果要支持模型切换，就得写三套分支。这还只是三个模型，如果扩展到十个呢？
LiteLLM 的做法是：它自己实现了一个统一的适配层，对外暴露的接口完全兼容 OpenAI 的格式。你只需要这样写：
from litellm import completion # 调用 OpenAI resp = completion( model="gpt-4o", messages=[{"role": "user", "content": "你好"}] ) # 调用 Anthropic resp = completion( model="claude-3-5-sonnet-20241022", messages=[{"role": "user", "content": "你好"}] ) # 调用国内某厂商 resp = completion( model="deepseek-chat", messages=[{"role": "user", "content": "你好"}] )调用方式完全一致，返回结构也完全一致。切换模型只需要改model参数这一个字符串。这就是统一接口层的核心价值——把 N 种调用方式收敛成 1 种。
2.2 为什么选择兼容 OpenAI 格式而不是自创一套
这里有个设计决策值得聊一聊。LiteLLM 完全可以自己定义一套全新的接口规范，但它没有这么做，而是选择了完全兼容 OpenAI 的格式。这个选择背后有几个很实际的考量。
第一，OpenAI 的接口格式事实上已经成了行业标准。市面上绝大多数大模型服务，不管是谁家的，基本都会提供一个"兼容 OpenAI 格式"的接口。这意味着用户对这套格式已经有认知了，学习成本几乎为零。
第二，现有的工具生态大部分都是围绕 OpenAI 格式建的。比如各种 Agent 框架、各种前端对话界面、各种评测工具，它们默认就是按 OpenAI 格式来对接的。LiteLLM 兼容这个格式，等于直接继承了整个生态。
第三，迁移成本最低。你原来用 OpenAI 写的代码，只需要把 import 换一下，其他几乎不用动。这种"无痛迁移"的体验，是它能快速被接受的关键。
实操心得：如果你现有的项目已经深度绑定了 OpenAI 的 SDK，不要急着全部重写。可以先把 LiteLLM 作为一个可选的调用通道加进去，新功能用 LiteLLM，老代码保持不动，逐步迁移。这样风险最小。
2.3 支持的模型范围与覆盖策略
LiteLLM 支持的模型列表非常长，我大致分个类：
| 类别 | 代表模型 | 说明 |
|---|---|---|
| 国际主流闭源 | GPT 系列、Claude 系列、Gemini 系列 | 覆盖最完整，更新也最及时 |
| 国际开源托管 | Llama 系列、Mistral 系列 | 通过各家托管平台调用 |
| 国内主流 | 通义、智谱、DeepSeek、月之暗面等 | 基本都有对应适配 |
| 自部署模型 | Ollama、vLLM、HuggingFace TGI | 本地或私有化部署场景 |
| 云平台托管 | 各大云厂商的模型服务 | 通过兼容接口对接 |
它的覆盖策略是：优先支持那些有稳定 API 的服务，对于自部署场景则通过兼容层来对接。这个策略很务实，因为自部署模型的接口五花八门，与其一个个适配，不如统一走兼容层。
2.4 架构上的分层设计
从架构上看，LiteLLM 大致分三层：
最底层是Provider 适配层，每个模型供应商对应一个适配器，负责把统一的请求翻译成各家自己的格式，再把各家的返回翻译回统一格式。这一层是它最核心的资产，也是工作量最大的部分。
中间层是路由与调度层，负责处理模型选择、负载均衡、失败重试、限流控制这些逻辑。这一层在 SDK 模式下相对简单，在 Proxy 模式下会复杂很多。
最上层是对外接口层，提供两种形态：一种是 Python SDK，直接在你的代码里 import 使用；另一种是 Proxy Server，启动一个独立的服务，对外暴露 HTTP 接口。
这两种形态的适用场景不太一样，后面我会详细对比。
3. 核心细节解析与实操要点
3.1 安装与基础配置
安装本身没什么好说的，标准 pip 流程：
pip install litellm但配置环节有几个细节值得注意。LiteLLM 读取 API Key 的方式是按环境变量约定来的。比如 OpenAI 的 key 读OPENAI_API_KEY，Anthropic 的读ANTHROPIC_API_KEY。这个约定你需要记住，因为配错了它不会报"key 格式错误"，而是直接报认证失败，容易让人以为是 key 本身的问题。
export OPENAI_API_KEY="sk-xxx" export ANTHROPIC_API_KEY="sk-ant-xxx"如果你不想用环境变量，也可以在调用时显式传入：
resp = completion( model="gpt-4o", messages=[{"role": "user", "content": "你好"}], api_key="sk-xxx" )注意事项：显式传 key 虽然灵活，但在多模型场景下容易混乱。我的建议是统一用环境变量管理，代码里不出现任何明文 key。这样既安全，也方便在不同环境之间切换。
3.2 模型命名规则与常见坑
LiteLLM 的模型命名有一套约定，理解这套约定能帮你少走很多弯路。
大部分模型的命名格式是provider/model-name，比如anthropic/claude-3-5-sonnet-20241022、gemini/gemini-1.5-pro。但 OpenAI 的模型是个例外，直接写模型名就行，比如gpt-4o，不需要加openai/前缀。
这个不一致性是最容易踩的坑。我第一次用的时候，写了openai/gpt-4o，结果报错说找不到模型。后来查了文档才知道 OpenAI 是默认 provider，不用加前缀。
对于国内模型，命名规则也各有不同。有的用厂商名做前缀，有的用模型系列名。最稳妥的办法是查官方文档的模型列表，或者用代码直接列出来：
import litellm # 查看支持的模型 print(litellm.model_list)3.3 参数传递的兼容性处理
LiteLLM 的一个核心能力是参数透传与转换。你按 OpenAI 的格式传参数，它会自动转换成目标模型能理解的格式。
比如temperature、max_tokens、top_p这些通用参数，大部分模型都支持，直接传就行。但有些参数是特定模型才有的，比如 Anthropic 的top_k，OpenAI 就没有。LiteLLM 的处理方式是：能转的就转，不能转的就忽略，同时给出警告。
这里有个细节：max_tokens这个参数在不同模型上的含义可能不一样。有的模型指的是"输入+输出的总长度"，有的指的是"仅输出的长度"。LiteLLM 会尽量做归一化，但你不能完全依赖它，最好还是查一下目标模型的具体定义。
resp = completion( model="claude-3-5-sonnet-20241022", messages=[{"role": "user", "content": "写一段话"}], max_tokens=500, temperature=0.7, top_p=0.9 )实操心得：在跨模型测试时，建议把参数配置单独抽出来做成一个字典，不同模型用不同的参数字典。这样既能保证兼容性，又方便对比调优。
3.4 流式输出的处理
流式输出是大模型应用的常见需求，LiteLLM 对这块的支持做得比较到位。你只需要加一个stream=True参数：
resp = completion( model="gpt-4o", messages=[{"role": "user", "content": "讲个故事"}], stream=True ) for chunk in resp: content = chunk.choices[0].delta.content if content: print(content, end="")返回的 chunk 结构也是 OpenAI 格式的，所以原来处理 OpenAI 流式输出的代码可以直接复用。
但这里有个坑：不同模型的流式返回节奏不一样。有的模型是逐字返回，有的是按词组返回，有的甚至会把整个句子一次性返回。如果你的前端做了打字机效果，需要针对不同模型调整动画速度，否则体验会很不一致。
3.5 异常处理与错误码统一
这是 LiteLLM 做得比较用心的一块。各家模型的错误码定义千差万别，LiteLLM 把它们统一映射成了 OpenAI 风格的异常类型。
| 异常类型 | 含义 | 常见触发场景 |
|---|---|---|
| AuthenticationError | 认证失败 | key 错误或过期 |
| RateLimitError | 限流 | 请求频率超限 |
| ContextWindowExceededError | 上下文超长 | 输入 token 超过模型上限 |
| ContentPolicyViolationError | 内容违规 | 触发安全审核 |
| APIError | 通用 API 错误 | 服务端异常 |
| Timeout | 超时 | 网络或服务响应慢 |
这样你在写异常处理逻辑时，就不用针对每个模型写一套了：
from litellm import completion from litellm.exceptions import RateLimitError, ContextWindowExceededError try: resp = completion(model="gpt-4o", messages=[...]) except RateLimitError: # 切换到备用模型 resp = completion(model="claude-3-5-sonnet-20241022", messages=[...]) except ContextWindowExceededError: # 截断输入或换长上下文模型 pass注意事项：异常映射不是 100% 准确的。有些模型的错误信息比较模糊，LiteLLM 可能无法准确判断类型，会统一归到 APIError。所以关键业务逻辑里，除了捕获具体异常，最好也加一层通用的兜底处理。
4. 完整实操流程：从零搭一个多模型调度系统
4.1 场景定义与需求拆解
假设我们要做一个内容生成服务，需求是这样的：
- 主模型用 GPT-4o，负责高质量生成
- 备用模型用 Claude，主模型限流时自动切换
- 低成本场景用 DeepSeek，控制预算
- 所有调用需要记录日志，方便排查问题
这个需求用 LiteLLM 来实现非常合适。下面我把完整流程走一遍。
4.2 环境准备与依赖安装
pip install litellm如果需要用 Proxy 模式，还要额外装：
pip install 'litellm[proxy]'环境变量配置：
export OPENAI_API_KEY="sk-xxx" export ANTHROPIC_API_KEY="sk-ant-xxx" export DEEPSEEK_API_KEY="sk-xxx"4.3 基础调用封装
先写一个基础的调用封装函数，把重试和降级逻辑加进去：
from litellm import completion from litellm.exceptions import RateLimitError, APIError import time def call_with_fallback(messages, primary="gpt-4o", fallback="claude-3-5-sonnet-20241022", max_retries=3): for attempt in range(max_retries): try: resp = completion( model=primary, messages=messages, timeout=30 ) return resp except RateLimitError: print(f"主模型限流，切换到备用模型") try: resp = completion( model=fallback, messages=messages, timeout=30 ) return resp except Exception as e: print(f"备用模型也失败: {e}") raise except APIError as e: print(f"第 {attempt+1} 次尝试失败: {e}") time.sleep(2 ** attempt) # 指数退避 raise Exception("所有重试均失败")这段代码里有几个设计点值得说明。
指数退避：time.sleep(2 ** attempt)让重试间隔按 1秒、2秒、4秒 递增。这样做的原因是，如果是服务端临时故障，立即重试大概率还是失败，不如等一会儿。指数退避是分布式系统里的经典策略。
降级顺序：先试主模型，限流了才切备用。这里没有对所有异常都降级，因为有些异常（比如内容违规）换模型也没用，降级反而浪费资源。
超时设置：timeout=30是必须的。大模型调用有时候会卡住，不设超时的话，你的服务可能被一个请求拖死。
4.4 成本控制与模型路由
不同模型的成本差异很大。我做过一个粗略的对比（以每百万 token 计）：
| 模型 | 输入成本 | 输出成本 | 适用场景 |
|---|---|---|---|
| GPT-4o | 较高 | 较高 | 高质量生成 |
| Claude Sonnet | 中等 | 中等 | 长文本处理 |
| DeepSeek | 低 | 低 | 批量处理、简单任务 |
| 开源自部署 | 硬件成本 | 硬件成本 | 数据敏感场景 |
基于这个差异，可以做一个简单的路由策略：
def smart_route(task_type, messages): if task_type == "high_quality": return call_with_fallback(messages, primary="gpt-4o") elif task_type == "long_context": return call_with_fallback(messages, primary="claude-3-5-sonnet-20241022") elif task_type == "bulk": return call_with_fallback(messages, primary="deepseek-chat") else: return call_with_fallback(messages, primary="gpt-4o-mini")实操心得：路由策略不要做太复杂。我见过有人搞了一套基于 token 数、任务类型、用户等级、时段的多维路由，结果维护成本极高，出了问题很难排查。建议从简单的规则开始，跑一段时间后再根据实际数据优化。
4.5 日志记录与可观测性
多模型场景下，日志特别重要。你需要知道每次调用用了哪个模型、花了多少 token、耗时多久、是否成功。
LiteLLM 内置了回调机制，可以挂载自定义的日志函数：
import litellm import logging logging.basicConfig(level=logging.INFO) def log_callback(kwargs, completion_response, start_time, end_time): model = kwargs.get("model") duration = (end_time - start_time).total_seconds() usage = completion_response.get("usage", {}) logging.info(f"model={model} duration={duration:.2f}s " f"prompt_tokens={usage.get('prompt_tokens')} " f"completion_tokens={usage.get('completion_tokens')}") litellm.success_callback = [log_callback]这个回调会在每次成功调用后触发，把关键信息记录下来。如果你用的是 Proxy 模式，它还支持直接对接各种可观测性平台。
4.6 Proxy 模式：什么时候该用，怎么用
前面讲的都是 SDK 模式，也就是在你的 Python 代码里直接 import。但 LiteLLM 还有一个 Proxy 模式，启动一个独立服务，对外暴露 HTTP 接口。
启动方式：
litellm --model gpt-4o --port 8000或者用配置文件：
model_list: - model_name: gpt-4o litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude litellm_params: model: claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEYlitellm --config config.yaml --port 8000启动后，你就可以用任何 HTTP 客户端来调用了：
curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "你好"}]}'SDK 模式和 Proxy 模式怎么选？
| 维度 | SDK 模式 | Proxy 模式 |
|---|---|---|
| 部署复杂度 | 低，直接 import | 中，需要独立服务 |
| 语言支持 | 仅 Python | 任意语言（HTTP） |
| 集中管理 | 分散在各服务 | 统一入口 |
| 密钥管理 | 各服务自己管 | 集中在 Proxy |
| 适用场景 | 单服务、快速验证 | 多服务、团队协作 |
我的建议是：个人项目或快速验证用 SDK 模式，团队协作或多服务架构用 Proxy 模式。Proxy 模式最大的好处是密钥集中管理，不用每个服务都配一遍环境变量。
5. 常见问题与排查技巧实录
5.1 认证类问题排查
认证失败是最常见的问题，但原因可能有很多种。我整理了一个排查顺序：
- 检查环境变量名是否正确。不同 provider 的环境变量名不一样，写错了不会报"变量不存在"，而是报认证失败。
- 检查 key 是否有多余空格。从网页复制 key 时经常带上首尾空格，这个坑我踩过不止一次。
- 检查 key 是否过期。有些平台的 key 有有效期，过期了需要重新生成。
- 检查账户余额。余额不足有时也会报认证类错误，容易误导排查方向。
排查技巧：如果怀疑是 key 的问题，先用最简代码单独测试，排除业务逻辑的干扰。比如直接跑一行
completion(model="gpt-4o", messages=[{"role":"user","content":"test"}])，看能不能通。
5.2 模型不存在或命名错误
这个问题的典型报错是 "model not found" 或类似的提示。原因通常是命名格式不对。
排查方法：
import litellm # 列出所有支持的模型 for m in litellm.model_list: print(m)如果列表里没有你要的模型，可能是版本太旧，升级一下：
pip install --upgrade litellm如果升级后还是没有，那可能是这个模型还没被支持，需要自己写适配器，或者用兼容接口的方式对接。
5.3 超时与网络问题
大模型调用超时是很常见的，尤其是高峰期。处理策略有几个层次：
第一层是设置合理的超时时间。我一般设 30 秒，复杂任务设 60 秒。太短了容易误杀，太长了会拖慢整体响应。
第二层是重试机制。配合指数退避，能解决大部分临时性超时。
第三层是降级切换。如果主模型持续超时，切到备用模型。
第四层是熔断机制。如果某个模型连续失败多次，暂时把它从可用列表里摘掉，过一段时间再试。这个在 LiteLLM 的 Proxy 模式里有内置支持。
5.4 Token 计算与上下文超限
上下文超限的报错信息有时候不太直观，尤其是不同模型的 token 计算方式不一样。LiteLLM 提供了一个 token 计算工具：
import litellm # 计算消息的 token 数 tokens = litellm.token_counter( model="gpt-4o", messages=[{"role": "user", "content": "你的文本"}] ) print(f"token 数: {tokens}")注意事项：token 计算是估算，不是精确值。不同模型的 tokenizer 不一样，LiteLLM 用的是近似算法。实际使用时要留一定的余量，比如模型上限是 128k，你最好控制在 120k 以内。
5.5 常见问题速查表
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
| 认证失败 | key 错误/过期/环境变量名错 | 检查 key 和环境变量 |
| 模型不存在 | 命名格式错误/版本旧 | 查模型列表，升级版本 |
| 请求超时 | 网络慢/服务端繁忙 | 设超时、重试、降级 |
| 上下文超限 | 输入太长 | 截断输入或换长上下文模型 |
| 返回格式异常 | 模型不兼容 | 检查参数，查文档 |
| 限流 | 请求频率过高 | 加限流控制，切换模型 |
| 成本超预期 | 路由策略不合理 | 优化路由，用便宜模型 |
5.6 几个我踩过的坑
坑一：以为所有模型都支持 system message。实际上有些模型对 system message 的处理方式不一样，有的会忽略，有的会报错。跨模型使用时，最好把 system message 的内容合并到第一条 user message 里，兼容性更好。
坑二：忽略了不同模型的输出格式差异。虽然 LiteLLM 做了统一，但有些模型在特定场景下（比如要求返回 JSON）的表现还是不一样。如果你的业务依赖结构化输出，一定要做格式校验和容错。
坑三：在流式输出里做复杂逻辑。流式输出的 chunk 是碎片化的，如果你在 chunk 处理里做复杂的字符串操作，很容易出 bug。建议先把流式内容拼成完整字符串，再做后续处理。
坑四：没有做成本监控。多模型场景下，成本很容易失控。一定要记录每次调用的 token 消耗，定期分析，及时调整路由策略。
6. 进阶玩法与扩展思路
6.1 自定义 Provider 适配
如果 LiteLLM 没有覆盖你需要的模型，可以自己写适配器。核心是实现一个转换函数，把统一格式转成目标格式，再把返回转回来。这个工作量不大，但需要对目标模型的接口比较熟悉。
6.2 与 Agent 框架结合
LiteLLM 可以作为 Agent 框架的底层模型调用层。很多 Agent 框架支持自定义 LLM 接口，你只需要把 LiteLLM 的 completion 函数包装一下接进去，就能让 Agent 用上所有支持的模型。
6.3 多模型投票与集成
一个有意思的玩法是：同一个问题同时发给多个模型，然后对结果做投票或融合。这在需要高可靠性的场景下很有用。LiteLLM 让这种模式的实现变得很简单，因为调用方式统一了，你只需要循环调用不同模型，再写一个结果聚合逻辑。
6.4 本地模型与云端模型的混合调度
对于数据敏感的场景，可以把敏感请求路由到本地部署的模型，非敏感请求走云端。LiteLLM 对 Ollama、vLLM 这些本地部署方案都有支持，混合调度完全可行。
def privacy_aware_route(messages, contains_sensitive): if contains_sensitive: return completion(model="ollama/llama3", messages=messages) else: return completion(model="gpt-4o", messages=messages)这个模式在实际项目里很有价值，既能保证数据安全，又能享受云端模型的能力。
我在实际使用 LiteLLM 的过程中，最大的感受是它确实解决了一个真实的痛点，而且解决得比较优雅。统一接口这个思路不新鲜，但能覆盖这么多模型、保持更新、还提供两种使用形态，这个工程量是实打实的。当然它也不是银弹，跨模型的差异不可能被完全抹平，该做的兼容处理和容错逻辑还是得做。但至少，它把最繁琐的那部分适配工作帮你干了，让你能专注于业务逻辑本身。如果你正在做多模型相关的项目，值得花点时间试试。
