litellm实战：统一大模型API接入，实现多模型切换、代理与限流

做后端开发这几年，我经手过不少接大模型API的项目。让人头疼的往往不是某一个平台不会用，而是平台太多、接口太多。今天聊的litellm，就是专门解决这个问题的开源库。它把各种模型服务商的接口统一成一套调用方式，同时还能做代理、限流、成本统计和故障切换。如果你正在写一个同时对接多家模型的AI应用，或者要给团队搭一个统一的模型入口，这篇文章值得看完。文章里不会出现特定商业品牌名，你需要对接哪家，按文档替换成对应服务商的标识前缀和模型ID即可。

1. 为什么需要litellm：多模型接入的混乱现场

1.1 模型API的“方言”困境

先还原一下最常见的低压场景：你的应用本来只接了一家模型服务商，一切岁月静好。然后业务方提了一个需求，说要加一个备选模型，理由是"万一这家挂了，我们不至于全挂"。于是你开始读第二家的接口文档，发现请求地址不一样，认证方式不一样，请求体字段名不一样，连错误码都完全不一样。写出来的代码很快就变成一堆 if-elif 分支，每加一家，复杂度不是线性增加，而是像意大利面一样乱作一团。

这有点像去不同国家旅行，每个国家插座形状不一样。手机没电时，你得找对应标准转换头；如果一天穿越三个国家，包里要带一堆转换头。模型API也一样，各家有各家的格式、参数和限制，应用层去兼容每一家，纯属内耗。更麻烦的是，这些接口文档还会升级，参数会被弃用，旧模型会被下线。维护这套兼容逻辑的人力成本，往往比调用模型本身还要贵。

我自己做过一个内部机器人项目，最初只接了一家，后来为了降本和多地域容灾，又接了两家。刚开始还能靠几个函数适配，后来模型一多，有人改了一个适配函数，另一个业务模块立刻坏掉。最后我不得不花一整天把所有调用点改成统一入口，但仍然担心下次新增模型要怎么办。这种痛点，应该不少读者都体会过。

1.2 litellm如何“翻译”和“统一”

litellm做的事并不复杂：它把上游各家API的差异，都封装在库内部，对外暴露一个统一请求结构。这个结构选择的是当前社区里最普遍、最接近事实标准的那套聊天补全格式。也就是说，你在代码里写一次请求体，就能发给不同的模型服务商。

它做了三件事：接口归一、参数归一、错误归一。

接口归一，指请求的路径、认证头、请求体、返回结构都由litellm统一。你不需要关心上游地址是/v1/chat/completions还是别的什么，只要按litellm的格式调用，它帮你翻译过去。返回时，它也会把各家五花八门的响应字段整理成同一个结构，你的业务代码拿到的永远是熟悉的那几个字段：choices、message、usage。

参数归一，指像temperature、max_tokens、stream这类通用参数，litellm会映射到各个平台对应的写法。有些平台的字段名不同，有些平台还多了限制，litellm在内部做了很多转换工作。至于每个平台特有的参数，它也留了透传口子，你可以把原始参数原样传进去。这保证了能力不会因为统一封装而被阉割。

错误归一，指它把上游返回的认证失败、限流、模型不存在等问题，统一映射成图书馆级的Python异常。业务代码里只要捕获一个异常类型，就能统一处理所有平台的错误，这对做重试和兜底帮助极大。

这层封装对业务的价值很直接：只要你的业务代码依赖litellm的接口，底层从A平台切换到B平台，通常只需要改一行模型标识。上层逻辑不用动，成本统计、灰度切换、故障回退都有空间去做了。

2. 从零开始落地：Python调用与接入准备

2.1 安装与第一个请求

litellm是一个Python库，安装方式很常规：

pip install litellm

装完之后，第一件事是配置平台密钥。它默认从环境变量里读API key，所以你需要把某个平台的密钥设置成对应的环境变量。不同平台对应的变量名不同，你可以查一下当前版本的文档，或者在代码里直接用api_key参数传入。个人习惯是统一用环境变量，因为这样代码里不出现密钥，也方便在不同环境里切换。

设置好密钥后，写一个最基本的请求：

import litellm litellm.set_verbose = True # 调试时可以打开，看到真实请求 response = litellm.completion( model="provider-a/model-x", messages=[ {"role": "user", "content": "你好，介绍一下你自己"} ], ) print(response["choices"][0]["message"]["content"])

这里model参数要拆开看：provider-a是litellm内部使用的平台标识前缀，用来告诉它该把请求转发给谁；model-x是你在该平台侧的真实模型ID。中间的斜杠是分隔符。如果你只填了model-x，litellm会默认按当前主流平台格式处理，但更稳妥的做法是带上前缀。

第一次请求如果被拒，别急着怀疑代码，先开litellm.set_verbose = True看看它实际发出的URL和请求体。这个开关是我强烈建议新手先打开的，因为能直接看到litellm是否已经把参数翻译正确，也能快速判断是密钥问题还是模型标识问题。

跑通一个请求后，你就有了一个最简单的模型接入点。接下来所有复杂功能，都是在这个基础上长出来的。

2.2 从“写死一家”到“随时切换”

很多项目的前期版本都是把模型名写死在代码里，比如直接在函数里填一个字符串。一旦要切换，就得改代码、发版、重启。用litellm的话，最值钱的改变就是把模型名从硬编码中解放出来。

我一般会先建一个模型映射配置：

MODELS = { "default": "provider-a/model-x", "coder": "provider-b/model-y", "cheap": "provider-c/model-z", }

然后在所有调用点里，只按场景选择key：

def chat(question: str, scene: str = "default"): model = MODELS.get(scene, MODELS["default"]) response = litellm.completion( model=model, messages=[{"role": "user", "content": question}], ) return response["choices"][0]["message"]["content"]

这样做的价值不是避免打字，而是让模型选择变成一个运行时变量。你可以把scene存到用户配置里，也可以做成接口参数，甚至接到灰度开关上。业务方说"我想把某条业务线的模型换成便宜的那个"，你只需要改一行配置，而不是翻代码。

更进一步，模型映射表也可以放到环境变量或配置文件里。我的做法是放在YAML里，服务启动时加载。这样运营人员在后台改配置就行，代码完全不用动。当然，模型切换不只是改名字那么简单，新模型的温度、最大token、提示词风格都可能要配合调整，所以建议用一套完整的"模型配置项"来表示，而不是只有一个字符串。

2.3 环境变量与密钥管理

密钥管理是接模型API最容易翻车的地方。哪怕是小项目，我也不建议把密钥硬编码到代码里，因为你不知道哪天这个仓库会被推到公开平台，或者被同事截图发出去。所有密钥都应该从环境变量或密钥管理系统读取。

litellm的惯例是把各平台密钥放在特定的环境变量名里，像这样：

export PROVIDER_A_API_KEY="sk-xxxxxx" export PROVIDER_B_API_KEY="sk-yyyyyy"

如果你需要在代码层面覆盖，也可以传入api_key参数，但这样容易导致密钥散落在代码里。我更推荐统一的环境变量方案，然后在团队文档里维护一张"每个平台对应哪个环境变量"的表。

本地开发时，可以用.env文件加上python-dotenv来加载。服务器上则用容器环境变量或密钥管理服务。如果团队多人共用一套平台账号，强烈建议引入代理模式，让成员不要直接使用上游密钥。这个我后面会详细讲。

还有一个小坑：不同平台的密钥有时长得差不多，但放到错误的环境变量里，litellm并不会立刻报错，而是会得到认证失败或404。排错时，先用os.environ.get("PROVIDER_A_API_KEY")确认环境变量确实读到了，再去看模型标识，这能省下不少时间。

3. 代理模式：给团队一个AI网关

3.1 为什么需要代理层

如果只是个人项目，直接用Python库就够了。但一旦进入团队协作，就会出现新的麻烦：每个开发都持有上游密钥，有人写代码时把密钥打印进日志；不同项目分别接模型，成本无法统一统计；想限制某个成员的使用量，也做不到。

litellm除了当Python库用，还内置了一个代理服务器。这个代理本质上是把你所有上游模型服务集中到一个入口，内部统一管理密钥、模型映射、限流和日志。业务方只需要面对一个标准API，连你后面到底换了哪家模型都不一定知道。

这种架构很像你们公司的对外网关：外面的人不需要知道内部有哪些机器，只要知道网关心跳，就能拿到想要的响应。代理能做权限隔离，也能做流量控制。所以我说它是"AI网关"。

使用代理模式后，上游密钥只保存在代理服务器环境里，业务方拿到的只是一个代理专用key。就算key泄露，也只是代理接入凭证，而不是某个平台的主账号，损失可控。同时，所有请求都经过代理，费用和用量也就自然地沉淀在代理日志里，方便管理。

3.2 配置文件的写法与启动

代理模式用YAML文件定义"对外模型名"和"内部模型映射"。先看一个最简配置：

model_list: - model_name: chat-main litellm_params: model: provider-a/model-x api_key: os.environ/PROVIDER_A_API_KEY - model_name: chat-backup litellm_params: model: provider-b/model-y

这里的model_name是你给外部用户看的名字，可以自己起。比如业务方要求"给我一个通用对话模型"，你就给他chat-main；有一天你想把背后实现换成另一家，只需要改litellm_params里的model，业务方完全无感。

启动代理也很简单：

litellm --config config.yaml --port 8000

启动时，代理会先加载配置文件，读取环境变量，然后对外开放一个HTTP服务。如果你还在本机测试，日志里会有一个master key，请求时要带上。生产环境下，建议通过LITELLM_MASTER_KEY环境变量提前设置主密钥，不要用自动生成的临时key。

配置文件里还可以加很多字段，比如每个模型的限流参数、重试参数，甚至自定义prompt模板。建议一开始只配两三个模型，确保能跑通，再逐步加复杂度。不要第一版就想把十几个模型全部塞进配置，那样出了问题都不知道怪谁。

3.3 用标准格式调用代理

代理对外提供的接口是标准的聊天补全格式。无论后端接的是什么平台，外部调用方式都一致。我用curl演示一个最常用的请求：

curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-your-master-key" \ -d '{ "model": "chat-main", "messages": [ {"role": "user", "content": "你好"} ] }'

你完全可以把这里的chat-main当成一个普通模型名来用，返回结构里的choices、message、usage都符合大家熟悉的格式。如果你的后端服务已经用了某个主流平台的SDK，多数情况下只要改一下base_url指向http://localhost:8000，再改下密钥，就能无缝切换。

流式请求也支持，把请求体里加"stream": true即可。但要注意，代理在流式模式下转发的是上游的流式字节流，不像普通请求那样有统一处理的余地。后面的章节我会专门讲流式里的坑。

我实际用过一段时间代理模式后，最大的感受是：运维终于不用追着每个项目去问"你的密钥在哪儿了"，模型侧的故障也可以集中处理。给团队立规矩的时候，我通常建议"默认走代理，例外才直连"。

4. 进阶能力：失败兜底、限流与费用追踪

4.1 fallback：让服务在波动下不中断

模型服务商也会挂，也会限流，也会因为网络拥塞而响应超时。如果你的应用只有一个模型依赖，一旦它出问题，用户面前就是一片空白。litellm的fallback功能就是为这种情况准备的。

fallback的意思是：当首选模型失败时，自动改发到备用模型。最简单的配置是直接在模型参数里加fallbacks数组：

model_list: - model_name: chat litellm_params: model: provider-a/model-x fallbacks: ["provider-b/model-y"]

这样当provider-a/model-x请求失败时，litellm会自动尝试provider-b/model-y。业务方依然调用model: chat，不需要知道底层切换。

如果你用Python的Router对象，还能做更细的控制。Router可以管理一组模型deployment，并支持加权路由、健康检查、重试策略。举个例子：

from litellm import Router router = Router(model_list=[ {"model_name": "chat", "litellm_params": {"model": "provider-a/model-x"}}, {"model_name": "chat", "litellm_params": {"model": "provider-b/model-y"}}, ]) response = router.completion( model="chat", messages=[{"role": "user", "content": "你好"}], )

Router会按配置顺序尝试上游，一个失败就换下一个。这个功能在线上的价值很大，特别是你做过灰度发布或者经历过上游故障时，能明显体会到什么叫"有备无患"。

不过要注意，fallback不是万能的。如果业务对模型输出风格有严格要求，备用模型返回的内容可能和首选模型差异很大。我的建议是：核心任务用相同的提示词和参数在两个模型上各测一轮，确认输出质量达标，再把备用模型放进fallback列表。否则，你以为的兜底可能只是在用户面前换了个人胡说八道。

4.2 重试与限流：把故障交给框架

调用大模型API，限流几乎是必遇的坑。各家平台的限流维度还不一样，有的是每分钟请求数，有的是每分钟token数，还有的是并发数。你对上游请求太猛，轻则响应变慢，重则被429错误砸脸。

litellm在客户端侧做了限流机制。比如可以在model_list里给每个deployment配置rpm（每分钟请求数）和tpm（每分钟token数）：

model_list: - model_name: chat litellm_params: model: provider-a/model-x rpm: 100 tpm: 50000

配置后，litellm会自己控制请求速率，把流量打散到限制范围以内。这样虽然会稍微拖慢一点请求的发起节奏，但能避免触发上游的惩罚性限流。与其让上游在高峰期打回头再退避，不如自己先排队，整体稳定性反而更好。

重试方面，litellm也有内置策略。你可以设置重试次数和超时时间：

import litellm litellm.num_retries = 3 litellm.request_timeout = 60

超时设置尤其重要。有些模型响应确实慢，但如果你把超时设得太短，会误杀正常请求；设得太长，用户体验又变差。我一般从30秒开始试，看线上P95延迟再动态调整。重试次数我通常控制在2到3次，因为如果连续三次都失败，大概率不是瞬时抖动，再重试只会浪费成本。

还有个容易忽略的点：流式请求的重试逻辑比普通请求复杂。因为流式连接一旦建立，可能已经产生了部分输出，强行重试可能导致用户看到输出跳变。所以对于流式对话，我更倾向于在业务层做"超时后重新生成"的处理，而不是完全依赖框架自动重试。

4.3 成本与用量统计：不做糊涂账

老板问你这个月模型花了多少钱，你要是答不上来，那项目预算就危险了。litellm对每个请求都会记录token的使用情况，返回里的usage字段是现成的：

print(response["usage"]) # 输出示例: {'prompt_tokens': 35, 'completion_tokens': 120, 'total_tokens': 155}

你自己写日志时，完全可以把这个usage带到业务日志系统里，按天、按业务线汇总。代理模式下更省事，所有请求都会经过它，你可以在代理日志里做统计，也可以对接外部监控。

如果你想从预算源头卡住开销，litellm还支持设置预算上限：

general_settings: max_budget: 100

超出预算后，代理会拒绝新的请求。这个功能适合做风控，防止测试人员把key打到失控。预算单位通常按美元计，但不同模型成本差异大，配置前要先确认单位。

为了把成本统计做细，我一般会强制每个业务线使用不同的model_name和代理key。这样财务拆账的时候，只要按model_name分组，就能知道是哪个业务线烧的钱。这也是代理模式比直连库方便的地方：直连库时，每个服务自己打日志，格式五花八门，最后很难汇总。

5. 常见问题与避坑记录

5.1 认证与模型标识类错误

我在踩坑群里最常看到的问题就是AuthenticationError。这个异常的常见原因有三类：环境变量没生效、密钥本身错误、平台侧账号欠费或权限不足。排查时不要只盯着代码，先确认环境变量：

echo $PROVIDER_A_API_KEY

如果输出是空的，那问题多半在部署环境没正确注入密钥。如果在本地能跑、服务器上不能用，重点看部署平台的密钥配置。

另一类高频错误是模型标识写错。litellm的model参数里，斜杠前面的平台前缀拼错，它会尝试路由到错误的平台；斜杠后面的模型ID拼错，通常会在上游返回模型不存在。这种错误往往只在某些平台出现，因为不同平台对模型ID的大小写很敏感。我遇到过有人把model-x写成了Model-X，结果404。建议复制官方文档里的ID，而不是自己手打。

我整理了一个排查速查表：

5.2 参数兼容与工具调用

litellm声称统一了参数，但不同平台的能力边界客观存在。比如有的模型不支持temperature，你传了就会报错；有的模型对max_tokens有上限，传太大会被拒绝。这些不是litellm的bug，而是上游模型的限制。

我的经验是：先用最小参数集跑通，再逐步加参数。把请求体精简到只有model和messages，确认无误后，再加上temperature、max_tokens等，每次只加一个。这样一旦报错，你立刻知道是谁的问题。

模型工具调用是另一个大坑。不同平台的函数调用（function calling）格式差异很大，litellm会做一些转换，但复杂schema偶尔还是会丢字段。如果你的业务重度使用工具调用，不要指望litellm把所有差异都抹平。建议在测试环境里把每一种工具定义都过一遍，确认字段能正确传给上游。

如果遇到litellm转换不了的平台特有参数，它支持透传原始参数。你可以在调用时传入extra_body，把平台原始字段塞进去。但说实话，这个功能要慎用，因为一旦用了，你的代码就又开始依赖特定平台了。能用统一参数解决的就用统一参数，透传参数只做最后手段。

5.3 性能、超时与流式处理的注意点

使用litellm之后，性能瓶颈往往从"没有适配层"变成了"代理转发开销"和"模型本身延迟"。直连库模式下，litellm只是一个Python调用库，开销很小；代理模式下，每一条请求都要经过代理转发，网络链路变长，延迟会略有增加。

对于响应速度敏感的业务，我建议先测一下代理的纯转发延迟。如果本机直连模型是1秒，通过代理变成1.5秒，你可以接受吗？不能的话，考虑让代理和业务服务部署在同一内网区域，减少网络跳数。

流式处理有个具体注意点：开启stream=True后，返回值是一个迭代器。你不能再沿用普通模式的response["choices"]结构，而要逐块读取增量。不同平台的流式增量格式略有差异，litellm已经做了转换，但你的代码仍要按流式接口来写。如果处理不当，常见问题是首字延迟（TTFT）变高，但实际首字在网络中已经到了。建议在代理和业务侧都测一下响应时间，定位延迟发生在哪一段。

高并发场景下，如果只有一个代理实例，它肯定会成为瓶颈。litellm代理是支持横向扩展的，可以在多个实例后面挂负载均衡。此时要注意配置里的密钥和配置一致性，不要让两个实例拿到的模型列表不一样，否则排查问题时会非常痛苦。

我还建议在代理层接入结构化日志，每个请求记录model_name、上游模型、延迟、token用量、成功失败状态。这样后续做监控和成本分析，都有据可查。不要等到出了问题才去翻日志，那时候你会发现什么日志都没有，只能干瞪眼。

最后再分享一个个人经验：litellm适合当"统一入口"，但不要把它当成一个可以让你完全不懂底层模型的魔法层。我用它接了好几个平台之后，最大的体会是“适配层解决的是格式问题，解决不了模型能力差异”。你仍然要清楚每个模型擅长什么、不擅长什么，才能设计好fallback和路由策略。如果你从一开始就把模型名配置化，把密钥收口到环境变量，切表和扩表都会变得非常轻松。实际上，我现在接手任何新的模型项目，第一件事就是搭一个litellm的最小调用，然后才写业务逻辑。这个习惯帮我省掉了大量反复修改适配代码的时间，希望能对你有用。