上个月我在做内部工具的时候需要同时接入三家不同厂商的大模型接口。第一家要 Authorization 头第二家把参数放在请求体里起另一个名字第三家连错误码风格都不一样。光是适配这三个接口就花了我两天时间。后来我发现了 litellm 这个项目它基本把这类兼容问题一次性解决了。litellm 本质上是一个“大模型统一调用层”你只需要学会一套请求格式就能在前面的主流闭源平台、开源模型服务甚至本地部署模型之间自由切换。它既可以用 Python 库的方式被直接 import 进代码也可以作为一个独立的代理服务部署在团队内部统一管理密钥、花费和流量。这篇文章我会从为什么需要这种抽象层讲起然后给出可复现的接入步骤、代理服务部署方案最后聊聊我实际踩过的几个坑。如果你手上有 AI 功能要做而且大概率未来会换模型或者接多家模型这篇应该能帮你省不少时间。1. 为什么需要一层“模型统一适配层”我切换模型时的真实痛点先别急着聊工具我想先还原一下大多数人第一次接大模型接口时的场景。你选中了一家主流供应商把它的 SDK 文档翻出来先是搞明白鉴权方式再是处理流式响应里的数据格式最后还要自己写一套重试逻辑。好不容易跑通了过三个月业务方跟你说“成本控制不住换另一家试试吧”结果一看新供应商的文档请求结构是另起炉灶的连流式返回的字段名都不同。于是又是一轮加班。这种痛苦本质上是“接口碎片化”造成的。大模型的 API 看起来都在做同一件事——把一段文本发给模型拿到补全结果——但在细节上却是各家独立王国鉴权头不同、消息结构不同、温度等采样参数的命名不同、报错码体系不同、限流策略不同。同一个功能你为每家用一份代码去适配维护成本随供应商数量线性上涨。这还没算上密钥管理、账单归集和模型效果对比这些衍生问题。统一适配层的思路就是加一个中间层把所有差异挡在外面。litellm 做的就是这件事它向外暴露的是一套统一的、兼容主流 chat completions 语义的接口向内它把请求翻译成各家各自的格式再把各家返回的结果翻译回统一格式。这套翻译工作其实挺繁琐的因为光参数映射就有几十个字段更不用说那些非标准的图片输入、工具调用等扩展能力。好在 litellm 把这些细节都封装掉了对业务代码来说你永远只跟一种格式打交道。什么时候值得引入这样一层我个人判断标准有三个第一你当前或未来会同时使用两家以上大模型服务第二你有切换模型供应商的可能性哪怕只是一个备用方案第三你不想把各家 SDK 的复杂性渗透到业务代码里。反过来如果只是某机制下的一个固定模型开发一次性脚本那直接用官方 SDK 反而更简单没必要多加一个依赖。这是似非而是的地方——抽象层的价值恰恰体现在“变”的那一刻。1.1 不同厂商接口差异到底有多大我整理了一个表格来说明这种差异不一定精确到每个版本但足够让你直观感受到碎片化程度对比维度平台A平台B平台C鉴权方式Bearer TokenAPI-Key 请求头签名认证核心请求体messages 数组prompt 字符串两者混合采样参数temperaturetemperaturetop_p 为主流式格式SSE data 前缀关键在响应体尾部二进制分块错误码401/429/500 语义清晰全用 400 兜底各自封装错误对象同一套业务逻辑在平台A上写出来的代码搬到平台C基本要重写解析层。而 litellm 内部维护了一个庞大的 provider 映射表每个 provider 声明自己的 base_url、鉴权方式、参数映射关系甚至错误码翻译规则。用的时候传入一个类似vendor-a/text-chat-xl这样的模型名它就自动路由到对应的 handler。这点也是我建议新手理解 litellm 时抓住的核心它与其说是一个 SDK不如说是一张不断在更新的“接口翻译对照表”。1.2 用适配器思路看 litellm 的底层逻辑熟悉设计模式的人一眼就能认出来这就是适配器模式目标接口是统一的 chat completions 协议适配者是各个供应商的 SDK 或 HTTP 接口适配器就是那些 per-provider 的 handler。好处是你业务代码依赖的是抽象接口而不是具体实现。如果你想替换模型只需要改一行模型名甚至通过配置项在运行时切换完全不用动消息构造逻辑。这个设计也决定了 litellm 的一个特性它并不想替代任何供应商的完整能力而是保证“常用能力的子集”在统一接口上可用。所以它官方文档里总在强调“支持 100 多家 LLM API”但落实到某个边缘特性上不同 provider 的支持度是不一样的。起步时你把它当成一个“把 complexity 收敛到一点”的工具来用认知负担会小很多。2. 快速试水用 Python SDK 把多模型接进同一套代码说再多原理不如直接上手。litellm 的 Python SDK 是最轻量的使用方式特别适合脚本工具、内部 Demo、或者在现有项目里快速集成。安装很简单pip install litellm[proxy]如果你只需要 SDK 不需要代理服务直接pip install litellm就行。那个[proxy]额外装的其实是后面章节要讲的 FastAPI 相关依赖。首次接触的话我建议先装完整版省得到时候切换网关方案又要重新装一遍。2.1 第一次调用三行代码换三家模型初始化后直接用completion函数发起请求。这是在写统一调用的关键所有模型都走同一个入口差别只在model字符串import litellm messages [{role: user, content: 用一句话解释什么是接口适配层}] # 切换模型只改这一行 resp_a litellm.completion( modelvendor-a/text-chat-xl, messagesmessages, api_key你的key_a ) resp_b litellm.completion( modelvendor-b/deep-think-1, messagesmessages, api_key你的key_b ) print(resp_a.choices[0].message.content) print(resp_b.choices[0].message.content)你没看错接口确实一模一样。我第一次用的时候也有点不真实的感觉——原先那套适配代码就这么被省掉了。choices[0].message.content这个访问路径也统一了不用再管各家返回结构里是text还是content。如果你的api_key已经放到环境变量里了比如VENDOR_A_API_KEY那么在completion里可以完全不传api_key参数。litellm 的规则是在环境变量里找它自己约定的变量名找不到就用 provider 官方的变量名再找不到才报错。这个设计对统一密钥管理很有帮助尤其在后文讲代理网关时。2.2 流式输出与工具调用的统一处理日常开发中除了普通补全流式输出几乎是必选项。litellm 对流式的支持方式也让业务代码保持简单resp litellm.completion( modelvendor-a/text-chat-xl, messagesmessages, streamTrue ) for chunk in resp: delta chunk[choices][0][delta][content] if delta: print(delta, end)每家的流式格式差异在这里被抹平了你拿到的是一个统一格式的增量对象。这对于做打字机效果的前端非常友好后端只需要维护一套流解析逻辑。同样现在各家都在推函数调用function/tool call用 litellm 也基本是同一套写法在请求里声明 tools 列表收到响应后读choices[0].message.tool_calls。注意不同 provider 对工具调用的支持程度不一样有的支持多轮工具循环有的只支持单轮。实操时如果遇到奇怪现象先看是不是 provider 自身版本的限制再怀疑 litellm。2.3 错误处理与自动重试出问题别慌网络请求总有失败的时候模型的 API 尤其如此限流、超时、服务端繁忙都是家常便饭。litellm 提供了litellm.completion_with_retries它包装了指数退避重试逻辑也遵循统一的异常类型比如RateLimitError、TimeoutError、APIError。代码上你只需要捕捉少数几个异常from litellm import RateLimitError, APIConnectionError try: resp litellm.completion_with_retries( modelvendor-b/deep-think-1, messagesmessages, num_retries3, timeout30 ) except RateLimitError: # 这里可以做排队提示而不是直接对用户报错 print(当前请求太多稍后再试) except APIConnectionError: # 切换备用模型 resp litellm.completion(modelvendor-a/text-chat-xl, messagesmessages)这里有个细节num_retries3只在可重试的异常上工作并不是所有异常都会重试。比如你的请求参数写错了导致 400重试一百次也没用litellm 也不会浪费那个次数。遇到 4xx 错误第一时间去查消息体和模型名遇到 5xx 或网络异常才交给重试逻辑。这种语义区分很符合直觉但确实需要使用者自己心里有数。2.4 用量统计与成本控制SDK 模式还有一个容易被忽略但很好用的能力litellm.response_cost(resp)。把一次请求的响应对象丢进去它就能算出这次调用花了多少钱因为它内部存了各家模型的 token 定价表。cost litellm.response_cost(resp) print(f本次请求成本: ${cost})这个功能看着不起眼实际价值非常大。我接完第一个 Demo 后把每次调用的 cost 打到日志里跑了两天就发现了某个模型在低延迟场景下性价比明显更差。后续做模型选型时这份日志是最有说服力的数据。就算你现在还没有成本优化压力我也建议从一开始就把 token 消耗和成本打进监控里后面真的想省钱了至少不会没有数据基础。3. 从个人脚本升级到团队网关Proxy 模式实战SDK 模式适合单机脚本和早期验证但到了团队协作阶段问题就来了群里传 API Key新人不知道用哪家环境变量每个服务各自消费花费、账单对不齐。这种局面下litellm 提供的 Proxy 模式也就是它的代理服务才是正解。Proxy 模式说白了就是部署一个轻量的 HTTP 服务统一对外暴露聊天补全接口。团队里的所有业务后端都只对接这个服务真正的上游模型密钥、模型切换、负载均衡和花费统计都沉淀在 Proxy 这一层。业务方拿到的只是一个虚拟 API Key完全可以按项目、按人独立签发。3.1 最小可用配置一份 config.yaml 跑起来Proxy 靠一个 YAML 文件描述模型列表和管理规则。这是我最小的可用配置model_list: - model_name: main-chat litellm_params: model: vendor-a/text-chat-xl api_key: os.environ/VENDOR_A_KEY - model_name: fallback-chat litellm_params: model: vendor-b/deep-think-1 api_key: os.environ/VENDOR_B_KEYmodel_name是对外可见的模型名业务方只认这个名字。litellm_params.model才是真正映射到上游的模型标识。重点来了api_key推荐用os.environ/XXX这种形式让 Proxy 从环境变量里读取真实密钥YAML 文件本身不落任何明文密钥这一点在团队共享仓库时特别重要。启动服务只需要一条命令litellm --config config.yaml --port 4000默认情况下它会起一个本地服务对外暴露兼容 chat completions 语法的端点。这时候业务后端可以这样调用curl http://localhost:4000/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-your-virtual-key \ -d {model: main-chat, messages: [{role: user, content: 你好}]}第三方 SDK 甚至能直接把它当成一个标准 endpoint 接入只需把 base_url 指向http://localhost:4000。这意味着你团队里已有的代码框架、开源应用只要支持标准接口都能几乎零成本切换到统一网关上来。3.2 虚拟密钥给每个人都发一把“租来的钥匙”Proxy 模式下最核心的管理能力是虚拟密钥。它跟上游真实密钥是两回事虚拟密钥是 Proxy 自己签发的绑定调用权限、速率上限和花费配额。你完全可以给每个开发、每个应用、甚至每个环境各发一把curl http://localhost:4000/key/generate \ -H Authorization: Bearer sk-master-key \ -H Content-Type: application/json \ -d { models: [main-chat, fallback-chat], max_budget: 50, budget_duration: 30d }响应里会给你一个sk-开头的虚拟 key。这个 key 只能在你的网关内使用即便泄露了影响范围也仅局限在网关许可的模型和预算之内上游真实密钥完全不可见。我不止一次看到有人把真实上游 key 直接写死在业务容器环境变量里一旦泄露就是直接的经济损失。用 Proxy 做一层隔断之后真实 key 只存在于网关服务器的环境变量中安全边界清晰很多。3.3 预算观测用数据复盘每次模型调用预算控制写完还得看得到用量。Proxy 提供了几个管理端点查询起来非常方便。你会得到一个类似一账本的视图哪个虚拟 key 花了多少、调用了多少次、分别用了哪些模型、每次响应延迟如何。我当时给团队搭好网关后最直观的感受是之前月底对账单要对半天现在从面板上拉个表格就能跟财务说清楚。而且因为虚拟 key 可以按客户维度签发哪个业务线消耗了多少成本、需不需要限额几乎是一目了然。做 AI 功能最容易失控的就是成本有一个能随时拉数据的网关心里会踏实很多。4. 流量调度与稳定性多模型备胎和本地模型接入Proxy 跑通之后很多人会想再做一步让流量在多个模型之间智能调度实现高可用和成本优化。litellm 在这一层提供了路由、重试、熔断等不少功能。这一章节就讲我在生产环境里实际用到、且验证有效的几项。4.1 同一逻辑名背后挂多个实际模型所谓“逻辑模型名 多个部署”核心配置是在model_list里让多个litellm_params共用同一个model_namemodel_list: - model_name: main-chat litellm_params: model: vendor-a/text-chat-xl api_key: os.environ/VENDOR_A_KEY model_info: weight: 700 - model_name: main-chat litellm_params: model: vendor-b/deep-think-1 api_key: os.environ/VENDOR_B_KEY model_info: weight: 300对外依然是同一个main-chat内部流量默认按权重分发七成走 vendor-a三成走 vendor-b。这种配置最有价值的场景是模型上线灰度新模型接进来只给 5% 流量跑几天看效果再逐步调高权重。不用改业务代码不用通知下游更新路由只改一个 YAML 然后热加载配置即可。我当时把一个新模型从 0% 到 100% 切了两周整个切换过程下游完全无感。4.2 重试、超时和区域降级请求必然有失败。路由模式下 litellm 会在一个模型出问题时自动把请求重试到另一个模型前提是你配置了fallbackslitellm_settings: fallbacks: [{main-chat: [fallback-chat]}]含义是main-chat失败后自动尝试fallback-chat。同时你还能设置每类请求的超时时间litellm_settings: num_retries: 3 request_timeout: 30 allowed_fails: 3 cooldown_time: 60allowed_fails和cooldown_time合起来是一种简单的熔断策略连续失败三次的模型会被冷却一分钟期间流量自动切给别的可用模型而不是继续傻傻地往一个不可用端点打请求。这套机制对线上稳定性提升很明显尤其是遇到某个厂商大范围故障的时候你的服务不会跟着一起瘫痪。4.3 把私有化部署的模型也收编进网关再顺带说一个我看重的能力litellm 不只接各家云厂商 API还能把本地用 vLLM、Ollama 之类框架起的大模型也接入统一网关。配置上和普通上游差不多只是把model指向本地服务地址即可model_list: - model_name: local-chat litellm_params: model: local/my-local-llm api_base: http://127.0.0.1:8000/v1这里api_base就是本地推理服务的地址。接进来之后业务方对它是云上 API 还是本地私有模型完全无感知。这种用法在数据敏感的私有化场景里非常实用对外只暴露统一接口背后的数据不出内网同时还能享受网关的密钥、限流和日志能力。5. 踩坑记录与兼容性边界哪些场景会让它翻车任何工具都有适用范围和死角。litellm 给我的整体感受是“覆盖率很高但远非万能”。下面这些坑是我实际使用中踩过的写出来帮大家少走弯路。5.1 参数透传不是百分之百完整我在用某个支持图片输入的模型时需要传一个非标准的图像参数。控制台文档里明确写了这个参数怎么传但通过 litellm 的images字段传过去对方接口并没有正确响应。定位后发现litellm 的 provider handler 里跟这个特定参数相关的映射没覆盖到。这个问题在非主流模型和新功能上尤其明显。处理思路有两个一是先用litellm.get_supported_openai_params(model...)查看某个模型支持哪些统一参数确认你的参数在当前版本是否被覆盖二是确实缺了就用additional_args之类的透传机制绕一下但不要抱太高期望。遇到这种情况我会先去项目仓库看这个 provider 的实现再决定要不要自己提交补丁或者降级处理。5.2 认准模型名拼写的血泪教训模型名拼错是最高频的入门事故。比如把一个平台的模型标识里多打了一个横杠litellm 不认识直接抛错。它内部维护了一张模型名到定价和上下文长度的对照表拼错会导致成本计算异常、上下文窗口判断错误甚至请求直接被拒。规范做法是每次接新模型前用litellm.model_list或官方文档确认精确的模型名称。另外要区分“模型别名”和“provider 真实模型名”。你在配置文件里定义的model_name是给自己看的逻辑名可以随便起但litellm_params.model必须跟供应商那边完全一致。我在一次升级版本后遇到过推理服务换了 API 路径导致全部 404排查半天才发现是上游兼容层的问题不是 litellm 的问题。5.3 请求超长被静默截断或报错大模型上下文有限这个问题其实跟 litellm 没有直接关系但在统一层接入多模型后问题变得更隐蔽。不同模型的上下文窗口大小不同vendor-a支持 128Kvendor-b可能只有 32K。你用同一个 Prompt 在 A 上跑得好好的路由到 B 上可能直接报“上下文过长”。litellm 的模型表会给部分模型提供上下文长度信息但也不是每个 provider 都准确。我的经验是在应用层做一个 Prompt 长度预检按照当前路由模型的最小上下文窗口去截断或压缩。如果你依赖 litellm 的自动处理大概率会在最不该出问题的时候迎来意外。5.4 什么时候别用它最后聊一下边界。如果你团队只有一家模型供应商且未来不可能换或者你的场景极其简单就是一个静态model某个固定模型的脚本那直接用官方 SDK 反而更直接。引入 litellm 毕竟多了一层抽象多一个依赖就多一份需要跟踪的兼容性问题这并非没有成本。另一种情况是你要自研一个超高吞吐的网关。litellm 的 Proxy 性能还不错但它毕竟是通用型实现不是专为极限吞吐设计的网关。如果你的核心目标是极致的请求转发效率和灰度路由控制像 APISIX 这类通用 API 网关配合你自己的转发逻辑反而更可控。litellm 的强项是模型兼容转换和模型管理它并非要在所有场景里都当主角。结尾一个关于抽象层的个人体会透过 litellm 我想多说一层判断一个抽象层工具好不好不是看它当下能不能跑通而是看它能不能真的简化“变化”。我经历过“上游模型厂商调整了接口格式导致全线代码改动”那种事之后就确立了在 AI 应用里先加一层适配层的习惯。哪怕你当下只接了一个模型只要这层接口是标准的、中立的未来切换和扩展的成本就能压在可控范围。具体到 litellm我个人的建议是先在小项目里用 SDK 模式验证它对模型的支持度跑两三天后如果不出大问题再考虑部署 Proxy 供团队使用。部署的时候从一开始就把虚拟密钥、预算上限和成本日志都打开不要等到模型调用量上来了再补救。顺带分享一个小技巧如果你在 Proxy 里已经配了很多模型可以在业务代码里加一个轻量的“健康检查”定时调用一个极小 token 的补全任务遇到连续失败就触发告警。我曾凭这个检查提前发现某上游模型因为版权调整临时下线避免了业务大面积异常。工具只是加速器监控和使用规范才是系统稳定性的真正底座。 
长河君 · 2026/10/14 9:24:57 · 阅读 1.2k 大模型接口统一调用与网关实战：用litellm解决多模型接入难题
上个月我在做内部工具的时候需要同时接入三家不同厂商的大模型接口。第一家要 Authorization 头第二家把参数放在请求体里起另一个名字第三家连错误码风格都不一样。光是适配这三个接口就花了我两天时间。后来我发现了 litellm 这个项目它基本把这类兼容问题一次性解决了。litellm 本质上是一个“大模型统一调用层”你只需要学会一套请求格式就能在前面的主流闭源平台、开源模型服务甚至本地部署模型之间自由切换。它既可以用 Python 库的方式被直接 import 进代码也可以作为一个独立的代理服务部署在团队内部统一管理密钥、花费和流量。这篇文章我会从为什么需要这种抽象层讲起然后给出可复现的接入步骤、代理服务部署方案最后聊聊我实际踩过的几个坑。如果你手上有 AI 功能要做而且大概率未来会换模型或者接多家模型这篇应该能帮你省不少时间。1. 为什么需要一层“模型统一适配层”我切换模型时的真实痛点先别急着聊工具我想先还原一下大多数人第一次接大模型接口时的场景。你选中了一家主流供应商把它的 SDK 文档翻出来先是搞明白鉴权方式再是处理流式响应里的数据格式最后还要自己写一套重试逻辑。好不容易跑通了过三个月业务方跟你说“成本控制不住换另一家试试吧”结果一看新供应商的文档请求结构是另起炉灶的连流式返回的字段名都不同。于是又是一轮加班。这种痛苦本质上是“接口碎片化”造成的。大模型的 API 看起来都在做同一件事——把一段文本发给模型拿到补全结果——但在细节上却是各家独立王国鉴权头不同、消息结构不同、温度等采样参数的命名不同、报错码体系不同、限流策略不同。同一个功能你为每家用一份代码去适配维护成本随供应商数量线性上涨。这还没算上密钥管理、账单归集和模型效果对比这些衍生问题。统一适配层的思路就是加一个中间层把所有差异挡在外面。litellm 做的就是这件事它向外暴露的是一套统一的、兼容主流 chat completions 语义的接口向内它把请求翻译成各家各自的格式再把各家返回的结果翻译回统一格式。这套翻译工作其实挺繁琐的因为光参数映射就有几十个字段更不用说那些非标准的图片输入、工具调用等扩展能力。好在 litellm 把这些细节都封装掉了对业务代码来说你永远只跟一种格式打交道。什么时候值得引入这样一层我个人判断标准有三个第一你当前或未来会同时使用两家以上大模型服务第二你有切换模型供应商的可能性哪怕只是一个备用方案第三你不想把各家 SDK 的复杂性渗透到业务代码里。反过来如果只是某机制下的一个固定模型开发一次性脚本那直接用官方 SDK 反而更简单没必要多加一个依赖。这是似非而是的地方——抽象层的价值恰恰体现在“变”的那一刻。1.1 不同厂商接口差异到底有多大我整理了一个表格来说明这种差异不一定精确到每个版本但足够让你直观感受到碎片化程度对比维度平台A平台B平台C鉴权方式Bearer TokenAPI-Key 请求头签名认证核心请求体messages 数组prompt 字符串两者混合采样参数temperaturetemperaturetop_p 为主流式格式SSE data 前缀关键在响应体尾部二进制分块错误码401/429/500 语义清晰全用 400 兜底各自封装错误对象同一套业务逻辑在平台A上写出来的代码搬到平台C基本要重写解析层。而 litellm 内部维护了一个庞大的 provider 映射表每个 provider 声明自己的 base_url、鉴权方式、参数映射关系甚至错误码翻译规则。用的时候传入一个类似vendor-a/text-chat-xl这样的模型名它就自动路由到对应的 handler。这点也是我建议新手理解 litellm 时抓住的核心它与其说是一个 SDK不如说是一张不断在更新的“接口翻译对照表”。1.2 用适配器思路看 litellm 的底层逻辑熟悉设计模式的人一眼就能认出来这就是适配器模式目标接口是统一的 chat completions 协议适配者是各个供应商的 SDK 或 HTTP 接口适配器就是那些 per-provider 的 handler。好处是你业务代码依赖的是抽象接口而不是具体实现。如果你想替换模型只需要改一行模型名甚至通过配置项在运行时切换完全不用动消息构造逻辑。这个设计也决定了 litellm 的一个特性它并不想替代任何供应商的完整能力而是保证“常用能力的子集”在统一接口上可用。所以它官方文档里总在强调“支持 100 多家 LLM API”但落实到某个边缘特性上不同 provider 的支持度是不一样的。起步时你把它当成一个“把 complexity 收敛到一点”的工具来用认知负担会小很多。2. 快速试水用 Python SDK 把多模型接进同一套代码说再多原理不如直接上手。litellm 的 Python SDK 是最轻量的使用方式特别适合脚本工具、内部 Demo、或者在现有项目里快速集成。安装很简单pip install litellm[proxy]如果你只需要 SDK 不需要代理服务直接pip install litellm就行。那个[proxy]额外装的其实是后面章节要讲的 FastAPI 相关依赖。首次接触的话我建议先装完整版省得到时候切换网关方案又要重新装一遍。2.1 第一次调用三行代码换三家模型初始化后直接用completion函数发起请求。这是在写统一调用的关键所有模型都走同一个入口差别只在model字符串import litellm messages [{role: user, content: 用一句话解释什么是接口适配层}] # 切换模型只改这一行 resp_a litellm.completion( modelvendor-a/text-chat-xl, messagesmessages, api_key你的key_a ) resp_b litellm.completion( modelvendor-b/deep-think-1, messagesmessages, api_key你的key_b ) print(resp_a.choices[0].message.content) print(resp_b.choices[0].message.content)你没看错接口确实一模一样。我第一次用的时候也有点不真实的感觉——原先那套适配代码就这么被省掉了。choices[0].message.content这个访问路径也统一了不用再管各家返回结构里是text还是content。如果你的api_key已经放到环境变量里了比如VENDOR_A_API_KEY那么在completion里可以完全不传api_key参数。litellm 的规则是在环境变量里找它自己约定的变量名找不到就用 provider 官方的变量名再找不到才报错。这个设计对统一密钥管理很有帮助尤其在后文讲代理网关时。2.2 流式输出与工具调用的统一处理日常开发中除了普通补全流式输出几乎是必选项。litellm 对流式的支持方式也让业务代码保持简单resp litellm.completion( modelvendor-a/text-chat-xl, messagesmessages, streamTrue ) for chunk in resp: delta chunk[choices][0][delta][content] if delta: print(delta, end)每家的流式格式差异在这里被抹平了你拿到的是一个统一格式的增量对象。这对于做打字机效果的前端非常友好后端只需要维护一套流解析逻辑。同样现在各家都在推函数调用function/tool call用 litellm 也基本是同一套写法在请求里声明 tools 列表收到响应后读choices[0].message.tool_calls。注意不同 provider 对工具调用的支持程度不一样有的支持多轮工具循环有的只支持单轮。实操时如果遇到奇怪现象先看是不是 provider 自身版本的限制再怀疑 litellm。2.3 错误处理与自动重试出问题别慌网络请求总有失败的时候模型的 API 尤其如此限流、超时、服务端繁忙都是家常便饭。litellm 提供了litellm.completion_with_retries它包装了指数退避重试逻辑也遵循统一的异常类型比如RateLimitError、TimeoutError、APIError。代码上你只需要捕捉少数几个异常from litellm import RateLimitError, APIConnectionError try: resp litellm.completion_with_retries( modelvendor-b/deep-think-1, messagesmessages, num_retries3, timeout30 ) except RateLimitError: # 这里可以做排队提示而不是直接对用户报错 print(当前请求太多稍后再试) except APIConnectionError: # 切换备用模型 resp litellm.completion(modelvendor-a/text-chat-xl, messagesmessages)这里有个细节num_retries3只在可重试的异常上工作并不是所有异常都会重试。比如你的请求参数写错了导致 400重试一百次也没用litellm 也不会浪费那个次数。遇到 4xx 错误第一时间去查消息体和模型名遇到 5xx 或网络异常才交给重试逻辑。这种语义区分很符合直觉但确实需要使用者自己心里有数。2.4 用量统计与成本控制SDK 模式还有一个容易被忽略但很好用的能力litellm.response_cost(resp)。把一次请求的响应对象丢进去它就能算出这次调用花了多少钱因为它内部存了各家模型的 token 定价表。cost litellm.response_cost(resp) print(f本次请求成本: ${cost})这个功能看着不起眼实际价值非常大。我接完第一个 Demo 后把每次调用的 cost 打到日志里跑了两天就发现了某个模型在低延迟场景下性价比明显更差。后续做模型选型时这份日志是最有说服力的数据。就算你现在还没有成本优化压力我也建议从一开始就把 token 消耗和成本打进监控里后面真的想省钱了至少不会没有数据基础。3. 从个人脚本升级到团队网关Proxy 模式实战SDK 模式适合单机脚本和早期验证但到了团队协作阶段问题就来了群里传 API Key新人不知道用哪家环境变量每个服务各自消费花费、账单对不齐。这种局面下litellm 提供的 Proxy 模式也就是它的代理服务才是正解。Proxy 模式说白了就是部署一个轻量的 HTTP 服务统一对外暴露聊天补全接口。团队里的所有业务后端都只对接这个服务真正的上游模型密钥、模型切换、负载均衡和花费统计都沉淀在 Proxy 这一层。业务方拿到的只是一个虚拟 API Key完全可以按项目、按人独立签发。3.1 最小可用配置一份 config.yaml 跑起来Proxy 靠一个 YAML 文件描述模型列表和管理规则。这是我最小的可用配置model_list: - model_name: main-chat litellm_params: model: vendor-a/text-chat-xl api_key: os.environ/VENDOR_A_KEY - model_name: fallback-chat litellm_params: model: vendor-b/deep-think-1 api_key: os.environ/VENDOR_B_KEYmodel_name是对外可见的模型名业务方只认这个名字。litellm_params.model才是真正映射到上游的模型标识。重点来了api_key推荐用os.environ/XXX这种形式让 Proxy 从环境变量里读取真实密钥YAML 文件本身不落任何明文密钥这一点在团队共享仓库时特别重要。启动服务只需要一条命令litellm --config config.yaml --port 4000默认情况下它会起一个本地服务对外暴露兼容 chat completions 语法的端点。这时候业务后端可以这样调用curl http://localhost:4000/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-your-virtual-key \ -d {model: main-chat, messages: [{role: user, content: 你好}]}第三方 SDK 甚至能直接把它当成一个标准 endpoint 接入只需把 base_url 指向http://localhost:4000。这意味着你团队里已有的代码框架、开源应用只要支持标准接口都能几乎零成本切换到统一网关上来。3.2 虚拟密钥给每个人都发一把“租来的钥匙”Proxy 模式下最核心的管理能力是虚拟密钥。它跟上游真实密钥是两回事虚拟密钥是 Proxy 自己签发的绑定调用权限、速率上限和花费配额。你完全可以给每个开发、每个应用、甚至每个环境各发一把curl http://localhost:4000/key/generate \ -H Authorization: Bearer sk-master-key \ -H Content-Type: application/json \ -d { models: [main-chat, fallback-chat], max_budget: 50, budget_duration: 30d }响应里会给你一个sk-开头的虚拟 key。这个 key 只能在你的网关内使用即便泄露了影响范围也仅局限在网关许可的模型和预算之内上游真实密钥完全不可见。我不止一次看到有人把真实上游 key 直接写死在业务容器环境变量里一旦泄露就是直接的经济损失。用 Proxy 做一层隔断之后真实 key 只存在于网关服务器的环境变量中安全边界清晰很多。3.3 预算观测用数据复盘每次模型调用预算控制写完还得看得到用量。Proxy 提供了几个管理端点查询起来非常方便。你会得到一个类似一账本的视图哪个虚拟 key 花了多少、调用了多少次、分别用了哪些模型、每次响应延迟如何。我当时给团队搭好网关后最直观的感受是之前月底对账单要对半天现在从面板上拉个表格就能跟财务说清楚。而且因为虚拟 key 可以按客户维度签发哪个业务线消耗了多少成本、需不需要限额几乎是一目了然。做 AI 功能最容易失控的就是成本有一个能随时拉数据的网关心里会踏实很多。4. 流量调度与稳定性多模型备胎和本地模型接入Proxy 跑通之后很多人会想再做一步让流量在多个模型之间智能调度实现高可用和成本优化。litellm 在这一层提供了路由、重试、熔断等不少功能。这一章节就讲我在生产环境里实际用到、且验证有效的几项。4.1 同一逻辑名背后挂多个实际模型所谓“逻辑模型名 多个部署”核心配置是在model_list里让多个litellm_params共用同一个model_namemodel_list: - model_name: main-chat litellm_params: model: vendor-a/text-chat-xl api_key: os.environ/VENDOR_A_KEY model_info: weight: 700 - model_name: main-chat litellm_params: model: vendor-b/deep-think-1 api_key: os.environ/VENDOR_B_KEY model_info: weight: 300对外依然是同一个main-chat内部流量默认按权重分发七成走 vendor-a三成走 vendor-b。这种配置最有价值的场景是模型上线灰度新模型接进来只给 5% 流量跑几天看效果再逐步调高权重。不用改业务代码不用通知下游更新路由只改一个 YAML 然后热加载配置即可。我当时把一个新模型从 0% 到 100% 切了两周整个切换过程下游完全无感。4.2 重试、超时和区域降级请求必然有失败。路由模式下 litellm 会在一个模型出问题时自动把请求重试到另一个模型前提是你配置了fallbackslitellm_settings: fallbacks: [{main-chat: [fallback-chat]}]含义是main-chat失败后自动尝试fallback-chat。同时你还能设置每类请求的超时时间litellm_settings: num_retries: 3 request_timeout: 30 allowed_fails: 3 cooldown_time: 60allowed_fails和cooldown_time合起来是一种简单的熔断策略连续失败三次的模型会被冷却一分钟期间流量自动切给别的可用模型而不是继续傻傻地往一个不可用端点打请求。这套机制对线上稳定性提升很明显尤其是遇到某个厂商大范围故障的时候你的服务不会跟着一起瘫痪。4.3 把私有化部署的模型也收编进网关再顺带说一个我看重的能力litellm 不只接各家云厂商 API还能把本地用 vLLM、Ollama 之类框架起的大模型也接入统一网关。配置上和普通上游差不多只是把model指向本地服务地址即可model_list: - model_name: local-chat litellm_params: model: local/my-local-llm api_base: http://127.0.0.1:8000/v1这里api_base就是本地推理服务的地址。接进来之后业务方对它是云上 API 还是本地私有模型完全无感知。这种用法在数据敏感的私有化场景里非常实用对外只暴露统一接口背后的数据不出内网同时还能享受网关的密钥、限流和日志能力。5. 踩坑记录与兼容性边界哪些场景会让它翻车任何工具都有适用范围和死角。litellm 给我的整体感受是“覆盖率很高但远非万能”。下面这些坑是我实际使用中踩过的写出来帮大家少走弯路。5.1 参数透传不是百分之百完整我在用某个支持图片输入的模型时需要传一个非标准的图像参数。控制台文档里明确写了这个参数怎么传但通过 litellm 的images字段传过去对方接口并没有正确响应。定位后发现litellm 的 provider handler 里跟这个特定参数相关的映射没覆盖到。这个问题在非主流模型和新功能上尤其明显。处理思路有两个一是先用litellm.get_supported_openai_params(model...)查看某个模型支持哪些统一参数确认你的参数在当前版本是否被覆盖二是确实缺了就用additional_args之类的透传机制绕一下但不要抱太高期望。遇到这种情况我会先去项目仓库看这个 provider 的实现再决定要不要自己提交补丁或者降级处理。5.2 认准模型名拼写的血泪教训模型名拼错是最高频的入门事故。比如把一个平台的模型标识里多打了一个横杠litellm 不认识直接抛错。它内部维护了一张模型名到定价和上下文长度的对照表拼错会导致成本计算异常、上下文窗口判断错误甚至请求直接被拒。规范做法是每次接新模型前用litellm.model_list或官方文档确认精确的模型名称。另外要区分“模型别名”和“provider 真实模型名”。你在配置文件里定义的model_name是给自己看的逻辑名可以随便起但litellm_params.model必须跟供应商那边完全一致。我在一次升级版本后遇到过推理服务换了 API 路径导致全部 404排查半天才发现是上游兼容层的问题不是 litellm 的问题。5.3 请求超长被静默截断或报错大模型上下文有限这个问题其实跟 litellm 没有直接关系但在统一层接入多模型后问题变得更隐蔽。不同模型的上下文窗口大小不同vendor-a支持 128Kvendor-b可能只有 32K。你用同一个 Prompt 在 A 上跑得好好的路由到 B 上可能直接报“上下文过长”。litellm 的模型表会给部分模型提供上下文长度信息但也不是每个 provider 都准确。我的经验是在应用层做一个 Prompt 长度预检按照当前路由模型的最小上下文窗口去截断或压缩。如果你依赖 litellm 的自动处理大概率会在最不该出问题的时候迎来意外。5.4 什么时候别用它最后聊一下边界。如果你团队只有一家模型供应商且未来不可能换或者你的场景极其简单就是一个静态model某个固定模型的脚本那直接用官方 SDK 反而更直接。引入 litellm 毕竟多了一层抽象多一个依赖就多一份需要跟踪的兼容性问题这并非没有成本。另一种情况是你要自研一个超高吞吐的网关。litellm 的 Proxy 性能还不错但它毕竟是通用型实现不是专为极限吞吐设计的网关。如果你的核心目标是极致的请求转发效率和灰度路由控制像 APISIX 这类通用 API 网关配合你自己的转发逻辑反而更可控。litellm 的强项是模型兼容转换和模型管理它并非要在所有场景里都当主角。结尾一个关于抽象层的个人体会透过 litellm 我想多说一层判断一个抽象层工具好不好不是看它当下能不能跑通而是看它能不能真的简化“变化”。我经历过“上游模型厂商调整了接口格式导致全线代码改动”那种事之后就确立了在 AI 应用里先加一层适配层的习惯。哪怕你当下只接了一个模型只要这层接口是标准的、中立的未来切换和扩展的成本就能压在可控范围。具体到 litellm我个人的建议是先在小项目里用 SDK 模式验证它对模型的支持度跑两三天后如果不出大问题再考虑部署 Proxy 供团队使用。部署的时候从一开始就把虚拟密钥、预算上限和成本日志都打开不要等到模型调用量上来了再补救。顺带分享一个小技巧如果你在 Proxy 里已经配了很多模型可以在业务代码里加一个轻量的“健康检查”定时调用一个极小 token 的补全任务遇到连续失败就触发告警。我曾凭这个检查提前发现某上游模型因为版权调整临时下线避免了业务大面积异常。工具只是加速器监控和使用规范才是系统稳定性的真正底座。