1. 从一个“模型调用地狱”说起：litellm 到底解决了什么问题

做过大模型应用开发的人，大概率都经历过这样一个阶段：项目最开始只接了一家模型服务商的接口，代码写得干干净净，一个client.chat.completions.create()走天下。可一旦业务方说“我们想同时支持另外两家的模型，做个对比”，或者“某个模型太贵了，能不能自动切换到便宜的”，代码就开始失控了。每家服务商的 SDK 不一样，鉴权方式不一样，请求参数命名不一样，返回结构更是千奇百怪，最后你的项目里塞满了各种if provider == "xxx"的分支判断，维护成本直线上升。

litellm就是冲着这个痛点来的。它是一个用 Python 写的开源库，核心目标只有一个：用一套统一的 OpenAI 格式接口，去调用市面上几乎所有主流的大模型服务。你写一次调用代码，改一个字符串参数，就能在多家模型之间自由切换。它同时提供了 SDK 和代理服务两种用法，前者嵌入到你的 Python 代码里，后者可以起一个本地或远程的网关，让任何支持 OpenAI 协议的工具都能直接对接。

这篇文章适合三类人看：一是正在做多模型接入、被各家 SDK 折磨的后端开发者；二是想给自己的应用加一层模型路由、成本控制、失败重试能力的架构同学；三是刚接触大模型应用、想找一个统一入口快速上手的新手。我会从设计思路、核心机制、实操步骤、踩坑经验几个维度，把 litellm 这套东西掰开揉碎讲清楚，尽量让你看完就能直接抄作业。

2. 整体设计思路拆解：为什么是“统一接口”而不是“统一 SDK”

2.1 核心矛盾：模型服务商的接口碎片化

要理解 litellm 的价值，得先理解它面对的是一个什么样的烂摊子。大模型服务这个领域，从 2023 年开始就进入了一种“百家争鸣”的状态。每家的 API 设计哲学都不一样：有的完全照搬 OpenAI 的格式，有的在参数命名上做自己的微调，有的在返回结构里塞了额外的字段，还有的连流式输出的分块格式都不一致。

举个最典型的例子，同样是“对话补全”这个动作，不同服务商在参数上的差异可能体现在这些地方：系统提示词有的放在messages数组里用role: system，有的单独开一个system字段；温度参数有的叫temperature，有的叫top_p配合使用；最大输出长度有的叫max_tokens，有的叫max_output_tokens；流式输出有的返回 SSE 格式的data:行，有的返回 JSON Lines。你如果要在项目里同时支持三家，光是写参数映射就能写出一堆胶水代码。

litellm 的设计思路很直接：以 OpenAI 的接口格式作为“通用语”，在内部做一层翻译。你按照 OpenAI 的写法传参，litellm 负责把它翻译成目标服务商能听懂的格式，再把返回结果翻译回 OpenAI 的结构。这样一来，你的业务代码只需要认一种格式，切换模型就是改一个模型名字符串的事。

2.2 两种使用形态：SDK 与 Proxy 的取舍

litellm 提供了两种使用方式，这个设计很值得说道说道，因为它直接对应了两类不同的使用场景。

第一种是Python SDK。你pip install litellm之后，在代码里from litellm import completion，然后就像调用 OpenAI 官方库一样调用它。这种方式适合你完全掌控自己的代码，想要在应用内部做精细的模型调度、异常处理、日志记录。它的优势是灵活，你可以拿到完整的返回对象，做各种自定义处理。

第二种是Proxy Server（代理网关）。你通过命令行启动一个服务，它对外暴露一个兼容 OpenAI 协议的 HTTP 接口。任何原本对接 OpenAI 的工具——比如各种聊天客户端、IDE 插件、自动化脚本——只要把 base_url 指向这个代理，就能瞬间获得调用多家模型的能力。这种方式适合你不想改代码，或者你的调用方根本不是 Python 程序。

我个人的经验是：开发阶段用 SDK 做快速验证，生产环境用 Proxy 做统一入口。因为 Proxy 天然适合做集中式的密钥管理、限流、成本统计和故障转移，而 SDK 更适合在业务逻辑里做细粒度的控制。两者不是互斥的，很多团队是 SDK 和 Proxy 混着用。

2.3 为什么不做成“统一 SDK”而是“统一接口”

这里有个容易被忽略的设计哲学问题。有些同类项目试图做一套全新的、抽象的 SDK，定义自己的请求和响应对象。litellm 没有这么做，它选择了“兼容 OpenAI 格式”这条路。这个选择背后的逻辑是：OpenAI 的接口格式事实上已经成了行业标准，大量的工具、框架、教程都是围绕它建立的。如果你定义一套新格式，就意味着用户要重新学习，生态工具要重新适配。

兼容现有标准的好处是立竿见影的：你现有的、基于 OpenAI 写的代码，几乎不用改就能用 litellm；你现有的、支持 OpenAI 的第三方工具，改个地址就能接入。这种“零迁移成本”的设计，是 litellm 能快速被接受的关键原因。当然代价也有，就是它必须紧跟 OpenAI 的接口演进，一旦官方加了新参数，litellm 也得跟着更新映射逻辑。

3. 核心机制深度解析：翻译层、路由与容错

3.1 请求翻译层是怎么工作的

litellm 最核心的部件就是它的翻译层。当你调用completion(model="某服务商/某模型", messages=[...])时，内部大致经历了这么几个步骤。

第一步是模型名解析。litellm 用provider/model_name这种命名约定来识别你要调用哪家服务。比如openai/gpt-4o、anthropic/claude-3-5-sonnet、deepseek/deepseek-chat这种写法。解析出 provider 之后，它就知道该用哪套翻译规则、该从哪个环境变量里读密钥。

第二步是参数映射。litellm 内部维护了一张巨大的映射表，把 OpenAI 风格的参数翻译成目标服务商需要的格式。比如你传的max_tokens，到了某些服务商那里可能要变成别的字段名；你传的messages数组，到了某些服务商那里可能需要把 system 消息单独抽出来。这些细节 litellm 都帮你处理了。

第三步是请求发送与响应转换。它用各家服务商的 HTTP 接口（很多情况下不依赖官方 SDK，而是直接发 HTTP 请求，这样依赖更轻）发送请求，拿到响应后，再把响应结构转换成 OpenAI 的ModelResponse对象。你拿到的返回对象，字段名和 OpenAI 官方库返回的几乎一模一样，response.choices[0].message.content这种写法可以直接用。

提示：模型名的前缀非常关键。如果你只写模型名不写 provider 前缀，litellm 会尝试猜测，但猜测不一定准。养成写全provider/model的习惯，能避免很多莫名其妙的报错。

3.2 路由与负载均衡：Router 组件

当你只有一两个模型时，直接调用就够了。但生产环境往往需要更复杂的调度策略：同一个模型有多个 API Key 想轮着用、某个服务商挂了想自动切到备用、想按成本或延迟做优先级排序。这些需求 litellm 用Router组件来满足。

Router 的核心概念是model group（模型组）。你可以定义一组逻辑上等价的模型部署，给它们起一个统一的名字，然后配置路由策略。比如你定义了一个叫gpt-4o-group的组，里面放了三个不同账号的 gpt-4o 部署，Router 就会按照你指定的策略（轮询、随机、最低延迟等）把请求分发到其中一个。

Router 支持的策略挺丰富的，我挑几个常用的说说。simple-shuffle是最简单的随机加权，适合多个等价部署做负载均衡。least-busy会把请求发给当前并发最少的部署，适合处理长请求场景。latency-based会根据历史延迟数据选择最快的，适合对响应速度敏感的应用。还有cost-based按成本排序，适合预算敏感的场景。

更实用的是它的容错机制。你可以配置num_retries，当某个部署失败时自动重试；可以配置fallbacks，当主模型组全部失败时降级到备用模型组；还可以配置cooldown_time，让连续失败的部署在一段时间内被暂时踢出，避免反复撞墙。这些能力如果自己实现，工作量不小，litellm 直接给你封装好了。

3.3 成本追踪与预算控制

多模型接入之后，一个绕不开的问题就是：钱花在哪了？哪个模型最烧钱？这个月的预算还剩多少？litellm 内置了成本计算能力，它维护了一张各模型的单价表，每次调用后会自动算出这次请求花了多少钱。

这个成本数据可以通过回调函数拿到，也可以配合 Proxy 的接口查询。你可以基于它做很多事情：给不同用户设置预算上限、按项目统计花费、在成本超阈值时告警。对于做 To B 应用的团队来说，这个能力几乎是刚需，因为客户会问“我这个月用了多少”，你得答得上来。

注意：litellm 的单价表是内置维护的，可能存在更新不及时的情况。如果你的成本核算要求非常精确，建议以服务商官方账单为准，把 litellm 的估算值当作参考。

3.4 可观测性：回调与日志

litellm 提供了丰富的回调钩子，可以在请求成功、失败、流式输出等各个节点触发。你可以把数据打到自己的日志系统、监控平台，或者对接第三方的可观测性服务。常见的用法包括：记录每次调用的模型、耗时、token 数、成本；统计各模型的成功率；追踪异常请求的完整上下文。

这些回调是异步执行的，不会阻塞主请求流程，所以对性能影响很小。但要注意回调函数里不要做太重的同步操作，否则可能拖慢整体响应。我一般会把回调数据先丢进队列，再由后台任务慢慢处理。

4. 实操落地：从零搭一套多模型调用环境

4.1 环境准备与安装

先说环境。litellm 是纯 Python 库，对 Python 版本的要求不算苛刻，3.8 以上基本都能跑。我建议用虚拟环境隔离，避免和系统里的其他包打架。

python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install litellm

如果你要用 Proxy 功能，还需要额外装代理相关的依赖：

pip install 'litellm[proxy]'

安装完成后，先做个最简单的验证。设置好某家服务商的 API Key 环境变量，然后跑一段最小代码：

import os from litellm import completion os.environ["OPENAI_API_KEY"] = "你的密钥" response = completion( model="openai/gpt-4o-mini", messages=[{"role": "user", "content": "用一句话解释什么是统一接口"}] ) print(response.choices[0].message.content)

如果这段能跑通，说明基础环境没问题。跑不通的话，八成是密钥没设对，或者模型名写错了。

4.2 多模型切换的实操演示

接下来演示核心能力：同一段代码切换不同模型。假设你想对比三家模型对同一个问题的回答：

from litellm import completion models = [ "openai/gpt-4o-mini", "anthropic/claude-3-5-haiku", "deepseek/deepseek-chat", ] question = "用三句话说明缓存穿透和缓存击穿的区别" for m in models: try: resp = completion( model=m, messages=[{"role": "user", "content": question}], temperature=0.3, max_tokens=500, ) print(f"=== {m} ===") print(resp.choices[0].message.content) print() except Exception as e: print(f"{m} 调用失败: {e}")

这段代码里，你只写了一套调用逻辑，模型名一换就切换了服务商。注意每家服务商的密钥要提前配好环境变量，litellm 会自动去读对应的变量名。这种写法在做模型对比评测时特别省事，不用为每家写一套代码。

4.3 用 Router 搭建带容错的模型组

单模型调用只是入门，真正体现 litellm 价值的是 Router。下面这段配置定义了一个模型组，包含两个部署，并开启了重试和降级：

from litellm import Router model_list = [ { "model_name": "my-fast-model", "litellm_params": { "model": "openai/gpt-4o-mini", "api_key": "密钥A", }, }, { "model_name": "my-fast-model", "litellm_params": { "model": "openai/gpt-4o-mini", "api_key": "密钥B", }, }, { "model_name": "my-backup-model", "litellm_params": { "model": "deepseek/deepseek-chat", "api_key": "密钥C", }, }, ] router = Router( model_list=model_list, routing_strategy="simple-shuffle", num_retries=2, fallbacks=[{"my-fast-model": ["my-backup-model"]}], cooldown_time=60, ) resp = router.completion( model="my-fast-model", messages=[{"role": "user", "content": "你好"}], )

这段配置的含义是：my-fast-model这个组里有两个等价的部署，请求会随机分发；如果某个部署连续失败，会被冷却 60 秒；如果整个组都挂了，自动降级到my-backup-model。这套机制在真实生产里非常有用，能显著降低单点故障带来的影响。

4.4 Proxy 网关的启动与配置

如果你想让非 Python 的工具也能用上多模型能力，Proxy 是更好的选择。最简启动方式：

litellm --model openai/gpt-4o-mini --port 4000

这样就在本地 4000 端口起了一个兼容 OpenAI 协议的服务。任何支持自定义 base_url 的工具，把地址指向http://localhost:4000就能用。

生产环境一般用配置文件来管理，因为要配的东西多。一个典型的配置文件长这样：

model_list: - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: claude-haiku litellm_params: model: anthropic/claude-3-5-haiku api_key: os.environ/ANTHROPIC_API_KEY general_settings: master_key: sk-my-master-key database_url: postgresql://user:pass@localhost:5432/litellm router_settings: routing_strategy: simple-shuffle num_retries: 2

启动命令：

litellm --config config.yaml --port 4000

配置文件里可以定义多个模型、设置主密钥做鉴权、接数据库存日志和用量、配置路由策略。master_key这个设置很重要，它相当于网关的管理密钥，客户端调用时要在请求头里带上它。

4.5 参数选择与成本估算的实操

聊几个实际调参时的经验。temperature这个参数，做事实性问答建议 0.1 到 0.3，做创意写作可以到 0.7 以上，做代码生成一般 0.2 左右比较稳。max_tokens不要设得太大，够用就行，因为很多服务商是按输出 token 计费的，设太大虽然不会真的用满，但有些场景下会影响调度。

成本估算这块，我习惯在开发阶段先跑一批测试请求，用 litellm 返回的usage字段统计 token 消耗，再乘以单价算出预估成本。比如一次请求输入 500 token、输出 300 token，某模型输入单价是每百万 token 若干元，输出单价是输入的几倍，这样一算就知道单次调用大概多少钱，再乘以预估的日调用量，就能判断预算是否可控。

5. 常见问题与排查技巧实录

5.1 调用报错排查速查表

实际用下来，报错主要集中在几类。我整理了一张速查表，遇到问题可以对照着看。

5.2 流式输出的坑

流式输出是踩坑重灾区。不同服务商的流式分块格式差异很大，litellm 虽然做了统一，但有些边界情况还是要注意。比如有的服务商在流的最后会发一个包含 usage 统计的特殊块，有的不发；有的在流中间会插入心跳包，有的不会。如果你自己解析流，要能容忍这些差异。

用 litellm 的流式接口时，记得用stream=True，然后迭代返回的生成器：

response = completion( model="openai/gpt-4o-mini", messages=[{"role": "user", "content": "讲个笑话"}], stream=True, ) for chunk in response: delta = chunk.choices[0].delta if delta and delta.content: print(delta.content, end="", flush=True)

提示：流式场景下，如果中途发生错误，已经输出的内容不会回滚。做前端展示时要考虑这种情况，给用户一个“重新生成”的入口。

5.3 密钥管理与安全实践

多模型接入意味着你要管理多家的密钥，这是个安全隐患点。我的建议是：永远不要把密钥硬编码在代码里，全部走环境变量或密钥管理服务。Proxy 模式下，客户端只需要知道网关的 master_key，各家的真实密钥都藏在服务端，这样即使客户端泄露，也不会波及上游服务商。

另外，Proxy 的 master_key 要设得足够复杂，并且定期轮换。如果网关暴露在公网，一定要配合访问控制，不要裸奔。我见过有人把没设鉴权的代理直接开到公网，结果被人扫到疯狂刷量，账单直接爆掉。

5.4 性能与超时的调优经验

litellm 本身是轻量级的翻译层，性能开销主要来自网络请求。但有几个地方如果没配好，会明显拖慢响应。一是超时设置，默认值可能偏长，遇到慢节点会一直等，建议根据业务容忍度设置合理的超时。二是重试策略，重试次数太多会放大延迟，一般 2 到 3 次足够。三是回调函数，如果回调里有同步的耗时操作，会拖慢主流程，务必改成异步。

还有一个容易被忽略的点：连接复用。litellm 底层用 HTTP 客户端发请求，如果每次请求都新建连接，开销不小。确保底层客户端开启了连接池，能显著降低高频调用场景下的延迟。

6. 进阶玩法与扩展思路

6.1 自定义 Provider 接入

litellm 虽然覆盖了主流服务商，但总有覆盖不到的。这时候可以用它的自定义 Provider 机制，自己写一个适配器。核心是实现请求转换和响应转换两个方法，把自定义服务商的接口翻译成 OpenAI 格式。这个能力对于接入内部自研模型服务特别有用，能让内部服务和外部服务在同一个网关下统一管理。

6.2 与现有框架的集成

litellm 的兼容性设计让它可以和很多现有框架配合。比如一些 Agent 框架、RAG 框架，底层调用大模型的部分可以直接换成 litellm，从而获得多模型能力。集成方式通常很简单，要么改 base_url 指向 Proxy，要么把底层的调用函数替换成 litellm 的 completion。这种“即插即用”的特性，是它兼容 OpenAI 格式这个设计决策带来的红利。

6.3 语义缓存与成本优化

高频调用场景下，很多请求是重复或高度相似的。litellm 支持接入缓存层，把相同请求的结果缓存起来，下次直接返回，省下真金白银。更进阶的玩法是语义缓存，用向量相似度判断两个请求是否等价，即使措辞不同也能命中缓存。这个能力在客服问答、知识库检索这类场景下效果很明显，能大幅降低调用量。

我在一个内部工具里试过缓存方案，把常见问题的回答缓存起来，命中率能到三成左右，成本直接降了一截。当然缓存也有代价，就是可能返回过时信息，所以要根据业务特点设置合理的过期时间。

6.4 多租户与权限隔离

如果你用 Proxy 给多个团队或客户提供服务，多租户隔离是必须考虑的。litellm 支持给不同的 key 设置不同的权限、预算、可用模型列表。比如给 A 团队只开放便宜模型，给 B 团队开放全部模型但设月度预算上限。这些配置通过数据库和虚拟密钥机制实现，配合管理接口可以动态调整。

这套机制对于做 SaaS 产品的团队很有价值，相当于把模型调用的计费、限流、权限都托管给了 litellm，自己不用重复造轮子。不过要注意，虚拟密钥和预算控制依赖数据库，部署时要确保数据库的可用性和性能。

7. 我踩过的几个真实坑

说几个文档里不太会写、但实际用起来很容易中招的点。

第一个坑是模型名的隐式匹配。有次我写了个模型名没带 provider 前缀，litellm 猜成了另一家服务商，结果密钥对不上，报了个很迷惑的错。后来养成习惯，模型名一律写全前缀，再没出过这类问题。

第二个坑是环境变量的加载时机。litellm 在导入时和调用时读环境变量的行为不完全一致，如果你在代码里动态设置环境变量，要确保在调用之前设置好，最好在模块导入前就设好。我遇到过在函数内部设环境变量结果不生效的情况，排查了半天。

第三个坑是成本统计的偏差。litellm 内置的单价表更新有滞后，新模型或者调价后的模型，统计出来的成本可能不准。如果你的业务对成本核算要求高，建议自己维护一份单价表，或者以服务商账单为准。

第四个坑是代理的并发瓶颈。Proxy 默认的并发配置可能不适合高流量场景，请求一多就开始排队。生产环境要根据实际 QPS 调整 worker 数量和并发参数，必要时用多进程部署配合负载均衡。

第五个坑是流式输出的错误处理。流式场景下，错误可能发生在流的中间，这时候前面的内容已经发出去了，处理起来比较麻烦。我的做法是在应用层做一层包装，记录已输出的内容，出错时给用户明确的提示和重试选项，而不是让界面卡在那里。

8. 写在最后的一点个人体会

litellm 这类工具的价值，不在于它有多高深的技术，而在于它把一件繁琐但必要的事情做到了足够简单。多模型接入这件事，单看每一家的对接都不难，难的是把它们统一起来、管理起来、容错起来。litellm 用“兼容 OpenAI 格式”这个巧妙的切入点，把碎片化的接口收敛成了一个统一入口，这个设计思路本身就值得学习。

我在实际项目里用它做过模型对比评测、做过带降级的线上服务、也用它给非 Python 的工具做过统一网关，整体体验是省心。当然它也不是银弹，遇到冷门服务商、特殊参数、极端性能要求时，还是需要自己动手补一些东西。但作为多模型调用的基础设施，它已经把 80% 的重复工作帮你干掉了，剩下的 20% 按需定制就好。

如果你正准备给自己的应用加多模型能力，我的建议是先用 SDK 跑通一个最小 demo，感受一下统一接口的便利，再根据实际需求决定要不要上 Proxy 和 Router。不要一上来就追求大而全的架构，从简单开始，按需演进，这样踩的坑最少。