统一大模型网关：模型切换、按量计费与多租户隔离的实战指南

前后端联调、模型切换、按量计费、多租户隔离——这些在接入各类大模型时总会遇到的活过去是各做各的每个模型一套接口一套鉴权一套SDK代码越堆越乱。后来我把模型调用统一代理到一个开源网关后面整套逻辑才顺了。这个网关就是本文要说的 litellm。litellm 本质上是一个模型路由器它对外暴露一个兼容主流接口的统一入口内部负责把请求转发给不同的大模型提供商各家模型厂商或自建服务并统一处理鉴权、重试、限流、预算控制、日志追踪这些外围工作。说白了它把调模型这件事从一个散装流程收敛成了一个标准化的内部基础设施。这篇文章适合正在做 AI 应用开发、或者维护公司内部模型服务的工程师参考。不管你是刚把第一个聊天机器人接上生产环境还是已经在维护多套模型调用体系这里面梳理的内容都是我实际部署和维护中沉淀下来的可以直接抄作业的那种。1. 核心设计思路为什么要做统一网关接入先讲清楚一个底层逻辑接入模型的方式其实有两种路线。一种是SDK 直连也就是在业务代码里直接调用各家模型厂商的 SDK 或 HTTP 接口。这种做法的好处是简单直接一个服务调两三个模型的时候非常清爽坏处是一旦模型数量多起来各种鉴权 key 散落在代码里、每个模型的错误码格式不一致、重试策略各写各的运维视角基本失控。另一种就是本文要展开的网关代理所有业务方只面对一个统一入口。这个网关对外提供一套固定的 API 协议内部再去适配不同模型厂商的请求格式、鉴权方式和返回结构。litellm 选的正是第二条路。它的核心思路用一句话概括将模型调用抽象为一个内部标准动作把用哪个模型、怎么计费、怎么限流、是否降级全部变成了配置项而非代码逻辑。这样做带来的实际收益我拆成三点来说。1.1 收益一业务代码与模型解耦接多模型这件事最大的坑在于绑定。假设你的应用一开始直连了某家模型后来因为效果、成本、合规等原因要切换另一家传统方式需要改动业务代码、重新联调、回归测试整体发布一次。有 litellm 之后业务代码里只需要保留一个调用地址和一套 API 格式。切换模型时改动只发生在网关的配置层换个模型名称或者调整一下路由规则即可业务服务完全无感知。这一点在模型效果迭代极快的当下价值非常大。1.2 收益二统一治理入口模型调用和数据库访问一样属于需要治理的基础设施。哪些应用在调模型、每个应用调了多少 token、月成本是多少、有没有异常调用这些问题在直连模式下非常难回答。统一网关之后所有流量都经过同一个节点。认证鉴权、调用审计、成本分摊、租户隔离、流控限流这些能力都可以在网关层面集中实现。litellm 自带的虚拟 key、预算管理、多租户功能解决的就是这一类问题。1.3 收益三高可用策略内置单模型服务发生故障或者限流时应用几乎没有还手之力。litellm 支持配置多个模型实例做负载均衡当主模型调用失败或超时时自动把请求转发到备用模型实现 failover。这套机制在业务上很有价值。比如你的主模型是效果最好的那个但时不时的限流或抽风你可以配一个效果略差但稳定的备用模型。当主模型出问题时系统自动降级保证产品功能的可用性。用户感知到的只是响应可能稍慢但绝对不会直接看到报错。2. 核心功能拆解路由、预算、密钥三位一体litellm 的功能模块里最值得先掌握的是三个东西模型路由规则、虚拟密钥体系和预算配额。这三者构成了网关的核心骨架。2.1 模型路由与降级机制litellm 的路由逻辑在配置文件中通过model_list声明。你可以为同一个逻辑模型名称配置多个实际模型端点网关按照策略进行分发。model_list: - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_key: sk-xxx - model_name: gpt-4o-mini litellm_params: model: anthropic/claude-sonnet-4 api_key: sk-yyy model_info: mode: fallback这里有个重要概念model_name是业务方看到的逻辑名称litellm_params里的model字段才是网关实际转发的目标模型标识。同一个model_name可以配置多次litellm 默认在所有可用实例间做负载均衡当主实例返回错误时尝试下一个。需要注意一点路由粒度的控制可以做得更细。官网支持按用户、按租户、按预算组来绑定不同的路由策略。比如你的免费用户默认走性价比高的模型付费用户走效果最好的模型可以在 key 生成时指定模型白名单来实现。2.2 虚拟密钥体系多租户与安全隔离litellm 不推荐直接把模型厂商的原始 key 交给业务方。它提供了一套虚拟 keyVirtual Key机制由管理员在网关里生成。生成的虚拟 key 可以绑定几个属性所属用户或团队、可访问的模型范围、预算额度、过期时间。业务方拿到的只是一个形如sk-litellm-xxxx的字符串背后对应的真实模型 key 由网关统一保管。这套机制的价值主要体现在三点安全隔离真实模型 key 不出网关降低了泄露的风险。即使某个业务方的虚拟 key 泄露了影响范围也仅限于该 key 绑定的模型和额度可以在网关一键吊销。用量审计每个虚拟 key 的调用量、token 消耗、费用都有独立记录月底对账直接按 key 维度导报表。权限控制通过 key 绑定模型范围天然解决了多团队场景下的模型越权问题。比如 A 组只能用模型 XB 组只能用模型 Y各自持 key 互不影响。2.3 预算配额与限流策略预算控制是 litellm 区别于普通代理工具的一个重要特性。它支持三个层级的预算全局预算、Key 预算、用户预算。预算单位可以是美元金额也可以是 token 数量。当某个 key 的消耗超过设定阈值时网关直接拒绝新的请求并返回 429 状态码业务方会收到明确的配额耗尽提示。我在实际使用中偏好在网关层直接做预算拦截而不是完全依赖模型厂商后台的用量报表做事后控制。原因很现实事后的账单能看但不及时等到月度账单出来才发现某个测试 key 因为循环调用跑了巨额费用那就晚了。网关层在每次请求前检查配额虽然多了一次查询开销但实时性是最好的。关于限流补充一个关键细节litellm 支持配置每分钟请求数RPM和每分钟 token 数TPM两种限流维度。前者适合聊天类应用后者更适合大规模跑批任务。在多模型混合路由时建议为每个后端模型分别配置限流参数避免一个租户的突发流量打爆整个网关。3. 部署实操从零搭建统一模型入口下面进入动手环节。我用 Docker 方式部署 litellm 网关配合内置的 SQLite 存储来做最小可用闭环。生产环境建议把 SQLite 换成 PostgreSQL但从零开始体验流程的话这个方案够用了。3.1 环境准备与启动litellm 的官方镜像发布在 Docker Hub 上直接拉取即可。假设你有一个干净的 Linux 服务器或本地 Docker 环境先准备一个存放配置和数据的目录mkdir -p /opt/litellm cd /opt/litellm创建配置文件config.yaml内容如下model_list: - model_name: my-main-model litellm_params: model: openai/gpt-4o-mini api_key: ${OPENAI_API_KEY} - model_name: my-fallback-model litellm_params: model: anthropic/claude-sonnet-4 api_key: ${ANTHROPIC_API_KEY}这里把模型厂商的真实 key 通过环境变量注入而不是直接写在文件里。这是一个安全性习惯配置文件可能会被复制、提交到仓库但环境变量通常不会被误传。启动容器docker run -d \ --name litellm-proxy \ -v /opt/litellm/config.yaml:/app/config.yaml \ -e OPENAI_API_KEYsk-xxxx \ -e ANTHROPIC_API_KEYsk-yyyy \ -p 4000:4000 \ ghcr.io/berriai/litellm:main-latest \ --config /app/config.yaml --port 4000启动后litellm 会在宿主机 4000 端口监听。验证方式很简单curl http://localhost:4000/health/liveliness返回{status: OK}即说明网关已正常运行。3.2 创建虚拟 Key 并完成首次调用登录管理后台默认地址是http://localhost:4000/ui初次进入需要设置管理员账号密码。登录后进入虚拟密钥页面点击创建。创建时可以指定允许访问的模型名称、绑定用户并设置预算额度。这里我通常建议从小额预算 单模型开始测试比如额度设为 1 美元只允许访问my-main-model这样即使调用出错也可以控制损失。拿到虚拟 key 后标准调用方式是curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-litellm-test-key \ -d { model: my-main-model, messages: [ {role: user, content: 你好请做自我介绍} ] }如果一切正常你会收到一份标准的 OpenAI 格式响应包含id、choices、usage等字段。此时业务方根本不需要关心接入的真实模型是哪家他们眼中只有一个事实我在调用一个统一入口。3.3 配置多云路由主备切换与负载均衡前面配置文件里其实已经埋了一个伏笔——my-main-model和my-fallback-model是两个独立的逻辑名称。要让它们形成主备自动切换的关系需要引入 litellm 的路由策略配置。配置方案如下在 model_list 中将多个实际模型绑定到同一个逻辑名称my-unified-model并利用model_info指定优先级和角色。model_list: - model_name: my-unified-model litellm_params: model: openai/gpt-4o-mini api_key: ${OPENAI_API_KEY} model_info: mode: default - model_name: my-unified-model litellm_params: model: anthropic/claude-sonnet-4 api_key: ${ANTHROPIC_API_KEY} model_info: mode: fallback请求时统一使用my-unified-model这个名称。litellm 会先尝试第一个实例default当该实例返回错误、超时或触发了重试条件时自动转发给 fallback 实例。这里有一个值得注意的细节默认情况下多个同名校验实例是同时参与负载均衡的并不会因为标记了 fallback 就只走主走备。具体的行为可以通过routing_strategy参数调整。如果想严格按主备而不是轮询的方式工作需要把策略改为usage-based-routing或显式配置权重。这个细节建议在你的测试环境里实际验证一下不同版本的默认行为可能有细微差别。3.4 Helm 方式部署到 Kubernetes 集群如果你的业务跑在 Kubernetes 里litellm 官方也提供了 Helm Chart部署方式更加贴合容器化工作流。helm repo add litellm https://litellm.github.io/helm-charts helm repo update helm install litellm-proxy litellm/litellm \ --set configPath/app/config.yaml \ --set config.yamlContent$(cat ./config.yaml | base64)Helm 方式的主要价值在于可以通过 values 文件管理不同环境测试、预发、生产的配置差异配合 ArgoCD 等 GitOps 工具实现配置即代码。对我个人体验来说Helm 方式相对省事因为升级版本、扩缩容、暴露 Service 这些都可以用标准化的 Chart 参数完成。4. 踩坑实录与问题排查速查所有生产系统的价值都体现在稳定运行上。litellm 用起来顺手但有些坑不提前知道的话排查起来会非常痛苦。这一节梳理我在实际操作中碰到的问题和对应解法。4.1 预算耗尽后调用静默失败这是一个非常隐蔽的问题。当你给某个 key 设置的预算额度较小调用量快速消耗完之后正常流程下网关会返回 429 状态码。但如果你在业务代码里没有对这种状态码做特殊处理而是统一当作普通错误重试就会出现大量重试请求堆在网关上造成雪球效应。建议方案是在网关的配置里针对预算超限状态码做限流策略并且在业务代码里对 HTTP 429 直接走短路逻辑不做重试。可以给用户一个友好提示等下一周期或提高配额后再调用。4.2 多模型切换时上下文格式不兼容litellm 会把 OpenAI 格式的请求转换成各模型厂商的内部格式。大多数情况下转换是透明的但有些模型对 system prompt 的支持方式不同有些模型对 message 里 role 字段的取值有自己的要求。一个典型场景是同一个对话上下文在主模型上正常工作切到备用模型后突然报参数错误或者返回结果明显偏离预期。这是因为不同厂商对同样的输入做了不一样的处理。经验是在做主备路由之前先用少量典型请求在目标模型上做一次格式兼容性验证而不是直接信任路由层的自动转换。4.3 日志追踪与联调排错litellm 在管理后台提供了较完整的请求日志查询功能可以看到每次调用的请求体、响应体、耗时、消耗 token 数量、命中了哪个后端模型。这个功能在联调排错时价值非常高。如果你需要将日志集成到公司已有的监控体系里litellm 支持将日志批量转发到 Prometheus 或自定义 Webhook。生产环境建议至少做到记录每次请求的模型名称、虚拟 key 身份、耗时记录响应状态码和错误信息定期统计每个模型组的调用量和 token 消耗有了这些数据你做成本归因和容量规划时才不是拍脑袋。4.4 高并发场景下的连接数规划litellm 作为网关本质是转发请求。当并发量上来之后它会同时维持与业务方的连接和与模型厂商的连接。如果模型厂商的上游速率限制较低比如每分钟只允许一定量的请求网关需要能感知并合理排队。配置参数max_retries和request_timeout建议按照你使用的模型厂商的限制来设置。不要盲目加大请求超时时间否则一个上游慢请求会占住你网关的连接资源拖垮其他正常请求。4.5 版本升级前备份litellm 功能迭代比较快升级版本前务必备份配置文件和数据库。配置文件倒还好说数据库里存储的虚拟 key、预算记录、日志数据属于可再生的部分但丢了重建起来也麻烦。升级后及时关注官方更新日志中关于路由策略和默认行为的变更提示。有时候一次升级会导致路由权重计算方式变化在你不注意的时候改变了流量分配结果。5. 后续可以扩展的方向litellm 这套体系搭起来之后你可以沿着几个方向继续深挖。一是对接公司内部的自建模型服务。只要自建服务暴露了兼容的 HTTP 接口litellm 可以通过自定义 provider 的方式接入把它和外部模型放在同一套路由逻辑里管理。内部服务和外部模型互为备份整体的容灾能力会明显提升。二是做细粒度的成本归因。虚拟 key 的维度已经能说明哪个团队花的钱多但如果想进一步精确到哪个功能模块花的钱多可以约定在请求的 metadata 字段里携带业务标签。litellm 支持将这部分数据随日志导出做进一步的透视分析。三是打通 CI/CD 流程。litellm 支持针对模型做离线评测在代码合并前自动用一组固定测试用例跑一遍模型效果帮助你在切换模型或修改提示词时提前发现问题。这套机制可以理解为模型调用的回归测试。回到开头那个问题当你的业务不再只依赖一家模型厂商时一个稳定的网关层就不是可选项而是必需品。litellm 在做到这一点的基础上还附送了预算控制、密钥治理、日志审计这些企业级能力。就我个人实际体验而言整套链路跑顺之后最明显的感受是心理负担小了很多——不需要担心某个模型挂了导致整个服务瘫掉不需要在月底对着账单一个个数接口调用次数新同事入职后也不用贴一张写着各家模型 API key 的便笺纸。基础设施不就该是这样吗用稳定的结构去承接变化的部分把不确定性挡在核心业务之外。