litellm：统一大模型API网关，搞定多模型接入、路由与故障切换

1. 先聊清楚：litellm到底是什么，为什么你要关注

1.1 你正在被多少套API协议折磨

做AI应用集成最磨人的一件事，不是模型效果差，而是模型厂商之间的接口差异大到让人怀疑人生。不同家的鉴权方式不一样、请求格式不一样、报错风格不一样、限流逻辑更是一个赛一个狠。我接手过一个内部AI平台，业务代码里藏着七八种SDK，每接一个新模型都要重新读一遍文档，改一遍封装，测一遍灰度。后来我把litellm放到了所有模型调用的前面，这个问题才算真正被解决。

这种感觉就像家里接了四五家快递公司，每家都有自己的面单系统、取件码规则和客服电话。你作为一个普通用户，肯定不希望每次寄快递都重新学一套流程，而是希望楼下有个收发室，把包裹统一收进来再分发出去。litellm干的正是这个活儿，它把模型提供方的差异消化在自己内部，让业务端不用关心你在背后到底调了哪个来源、用的什么格式、怎么鉴权。

1.2 litellm的定位：一个统一的大模型API网关

litellm是一个开源的大模型接入中间层，你可以把它理解成一个专门为模型调用而生的网关翻译器。它对外暴露一套统一规范的补全接口，业务侧只需要按照通用的请求格式把消息发过来，剩下的路由、重试、密钥注入、成本计量都由它接管。

它的工作模式分两种。一种是当作一个Python库直接在应用进程里调用，适合本地调试、快速验证逻辑；另一种是启动一个独立的代理服务，通过HTTP请求访问，适合生产环境做统一管控。这两种模式共用同一套模型配置，只是接入方式不同。对于已经熟悉标准补全接口的客户端来说，接入litellm代理几乎是无痛的，把请求地址换成litellm的地址，模型名换成配置里的逻辑名，就能跑起来。

1.3 适合谁用，能解决哪些具体的痛点

如果你是后端工程师，正在给多个模型能力做集成，litellm可以帮你少写大量适配代码。如果你是团队里负责基建的人，想统一管理模型密钥、控制预算、做故障切换，litellm的代理模式能直接落地。哪怕你只是自己写脚本批量跑模型，不太关心网关这些概念，用它的SDK模式也能省掉不少样板代码。

我个人的体会是，它最大的价值不是“多了一个中间件”，而是把“模型调用”这件事从代码里的散点变成了基础设施里的一个可控节点。你把它想成数据库连接池或者消息队列，一旦立住了，后面所有模型变动都变成改配置，而不是改代码。这也是我推荐任何人尽早尝试的原因，越早把模型调用收口，后面越省心。

2. 核心设计思路：为什么“中间层”是个好选择

2.1 与其到处写适配代码，不如把差异收敛到一个点

很多团队遇到多模型接入时，第一反应是写一个工具函数，把每个来源的API封装一遍。这个思路在小规模阶段没问题，但越往后越难维护。每增加一个来源，你就要学一套新协议、处理一套新的错误码和限流窗口，代码里很快会堆满“根据来源类型执行不同逻辑”的分支。三个月后再回头看，这个函数基本没人敢改。

中间层的思路是完全反过来的：所有的变化都被拦截在网关外部，业务侧只面对一个稳定的接口。litellm把这种思路变成一个开箱即用的项目，不需要每个团队重复造轮子。它有完善的配置模型，你只需维护一份声明式的配置文件，就能告诉它有哪些模型来源可用、每个来源的钥匙在哪、超时怎么设、失败以后怎么切换。真正实现了模型接入的变化与业务代码的解耦。

2.2 两种工作模式：SDK模式与代理模式

litellm的SDK模式很简单，就是直接导入Python包调用，适合在本地开发环境快速验证模型效果。代理模式则是启动一个独立服务进程，监听固定端口，业务侧通过HTTP接口访问，适合生产环境做统一治理。

这两者的取舍要搞清楚。SDK模式少了一层网络转发，延迟更低，适合延迟敏感的单机场景；但它把日志、密钥、预算这些管控能力留在了业务进程内，不适合多服务共享。代理模式多一次网络跳转，却换来了集中管控：所有服务共享同一个模型入口，新增一个模型只需要改网关配置，业务服务不用发版。我的建议是，小团队先用SDK模式跑通业务流程，确定模型确实能满足需求之后，再花半天时间把代理模式部署上去，不要一上来就用代理，否则排查问题时容易多一道跳板。

2.3 它替你扛下的脏活：路由、容灾、计量

很多人以为litellm就是一个格式转换器，其实它真正值钱的地方是网关层的那一整套治理能力。你可以在配置里把同一个“逻辑模型”映射到多个真实来源，网关会根据策略做负载均衡。某个来源突然开始报错时，它会把请求转移到其他来源；请求失败时支持自动重试，连续失败过多时会把这个来源暂时下线，过一会儿再放流量探测恢复情况。

这些能力如果全在自己的业务代码里实现，少说也要一两周，而且大概率没有litellm做得到位。自己实现时最容易漏掉的是熔断后的恢复探测和重试时的等待策略，而这些细节在litellm里只是几个配置项。另一个容易被忽略的是计量能力。litellm可以按API Key、用户或团队维度统计token消耗和费用，设置速率和预算上限，这对团队规模变大后的成本管控几乎是刚需。

3. 快速上手：10分钟搭起自己的统一模型接口

3.1 安装与基础配置

先安装依赖，SDK模式和代理模式都在同一个包里，不需要分别安装：

pip install "litellm[proxy]"

装完以后，我建议先设置一个模型来源的密钥环境变量。后面在配置里，litellm支持通过特定写法引用环境变量，这样你可以在配置库里只写变量名，不暴露真实凭证：

export UPSTREAM_A_KEY=sk-your-key

记住这个原则：任何钥匙都不要写死在YAML或者代码里。你写死在本地测试没问题，一旦配置文件被提交到公共仓库，密钥就等着被扫描工具扒出来换成币。litellm的配置读取环境变量很方便，养成这个习惯后面部署才不会踩大坑。

3.2 用SDK模式直接发请求

SDK模式的核心是litellm.completion。先跑一个最小示例：

import litellm response = litellm.completion( model="upstream-a/your-model-name", messages=[ {"role": "user", "content": "用一句话解释API网关"} ], api_key="sk-your-key" ) print(response.choices[0].message.content)

第一次跑通之后，你可以试试加参数，比如temperature、top_p、max_tokens，这些参数和标准补全接口基本一致。litellm还支持传api_base，这非常重要。当你需要对接私有化部署的服务，或者某个自定义网关时，可以直接把api_base指向那个地址，litellm会按照标准格式帮你把请求发过去。这么一来，不管上游是原生模型服务还是一个兼容层，业务代码看到的接口始终是统一的。

3.3 用代理模式暴露一个标准接口

代理模式启用前，建议先准备一份配置文件。配置文件的作用是告诉litellm：你能调用哪些模型来源、这些来源暴露在哪个逻辑名下面、超时重试策略是什么、哪些钥匙能访问哪些模型。

启动代理只需要一条命令：

litellm --config config.yaml --port 4000

启动成功后，业务侧只需要把请求地址改成http://127.0.0.1:4000，请求体里带上配置的逻辑模型名，其他几乎不用改。验证一下：

curl http://127.0.0.1:4000/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-litellm-master-key" \ -d '{ "model": "assistant-pro", "messages": [{"role": "user", "content": "你好"}] }'

正常的话，响应结构和直接调用上游模型是基本一致的，但请求已经被分发到了你配置的某个真实来源。这一步打通以后，你的业务代码就不再关心“到底调了谁家的模型”，只关心“有没有拿到正常补全结果”。

3.4 一个能落地的config示例

这里给一份我在项目里会用的基础配置，模型名和地址都做了脱敏处理，你直接替换成自己的真实值就能跑：

model_list: - model_name: "assistant-pro" litellm_params: model: "upstream-a/assistant-pro" api_key: "os.environ/UPSTREAM_A_KEY" api_base: "https://api.example-a.com/v1" - model_name: "assistant-pro" litellm_params: model: "upstream-b/assistant-pro-v2" api_key: "os.environ/UPSTREAM_B_KEY" api_base: "https://api.example-b.com/v1" litellm_settings: drop_params: true request_timeout: 30 router_settings: routing_strategy: "simple-shuffle" num_retries: 3 retry_after: 0.5 allowed_fails: 2 cooldown_time: 60 general_settings: master_key: "sk-litellm-master-key"

model_name是你给业务侧看的逻辑名，同一个逻辑名可以对应多个上游来源。litellm_params里的model是上游真实模型标识，api_base是对应的服务地址。drop_params设为true表示自动丢弃目标模型不支持的参数，这对提高兼容性很有帮助。master_key是网关的访问钥匙，所有业务侧请求必须带上它。

注意：这里几个配置项的名称和具体行为会随litellm版本变化，建议以你安装的版本文档为准。核心思路是“逻辑名映射到真实模型来源”，这个设计在任何版本里都成立。

4. 生产环境的关键玩法：路由、负载均衡与故障切换

4.1 模型别名与多来源配置

生产环境第一步要做的是“逻辑模型”和“真实模型”的映射。你可能会遇到某个来源要临时维护、模型版本升级，或者你想在两个不同来源之间做灰度对比。这些都不应该让业务代码感知，所以模型别名特别重要。

别名的好处是，你可以随时改配置文件，把assistant-pro这个逻辑名指向新的来源，业务端完全不用发版。我见过很多团队在代码里硬编码模型字符串，一旦上游改个模型版本号，就要全仓库搜索替换，非常痛苦。用litellm以后，模型配置集中在一个地方，改起来就是一次配置变更，还能通过git记录追踪每次改动时间点，出问题可以快速回滚。

4.2 同模型多密钥轮询与健康检查

业务量上来以后，单个密钥的限流很快就会变成瓶颈。litellm允许你为同一个真实模型配置多个litellm_params，这样多个来源或多个密钥之间可以轮询，把流量分散开，降低单个密钥触发限流的概率。

健康检查机制容易被忽略，但它是生产环境稳定性的关键。如果某个来源的密钥已经失效，或者某个来源持续返回5xx，litellm会根据最近失败次数把该来源临时隔离，隔一段时间再放少量流量探测。这样业务不会因为某一个来源的故障而完全不可用。我记得有一次某个上游服务升级导致间歇性超时，线上业务几乎没有感知，只在网关日志里看到失败来源被自动下线又自动拉起来的过程。这种容灾能力，如果自己实现，很容易漏掉“恢复探测”这一步。

4.3 重试、熔断、超时，别让一个慢请求拖垮全链路

网关层最重要的策略是“快速失败”和“自动重试”。给请求设置一个合理超时非常重要，太短会误杀大模型长输出场景，太长会卡住业务线程池。litellm里可以区分连接阶段和读取阶段，我的建议是普通补全请求设20到30秒，流式输出可以更宽松，但要配合客户端侧的超时设置。

重试策略上，不要对所有错误都重试。值得重试的是限流错误和瞬时5xx，业务参数错误这类4xx问题重试一万次也没用。最好加上退避等待，避免上游已经过载时我们还疯狂重试把它打得更死。litellm的重试次数、等待时间、失败触发冷却的阈值都可以通过路由设置控制，这些字段在生产环境值得认真调，而不是照抄默认值。

4.4 成本与速率限制：让预算可控

网关层做计量的价值，往往比想象中大得多。litellm可以按虚拟API Key、用户或团队维度统计token消耗和费用，并设置速率上限和预算上限。团队规模变大以后，这功能几乎是刚需，否则你月底收到账单才发现某个内部服务上个月把额度刷爆了，就太晚了。

设置预算的示意如下：

general_settings: max_cost_per_key: 100 max_parallel_requests: 10

这只是示意，具体字段以版本为准。核心思想是让“花钱”这件事变得可视、可控，而不是等账单出来再复盘。我还建议在网关日志里记录每个请求对应的虚拟Key和应用来源，这样后续做成本分摊时，就不用手工翻日志对账了。

5. 实战中的细节与避坑

5.1 SDK模式和代理模式混着用，会出什么问题

最常见的问题是，把SDK模式写的代码直接搬到代理模式场景，然后发现钥匙对不上。SDK模式下，你可以在代码里直接传api_key；代理模式下，钥匙其实来自网关配置，客户端只需要带网关自己的master_key或虚拟Key。如果你在两端都传入不同来源的钥匙，很容易出现“同一个逻辑模型，在本地能调通，在代理里就报认证失败”的怪现象。

我的建议是先明确边界。SDK模式定位于开发自测，生产流量尽量走代理模式。代理模式下，业务代码不持有任何上游钥匙，只认网关的访问钥匙，这样密钥泄露面会小很多。出了问题时，排查链路也更干净：先查业务是否正常到达网关，再查网关是否成功转发到上游，两头日志一对照，问题基本就定位了。

5.2 流式输出、上下文管理、批量请求的一些注意点

litellm可以透传流式输出，使用方法和标准补全接口一致。流式模式下，网关需要保持连接更长时间，所以代理服务的空闲超时要调大，否则长响应会在中途被切断。

批量场景建议用异步方式，而不是开一堆线程硬碰硬。litellm提供异步接口，配合并发控制可以稳定跑大批量任务。至于上下文管理，litellm不会替你维护会话历史，你必须自己把多轮消息传给网关。别以为上了网关就能自动记住上下文，它只负责路由和转发。我实际做下来最顺手的做法是，业务层统一维护会话消息，调用前拼接好，网关保持无状态，这样水平扩展时才不会有会话丢失问题。

5.3 部署运维：容器化、持久化、安全加固

代理模式的部署不复杂：把配置文件和程序打成镜像，启动后暴露服务端口，前面再加一层反向代理处理TLS和访问控制。要真上生产，有几个点必须认真处理。

数据库持久化是第一个重点。litellm的虚拟Key、预算、日志默认存在本地嵌入式数据库里，进程重启后数据容易丢，生产环境一定要配置外部数据库连接串，把状态数据持久化到可靠的地方。密钥管理是第二个重点。配置文件里不要出现明文密钥，全部用环境变量引用。访问控制是第三个重点。一定要设置主钥匙，所有业务侧请求都必须携带访问凭证，不要让网关裸奔在公网。日志与监控是第四个重点。把网关访问日志接入第三方可观测平台，这样排查“为什么模型变慢了”这类问题时，才有依据而不是靠感觉。

5.4 我踩过的几次典型坑与排查思路

这张表帮我解决了日常八成问题。很多时候问题不在litellm本身，而在“模型标识”和“钥匙管理”上。先查配置再怀疑框架，会省很多时间。

6. 几点个人经验

最后分享几条我自己使用litellm的原则。第一，先把单一模型跑通，再谈路由和负载均衡，不要第一天就把复杂配置堆上去，不然出问题根本没法定位。第二，模型别名是投资回报率最高的设计，哪怕现在只有一个来源，也要用别名，因为以后一定会加模型。第三，重视日志的可观测性，网关类组件本身就是流量枢纽，如果日志不清晰，等你排查线上事故时会非常痛苦。第四，钥匙管理一定要从第一天就规范起来，环境变量引用、最小权限、定期轮换，这三件事做到位比用任何安全插件都强。

litellm不是银弹，它更像一个房间里的总电闸，帮我把散落在各处的线路收拢到一处管理。只要配置、监控、密钥三件事做扎实，后面模型接入、切换、限流这些事，都会变得简单得多。我建议你找个下午，挑两个不同来源的模型，用文中的配置示例把它跑起来，亲身体验一次“业务代码一行不改，模型来源随便换”的感觉，后面你就知道该往哪个方向使力了。