做 AI 应用的人这两年最深的感受应该就是模型越来越多了接口也越来越乱了。今天接了一家大模型服务的 API明天产品经理说要换另一家的开源模型试试这个场景适合快一点的模型那个任务需要更强的推理能力还有团队协作时密钥怎么管理、成本怎么统计——这些问题堆在一起比调模型本身还让人头大。我第一次见到 litellm 这个项目的时候第一反应是又一个封装库但真正用起来才发现它解决的远不止是接口统一这么简单。这篇文章我把自己的使用经验完整梳理一遍从原理到配置再到踩坑给正被多模型接入折磨的同学一个可以直接照做的参考。1. 为什么需要统一模型网关碎片化时代的真实痛点1.1 每多接一家模型就多一层痛苦先还原一个很典型的场景。你是一家创业公司的后端开发产品里集成了三个语言模型一个负责实时对话要求低延迟一个负责长文档总结要求上下文够长还有一个是内部微调过的模型部署在自建的推理服务上。这三家服务的请求格式不一样鉴权方式不一样错误码不一样连流式返回的数据结构都不一样。写业务代码的时候你不得不针对每一家分别封装一层 client然后在上层再做一次适配。更麻烦的是任何一家服务升级了模型版本、改了限流策略你的代码可能就要跟着改。我见过一个项目里光是一段调用模型的逻辑就写了三个条件分支而且每个分支里还各自处理超时、重试、异常转换。这种代码短期能跑长期就是技术债。litellm 的核心理念其实很朴素它把所有主流模型服务的 API 统一成一个格式让你用一套调用代码就能对接不同服务商。底层不管你怎么变上层永远是一份稳定的接口。它本质上是一个模型网关放在你的应用和各家的模型 API 之间专门负责格式转换、路由转发、错误归一化这些脏活累活。1.2 它解决的五个核心问题我用了半年之后觉得 litellm 解决的核心问题可以归纳成五类第一是接口统一。这是最表层的能力但也是最省事的地方。所有模型调用都长一个样新接入一家服务商只需要在配置里加一行不需要写新代码。第二是故障转移。某一家模型服务不稳定是常有的事。原来你可能需要自己写 failover 逻辑在 litellm 里可以通过路由策略自动降级到备用模型用户无感知。第三是密钥安全。团队成员各自持有各家 API 密钥本身就是安全隐患。通过代理集中管理密钥业务方拿到的只是一个受限访问令牌方便做权限隔离。第四是成本与用量统计。各家服务商的计费口径不同手工统计费用很麻烦。litellm 能在调用层统一记录 token 消耗按模型、按用户、按时间段聚合月底对账非常方便。第五是团队标准化。前后端、算法、产品都通过同一个代理访问模型请求格式、错误格式、日志格式全都统一了联调和排查问题的效率高很多。1.3 什么时候不需要 litellm当然这个工具也不是银弹。如果你的项目只是固定调用一家模型服务而且没有团队协作、成本统计、模型切换这些需求那直接用原厂的 SDK 反而是更轻的选择。引入 litellm 意味着多维护一个中间层多了解一套配置体系这是需要权衡的。但我个人判断一旦你的项目里有第二家模型接入这个计划或者需要多人共用密钥统一网关的收益就远远大于成本了。2. 核心机制拆解它是怎么做到一套代码打天下的2.1 统一的请求入口litellm 最基础的使用方式是作为 Python 包直接调用。它的核心函数只有一个叫做 completion看起来长这样from litellm import completion response completion( modelprovider-a/model-large, # 这里的 provider-a 是占位符实际换成你的服务商标识 messages[{role: user, content: 介绍一下你自己}], api_key你的访问密钥, )这个函数的入参风格模仿了聊天补全接口的通用写法。litellm 拿到你的请求之后会根据 model 参数里斜杠前面的前缀判断出你要调用哪家服务然后把你的请求转换成那家服务要求的原生格式再发出去。也就是说你写的 messages 结构是通用的temperature、max_tokens 这些参数也是通用的。不同的服务商对参数命名有细微差异比如有的叫 max_tokens有的叫 max_output_tokens有的还限制枚举值这些差异都由 litellm 在内部消化掉了。2.2 模型命名规则要正确使用 litellm必须先理解它的模型命名规则。规范是服务商/模型名斜杠前面是提供方的标识斜杠后面是具体的模型名。举几个例子你就会发现规律provider-a/model-large 表示服务商 A 的大尺寸模型provider-b/model-fast 表示服务商 B 的快速模型本地部署的托管服务则可以把服务商标识配置成你自己起的名字。这个设计最聪明的地方在于模型名本身就成了路由的依据。你不需要额外写 if-else 去判断走哪条链路litellm 看到前缀自然就知道该往哪里转发。而且它还支持给模型起别名。假设你的代码里到处都写了 modelprimary-model后来发现一家服务商不够稳想换成另一家不需要改代码只要在配置里把 primary-model 这个别名重新指向新的服务商即可。2.3 代理模式和 SDK 模式的区别litellm 有两种使用形态很多人刚接触时会困惑。第一种是 SDK 模式也就是在 Python 代码里直接 import litellm当作一个库来调用。这种方式适合单机脚本、快速原型、或者已经用 Python 做 AI 应用的团队。它的优点是轻量不需要额外起服务缺点是密钥还是分散在各处也没有统一的访问控制。第二种是代理模式部署一个独立的 litellm 代理服务所有请求都打给这个代理由代理再去转发给各个模型服务商。这种方式才是完整的网关形态。业务端只需要配置一个代理地址和一个代理密钥真正各家的 API 密钥都集中存放在代理这一侧。代理模式最大的价值在于它把一个团队级别的模型接入问题变成了一个配置并部署一个服务的运维问题。前端、后端、算法同学不再需要各自去申请各家模型服务的密钥只需要找管理员申请一个代理令牌。后续要调模型路由、限流、日志审计也都在代理层统一完成。2.4 路由器从单点调用到策略分发litellm 的代理内置了一个路由器组件。它的作用不仅仅是转发请求还可以根据你定义的策略做智能分发。最常见的三种策略是基于权重的路由。你给同一个模型别名配置两个真实模型设置权重。比如 main-model 背后指向两家不同服务商的同级别模型权重各占 50%请求会被近似均匀地分发过去。这天然就能实现负载均衡。基于优先级的回退。你配置一个主模型再配置一个或多个备用模型。主模型超时或者返回错误时litellm 自动重试备用模型。这种机制在关键业务里非常实用能大幅提高调用成功率。我实际用过一次某家服务商下午出现大面积抖动我那段时间的线上请求因为自动降级成功率几乎没掉。基于用量的路由。litellm 会统计各个模型最近的延迟和错误率自动把流量导向表现更好的模型。这种策略适合有多家同类模型且希望哪个好用用哪个的场景。这些路由策略都是通过 yaml 配置声明的不需要写业务代码改配置即可调整。对应到团队协作场景中产品想调整模型分配比例只需要提一个配置变更不用等开发排期。3. 实操从零搭建一个可用的统一模型网关3.1 安装与最小启动litellm 的安装非常简单直接用 pippip install litellm[proxy]注意我推荐加 [proxy] 这个扩展标志因为代理模式需要额外的 server 依赖。如果只用 SDK 模式直接 pip install litellm 就够了。装好之后先不急着配置运行一下命令行工具验证安装是否成功litellm --help能看到帮助信息就说明装好了。此时你可以尝试用 SDK 模式做一次最小调用验证环境整体正常import litellm resp litellm.completion( modelprovider-a/model-large, messages[{role: user, content: 测试一下}], api_key你的密钥, ) print(resp.choices[0].message.content)这里能用起来基础调用链路就通了。下面我们进入代理模式的完整搭建。3.2 编写网关配置文件代理模式的灵魂在配置。我建议从最小可用的配置开始然后逐步扩展。先看一个基础的 config.yamlmodel_list: - model_name: main-chat litellm_params: model: provider-a/model-large api_key: os.environ/PROVIDER_A_KEY - model_name: fast-chat litellm_params: model: provider-b/model-fast api_key: os.environ/PROVIDER_B_KEY general_settings: master_key: sk-local-test-key database_url: sqlite:///litellm.db这个配置做了三件事定义了模型列表把 main-chat 和 fast-chat 两个别名分别映射到两家真实模型开启了一个本地数据库用于记录日志。启动代理只需要一条命令litellm --config config.yaml --port 4000启动成功后你会看到代理监听在本地的 4000 端口。现在用 curl 测一下curl http://localhost:4000/chat/completions \ -H Authorization: Bearer sk-local-test-key \ -H Content-Type: application/json \ -d { model: main-chat, messages: [{role: user, content: 你好}] }注意请求体里的 model 字段传的是别名 main-chat而不是原来的provider-a/model-large。代理看到别名后会去 model_list 里找到对应的路由目标然后完成转发。到这里一个最简模型网关就跑起来了。接下来你可以让其他同事把接口地址指向你的代理把密钥换成 master_key他们不需要再关心 provider-a 是什么了。3.3 配置回退和负载均衡前面说的还是单点转发真正体现 litellm 优势的是复杂路由。我们在模型列表里增加一个回退配置model_list: - model_name: main-chat litellm_params: model: provider-a/model-large api_key: os.environ/PROVIDER_A_KEY model_info: mode: completion - model_name: backup-chat litellm_params: model: provider-b/model-medium api_key: os.environ/PROVIDER_B_KEY litellm_settings: fallbacks: main-chat: - backup-chatfallbacks 配置的意思是调用 main-chat 时如果出现超时或特定错误自动改用 backup-chat。这个机制对生产环境极其重要。模型服务商的稳定性不受你控制但你可以在网关层面给业务上一道保险。如果想做负载均衡也有对应的配置方式。可以在同一个 model_name 下面挂多个 litellm_paramsmodel_list: - model_name: balanced-chat litellm_params: model: provider-a/model-large api_key: os.environ/PROVIDER_A_KEY - model_name: balanced-chat litellm_params: model: provider-b/model-large api_key: os.environ/PROVIDER_B_KEY router_settings: routing_strategy: simple-shuffle此时请求会轮询到这两家真实模型上。如果你更希望谁快用谁可以把 routing_strategy 改成 usage-based-routing让路由器根据实时延迟和错误率自动决策。3.4 多副本部署和监控代理本身是无状态的但依赖数据库来记录日志和 key 信息。所以生产环境里做多副本部署是水到渠成的事general_settings: master_key: sk-prod-master-key database_url: postgresql://user:passworddb-host:5432/litellm数据库从 sqlite 换成 postgres 之后多个代理副本可以共享同一份配置和日志存储。前方再挂一个负载均衡器就完成了一个小规模但完整的模型网关集群。在这套架构下流量路径是业务应用 → 负载均衡 → litellm 代理副本 → 各家模型服务。任何一层出了问题都可以通过扩容或重启来恢复不会直接波及业务代码。3.5 预算控制与用量观测网关集中流量的一个额外好处是可以做预算管理。litellm 提供了按 key 限制配额的能力。比如给某个内部项目发一个专用 key限制它每分钟最多请求 100 次general_settings: master_key: sk-prod-master-key database_url: postgresql://user:passworddb-host:5432/litellm litellm_settings: max_budget: 1000 # 总预算 1000 美元 budget_duration: 30d同时每次请求后litellm 会在数据库中记录模型的输入 token 数、输出 token 数、响应延迟等信息。基于这些数据你可以直接查出上个月各个模型花了多少钱哪个用户调用最频繁比人工统计各家服务商账单要省心太多。这一点在成本敏感的业务里属于刚需。4. 常见问题与排查技巧实录4.1 拿到 404 或 Unknown provider 报错最常遇到的问题是模型名写错了。我已经不知道多少次在代码里写了一个不存在的 provider 前缀然后看到 404。litellm 对未知前缀的报错信息还算明确会直接提示 unknown provider。排查思路很简单先确认 model 参数斜杠前面的标识符在 litellm 的支持列表里再确认斜杠后面的模型名是那家服务真实存在的版本号。如果用的是自定义托管服务确认 config.yaml 里是否正确配置了服务商标识和 base_url。我自己的习惯是先在 SDK 模式下测试最小调用确认某个 provider 前缀能通再把它写进代理配置。不要直接一步到位改 yaml不然错误发生在代理转发层排查链路会拉长。4.2 请求超时和重试风暴代理模式下超时配置是一个容易踩坑的地方。默认情况下litellm 代理的请求超时时间可能不太符合你的业务预期。比如你调用的模型是个长文本生成模型正常情况下需要两分钟才能返回但代理在 60 秒就超时了结果上游模型还在继续生成代理已经返回错误。客户端如果设置自动重试就会造成请求重复堆积费用翻倍。这个问题的解法是分层设置超时。当你使用回退功能时建议给每层模型单独设置合理的超时时间litellm_settings: request_timeout: 600 fallbacks: main-chat: - backup-chat如果某个模型服务固定需要较长时间还可以在模型配置里单独指定- model_name: slow-model litellm_params: model: provider-a/model-extra-long api_key: os.environ.PROVIDER_A_KEY timeout: 900另外一个实操心得是客户端不要做过于激进的自动重试。网关层已经有回退机制了客户端只需要处理最终的超时错误即可。如果两边都在重试一旦上游服务抖动重试流量会被放大好几倍反而是帮倒忙。4.3 密钥管理不当导致的安全隐患代理模式的初衷之一是集中管理密钥但很多人用着用着就会犯一个错误把各家服务商的密钥直接写在 yaml 明文里然后整个仓库提交到代码管理平台。我第一次部署时也这么干过后来意识到这就是给公司的账单送人头。正确做法是利用环境变量注入model_list: - model_name: main-chat litellm_params: model: provider-a/model-large api_key: os.environ/PROVIDER_A_KEY服务商密钥只放在服务器环境变量或者密钥管理服务中yaml 文件本身可以安全入库。另外代理的 master_key 务必使用高强度随机串不要用 sk-test 这类弱口令。之前就有团队把默认 master_key 暴露在公网结果被人盗用疯狂调用模型月底账单直接爆掉。4.4 同一模型在不同服务商之间的效果差异很多人误以为同一个模型名在不同服务商那里差不多。实际上即使是同级别的模型不同服务商的提示词格式、默认参数、上下文裁剪策略都不一样。我在一次迁移中发现同一段提示词在服务商 A 上输出正常换到服务商 B 后格式明显变差。排查了半天最后发现是服务商 B 的接口对 system 消息和 user 消息的处理方式与 A 不完全一致。litellm 虽然统一了调用格式但它不会替你做提示词层面的适配。切换模型后一定要针对新模型的输出做一些回归测试尤其是涉及结构化输出时。4.5 数据库连接池和日志写入瓶颈如果你用了 sqlite 作为代理的数据库在请求量上来之后很快会遇到写入瓶颈。sqlite 不擅长高并发写入日志记录本身会拖慢请求响应。我的建议是生产环境至少换到 postgres并且给 litellm 的数据库表做定期归档。因为 token 使用量和请求日志都是增长型数据长时间不清理会让查询变慢甚至影响代理本身的持久化操作。早期我部署时没在意结果跑了三个月之后日志表已经有几千万行控制台打开都要等好几秒。4.6 本地测试和远程模型服务的网络问题另外一个小经验本地起代理、远程调模型服务时要确认你的服务器能稳定访问模型服务商的接口。有些云环境的出网策略比较严格需要配置白名单或者网络代理。很多同学在本地跑通了一到服务器上就各种超时八成不是 litellm 的问题而是网络出网被限制。排查这类问题可以先不通过 litellm直接在服务器上用 curl 测试模型服务商的接口看能不能通再回过来排查配置。5. 一些值得深入的方向如果你已经把 litellm 跑起来了后面有几个方向值得继续探索。第一是缓存。litellm 支持对历史请求做语义缓存重复的 prompt 可以直接返回缓存结果。对于业务中重复率高的场景比如客服问答、知识库检索缓存可以显著降低成本和延迟。配置上一两行就能开起来但需要想清楚缓存命中条件和失效策略避免给用户返回过期内容。第二是模型质量看板。加上数据库之后你已经有了所有请求的延迟、token 消耗、错误率数据。可以基于这些数据做一个简单的可视化看板按模型维度看调用量和成本趋势。这个对技术管理者和预算决策特别有帮助比月底翻账单靠谱得多。第三是多环境管理。开发、测试、生产三套环境用不同的代理配置通过环境变量区分。开发环境可以用便宜的模型生产环境用质量更高的模型而业务代码完全不用改因为统一用的是别名。这几乎是无感切换也是我推荐每个团队都试一下的做法。我自己在实际操作中最深的体会是litellm 真正省下的不是写那几行适配代码的时间而是团队协作中的沟通成本。以前接一个新模型要拉群、对文档、联调折腾一两天。现在配置里加一行测试几分钟再灰度上线整个链路顺畅很多。而且因为错误格式统一了排查问题也不再需要对照不同服务商的文档去翻译报错信息定位速度提升非常明显。如果你正在为多模型接入的事发愁建议先拿一个小项目把代理跑起来感受一下所有模型长一个样的开发体验。等用顺手了再把路由策略、预算控制、监控面板一个个加上去。这个工具不难但能把很多人从模型接入的泥潭里解放出来把精力放回真正的业务逻辑上。 
长河君 · 2026/10/13 11:42:30 · 阅读 1.2k LiteLLM模型网关实战：统一多模型接入，告别API碎片化
做 AI 应用的人这两年最深的感受应该就是模型越来越多了接口也越来越乱了。今天接了一家大模型服务的 API明天产品经理说要换另一家的开源模型试试这个场景适合快一点的模型那个任务需要更强的推理能力还有团队协作时密钥怎么管理、成本怎么统计——这些问题堆在一起比调模型本身还让人头大。我第一次见到 litellm 这个项目的时候第一反应是又一个封装库但真正用起来才发现它解决的远不止是接口统一这么简单。这篇文章我把自己的使用经验完整梳理一遍从原理到配置再到踩坑给正被多模型接入折磨的同学一个可以直接照做的参考。1. 为什么需要统一模型网关碎片化时代的真实痛点1.1 每多接一家模型就多一层痛苦先还原一个很典型的场景。你是一家创业公司的后端开发产品里集成了三个语言模型一个负责实时对话要求低延迟一个负责长文档总结要求上下文够长还有一个是内部微调过的模型部署在自建的推理服务上。这三家服务的请求格式不一样鉴权方式不一样错误码不一样连流式返回的数据结构都不一样。写业务代码的时候你不得不针对每一家分别封装一层 client然后在上层再做一次适配。更麻烦的是任何一家服务升级了模型版本、改了限流策略你的代码可能就要跟着改。我见过一个项目里光是一段调用模型的逻辑就写了三个条件分支而且每个分支里还各自处理超时、重试、异常转换。这种代码短期能跑长期就是技术债。litellm 的核心理念其实很朴素它把所有主流模型服务的 API 统一成一个格式让你用一套调用代码就能对接不同服务商。底层不管你怎么变上层永远是一份稳定的接口。它本质上是一个模型网关放在你的应用和各家的模型 API 之间专门负责格式转换、路由转发、错误归一化这些脏活累活。1.2 它解决的五个核心问题我用了半年之后觉得 litellm 解决的核心问题可以归纳成五类第一是接口统一。这是最表层的能力但也是最省事的地方。所有模型调用都长一个样新接入一家服务商只需要在配置里加一行不需要写新代码。第二是故障转移。某一家模型服务不稳定是常有的事。原来你可能需要自己写 failover 逻辑在 litellm 里可以通过路由策略自动降级到备用模型用户无感知。第三是密钥安全。团队成员各自持有各家 API 密钥本身就是安全隐患。通过代理集中管理密钥业务方拿到的只是一个受限访问令牌方便做权限隔离。第四是成本与用量统计。各家服务商的计费口径不同手工统计费用很麻烦。litellm 能在调用层统一记录 token 消耗按模型、按用户、按时间段聚合月底对账非常方便。第五是团队标准化。前后端、算法、产品都通过同一个代理访问模型请求格式、错误格式、日志格式全都统一了联调和排查问题的效率高很多。1.3 什么时候不需要 litellm当然这个工具也不是银弹。如果你的项目只是固定调用一家模型服务而且没有团队协作、成本统计、模型切换这些需求那直接用原厂的 SDK 反而是更轻的选择。引入 litellm 意味着多维护一个中间层多了解一套配置体系这是需要权衡的。但我个人判断一旦你的项目里有第二家模型接入这个计划或者需要多人共用密钥统一网关的收益就远远大于成本了。2. 核心机制拆解它是怎么做到一套代码打天下的2.1 统一的请求入口litellm 最基础的使用方式是作为 Python 包直接调用。它的核心函数只有一个叫做 completion看起来长这样from litellm import completion response completion( modelprovider-a/model-large, # 这里的 provider-a 是占位符实际换成你的服务商标识 messages[{role: user, content: 介绍一下你自己}], api_key你的访问密钥, )这个函数的入参风格模仿了聊天补全接口的通用写法。litellm 拿到你的请求之后会根据 model 参数里斜杠前面的前缀判断出你要调用哪家服务然后把你的请求转换成那家服务要求的原生格式再发出去。也就是说你写的 messages 结构是通用的temperature、max_tokens 这些参数也是通用的。不同的服务商对参数命名有细微差异比如有的叫 max_tokens有的叫 max_output_tokens有的还限制枚举值这些差异都由 litellm 在内部消化掉了。2.2 模型命名规则要正确使用 litellm必须先理解它的模型命名规则。规范是服务商/模型名斜杠前面是提供方的标识斜杠后面是具体的模型名。举几个例子你就会发现规律provider-a/model-large 表示服务商 A 的大尺寸模型provider-b/model-fast 表示服务商 B 的快速模型本地部署的托管服务则可以把服务商标识配置成你自己起的名字。这个设计最聪明的地方在于模型名本身就成了路由的依据。你不需要额外写 if-else 去判断走哪条链路litellm 看到前缀自然就知道该往哪里转发。而且它还支持给模型起别名。假设你的代码里到处都写了 modelprimary-model后来发现一家服务商不够稳想换成另一家不需要改代码只要在配置里把 primary-model 这个别名重新指向新的服务商即可。2.3 代理模式和 SDK 模式的区别litellm 有两种使用形态很多人刚接触时会困惑。第一种是 SDK 模式也就是在 Python 代码里直接 import litellm当作一个库来调用。这种方式适合单机脚本、快速原型、或者已经用 Python 做 AI 应用的团队。它的优点是轻量不需要额外起服务缺点是密钥还是分散在各处也没有统一的访问控制。第二种是代理模式部署一个独立的 litellm 代理服务所有请求都打给这个代理由代理再去转发给各个模型服务商。这种方式才是完整的网关形态。业务端只需要配置一个代理地址和一个代理密钥真正各家的 API 密钥都集中存放在代理这一侧。代理模式最大的价值在于它把一个团队级别的模型接入问题变成了一个配置并部署一个服务的运维问题。前端、后端、算法同学不再需要各自去申请各家模型服务的密钥只需要找管理员申请一个代理令牌。后续要调模型路由、限流、日志审计也都在代理层统一完成。2.4 路由器从单点调用到策略分发litellm 的代理内置了一个路由器组件。它的作用不仅仅是转发请求还可以根据你定义的策略做智能分发。最常见的三种策略是基于权重的路由。你给同一个模型别名配置两个真实模型设置权重。比如 main-model 背后指向两家不同服务商的同级别模型权重各占 50%请求会被近似均匀地分发过去。这天然就能实现负载均衡。基于优先级的回退。你配置一个主模型再配置一个或多个备用模型。主模型超时或者返回错误时litellm 自动重试备用模型。这种机制在关键业务里非常实用能大幅提高调用成功率。我实际用过一次某家服务商下午出现大面积抖动我那段时间的线上请求因为自动降级成功率几乎没掉。基于用量的路由。litellm 会统计各个模型最近的延迟和错误率自动把流量导向表现更好的模型。这种策略适合有多家同类模型且希望哪个好用用哪个的场景。这些路由策略都是通过 yaml 配置声明的不需要写业务代码改配置即可调整。对应到团队协作场景中产品想调整模型分配比例只需要提一个配置变更不用等开发排期。3. 实操从零搭建一个可用的统一模型网关3.1 安装与最小启动litellm 的安装非常简单直接用 pippip install litellm[proxy]注意我推荐加 [proxy] 这个扩展标志因为代理模式需要额外的 server 依赖。如果只用 SDK 模式直接 pip install litellm 就够了。装好之后先不急着配置运行一下命令行工具验证安装是否成功litellm --help能看到帮助信息就说明装好了。此时你可以尝试用 SDK 模式做一次最小调用验证环境整体正常import litellm resp litellm.completion( modelprovider-a/model-large, messages[{role: user, content: 测试一下}], api_key你的密钥, ) print(resp.choices[0].message.content)这里能用起来基础调用链路就通了。下面我们进入代理模式的完整搭建。3.2 编写网关配置文件代理模式的灵魂在配置。我建议从最小可用的配置开始然后逐步扩展。先看一个基础的 config.yamlmodel_list: - model_name: main-chat litellm_params: model: provider-a/model-large api_key: os.environ/PROVIDER_A_KEY - model_name: fast-chat litellm_params: model: provider-b/model-fast api_key: os.environ/PROVIDER_B_KEY general_settings: master_key: sk-local-test-key database_url: sqlite:///litellm.db这个配置做了三件事定义了模型列表把 main-chat 和 fast-chat 两个别名分别映射到两家真实模型开启了一个本地数据库用于记录日志。启动代理只需要一条命令litellm --config config.yaml --port 4000启动成功后你会看到代理监听在本地的 4000 端口。现在用 curl 测一下curl http://localhost:4000/chat/completions \ -H Authorization: Bearer sk-local-test-key \ -H Content-Type: application/json \ -d { model: main-chat, messages: [{role: user, content: 你好}] }注意请求体里的 model 字段传的是别名 main-chat而不是原来的provider-a/model-large。代理看到别名后会去 model_list 里找到对应的路由目标然后完成转发。到这里一个最简模型网关就跑起来了。接下来你可以让其他同事把接口地址指向你的代理把密钥换成 master_key他们不需要再关心 provider-a 是什么了。3.3 配置回退和负载均衡前面说的还是单点转发真正体现 litellm 优势的是复杂路由。我们在模型列表里增加一个回退配置model_list: - model_name: main-chat litellm_params: model: provider-a/model-large api_key: os.environ/PROVIDER_A_KEY model_info: mode: completion - model_name: backup-chat litellm_params: model: provider-b/model-medium api_key: os.environ/PROVIDER_B_KEY litellm_settings: fallbacks: main-chat: - backup-chatfallbacks 配置的意思是调用 main-chat 时如果出现超时或特定错误自动改用 backup-chat。这个机制对生产环境极其重要。模型服务商的稳定性不受你控制但你可以在网关层面给业务上一道保险。如果想做负载均衡也有对应的配置方式。可以在同一个 model_name 下面挂多个 litellm_paramsmodel_list: - model_name: balanced-chat litellm_params: model: provider-a/model-large api_key: os.environ/PROVIDER_A_KEY - model_name: balanced-chat litellm_params: model: provider-b/model-large api_key: os.environ/PROVIDER_B_KEY router_settings: routing_strategy: simple-shuffle此时请求会轮询到这两家真实模型上。如果你更希望谁快用谁可以把 routing_strategy 改成 usage-based-routing让路由器根据实时延迟和错误率自动决策。3.4 多副本部署和监控代理本身是无状态的但依赖数据库来记录日志和 key 信息。所以生产环境里做多副本部署是水到渠成的事general_settings: master_key: sk-prod-master-key database_url: postgresql://user:passworddb-host:5432/litellm数据库从 sqlite 换成 postgres 之后多个代理副本可以共享同一份配置和日志存储。前方再挂一个负载均衡器就完成了一个小规模但完整的模型网关集群。在这套架构下流量路径是业务应用 → 负载均衡 → litellm 代理副本 → 各家模型服务。任何一层出了问题都可以通过扩容或重启来恢复不会直接波及业务代码。3.5 预算控制与用量观测网关集中流量的一个额外好处是可以做预算管理。litellm 提供了按 key 限制配额的能力。比如给某个内部项目发一个专用 key限制它每分钟最多请求 100 次general_settings: master_key: sk-prod-master-key database_url: postgresql://user:passworddb-host:5432/litellm litellm_settings: max_budget: 1000 # 总预算 1000 美元 budget_duration: 30d同时每次请求后litellm 会在数据库中记录模型的输入 token 数、输出 token 数、响应延迟等信息。基于这些数据你可以直接查出上个月各个模型花了多少钱哪个用户调用最频繁比人工统计各家服务商账单要省心太多。这一点在成本敏感的业务里属于刚需。4. 常见问题与排查技巧实录4.1 拿到 404 或 Unknown provider 报错最常遇到的问题是模型名写错了。我已经不知道多少次在代码里写了一个不存在的 provider 前缀然后看到 404。litellm 对未知前缀的报错信息还算明确会直接提示 unknown provider。排查思路很简单先确认 model 参数斜杠前面的标识符在 litellm 的支持列表里再确认斜杠后面的模型名是那家服务真实存在的版本号。如果用的是自定义托管服务确认 config.yaml 里是否正确配置了服务商标识和 base_url。我自己的习惯是先在 SDK 模式下测试最小调用确认某个 provider 前缀能通再把它写进代理配置。不要直接一步到位改 yaml不然错误发生在代理转发层排查链路会拉长。4.2 请求超时和重试风暴代理模式下超时配置是一个容易踩坑的地方。默认情况下litellm 代理的请求超时时间可能不太符合你的业务预期。比如你调用的模型是个长文本生成模型正常情况下需要两分钟才能返回但代理在 60 秒就超时了结果上游模型还在继续生成代理已经返回错误。客户端如果设置自动重试就会造成请求重复堆积费用翻倍。这个问题的解法是分层设置超时。当你使用回退功能时建议给每层模型单独设置合理的超时时间litellm_settings: request_timeout: 600 fallbacks: main-chat: - backup-chat如果某个模型服务固定需要较长时间还可以在模型配置里单独指定- model_name: slow-model litellm_params: model: provider-a/model-extra-long api_key: os.environ.PROVIDER_A_KEY timeout: 900另外一个实操心得是客户端不要做过于激进的自动重试。网关层已经有回退机制了客户端只需要处理最终的超时错误即可。如果两边都在重试一旦上游服务抖动重试流量会被放大好几倍反而是帮倒忙。4.3 密钥管理不当导致的安全隐患代理模式的初衷之一是集中管理密钥但很多人用着用着就会犯一个错误把各家服务商的密钥直接写在 yaml 明文里然后整个仓库提交到代码管理平台。我第一次部署时也这么干过后来意识到这就是给公司的账单送人头。正确做法是利用环境变量注入model_list: - model_name: main-chat litellm_params: model: provider-a/model-large api_key: os.environ/PROVIDER_A_KEY服务商密钥只放在服务器环境变量或者密钥管理服务中yaml 文件本身可以安全入库。另外代理的 master_key 务必使用高强度随机串不要用 sk-test 这类弱口令。之前就有团队把默认 master_key 暴露在公网结果被人盗用疯狂调用模型月底账单直接爆掉。4.4 同一模型在不同服务商之间的效果差异很多人误以为同一个模型名在不同服务商那里差不多。实际上即使是同级别的模型不同服务商的提示词格式、默认参数、上下文裁剪策略都不一样。我在一次迁移中发现同一段提示词在服务商 A 上输出正常换到服务商 B 后格式明显变差。排查了半天最后发现是服务商 B 的接口对 system 消息和 user 消息的处理方式与 A 不完全一致。litellm 虽然统一了调用格式但它不会替你做提示词层面的适配。切换模型后一定要针对新模型的输出做一些回归测试尤其是涉及结构化输出时。4.5 数据库连接池和日志写入瓶颈如果你用了 sqlite 作为代理的数据库在请求量上来之后很快会遇到写入瓶颈。sqlite 不擅长高并发写入日志记录本身会拖慢请求响应。我的建议是生产环境至少换到 postgres并且给 litellm 的数据库表做定期归档。因为 token 使用量和请求日志都是增长型数据长时间不清理会让查询变慢甚至影响代理本身的持久化操作。早期我部署时没在意结果跑了三个月之后日志表已经有几千万行控制台打开都要等好几秒。4.6 本地测试和远程模型服务的网络问题另外一个小经验本地起代理、远程调模型服务时要确认你的服务器能稳定访问模型服务商的接口。有些云环境的出网策略比较严格需要配置白名单或者网络代理。很多同学在本地跑通了一到服务器上就各种超时八成不是 litellm 的问题而是网络出网被限制。排查这类问题可以先不通过 litellm直接在服务器上用 curl 测试模型服务商的接口看能不能通再回过来排查配置。5. 一些值得深入的方向如果你已经把 litellm 跑起来了后面有几个方向值得继续探索。第一是缓存。litellm 支持对历史请求做语义缓存重复的 prompt 可以直接返回缓存结果。对于业务中重复率高的场景比如客服问答、知识库检索缓存可以显著降低成本和延迟。配置上一两行就能开起来但需要想清楚缓存命中条件和失效策略避免给用户返回过期内容。第二是模型质量看板。加上数据库之后你已经有了所有请求的延迟、token 消耗、错误率数据。可以基于这些数据做一个简单的可视化看板按模型维度看调用量和成本趋势。这个对技术管理者和预算决策特别有帮助比月底翻账单靠谱得多。第三是多环境管理。开发、测试、生产三套环境用不同的代理配置通过环境变量区分。开发环境可以用便宜的模型生产环境用质量更高的模型而业务代码完全不用改因为统一用的是别名。这几乎是无感切换也是我推荐每个团队都试一下的做法。我自己在实际操作中最深的体会是litellm 真正省下的不是写那几行适配代码的时间而是团队协作中的沟通成本。以前接一个新模型要拉群、对文档、联调折腾一两天。现在配置里加一行测试几分钟再灰度上线整个链路顺畅很多。而且因为错误格式统一了排查问题也不再需要对照不同服务商的文档去翻译报错信息定位速度提升非常明显。如果你正在为多模型接入的事发愁建议先拿一个小项目把代理跑起来感受一下所有模型长一个样的开发体验。等用顺手了再把路由策略、预算控制、监控面板一个个加上去。这个工具不难但能把很多人从模型接入的泥潭里解放出来把精力放回真正的业务逻辑上。