不少人以为接大模型 API 就是“买个 key，抄一段官方示例，跑通就完事”。真去接第二家、第三家的时候才发现，事情远没有这么简单：鉴权方式不一样、请求参数名不一样、返回结构不一样、报错风格也完全不一样。我之所以特意花时间研究 litellm，就是因为它把这些乱七八糟的差异全部收到一层统一接口后面。它的定位很简单：一个 Python 库加一个轻量代理进程，让你用一套 OpenAI 风格参数，去调用市面上几乎所有的模型服务商，包括自建的本地模型服务。这篇文章我会把实际跑通过的内容完整整理出来——从安装、统一调用、代理模式，到生产环境真正关心的负载均衡、故障转移、预算管控，最后是我踩过的一串坑和对应的排查思路，希望对正在做多模型接入或模型网关的同学有帮助。

1. 多模型接入的接口混乱，是我上手的直接原因

1.1 各家服务的 API 差异到底有多大

很多人会误以为大模型 API 的差异只是“公司不同、模型名字不同”，实际上接口层面的差异相当细碎。以最常见的两种接口风格为例：OpenAI 风格和 Anthropic 风格。两者虽然都使用 messages 数组来传对话内容，但细节上有一堆不一致。

这还只是“最常见的两家”，实际接的时候还有更多服务商，有的走完全自定义的协议，有的虽然声称兼容 OpenAI 格式，但在工具调用、图片输入、返回字段上各有各的“扩展”。于是你的代码里会出现大量 if 分支：如果当前是厂商 A 就拼这种请求，如果当前是厂商 B 又拆另一种返回。第一次接的时候这种分支还能忍受，等要接入五六家的时候，代码基本就没法看了。

更麻烦的是这些接口本身也在迭代，厂商偶尔会调整字段已经不是什么新鲜事。一旦某个上游接口小改，你的适配层就要跟着改，改完还得重新验证别家有没有受影响。这个维护成本远超一开始写几行适配代码时的心态预期。

1.2 自己写适配层为什么会半途而废

团队刚开始接多模型的时候，很容易走“自己写适配层”这条路。我当时也这么想过：反正无非是请求转换、响应转换、再加一个映射字典，几百行代码就能搞定。

真正动手后你会发现，除了最基础的文本对话，后续还要处理流式输出、异步调用、多轮对话、超时重试、token 计费、工具调用、长文本分段、不同厂商对参数合法范围的定义差异。比如有的服务 temperature 只能取 0 到 1，有的可以取 0 到 2，你把同样的参数传过去，一边正常工作，一边直接报参数非法。再比如有的服务没有 max_tokens 字段，叫 max_tokens_to_sample，字段错误就静默忽略，不是报错，而是输出被截断你都不知道。

这些看着是小问题，攒到一起就成了专门的项目。而 litellm 本质上就是把“很多团队重复发明过很多次的适配轮子”集中成了一个成熟开源项目，它内部已经处理了这些争吵不休的细节。我在后面几节会具体拆它到底是怎么处理的。

2. LiteLLM 的核心设计：把多协议翻译成一套通用接口

2.1 从调用入口到服务商适配层的请求链路

litellm 最核心的入口是litellm.completion()。看起来只是发一个请求，实际上内部有明确的链路：先解析模型参数，再查路由配置，接着做参数翻译，然后发请求，最后返回一个统一格式的响应对象。

拿模型参数来说，你传model="gpt-3.5-turbo"，它会根据环境变量里的OPENAI_API_KEY知道要走 OpenAI 风格协议；你传model="anthropic/claude-3-5-sonnet"，它就识别出anthropic/前缀，走 Anthropic 风格协议。这个带前缀的写法非常实用，等于在模型名里嵌入了路由信息。如果用了代理模式，模型名到具体服务商的映射还可以由配置文件里的model_list决定，调用方根本不需要知道背后到底是哪家。

参数翻译层是它最有价值的部分。你统一传temperature、max_tokens、messages、tools，litellm 会把这些 OpenAI 风格参数改成目标服务商需要的字段名、单位、结构。同理，服务商返回的结果也会被翻译回 OpenAI 风格的对象，所以无论你调用哪家，代码里拿到的都是response.choices[0].message.content这种熟悉的访问路径。

这套设计的核心思路相当于：上游是万国牌协议，下游是统一插座。你只需要把自己家的设备插到统一插座上，不用为每个国家单独改装插头。

2.2 流式、异步与多轮对话的处理逻辑

很多模型应用离不开流式输出。各家厂商的流式协议差异更大，有的用标准 SSE，有的事件名都不一样。litellm 把流式响应封装成了一个统一的迭代器，你拿到的是一个个chunk对象，每个对象都有choices[0].delta.content这类字段，屏蔽了底层到底是文本增量还是内容块数组。

异步支持方面，litellm.acompletion()是并发场景的关键。我实际测下来，在需要同时请求多个模型做对比评测、或者要给多个用户并发转发请求的场景，异步接口能省下大量等待时间。官方内部基于异步 HTTP 客户端实现，开多个并发任务不会互相阻塞。

多轮对话在 litellm 里没有特殊魔法，就是把完整的历史消息一股脑传给 messages 数组。真正要注意的是 token 总量：对话轮数一多，历史消息会越来越长，最终要么超出模型上下文窗口，要么成本飙升。这块建议自己在业务层做裁剪或摘要策略，litellm 本身不负责管理对话历史。

3. 从零跑通：安装、环境变量与第一个请求

3.1 安装与环境准备的实操细节

安装分两种情况。如果你只是在 Python 项目里调用模型，装核心包就够了：

pip install litellm

如果你还想用它的代理服务模式，也就是对外提供一个兼容接口的本地服务，建议直接装带可选依赖的版本：

pip install 'litellm[proxy]'

代理模式会额外引入服务端相关依赖，比如配置解析、密钥管理这些。我建议创建一个独立的虚拟环境来安装，因为下面马上要说到，litellm 的依赖版本有时候会和主项目互相打架，隔离环境能省掉很多头疼的事。

环境变量是关键一步。litellm 通过约定的环境变量名识别各家 API 的密钥，比如 OpenAI 风格的就叫OPENAI_API_KEY，Anthropic 风格的就叫ANTHROPIC_API_KEY。你可以在.env文件里配置，然后显式加载：

from dotenv import load_dotenv load_dotenv()

也可以直接在 shell 里 export。这里有个容易忽略的点：如果你只配置了一个叫MY_API_KEY的变量，litellm 是不会自动认的，因为它在路由时按标准变量名去查。命名不对的 key 等于没配。

3.2 同步调用与流式输出的代码示例

装好之后，最基础的一次调用是这样：

import litellm response = litellm.completion( model="gpt-3.5-turbo", messages=[ {"role": "user", "content": "用一句话介绍你自己"} ], temperature=0.7, ) print(response.choices[0].message.content)

返回值是 OpenAI 风格的完整响应对象，里面除了文本内容，还有usage字段，包含 prompt_tokens、completion_tokens、total_tokens 这些计费数据。如果你需要拿到当前请求花费的 token 数量，这个字段是主要来源。

流式输出同样很简单：

response = litellm.completion( model="gpt-3.5-turbo", messages=[{"role": "user", "content": "写一段关于秋天的散文"}], stream=True, ) for chunk in response: delta = chunk.choices[0].delta.content if delta: print(delta, end="", flush=True)

这里特别注意：流式响应对象不是一个完整的 JSON，而是一个逐个产出 chunk 的迭代器。如果你还是用平时访问response["choices"][0]["message"]["content"]的习惯去拿，肯定会报错。流式结束后你要自己把 delta 拼成完整文本，并处理每个 chunk 里的finish_reason来判断是不是正常结束。

3.3 用代理模式对外提供 OpenAI 风格端点

单独一个 Python 库还不够解决团队协作的问题。代理模式才是 litellm 在生产环境里最常用的形态：启动一个本地或远端服务，由这个服务统一管理模型路由、密钥、预算和日志，应用侧只需要记住这一个地址。

用配置文件启动代理，是更清晰的做法。创建一个config.yaml，大致长这样：

model_list: - model_name: gpt-3.5-turbo litellm_params: model: openai/gpt-3.5-turbo api_key: os.environ/OPENAI_API_KEY timeout: 30 - model_name: claude-3-5-sonnet litellm_params: model: anthropic/claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY timeout: 30

然后启动服务：

litellm proxy --config config.yaml --port 4000

服务监听在 4000 端口，对外提供的是 OpenAI 兼容格式的接口。你甚至可以直接把自己手里的 OpenAI SDK 指到它上面，只要把 base_url 改成http://localhost:4000，密钥随便填一个占位字符串即可。这种方式的好处是，原本为一家服务商写的代码，几乎不用改就能接入别的模型，这对团队内部做模型对比、灰度切换、成本评估都非常友好。

4. 生产环境真正看中的：负载均衡、故障转移与预算管控

4.1 多 Key 负载均衡与权重分配

实际生产环境里，单一 API key 很容易触发限流，尤其是做大量并发请求时。litellm 的代理模式支持给同一个模型名配置多个后端条目，每个条目可以使用不同的 key，由它来决定请求往哪个 key 上分发。

分发策略可以根据需要调，轮询、按当前用量路由都有。比如你可以把两个 key 配在同一个模型名下：

model_list: - model_name: gpt-3.5-turbo litellm_params: model: openai/gpt-3.5-turbo api_key: os.environ/OPENAI_API_KEY - model_name: gpt-3.5-turbo litellm_params: model: openai/gpt-3.5-turbo api_key: os.environ/OPENAI_API_KEY_2

这样请求会在两个 key 之间分散。我个人的经验是，负载均衡配置主要解决两类问题：一类是并发请求被某个 key 的速率限制卡住，另一类是某个 key 的配额即将用完，需要把流量匀到其他账号上。做权重分配时不要只考虑“均分”，要结合账号的配额和并发限制来调，否则可能出现某个 key 被打满、另一个 key 闲着的情况。

4.2 Fallback 机制的设计思路

模型服务没有 100% 可用的时候。某个厂商某个时段可能因为负载高而变慢，甚至直接返回错误。litellm 支持故障转移，也就是主模型失败后自动切换备用模型。

调用时可以直接指定：

response = litellm.completion( model="gpt-3.5-turbo", messages=[{"role": "user", "content": "你好"}], fallbacks=["anthropic/claude-3-5-sonnet"], )

这样主模型请求失败后，会尝试走claude-3-5-sonnet。这个机制的价值不只是防止服务不可用，也能应对某一家的限流政策过于严格的情况。平时写代码，我会主动在主请求上设置一个较短超时时间，让它尽快失败并触发 fallback，而不是干等很久才切换。

不过 fallback 也有一个要注意的地方：不同模型能力可能有差异。你从 GPT 系列切到别的系列，输出风格、响应结构、支持的参数范围都可能不一样，如果业务里依赖了某个模型的特殊能力，切换后要做一轮功能回归。备用模型不是用来完全顶替主模型的，而是保证核心业务不中断。

4.3 预算限制与用量追踪

大模型 API 的账单是不可控感最强的部分。litellm 提供了预算限制能力，可以设置总预算上限、按用户维度设置上限、按周期配置预算窗口。比如在配置里设置：

litellm_settings: max_budget: 200 budget_duration: 30d

这表示 30 天内总花费上限 200 美元（具体币种按你的配置和统计方式）。在代理模式下，还可以为每个内部用户或项目生成独立密钥，给每个密钥单独设限额，哪个项目超支了不会拖累全团队。

用量追踪方面，每次请求返回的usage字段会告诉你 token 数，配合各家的定价表就能估算成本。litellm 在代理模式下也会记录请求日志，你可以从日志里统计每天、每个用户、每个模型的调用量。

这里要提醒一句：预算统计依赖计数服务，默认可能是进程内内存计数。如果你同时部署了多个代理实例，内存计数是各算各的，预算总额就会失真。需要多实例共享预算数据时，通常要挂一个共享存储来做计数同步。

5. 实测中踩过的坑，以及一条完整的排查链路

5.1 依赖冲突与版本问题的处理

这类工具最常见的安装问题就是依赖冲突。litellm 重度依赖 HTTP 客户端、参数校验这些库，如果你所在的项目里已经装了一堆其他框架，版本很容易撞车。我遇到过一次很典型的报错：某个 Python 库要求 pydantic 版本在 1.x，litellm 又要求 2.x 起步，两边一起导入直接崩。

解决方案不算复杂，但需要有点耐心。最简单的是把 litellm 装到独立虚拟环境或容器里，通过代理模式对外提供服务，这样 litellm 的 Python 环境和公司主项目彻底隔离。如果必须在同一环境共存，建议用虚拟环境管理器把项目依赖记录清楚，然后手动把两个依赖的版本对齐到互相兼容的区间。不要硬装最新版，稳定优先。

5.2 请求失败但日志不明：一次真实排查过程

有段时间我用代理模式调用模型，请求一直超时，错误日志只有一句超时描述，没有更多有效线索。完整的排查链路大概是这样的：

第一步，打开 litellm 的 verbose 日志。Python 调用时：

import litellm litellm.set_verbose(True)

代理模式可以加 debug 参数启动。打开后能看到请求路由到了哪个后端、用了哪个环境变量里的 key、请求体长什么样，这些信息对定位问题很关键。

第二步，验证环境变量是否真的被读取。很多时候不是 key 配错了，而是进程根本没加载.env。我习惯在代码里先打印一下：

import os print(os.getenv("OPENAI_API_KEY"))

如果打印出来是空，那就是加载问题，先解决加载，再看别的。

第三步，绕开 litellm 直接用 curl 打服务商的接口。这一步是为了确认问题到底出在 litellm 还是出在上游服务本身。如果 curl 也超时，那是网络或服务商问题；如果 curl 正常，说明问题在 litellm 这边的路由或配置。

第四步，检查 config.yaml 里的模型映射。当时我配置的 model 名带错了服务商前缀，导致请求被路由到一个根本不存在的模型上，服务端不报模型不存在，而是直接让请求挂在那里直到超时。纠正前缀后请求立刻正常。

这套排查链路我后来走了很多次，基本能覆盖 80% 的连接类问题。总的原则是从外到内：先确认密钥和网络，再确认路由和参数，最后才怀疑工具本身。

5.3 成本侧最容易忽略的重复计费问题

成本问题比技术问题更隐蔽。litellm 默认有重试机制，当请求超时或遇到临时错误时，会自动重试。这本来是好功能，但在某些场景下会变成花费翻倍的元凶。

举个例子，客户端发出的请求其实已经到达模型服务端并开始推理了，只是响应在网络上堵了一会儿，客户端这边恰好超时并触发重试。服务端第一次已经扣了费，第二次重试又是一笔新的推理费用，两次都算钱。这个问题在长时间流式输出时尤其明显，流任务跑了几十秒，客户端突然断连，服务端那边的任务并没有立即停止，计费一直持续到任务自己结束。

我现在的处理方式是：给请求设置合理的超时时间，不要用默认的大超时值；把重试次数调低，宁可失败后走人工处理，也不要让系统自动重试把成本放大；对长时间任务增加额外监控，发现异常时主动中止或排查。

另外，账单核实不能只依赖 token 估算。每个服务商的单价不同，有的按输入输出分开计费，有的对缓存命中打折，有的还会收额外的工具调用费用。我习惯每周从服务商后台拉一次实际账单，跟 litellm 日志里的调用量做交叉核对，发现差异后再逐个小时看。

6. 什么时候推荐用 LiteLLM，什么时候不建议

6.1 我建议使用 LiteLLM 的场景

如果一个团队同时接入多家模型服务商，这是我推荐使用的最典型场景。用统一接口代替满屏的 if 分支，开发效率会明显提升。需要做模型评测、A/B 对比、上线前候选模型测试的团队，也很适合通过代理模式管理多个模型入口，随时切换目标模型而不动业务代码。

预算控制有强需求的团队同样值得考虑。运维侧希望能统一管控每个项目的 API 消耗，避免某个测试脚本跑飞导致账单爆炸，用代理模式加独立密钥来管理是可行且有效的方案。

从已有代码迁移的角度看，如果你现有项目本来就是 OpenAI 风格接口，想低成本接入别的模型，litellm 是比较平滑的选择。它几乎不需要改业务代码，只需把请求转发到代理地址或替换调用点，就能完成模型切换。

6.2 不建议使用的场景与原因

如果你的业务只调用一家服务商，而且确定以后也不会接第二家，那就直接用官方 SDK，没必要引入一层额外的抽象。少一层依赖意味着少一层故障源和版本维护成本。

对延迟极度敏感的场景也要慎重。litellm 会做参数转换和响应转换，虽然这部分开销通常很小，但毕竟是额外一层。在局域网内部高频小请求的极端场景下，这层开销会被放大，建议先做压测再决定。

还有一种情况是团队里没人愿意维护这个基础设施。litellm 是开源项目，版本迭代很快，配置文件格式和命令行参数偶尔会变。如果你只是图一时方便把它引进来，但后续没有人力跟进升级、没有能力排查问题，那它带来的复杂度可能大于价值。

最后分享一个我自己的习惯：引入这类抽象层之后，一定要把它的版本锁定在一个固定版本上，不要随手升级。大模型生态变化太快，上游 API 和这个工具本身都在频繁更新，固定版本可以保证线上行为的可控性。等真正需要新功能时，先在测试环境做一轮完整的回归验证，再决定要不要滚动升级。这套流程虽然保守，但对生产环境来说，稳定永远是最重要的。