如果你的项目里也接了不止一家大模型 API，那你一定对 LiteLLM 这个名字有印象。它是当前开源社区里很活跃的一个模型网关工具，核心思路很简单：把各种不同厂商、不同协议、不同计费规则的大模型接口，统一收敛成一个 OpenAI 兼容标准入口。业务代码不再需要分别维护多套 SDK、多套鉴权逻辑和多套重试兜底，只需要面对一个本地代理地址。这篇文章我会从实际使用者的角度，拆解 LiteLLM 能解决什么、怎么快速搭起来、哪些配置最值得花时间研究，以及我在真实项目里踩过的坑。
LiteLLM 适合谁？如果你正在做 AI 应用开发，手里有两三个甚至更多的模型渠道；如果你们团队需要多人共享大模型 API 额度，又不想把上游密钥暴露给每个人；如果你想在切换模型时只改配置文件而不是改代码——那这篇内容基本就是为你准备的。
1. 为什么团队会需要一个“模型网关”
1.1 一个真实的多模型接入痛点
先描述一个非常常见的场景。早期做智能客服系统的时候，只需要接某个头部闭源模型平台，代码里直接调用它的 SDK，一切都很听话。后来为了降低成本和提升效果，又接入了另一个模型托管服务；再后来，公司内部还部署了一个开源模型的私有化实例。从这一刻起，事情开始失控。
每一家的 SDK 都有自己的请求方式。有的基于 HTTP 调用，有的提供官方 Python 包；鉴权方式各不相同，有的用 Header 明文传 key，有的要求先申请临时 token；超时设置、重试策略、错误码含义也完全不是一回事。这就导致核心业务代码里堆满了各种if ... else ...分支，每当要换一个供应商，就要修改上游适配层，测试一轮再发版。更麻烦的是账单管理：每个平台的后台我都要登录，看各自的 token 消耗和费用，再手动汇总到 Excel。说实话，给老板汇报用量曲线的时候，我经常要花一晚上整理数据。
这类问题做大了以后，解决方案通常有两个方向：一个是自己写一套适配层，把各家 SDK 包一层；另一个是直接用开源模型网关。前者的开发维护成本很高，新接入一家模型就要改一次代码，而且每个项目的适配层都要单独维护。后者就是 LiteLLM 这类工具出现的意义。
1.2 网关方案如何改变调用方式
LiteLLM 的思路是：代理服务在本地独立运行，它负责和目标模型服务商打交道，对外暴露一个固定风格接口。也就是说，业务代码从“直接面对 N 家厂商”变成了“只面对一个本地网关”。从工程上看，这是标准的引入中间层来解耦的思路。你可以把它类比成：原来你要分别跑各家银行柜台办业务，现在门口多了一台统一 ATM，卡不变、操作流程不变，但中间清分结算全是 ATM 帮你处理。
具体到 LiteLLM，它对外暴露的是 OpenAI 兼容接口。现在大量的开源工具、LangChain 类框架、各种编程语言的 SDK 都认这套请求格式。这意味着你只需要把业务代码里的base_url指向 LiteLLM 服务，再把 API Key 换成网关给的虚拟 Key，基本上就能跑起来。上游供应商使用的真实密钥被安全地留存在网关的环境变量或配置中，业务侧完全感知不到。
网关层能做的事也远远不止转发请求：
- 多模型路由：调用时可以指定别名，网关解析别名后把请求分发到真正的上游模型。
- 负载均衡：同一个模型可以配置多个上游渠道，按权重分发请求，还能自动容灾。
- 密钥管理：用主 Key 生成多个虚拟 Key，不同团队不同项目用不同 Key，方便审计和回收。
- 成本控制：按 Key、按用户甚至按模型维度记录 token 用量和费用，还能设置预算上限。
- 统一容错：超时重试、fallback 到备用模型、限流限速都可以在配置里完成。
这些能力如果自己写，估计要耗掉小半个月的开发量。而用 Litellm，基本上是配置项的问题。
2. 5分钟搭好基础网关：最小可用配置
2.1 安装和第一个代理
先说明一下环境。LiteLLM 建议跑在 Python 3.9 以上的环境里，我日常开发机用 Python 3.11，跑起来没什么问题。最简单的安装方式是直接用 pip：
pip install 'litellm[proxy]'加[proxy]这个 extra 会把代理服务相关的依赖一起拉下来。装完之后，你会多一个litellm的命令行工具，还有一个可以启动代理服务的模块。
接下来创建第一份最小配置。我习惯把配置文件命名为config.yaml。先看一个最简版本：
model_list: - model_name: "primary-model" litellm_params: model: "provider-a/text-model-001" api_key: "os.environ/PROVIDER_A_API_KEY"这里面的逻辑不复杂。model_name是暴露给业务侧的名字，业务代码请求里带的是这个；litellm_params里的model是真实上游模型的完整标识符，格式一般是“提供商/模型名”，LiteLLM 会依据这个前缀去匹配对应的请求协议。api_key那一行用os.environ/XXX表示从环境变量里读取真实 Key，不要把明文密钥写进 YAML 文件。
启动代理服务：
export PROVIDER_A_API_KEY="你的真实上游密钥" litellm --config config.yaml --port 8000看到启动日志里出现类似Uvicorn running on http://0.0.0.0:8000的输出，代理就起来了。此时它已经默认提供一个/v1/chat/completions的 OpenAI 兼容接口。如果不指定--port，默认会跑在 4000 端口，我习惯显式指定成 8000，方便和其他服务区分。
2.2 用 OpenAI 兼容方式快速验证
代理起来之后，先别急着写业务代码，用 curl 验证一下最直接：
curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-your-master-key" \ -d '{ "model": "primary-model", "messages": [{"role": "user", "content": "你好，做一个简单自我介绍"}] }'这里sk-your-master-key是你在 LiteLLM 里设置的 Master Key，也就是网关自己的主密钥。默认情况下，如果没配置，代理也会生成一个临时访问 key，具体可以看启动日志。返回结果里包含choices、usage等字段，结构和 OpenAI 接口保持一致。
接下来看业务侧代码改造。假设你原来的 Python 代码是这样的：
from openai import OpenAI client = OpenAI( base_url="https://某个上游真实地址", api_key="上游真实密钥", )改成走 LiteLLM 网关：
from openai import OpenAI client = OpenAI( base_url="http://localhost:8000/v1", api_key="sk-your-master-key", ) response = client.chat.completions.create( model="primary-model", messages=[{"role": "user", "content": "你好"}], ) print(response.choices[0].message.content)改动点非常小：base_url指向网关，api_key换成网关的 Master Key，model传网关里定义的别名。其余逻辑完全不用动。我之前接新模型时，甚至不用重启业务进程，只需要在网关配置里加一条新的model_list映射，然后重新加载配置，业务侧换个 model 名称参数就切过去了。这就是网关带来的最大体感变化：模型切换从写代码变成填配置。
3. 模型路由、负载均衡与容错配置
3.1 把多个上游服务池化
基础代理只能满足单模型转发，生产环境里更常见的是多个上游渠道并存。我手里曾经有两个不同平台都提供能力很接近的模型，一个是官方直连，一个是某云厂商的托管服务。出于成本、稳定性的权衡，我希望平时流量按比例分配，同时在一个渠道故障时自动漂移到另一个。LiteLLM 对这种场景的支持方式比较直观：同一个model_name下面配置多条litellm_params，再加权重。
看一个示例配置：
model_list: - model_name: "chat-model" litellm_params: model: "provider-a/llm-v3" api_key: "os.environ/KEY_A" weight: 3 - model_name: "chat-model" litellm_params: model: "provider-b/llm-v3" api_key: "os.environ/KEY_B" weight: 1weight不是百分比，而是相对权重。上面这两条配置意味着：每 4 个请求里，大约 3 个交给 provider-a，1 个交给 provider-b。这样做的好处是：如果某一个上游偶尔出现问题，请求还有机会自动落到另一个上游；同时我也可以先给新渠道小流量灰度，比如权重设成 9:1，观察几天没问题再调到 5:5。
需要注意一个细节：不同 provider 的实际能力可能差异很大。比如一个支持 128k 上下文，另一个只支持 32k；一个支持流式输出，另一个延迟较高。这些差异不会因为网关的存在而消失。所以做权重路由前，我建议先把用量大的业务场景摸清楚，至少确保两个渠道在关键指标上能满足要求，再谈负载均衡。
3.2 重试、超时与 fallback
模型接口是非常典型的“少部分请求会比较慢、甚至失败”的服务。网络抖动、上游限流、模型推理超时都有可能发生。如果业务代码存在大量同步调用，网关的重试策略就直接影响到最终用户感知。
LiteLLM 让我比较满意的是重试和 fallback 不依赖业务代码，全部可以在配置里完成。我常用的配置示例：
litellm_settings: num_retries: 2 request_timeout: 60 fallbacks: - "chat-model": ["backup-model"]num_retries表示单个请求失败后的最大重试次数；fallbacks表示当chat-model对应的上游都失败时，把请求降级到backup-model这个备用模型。这种配置让系统在面对第三方不稳定服务时，有了天然的缓冲。
在实际调参时，有个很容易忽略的点：超时时间不是越大越好。request_timeout设置得太短，稍微有点网络波动就误重试；设置得太长，大量慢请求会占满网关的并发连接。我通常先给 60 秒，然后观察一周的成功率和 p95 延迟，如果 p95 明显低于 30 秒，可以考虑下调到 45 秒。
还有一个更隐蔽的问题：客户端超时要大于网关超时。如果业务侧自己设了 30 秒超时，而网关给上游是 60 秒，那业务侧断开连接以后，网关还在傻傻地等上游响应，白白消耗资源。所以我在做接入规范时，特意要求各团队按“客户端超时 > 网关超时 > 上游平台超时”的优先级来配置。
3.3 并发控制和限流
有时候上游平台有每分钟请求数限制，或者有并发数限制。如果没有控制，可能会出现大量请求同时到达上游，触发 429 限流。LiteLLM 提供了路由层面的并发控制参数，比如在router_settings里设置max_parallel_requests，或者在每条上游配置里限定并发。
我自己的经验是：高峰期的突发流量很难预判，与其去压测上游极限，不如在网关层设置一个保守的并发上限。比如日常需要 10 并发，我可以先设 15，看有没有排队和失败；如果上游稳定，再把上限慢慢提高。这样就算下游业务被刷爆，也不会把所有流量都打到上游去，等于给系统加了一层保险丝。
4. 密钥、预算与成本追踪
4.1 API Key 的分层管理
在团队开发大模型应用时，最让我头疼的往往不是模型效果，而是密钥管理。直接在上游平台创建一个 Key 丢给所有开发同学，看起来省事，但隐患很多：有人拿去调到别的项目、超过预算、或者不小心把 Key 提交到公开仓库，这些风险一旦发生都很难追责。
LiteLLM 的虚拟 Key 机制把这个问题解决了。你可以用一个 Master Key 启动网关，然后在网关上创建多个虚拟 Key，每个虚拟 Key 可以限制能访问的模型列表、每分钟请求次数、总预算额度。团队成员调接口时，只需要拿虚拟 Key 跟网关说话，真正上游平台暴露的 Master Key 始终留在网关服务端。
举个我实际用过的例子。一个项目叫模拟项目 X，前端、后端、质检三个角色都需要访问模型能力。我给前后端各分配了一个虚拟 Key，设置每天 5 万 token 的预算；质检这边因为要跑批量测试，我给了单独的一个 Key，限制只能访问轻量模型。这样哪一方的用量异常，我很快就能定位到具体 Key，而不是像从前那样对着一个全局 Key 发呆。
虚拟 Key 的创建方式可以通过管理接口来做，也可以直接在 LiteLLM 的管理界面里点鼠标完成。我的个人建议是：如果团队不大，就用管理界面；如果 Key 数量很多，就写脚本调用管理接口，把创建 Key 的流程固化到团队文档里。
4.2 用量统计与预算控制
模型网关如果只做转发，那价值会大打折扣。LiteLLM 一个很实用的能力是自动记录每次请求的 token 用量和估算费用。只要启动时配置了数据库连接，它就会把请求日志写到数据库里，之后你可以通过 UI 或 API 查看不同 Key、不同模型的消耗情况。
数据库连接通常在general_settings里配置：
general_settings: master_key: "sk-your-master-key" database_url: "postgresql://user:password@db-host:5432/litellm"连上数据库后，我每个月看成本报表就再也不用到各平台后台手动拉数据了。直接在网关页面上选时间范围、选模型、选 Key，就能看到费用分布。这对于“多模型成本对比”这件事特别有效。之前我想比较两个供应商的性价比，只能各跑一轮压测再手动算，现在网关自己记录了所有调用数据，直接导出 Excel 分析就行。
预算控制方面，LiteLLM 支持给虚拟 Key 设置max_budget。一旦达到预算上限，对应 Key 的请求会被拒绝，直到重置预算或者人工调整额度。我把它用在一个内部福利项目上，给每个体验用户一个独立 Key，日常额度设置得很小，防止有人在内部工具上跑重型任务把预算烧爆。这个机制帮我挡了好几次意外开销。
5. 实战中容易踩的坑
5.1 模型别名映射错误
最常遇见的错误就是模型名写错或者理解错。有次我把业务代码里的model直接写成了上游平台的真实模型名，而网关里没有配置这个别名，结果代理返回 404。翻日志才发现，LiteLLM 是按model_name做映射的，不是按真实模型名。也就是说，客户端传什么名字，网关注册表里必须存在对应的model_name。
排查这类问题有一个快捷方法：请求网关的/v1/models接口，它会把当前所有可用的别名列出来。我后来要求团队在联调前先跑一遍这个接口，确认自己的 model 参数在列表里，能省掉不少沟通时间。
另外还有一层坑：YAML 配置里如果缩进写错，或者model_list没有顶格，LiteLLM 启动时可能不会报任何错误，只会拒绝转发。所以我会用格式检查工具先过一次配置文件，确保 YAML 结构合法。
5.2 环境变量配置不生效
很多人第一次配置时都会遇到一个问题：配置里明明写了api_key: "os.environ/PROVIDER_A_API_KEY"，但启动代理以后请求还是 401。原因一般是环境变量没有传进 LiteLLM 服务的进程。本地 shell 启动时，要先export；用 systemd 管理时，要在 service 文件里加Environment=；用 Docker 时，要写在environment列表里。任何一个环节漏了，配置就会变成空字符串。
我踩过一次比较惨的坑：在 Docker Compose 里忘了把上游 Key 放进环境变量，结果生产环境跑了半小时，所有请求都在 401，业务侧报错率直线上升。从那以后，我养成了一个习惯：部署前先跑一个内部接口返回当前解析到的上游 Key 的前缀，核对无误再放流量。
5.3 超时与并发配置的误区
除了前面说的客户端超时要大于网关超时之外，还有一个常见的认知偏差：把weight当成并发数。weight只影响路由分配的相对比例，并不影响两个 provider 同时处理请求的并发上限。真正限制并发的是max_parallel_requests这类参数。如果你在一个 provider 上设置了 weight 大，但上游平台并发限制很低，该平台还是会被触发限流。
另一个容易忽略的问题是流式请求。有些业务要求模型流式输出，但网关日志里看到的是连接建立后的状态，实际 token 生成可能比较慢。如果上游的流式处理特别慢，而网关和客户端的超时又偏短，用户会看到“连接已经建立但迟迟没有内容”的卡顿。这种情况下，要提高的是流式空闲超时，而不是简单的请求超时。
5.4 日志和数据延迟
LiteLLM 的成本统计并不是实时的，在某些流式请求或者异步调用场景下，用量记录可能会延迟几分钟才落库。如果你做的是对账系统，建议不要把网关的 spend 数据当作唯一事实来源，而应该结合上游平台的官方账单做交叉核对。我之前就遇到过度量统计和实际账单差了几天的情况，最后发现是上游平台自己的统计口径也有延迟，两边对比一下心里才踏实。
6. 生产环境部署实践
6.1 用 Docker Compose 独立部署
本地命令行启动适合调试，但到了生产环境，我强烈建议用容器方式独立部署。这样网关和业务服务的生命周期隔离，升级回退都方便。我常用的 Compose 配置大概长这样：
services: litellm: image: your-registry/litellm-proxy:latest ports: - "8000:8000" volumes: - ./config.yaml:/app/config.yaml environment: - DATABASE_URL=postgresql://user:password@db-host:5432/litellm - PROVIDER_A_API_KEY=${PROVIDER_A_API_KEY} - PROVIDER_B_API_KEY=${PROVIDER_B_API_KEY} command: ["--config", "/app/config.yaml"] healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8000/health/liveliness"] interval: 30s timeout: 5s retries: 3需要注意：不要把敏感配置直接写进 Compose 文件，尽量用环境变量替换；数据库地址建议通过独立的 secrets 管理。健康检查接口用 LiteLLM 自带的/health/liveliness，也可以在启动参数里开启。配置了健康检查以后，上游负载均衡器才能自动摘除不健康的网关实例。
生产环境里，我通常只在内网暴露网关端口，外部请求一律通过内部负载均衡器转发。这样做的好处是，即使有人拿到虚拟 Key，也不能绕过负载层直接打到网关所在机器。
6.2 监控与日志收集
模型网关成为所有模型请求的唯一入口后，它的监控价值变得非常高。LiteLLM 提供了一些内置指标接口，可以接入常见的监控系统，核心关注的指标包括：请求成功率、平均延迟、token 消耗速率、当前并发数、重试次数。
日志方面，我会让网关日志带上请求 ID，方便业务侧在出问题时把某个请求的全链路日志拉出来。具体做法是在业务侧生成一个关联 ID，透传到模型请求上下文中，LiteLLM 会在日志里记录请求元数据。虽然这种细节排查起来费事，但一旦出现线上故障，它能帮你从“大海捞针”变成“按图索骥”。
考虑到日志数据量不小，建议设置日志轮转，或者直接接入日志采集系统，避免日志文件无限增长把磁盘打满。这是我曾经踩过的一个实际教训，某次网关所在机器日志盘直接写满，服务无响应，查了半天才发现是日志没做清理。
6.3 团队协作：从共享 Key 到独立 Key
最后聊聊团队协作。我见过很多团队把一个共享 Key 贴在项目的 README 里，后续所有成员都用同一个 Key 调网关。这样做一出问题很难办——分不清是谁的用量、是谁在刷接口。我比较推荐的做法是：每位开发者或每套环境单独创建一个虚拟 Key，Key 的名称按“项目-环境-用途”来命名。LiteLLM 支持在创建 Key 时添加 metadata，把负责人、项目名写进去。
这样规范化以后，每周复盘用量时，我可以清晰地看到：某个环境占了 80% 的 token，原因是测试脚本在跑批量任务；另一个项目的 Key 预算快用完了，需要及时充值或者优化提示词。这种透明度会倒逼团队更关注成本，而不是像以前那样稀里糊涂地烧钱。
还有一个容易被忽略的好处：当有人离职或者某个项目下线时，我可以直接把对应 Key 吊销，而不影响其他项目。相比之下，共享 Key 模式下想清理权限，几乎只能全局重置，成本很高。
最后说一点我的个人习惯。我使用 LiteLLM 的经验是从一个简单需求开始的：只是想把两个模型的调用统一一下。后来逐步加了路由、预算、监控、团队权限，整个系统也越来越顺手。踩过几次配置坑之后，我把最小可用配置、备份模型、成本告警这些都沉淀成了团队模板，新项目接入时只需要复制模板改模型名。如果你准备在项目里尝试，我建议先从最小配置开始，跑通一次真实请求，再加负载均衡和预算控制，慢慢把网关的稳定性打磨起来。模型接入这件事，真正顺手的方案往往是先用起来，再逐步优化出来的。
