1. 先搞清楚litellm 到底是干什么的大概从去年开始我经手的所有涉及大模型的项目几乎都绕不开一个叫 litellm 的工具。它不是某个大厂出的云服务也不是某个框架的附属插件而是一个纯开源的 Python 库核心就做一件事把市面上你能叫得出名字的大模型 API全部统一成一套调用格式。说白了你原来用 OpenAI 的 SDK 写好的代码现在想换成 Claude、文心、通义、Gemini 或者本地跑的 Llama不需要改业务逻辑只要在 litellm 里改一行配置甚至只是换个模型名字请求就过去了。这在今天这个“今天用这家、明天换那家”的开发环境里属于典型的刚需。我自己最早接触 litellm是在一个模拟项目里需要同时接三家模型做对比评测。当时最头疼的就是每家 API 的请求格式、鉴权方式、超时处理都不一样光写适配层就够喝一壶的。后来发现 litellm 把这一步全都封装好了而且用下来手感非常接近 OpenAI 的调用风格迁移成本极低。从那以后凡是涉及多模型接入的场景我第一个想到的就是拿它来垫底。这篇文章不打算写官方文档的复述而是从一个实际使用者的角度把 litellm 能解决什么问题、怎么快速上手、生产环境有哪些坑一次性讲清楚。你可以把它当成一份踩坑总结加实战笔记来看而不是当说明书。2. 为什么需要统一调用层大模型 API 的“格式割裂”问题2.1 各家大模型 API 到底有多不统一很多人第一次接触多家大模型 API 的时候会觉得“不就是发个 HTTP 请求换一下地址和 key 吗”。真上手就不是这个感觉了。OpenAI 的接口走的是chat/completions请求体里是messages、model、temperature这些字段Anthropic 的接口走的是/v1/messages角色字段叫role内容字段的格式也不一样Google 的 Gemini 用的是generateContent请求深层嵌套跟前面两家完全是两套思路。再加上国内的几家厂商虽然号称兼容 OpenAI 格式但总在细节上搞点“微创新”——比如某个参数不支持、某个字段必须传、返回结构里多包一层。这些差异单独看都不大但一旦你要在代码里同时维护多套 SDK、多套数据解析逻辑维护成本就上来了。如果只是在代码里写死一套也还好更麻烦的是业务方今天说要加一个新模型明天说要换一个更便宜的供应商。每次需求一变你就要重新读一遍新文档、改一遍请求构造、改一遍错误处理、再改一遍返回解析。改一次两次还能忍改多了你就明白这活儿本质上是在给各家厂商做“格式翻译官”而且这个翻译官还不能被替代。2.2 统一网关模式的思路litellm 的思路其实很简单它把“各家 API 的差异”全部收拢到自己这一层对外暴露一套统一的接口。你这边的代码只需要跟 litellm 打交道至于背后是 OpenAI 还是 Anthropiclitellm 帮你处理。打个比方你家里有各种不同接口的电器——有的是两脚插头有的是三脚插头有的还要转换电压。你不用每个电器都配一个专用插座只需要在总线上挂一个万能转换器把所有差异挡在外面后端的电器怎么变前面用起来都一样。litellm 就是那个万能转换器。这个设计带来的直接好处是业务代码只依赖一套 SDK 约定不随供应商变动而重写模型切换从“改代码”降级为“改配置”可以在网关层统一处理鉴权、限流、日志、计费、缓存这些横切关注点多个团队可以共享同一个网关不用各自维护一套接入逻辑从架构角度来看它就相当于 LLM 领域的反向代理或 API 网关只是它代理的对象不是普通的 HTTP 服务而是各家大模型服务。2.3 什么时候应该用什么时候不该用litellm 不是万能的也不需要什么项目都往里硬塞。我个人的经验是当你满足下面任意两条时就值得考虑了项目里同时接入了两家以上大模型供应商业务方频繁提出换模型、加模型的需求你有几个后端服务要复用同一组模型配置你需要在多套模型之间做 A/B 对比、灰度切换或负载均衡反过来如果只是个人写个脚本、调一个固定模型那你直接用官方 SDK 最简单没必要额外引入一层依赖。这个“度”要自己掂量好工具是拿来解决复杂度的不是拿来制造复杂度的。3. 上手实战十分钟跑通第一次请求3.1 安装与基本项目结构litellm 的安装非常简单基础库可以直接用 pippip install litellm如果要用代理服务模式后面会详细讲需要额外装 Proxy 相关依赖pip install litellm[proxy]装完之后你可以在项目里用一个全局的litellm对象直接调模型也可以通过Router来做路由管理。最基础的用法是这样的import litellm response litellm.completion( modelgpt-3.5-turbo, messages[ {role: user, content: 你好介绍一下你自己} ] ) print(response.choices[0].message.content)看到没有这个调用方式跟 OpenAI SDK 几乎一模一样。关键区别在于model参数里可以传各种供应商的模型名比如claude-3-5-sonnet、gemini/gemini-1.5-pro、ollama/llama3等等。litellm 在内部会解析模型名自动选择对应的客户端去请求。3.2 API Key 的配置方式API Key 可以通过环境变量传递也可以在代码里手动设置。我建议即使在本地测试也养成用环境变量的习惯防止把 Key 提交到代码仓库里。常用环境变量命名规则是供应商名加大写export OPENAI_API_KEYsk-... export ANTHROPIC_API_KEYsk-ant-... export GEMINI_API_KEYAI...如果你用的模型不在环境变量识别的范围内也可以直接在参数里传api_keyresponse litellm.completion( modelopenai/gpt-4o, messages[{role: user, content: hi}], api_keysk-... )注意看这里的模型名是openai/gpt-4o带了前缀。这个前缀是 litellm 用来识别供应商的。不过好消息是对于常见模型你也可以直接写gpt-4olitellm 会自动推断。但如果你用了比较冷门或命名容易混淆的模型建议还是显式加前缀避免被错误路由。3.3 一次请求的完整拆解我实际开发中经常用 litellm 做多模型对比测试这时候最方便的做法是写一个通用函数把模型名当参数传入def ask_model(model_name: str, content: str) - str: response litellm.completion( modelmodel_name, messages[{role: user, content: content}], temperature0.3, max_tokens1024 ) return response.choices[0].message.content # 测试三个模型 for model in [gpt-4o, claude-3-5-sonnet, gemini/gemini-1.5-flash]: try: result ask_model(model, 用一句话解释什么是递归) print(f{model}: {result}) except Exception as e: print(f{model} 调用失败: {e})用这样的方式同一个业务逻辑就能在多个模型之间无缝横跳对比结果一目了然。这也是 litellm 最直观的价值所在——你没有改过任何跟厂商相关的逻辑只是换了个名字。3.4 一些容易忽略的细节第一返回对象是统一的。不管你后面接的是什么模型返回的都是一个类似 OpenAI 风格的CompletionResponse对象。这意味着你的下游代码不需要为每家模型写不同的解析逻辑。第二异步调用也支持。如果你的项目是异步框架直接这样用import asyncio import litellm async def main(): response await litellm.acompletion( modelgpt-3.5-turbo, messages[{role: user, content: 讲个笑话}] ) print(response.choices[0].message.content) asyncio.run(main())litellm 把异步客户端也统一了你不需要关心底层是 httpx 还是 aiohttp也不需要自己去维护连接池。第三流式输出。需要打字机效果的时候把参数换成streamTrue即可response litellm.completion( modelgpt-3.5-turbo, messages[{role: user, content: 写一首短诗}], streamTrue ) for chunk in response: print(chunk.choices[0].delta.content or , end, flushTrue)这里要注意不同厂商的流式返回格式差异挺大但 litellm 把 chunk 结构也统一成了 OpenAI 格式这点在实际项目中非常省心。4. 架起代理服务把 litellm 变成基础设施4.1 为什么需要 Proxy 模式直接调用函数的方式适合单机脚本和简单集成但如果你有多个后端服务同时要用模型或者想让前端直接跟大模型交互总不能每个服务都去装一遍 litellm、各配各的 Key 吧。这时候就需要一个集中的代理服务也就是 litellm Proxy。Proxy 模式启动之后相当于你在本地或内网起了一个服务这个服务对外暴露一个 OpenAI 兼容的接口。你所有业务的 base_url 都指向这个服务模型配置、Key 管理、限流策略全部在服务端统一管理。这带来的好处是Key 不需要散落在各个业务服务里模型切换直接在代理配置里改业务方无感知可以统一加缓存、限流、审计日志多个环境开发、测试、生产共用一套入口但配置可以独立4.2 最小配置示例litellm Proxy 的配置是一个 YAML 文件下面这个是最小可用的例子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: claude-sonnet litellm_params: model: anthropic/claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEYmodel_name是暴露给使用方的对外名字litellm_params.model是真实要请求的模型。为什么要区分这两个字段这是为了解耦。比如业务方已经习惯了叫claude-sonnet但实际上你想把后端从旧版本换到新版本只需要改litellm_params里的真实模型名对外名字不变业务方完全不用动。启动命令也很简单litellm --config config.yaml --port 4000服务起在 4000 端口你就可以直接用 OpenAI SDK 来发请求了from openai import OpenAI client OpenAI( api_keydummy, # 随便填litellm 代理层会替换成真实 Key base_urlhttp://localhost:4000/v1 ) response client.chat.completions.create( modelclaude-sonnet, messages[{role: user, content: 你好}] ) print(response.choices[0].message.content)这里完全用的是 OpenAI 的 SDK但实际发送到的是 Anthropic 的模型这个“狸猫换太子”的过程全部在代理层完成。4.3 用 curl 直接验证不想写 Python 的时候直接用 curl 也可以测curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: claude-sonnet, messages: [{role: user, content: ping} }返回的 JSON 结构也是 OpenAI 格式可以直接被前端或其它 SDK 消费。这个兼容性很关键因为很多开源工具链比如某些前端聊天组件已经默认支持 OpenAI 格式接 litellm 的代理等于零改动接上来。4.4 生产环境部署建议我自己在真实项目里跑 Proxy 时一般会做几件事用 systemd 或容器编排来托管进程确保崩溃自动重启前面再挂一层 Nginx把 TLS 终结在外面环境变量统一走配置管理不直接写在 YAML 里打开保存请求日志的回调方便追踪问题和核算成本还有一点Proxy 的默认端口是 4000如果你部署在云服务器上注意安全组只放行你需要开放的端口不要把调试接口暴露到公网。5. 生产环境的核心玩法路由、故障转移、预算控制5.1 多模型的权重路由与负载均衡如果你同一个对外模型名背后配了多个真实模型litellm 可以按权重进行负载均衡。比如你想把流量大部分打到便宜的模型上少部分打到贵的模型上可以在配置里写model_list: - model_name: gpt-3.5-turbo litellm_params: model: openai/gpt-3.5-turbo weights: 8 - model_name: gpt-3.5-turbo litellm_params: model: openai/gpt-4o-mini weights: 2这样请求进来时litellm 会按 8:2 的比例把流量分到两个真实模型上。这种玩法在压测、灰度上线新模型的时候特别好用。你可以先让新模型拿一小部分流量观察效果稳定了再逐步加大权重。5.2 故障转移配置单个供应商偶尔会抽风——限流、超时、网络波动。litellm 支持在某个模型调用失败后自动切换到备选模型。Router 模式下的配置大致是这样的from litellm import Router router Router(model_list[...], fallbacks[{gpt-3.5-turbo: [claude-sonnet]}]) response router.completion( modelgpt-3.5-turbo, messages[{role: user, content: 测试故障转移}] )这里的意思就是如果gpt-3.5-turbo调用失败自动换到claude-sonnet。在 Proxy 模式里同样可以在 YAML 中声明router_settings的fallbacks来达到一致的效果。这个功能在关键业务里的价值不用多说等于给你的模型调用加了一个保险丝。但也要注意故障转移之后的结果可能来自不同模型质量、风格、甚至返回内容格式都会有点变化所以要留足容错空间。5.3 预算和限流管理生产环境最重要的一点就是控制成本。litellm 提供了三层预算控制全局预算整个网关的花费上限每个 Key 的预算给不同的业务方分配不同的 API Key各算各的账每个模型的限流设置每分钟请求数RPM和每分钟 Token 数TPM比如你想让某个业务方每个月最多只能用 50 美元可以在 YAML 里这样配general_settings: master_key: sk-1234 # 管理密钥用来生成子 Key router_settings: max_budget: 200 # 全局月度预算 200 美元再配合虚拟 Key 功能可以给不同团队发不同的 Key每个 Key 单独设置预算curl http://localhost:4000/key/generate \ -H Authorization: Bearer sk-1234 \ -H Content-Type: application/json \ -d {max_budget: 50}这样可以非常清楚地看到每个团队每个月的模型花费再也不用人肉去翻账单了。5.4 自定义模型映射与团队共享litellm 还有一个很实用的细节model_name可以由你自己随便起。你完全可以定义一个叫main-chat的对外模型名把团队内部所有人都指向这个入口而真正的后端模型可以随时切换。对于团队协作场景这相当于在模型和用户之间加了一层“接口约定”你换模型不换约定。另外litellm 也支持自定义 API 的接入不局限于云厂商。比如你有一个内部部署的模型服务只要格式能对齐也可以通过 litellm 统一暴露出来。这意味着你用一套网关就能把云厂商模型和私有化模型全部纳管了。6. 常见问题与排查实录6.1 模型前缀没写对导致路由失败这是我最常碰到的问题。明明配的是gpt-4o返回的报错却说Unknown provider。大多数情况是因为 litellm 模型名里带了不支持的前缀或者拼写不规范。解决办法先用litellm.model_list查看一下当前支持哪些模型名或者直接看文档里的模型目录确认前缀。比如 Gemini 一般是gemini/gemini-1.5-proOllama 是ollama/llama3.1Bedrock 是bedrock/*。写错一个斜杠都会导致路由失败。6.2 超时设置与重试机制大模型接口有时候响应会特别慢尤其是长上下文生成。litellm 默认超时是 600 秒但如果你的业务对响应时间有要求自己应该显式设置litellm.request_timeout 30 # 全局超时 30 秒同时你可以设置重试次数litellm.num_retries 3 # 失败后自动重试 3 次但要注意num_retries对某些非幂等的请求可能会产生重复扣费。所以重试策略要结合具体业务来判断不能盲目的“重试拉满”。6.3 流式响应报错的排查流式模式偶尔会遇到流写到一半断掉的情况。我之前排查的一个项目里问题出在供应商的流式事件格式里多了一个字段litellm 解析到一半抛异常。这种情况通常先抓原始响应litellm.set_verbose True开启后litellm 会打印出完整的请求和响应链路包括原始返回体。这是定位一切接口问题的第一把钥匙。6.4 Key 权限与子 Key 管理混乱多人共用代理服务时子 Key 的管理容易混乱。常见问题是明明该业务方说报错了但看日志却发现是另一个 Key 在调用。我的建议是子 Key 的命名要有明确业务标识并且每个 Key 只给最小权限和有限预算用完再单独分配。litellm 的虚拟 Key 管理接口提供了比较细的权限控制建议花点时间研究一下不要图省事共用一把 Key。6.5 本地环境与容器网络问题在 Docker 里跑 litellm Proxy业务容器也跑在 Docker这时候localhost:4000是访问不到宿主机的。你需要用host.docker.internal或者把服务也部署在同一个 Docker 网络里。这个坑几乎所有人都踩过说到底不是 litellm 的问题是容器网络的基础知识但结合在一起就容易让人绕圈子。6.6 常见问题速查表现象可能原因排查方式调用报 Unknown provider模型名前缀写错查看官方模型目录确认前缀请求一直超时网络问题或服务端过载调大超时时间检查网络连通性费用异常飙升重试次数过多或未设预算上限设置num_retries1启用预算控制返回内容格式不一致故障转移落到了其它模型检查 fallbacks 配置确认模型能力相近代理服务内存上涨请求日志积累过多关闭冗余日志增加日志轮转策略7. 经验心得用好 litellm 的几个关键认知用了一段时间 litellm 之后我最大的体会是它的价值不在于把“调模型”这件事变简单而在于把“换模型”这件事变简单。前者官方 SDK 本来就能做到后者才是业务中最贵的环节。我见过太多项目前期选型选了一家模型写了一大堆代码结果中期发现效果不好或者成本太高想换一家牵一发动全身。如果一开始就通过 litellm 做代理接入后面换模型就只是一次配置变更而不是一次代码重构。这种“提前铺路”的思路在日新月异的大模型领域尤其重要。另外一个体会是litellm 的功能边界其实一直在扩展。它已经不只是一个“格式翻译器”了而是逐渐往 LLM 运维平台的方向在走包括缓存、日志、成本追踪、Key 管理、负载均衡这些都集成进来了。对于中小团队来说这等于用开源方案搭了一个简化版的 LLM 网关底座性价比非常高。最后再分享一个小技巧如果你在团队里推行 litellm别急着把所有人都拉到一个大群教配置。先把代理服务搭好、配好两三个常用模型、写一页使用说明让大家直接按 OpenAI 格式调用就行。大部分人感受不到 litellm 的存在但他们会感受到“这个月换模型真方便”。工具做到这一步就算落地成功了。