做了一个季度的 AI 应用开发我被同一件事反复折腾今天接这家模型厂商明天切那家的接口代码里全是 if-else密钥散落在各个环境变量账单月底对不上线上出了故障还得手动改配置。直到同事把 litellm 甩给我我才反应过来——这类问题不该让业务代码去硬扛而是应该在入口处加一个统一网关。litellm 是一个开源的大模型网关与统一调用框架它能把几十家模型服务商的接口收敛成同一套规范同时提供代理服务、路由容灾、成本追踪和密钥管理适合所有需要对接多个大模型接口的团队和个人开发者。这篇文章会把我从接触到生产落地的完整经验拆给你看包括原理、配置、踩坑以及一份可以直接抄走的实操方案。1. 先搞清楚 litellm 是什么1.1 一句话理解模型接口的“转换插头”你出差去不同国家带的笔记本充电器插头形状不一样总不能每次换电脑。转换插头解决的就是这个事不管当地插座长什么样你只需要带一个万能转换头。litellm 做的就是大模型接口界的转换插头。它把各家模型厂商的鉴权方式、请求格式、返回结构、错误码统一成一套协议。你在代码里只写一份逻辑后面换模型、换厂商改一行配置就行不用动业务代码。这个项目分为两部分。第一部分是 Python SDK你可以在自己的代码里直接调用第二部分是一个高仿主流厂商接口格式的代理服务把模型能力封装成公司内部 API。两者共用同一套模型配置所以你可以先用 SDK 做快速验证等要上生产了再把流量切到代理上。1.2 它到底解决了哪几个层面的痛点先说说我实际遇到的痛点你大概率也遇到过。第一接口碎片化。每个模型厂商都有自己的请求格式有的用聊天补全接口有的用消息补全接口流式返回的字段名都不一样。业务代码里每接一家新模型就要多写一层适配。轻则几十行重则牵扯到流式解析、工具调用、内容审核全是细节。用 litellm 之后这些适配逻辑被收敛到网关里业务代码只认一套格式。第二密钥管理混乱。早期我们团队把各家厂商的密钥分别存在不同环境变量里前端再透传给后端。谁有密钥谁就能直接调模型账单爆了都不知道是哪条业务线花的。litellm 的代理模式可以把密钥全部收敛在服务端前端和业务方只拿到虚拟密钥权限和额度都能控制。第三容灾切换太慢。某厂商的接口偶尔抽风以前只能手动改代码切备用模型等改完发布线上可能已经挂了半小时。litellm 支持配置多个备用模型和自动重试主模型挂了自动迁移到备选用户基本无感知。第四成本归因困难。不同团队、不同项目用了多少 token月底对账全靠猜。litellm 可以按虚拟密钥、按用户、按标签记录每一次调用的模型、token 数、费用直接导出报表对账这件事从小时级变成秒级。2. 核心功能拆解为什么说它是网关而不只是 SDK2.1 统一调用接口一套代码接所有模型先说最基础的部分SDK 的调用方式。装好 litellm 之后最基本的调用长这样from litellm import completion response completion( modelyour-provider/your-model, messages[ {role: system, content: 你是一个智能助手}, {role: user, content: 介绍一下你自己}, ], temperature0.7, ) print(response[choices][0][message][content])注意这里的model参数它带着一个服务商前缀。litellm 看到your-provider/你的模型名就能识别出应该走哪家厂商的鉴权和接口。前缀换成其他厂商调用的还是同样的completion函数返回格式也一样。这个设计的价值在换模型的时候体现得最明显。我做过一个模拟项目最开始用的模型翻译效果一般后来想换另一个厂商的大模型。整个改动就是modelyour-provider/your-model # 改成 modelanother-provider/another-model业务层代码零改动连 messages 的结构都不用变。这套体验不是靠魔法实现的是因为 litellm 内部帮我把每家厂商的请求参数映射、响应解析、错误码转换全部做完了。2.2 代理模式把模型能力变成公司内部的 APISDK 适合自己一个人用但到了团队协作阶段问题就来了。前端要调模型密钥不能给到浏览器后端不同服务都要调模型每个服务都配一遍密钥密钥泄露面越来越大过了几个月想审计谁在乱调用发现根本没有日志。litellm 的代理模式解决的就是这个。它启动一个本地服务默认跑在 4000 端口对外暴露的接口风格和主流聊天补全接口一致。你只需要拿到一个 litellm 服务地址用它提供的虚拟密钥来访问真正的模型厂商密钥全部锁在网关里。这样一来模型能力就从“某个人的密钥”变成了“公司内部 API”。服务的稳定性、限流、审计、配额都在这一层统一做业务侧觉得就是在调一家很稳定的模型厂商。2.3 路由与容灾负载均衡、退避重试、故障转移这是 litellm 在生产环境里最能救命的功能。你可以把同一个模型逻辑名映射到多个真实的模型实例上litellm 会自动分配请求压力。我举一个真实场景。某公司做了一个智能客服系统每天早晚高峰请求量是平时的三倍。以前只接一个厂商的模型限流一触发用户就看到“系统繁忙”。后来在 litellm 的配置里给同一个逻辑模型配了两个真实模型源再配上权重流量自动分到两边。限流触发率明显下降就算一家厂商临时故障另一家也能扛住。model_list: - model_name: customer-service litellm_params: model: your-provider/your-model api_key: os.environ/KEY_A model_info: weight: 2 - model_name: customer-service litellm_params: model: another-provider/another-model api_key: os.environ/KEY_B model_info: weight: 1上面的配置表示请求按 2:1 的比例分配。如果第一家返回限流或者超时litellm 会自动把请求转到第二家业务方无感知。配合max_retries、request_timeout、fallbacks这几个参数容灾策略基本够用。2.4 成本追踪与配额控制为什么成本追踪是刚需因为大模型账单是按 token 计算的而 token 消耗分散在各条业务线、各个接口、各个用户。没有独立的计量层月底财务找你对账的时候你只能尴尬地说“我猜大概这个数”。litellm 的代理会为每一次请求记录模型名、输入输出 token、估算费用、请求耗时、状态码、虚拟密钥、用户标识以及你可以自定义的 metadata 标签。这些数据可以在管理端界面查看也能通过接口拉取。更实用的能力是配额控制。你可以给某个虚拟密钥设置每月的美元上限或者每分钟的请求数上限。到了阈值网关直接拒绝请求返回明确的错误信息。这个功能对 SaaS 产品特别有用不同套餐给不同额度成本完全可控。3. 实操从零搭起可用的模型网关3.1 安装与最小化调用先说环境Python 3.9 以上都行推荐用独立的虚拟环境避免依赖冲突。pip install litellm[proxy]方括号里的[proxy]是额外安装代理服务所需的依赖。如果只用 SDK 调用直接pip install litellm就够。接着配置密钥。litellm 支持两类密钥来源环境变量和配置文件。先用环境变量跑通最小链路export YOUR_PROVIDER_API_KEY你的真实密钥然后写一个临时脚本import litellm response litellm.completion( modelyour-provider/your-model, messages[{role: user, content: 讲个简短的笑话}], ) print(response.choices[0].message.content)跑通之后说明 SDK 本身没问题。接下来就进入代理模式。3.2 配置模型别名与密钥代理模式的核心是一个配置文件里面声明了这个网关能代理哪些模型。我给这个文件起名litellm_config.yamlmodel_list: - model_name: chat-model litellm_params: model: your-provider/your-model api_key: os.environ/YOUR_PROVIDER_API_KEY api_base: https://your-provider.example.com/v1这里有一个值得理解的概念model_name是逻辑名是给业务方看的litellm_params里那个model才是真实模型标识。业务方永远只认chat-model这个名字你在后面换厂商、换模型只要改配置文件就行业务方完全感知不到。api_base不是必填项。如果你的服务商提供的是标准接口可以直接用默认地址。如果公司内部有自建的模型服务用它指向内部地址就好。3.3 启动代理服务并验证配置写好后启动命令非常简单litellm --config litellm_config.yaml --port 4000看到日志输出Uvicorn running on http://0.0.0.0:4000说明服务已经起来了。先不急着接业务用 curl 验证一下网关是否正常工作curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-litellm-test \ -d { model: chat-model, messages: [{role: user, content: 你好}] }第一次跑通这个请求你会感受到这个项目的设计哲学业务方调用代理和直接调用模型厂商体验几乎一样只是地址换成了内网网关密钥换成了虚拟密钥。3.4 把现有项目接进来既然代理对外暴露的是主流聊天补全接口那么迁移成本就非常低。假如项目原本是直接用官方 SDK 调模型的只需要把base_url改到 litellm 服务把 key 换成虚拟密钥。from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000/v1, api_keysk-litellm-test, ) response client.chat.completions.create( modelchat-model, messages[{role: user, content: 你好}], ) print(response.choices[0].message.content)这行代码的价值在于你的业务系统对接的模型源从“某个具体厂商”变成了“内部模型网关”。之后网关后面加模型、换模型、做负载均衡业务代码一行都不用动。如果是其他语言的客户端只要它支持标准聊天补全接口配置方式同理base_url 指向 litellmkey 用虚拟密钥。项目里有多个服务就这么挨个指向网关整个接入过程一般一个小时内能完成。4. 进阶玩法一个生产级网关还要做什么4.1 多模型负载均衡与故障转移前面演示了权重分配这里再说两个生产环境常用的参数。第一个是fallbacks它在你指定的所有模型都不可用的时候生效相当于最后一道保险。第二个是allowed_failures它规定连续失败多少次之后才把某个模型标记为不可用避免一次抖动就触发切换造成雪崩效应。model_list: - model_name: main-model litellm_params: model: your-provider/your-model api_key: os.environ/KEY_MAIN model_info: weight: 3 - model_name: main-model litellm_params: model: another-provider/backup-model api_key: os.environ/KEY_BACKUP model_info: weight: 1 litellm_settings: fallbacks: [ { main-model: [another-provider/backup-model] } ] allowed_failures: 3 request_timeout: 60个人经验容灾配置要遵循“快速失败、快速转移”的原则。超时时间不要设太长默认 60 秒对一个普通用户来说已经像卡死我一般设 30 秒配合两次重试整体体验更可控。4.2 预算、限流与密钥隔离生产环境一定要管理虚拟密钥不要让大家用同一个密钥直连。litellm 提供了密钥管理的命令行工具litellm --config litellm_config.yaml --port 4000 --detailed_startup在管理端界面里可以创建虚拟密钥为每个密钥设置每月的最大消费金额每分钟的最大请求数允许访问的模型列表可选的过期时间实操中我的建议是即使是一两个人的小团队也每人一个虚拟密钥。这样线上任何一个密钥出现问题你都可以精准定位到人而不是面对一个“公共密钥被滥用”的盲区。限流的参数还有一个容易踩坑的地方max_parallel_requests控制的是同一时刻并发数tpm_limit和rpm_limit控制的是每分钟 token 数和请求数。三个参数作用域不同建议先压测出单模型的实际吞吐再反推设置。数值设太小会把正常流量误伤设太大则起不到保护作用。4.3 日志、缓存与下游观测网关层天然是打日志的好位置。litellm 支持把每次请求的元信息推送到多种下游系统我这里说两个常用的一个是可以把成本数据推到自建的报表库另一个是把调用日志推到日志平台做检索。还有一个容易被忽略的配置是缓存。如果业务里有大量相似的提示词反复请求比如前端的固定引导语、用户发送前的系统提示开启缓存能省不少钱。litellm_settings: cache: true cache_params: type: redis ttl: 3600缓存的原理是按提示词内容做哈希相同请求在 TTL 内直接返回缓存结果不再真实调用模型。注意动态内容或者对实时性要求高的场景不建议开缓存比如股票行情、实时翻译。我的建议是只对完全确定性的静态提示开启而且要设置合理的 TTL。5. 常见问题与排查实录5.1 报错“model not found”的排查思路这是新手最常见的问题。出现model not found时先确认请求里传的 model 是不是配置里的model_name。很多人会直接传your-provider/your-model但这个真实标识如果没有在model_list里声明网关是不认识的。还有一种情况是配置里写了但改完没重启服务。litellm 的配置是启动时加载的改 YAML 之后必须重启进程。建议启动命令加--detailed_startup它会打印出所有已注册的模型列表一眼就能看出配置是否生效。5.2 超时、限流与连接复用网关上线后第一个遇到的稳定性问题大概率是超时。三方模型接口普遍慢流式接口还可能长时间不返回数据。我看到几个团队踩过同一个坑把request_timeout设成 10 秒结果厂商接口反射弧长一点就误判超时。我的建议是普通聊天接口 30 秒流式接口要区分首包延迟和整体延迟litellm 里可以配合stream_timeout做精细控制。如果设置了重试还要考虑重试对上游厂商可能造成双倍压力所以重试次数最多两次且要开cooldown。5.3 流式响应和工具调用的兼容问题流式响应是最容易出现“看起来像 bug”的地方。如果你用 SDK 直接调用是正常的换成代理之后流式输出中断先检查两件事代理版本是否太老以及是否开启了use_responses之类的实验开关。另外一个高频问题是工具调用。很多团队做 Agent 应用时发现网关返回的tool_calls字段和预期对不上。litellm 对各家厂商的 tool_calls 格式做了统一映射但如果你同时传了tools和response_format某些厂商兼容性会变差。遇到这种情况先用最简单的消息结构复现逐步加参数定位是哪个字段引起的。5.4 成本数字对不上月底对账发现网关统计的费用和厂商账单不一致这是常见情况。先看单位litellm 默认按美元估算而某些厂商账单可能按人民币或按不同 token 计价单位出账。再看模型单价配置litellm 有内置的价格表但新出的模型、特殊定价的模型可能没收录需要你手动补充。model_list: - model_name: custom-priced-model litellm_params: model: your-provider/custom-model api_key: os.environ/KEY model_info: input_cost_per_token: 0.000001 output_cost_per_token: 0.000002补充完单价后还要注意提示词缓存命中、批量接口这类特殊计费项它们通常不计入常规 token 单价。我建议在网关日志里额外记录原始厂商账单号月底拿厂商账单和网关报表做双向核对基本一次就对平。现象可能原因排查方向请求报 model not found传了真实模型名而非逻辑名检查 model_list 中的 model_name请求超时request_timeout 设置过短调大到 30~60 秒流式输出中断代理版本过旧升级 litellm 到最新版tool_calls 解析失败同时使用 tools 与 response_format简化请求逐步定位费用对不上单价未配置或计价单位不同手动补充 model_info 单价某模型频繁触发限流权重配置不合理调整负载均衡权重虚拟密钥失效未设置 TTL 或配额耗尽检查密钥配置与预算个人经验网关这类基础设施上线前一定要做一次压测和故障演练把主模型断掉试试 fallback 是否真的会切换把虚拟密钥额度调成 0 试试拒绝逻辑是否生效。别等到线上真出问题才验证那时候每一分钟都是成本。用 litellm 这套方案落地之后我最大的感受是“模型厂商的选择自由”终于回到了自己手里。今天觉得这家贵了换那家明天觉得那个模型效果好加个配置就上线。它不会帮你选模型但能让你换模型的成本降到最低。最后分享一个小习惯每次升级 litellm 之前先看 release notes 里的 breaking changes它迭代很快但只要你 Config 文件里字段不依赖内部临时参数升级基本是无痛的。