前后端联调、模型切换、按量计费、多租户隔离——这些在接入各类大模型时总会遇到的活，过去是各做各的，每个模型一套接口一套鉴权一套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 交给业务方。它提供了一套虚拟 key（Virtual Key）机制，由管理员在网关里生成。
生成的虚拟 key 可以绑定几个属性：所属用户或团队、可访问的模型范围、预算额度、过期时间。业务方拿到的只是一个形如sk-litellm-xxxx的字符串，背后对应的真实模型 key 由网关统一保管。
这套机制的价值主要体现在三点：
安全隔离：真实模型 key 不出网关，降低了泄露的风险。即使某个业务方的虚拟 key 泄露了，影响范围也仅限于该 key 绑定的模型和额度，可以在网关一键吊销。
用量审计：每个虚拟 key 的调用量、token 消耗、费用都有独立记录，月底对账直接按 key 维度导报表。
权限控制：通过 key 绑定模型范围，天然解决了多团队场景下的模型越权问题。比如 A 组只能用模型 X，B 组只能用模型 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_KEY=sk-xxxx \ -e ANTHROPIC_API_KEY=sk-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 的便笺纸。基础设施不就该是这样吗？用稳定的结构去承接变化的部分，把不确定性挡在核心业务之外。
