搞大模型应用的同学最近一年多应该都有个共同体感模型越来越多各家的接口协议却各写各的。有的用 JSON 返回有的在鉴权头上有自己的癖好有的流式格式跟别人都不一样。你刚在 A 平台上把效果调好想切到 B 平台试试性价比代码先得改一遍。这种“接一家模型就要写一套适配”的日子任谁都会觉得烦。litellm 就是在这个背景下被越来越多团队拿来当“中间层”的开源方案。简单说它是一个开源的 LLM API 网关/代理服务核心能力是把市面上主流模型的接口统一转成“OpenAI 兼容格式”。你的应用只需要按 OpenAI 的调用习惯去请求 litellmlitellm 在背后帮你路由到真实的模型供应商完成协议转换、密钥托管、负载均衡、预算控制和日志记录。我最早接触这个项目时只是图它省事用久了才发现它解决的远不止“少写几行适配代码”这么简单。这篇文章我从实际使用者的角度出发把 litellm 的定位、部署、核心功能、实测过程以及我踩过的坑一次讲清楚。适合正在做多模型集成、需要集中管理模型密钥或者想在团队里做模型成本和访问权限管控的朋友参考。不管你是刚入门还是已经在生产环境里跑业务应该都能从中找到有用的东西。1. litellm 到底是什么先理清它的定位1.1 这不是又一个 SDK而是一个反向代理我第一次看到 litellm 时差点把它归到“封装好的客户端库”那一类。真正用起来才发现它做的事情和 SDK 有本质区别。SDK 是嵌在你的进程里帮你拼请求、解析响应的代码库而 litellm 是一个独立运行的服务你发请求给它它再转发给上游的模型供应商。所以它本质上是“反向代理 协议转换”。你可以把它想象成公司前台的总机不管你要找技术部还是销售部你只要拨同一个总机号码说明你要找谁总机帮你转接。你不需要知道对方的分机号也不需要熟悉对方的电话线路。对应到模型调用场景你的应用只需要知道 litellm 的地址剩下的模型供应商、鉴权参数、接口格式都由 litellm 去处理。这个定位带来了两个直接好处。第一你的应用代码里只需要维护一套 OpenAI 风格的调用逻辑不需要因为换供应商而改业务代码。第二你可以把多个供应商的密钥集中在一个地方管理而不是散落在各个服务或者客户端里。这两点在团队协作和生产环境里比单机开发重要得多。1.2 为什么偏偏选“OpenAI 兼容格式”作为统一标准litellm 对外暴露的统一接口选择了 OpenAI 的请求/响应格式这一点在设计上是很聪明的。OpenAI 的接口格式算是当前大模型领域事实上的“通用语言”主流客户端、开源工具、云厂商都有大量兼容 OpenAI 格式的组件。你用 litellm 之后那些原本为 OpenAI 写的chat/completions调用几乎可以原样保留只是把 base_url 指向 litellm把 key 换成 litellm 发的 key其他的都不用动。这背后其实是一个生态问题。如果你自己定义一个“统一格式”哪怕设计得再优雅别人不认也没用。但如果你顺着生态里已经存在的标准走你的应用侧零改造社区里的各种现成监控、调试工具也都可以直接复用。litellm 选择“兼容 OpenAI”本质上是把一个复杂的工程问题简化为“接入方只需要认一个约定”。我在实际接入时深有体会公司的老项目原本直接对接某家大模型的官方接口后来因为成本原因想换另一家传统做法是改调用层代码、换 SDK、重新测流式解析。用 litellm 之后我只需要改配置里 model_name 对应的真实后端然后重启服务应用侧一行代码没动切换就完成了。1.3 哪些场景真正适合上 litellmlitellm 功能很全但并不是所有场景都需要它。先给你泼盆冷水如果你的项目固定只用一个模型而且完全没有切换计划那么引入 litellm 等于多了一层网络跳转只会增加延迟和运维负担。这种情况我建议你直接用官方 API。真正需要它的是下面几类场景多模型冗余与容灾主模型供应商偶尔抽风你需要自动切换到备选模型保证业务不被单点拖死。成本分摊与预算控制团队里多个项目共用模型资源你希望按项目、按调用方设置月度预算做到成本可追溯、超额自动拦截。密钥集中管控不想把高权限的主密钥交给前端或者多个后端服务用 litellm 托管客户端只拿受限的虚拟 key。灰度切换模型新模型上线后想先让少量流量试跑再逐步放量需要灵活的路由规则。合规与审计内部要求记录所有请求日志追踪谁在什么时候调了哪个模型litellm 自带日志功能方便对接审计。反过来说如果你只是本地跑实验、调 prompt那直接用模型供应商的 SDK 更轻量没必要部署一个服务。litellm 的价值在“集中、统一、可控”当这些词成为你的痛点时它才会真的香。2. 部署实操从本地快速启动到生产化配置2.1 安装与版本选择litellm 的安装方式很简单Python 环境里执行pip install litellm[proxy]注意这里带[proxy]后缀这才会安装代理服务相关依赖。如果你只装基础包那只有调用库功能没有litellm --config这类的服务命令。我第一次就踩了这个坑装完发现没有 proxy 命令还以为哪步弄错了。版本方面我建议你养成固定版本的习惯。这个项目迭代很快新版本偶尔会调整配置项写法。生产环境里把版本写死例如用pip install litellm[proxy]某版本号或者在 Docker 镜像里 tag 固定到具体版本可以有效避免“过几天升级后配置突然不认了”的情况。如果你用 Docker 部署官方镜像可以直接用docker pull ghcr.io/某组织/litellm:main强调一下拉镜像时也尽量固定 tag不要长期跟 latest。这个项目的主分支可能一天一个样固定版本才是生产环境该有的姿态。2.2 最小可运行配置先把最简单的场景跑起来假设你有一个模型供应商的 API key你想通过 litellm 统一出口。配置文件config.yaml写model_list: - model_name: my-llm litellm_params: model: provider-one/model-a api_key: os.environ/PROVIDER_ONE_API_KEY解释一下这个配置model_name是你自己起的“逻辑名字”应用侧是用这个名字来请求的。你可以叫它my-llm、gpt-lite、text-any随意。litellm_params.model是真实的模型标识格式一般是供应商前缀/模型ID例如provider-one/model-a。这个前缀告诉 litellm 走哪家供应商的接入逻辑。api_key这里我推荐写成os.environ/环境变量名真正请求时 litellm 会去读环境变量不要把明文密钥写在配置里提交到仓库。然后启动export PROVIDER_ONE_API_KEY你的密钥 litellm --config config.yaml --port 4000启动后litellm 会监听 4000 端口。用 curl 验证一下curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-1234 \ -d { model: my-llm, messages: [{role: user, content: 你好}] }这里有个细节如果你没有额外配置 master key默认的虚拟 key 是sk-1234。生产环境必须改掉后面我会专门说。请求成功后你会收到一个和 OpenAI 格式完全一致的响应。也就是说你的应用如果原本接的是 OpenAI现在只要把 base_url 改成http://localhost:4000就像什么都没发生一样。2.3 生产部署的几个建议本地跑通之后拿到生产环境部署就不是一条命令的事了。我基于自己实际部署的经验给你几条具体建议。第一用进程管理器或者容器编排来跑不要裸挂 nohup。litellm 本身是 Python 服务建议用 systemd、Supervisor 或者 Docker Compose 管理生命周期。如果你用 Docker可以用类似下面的 Compose 片段services: litellm: image: ghcr.io/某组织/litellm:某版本 ports: - 4000:4000 environment: - PROVIDER_ONE_API_KEY你的密钥 - LITELLM_MASTER_KEY你的主密钥 volumes: - ./config.yaml:/app/config.yaml command: [--config, /app/config.yaml, --port, 4000]第二日志要单独接走。litellm 的控制台输出包含了每次请求的模型、耗时、token 用量和费用估算这些信息很宝贵。生产环境里把它收集到统一日志平台或者至少落盘不要让它被 Docker 日志滚动清掉。我见过有人因为日志丢失排查线上问题时连“那几分钟到底调了哪个模型”都查不到非常被动。第三给 litellm 留足够的连接池和超时余量。上游大模型接口偶尔慢如果客户端默认的超时时间很短你会在 litellm 里看到大量超时重试。建议在配置里调大超时相关参数并在客户端侧把超时设置得比 litellm 的超时略大这样链路才不会出现“上游还没返回、中间层先断”的怪毛病。3. 核心功能逐个拆解路由、预算、缓存、观测3.1 多模型路由与故障转移机制litellm 最常用的核心功能是“多个真实模型映射到同一个逻辑模型名”然后根据策略自动选择后端。比如你希望my-llm主要走模型 A但 A 挂了能自动切到模型 B配置可以这样写model_list: - model_name: my-llm litellm_params: model: provider-one/model-a api_key: os.environ/PROVIDER_ONE_API_KEY - model_name: my-llm litellm_params: model: provider-two/model-b api_key: os.environ/PROVIDER_TWO_API_KEY两个条目的model_name相同litellm 会把它们视为同一个逻辑模型的多个候选后端按顺序或策略分发请求。默认情况下如果第一个后端报错litellm 可以自动尝试下一个这个“故障转移”能力在多供应商容灾场景里非常管用。除了故障转移litellm 还支持负载均衡。你可以给每个候选后端设置权重让流量按比例分配。比如 80% 走成本较低的供应商20% 走效果更好的供应商便于在真实流量里对比效果和成本。策略配置在router_settings里支持轮询、加权路由等。实际使用中我建议先用最简单的“顺序优先 故障转移”跑起来等业务稳定了再考虑按权重做灰度放量。一上来就搞复杂路由策略配置容易看不明白出了问题反而难排查。路由还有一个细节litellm 支持按请求内容设置匹配规则比如包含特定关键词的请求走某一个模型其他请求走另一个模型。这个功能在“把简单问题交给便宜模型、复杂问题交给强模型”的路由场景里很实用但规则养多了之后维护成本不小新手阶段不建议急着上。3.2 预算与虚拟密钥管理团队协作时密钥管理是个大问题。你不可能把主账号的 key 直接发给每个开发也不希望每个人都能用到所有供应商的全部额度。litellm 提供了“虚拟密钥”机制你先生成一个 master key再用 master key 去签发多个受限的虚拟 key每个虚拟 key 可以绑定预算、限额和访问模型范围。生成虚拟 key 可以直接调 APIcurl http://localhost:4000/key/generate \ -H Authorization: Bearer 你的master_key \ -d {models: [my-llm], max_budget: 10}返回结果里会有一个新的 token把这个 token 发给客户端用。客户端请求 litellm 时带上这个 token 作为 Bearer 凭证litellm 会校验它有没有权限访问对应的模型同时统计它产生的 token 消耗和费用。预算控制支持两种维度一种是给某个虚拟 key 设置总额度达到额度后这个 key 的请求会被拒绝另一种是按用户维度设置比如同一个用户不管换几个 key累计消耗都不能超过某个限额。这两种我建议都设置防患于未然。实际运营时遇到过开发环境被测试脚本跑爆额度的案例如果没有预算拦截账单会非常难看。3.3 响应缓存省钱也省延迟litellm 支持对响应做缓存。如果同一个请求之前已经被问过并且返回结果还在缓存有效期内litellm 会直接返回缓存内容不再真实调用上游模型。这个功能对两类场景特别有效一类是 Prompt 高度重复的测试或质检任务另一类是文档问答里多次查相同内容的场景。缓存有本地内存缓存和 Redis 缓存两种模式。单机部署、请求量不大时本地缓存就够用如果你有多个 litellm 实例或者希望多个实例共享同一份缓存那就得用 Redis。配置示例cache: true cache_params: type: redis host: localhost port: 6379配置里还能设置缓存 TTL比如cache_params: ttl: 604800这里的 604800 秒对应的是一周。实际使用中我建议 TTL 别设太长因为模型会更新、prompt 涉及的知识可能过期尤其是涉及动态数据的应用缓存太长容易出现“旧答案反复复用”的问题。我看过有人把 TTL 设成一个月业务反馈“模型怎么不变了”排查半天才发现是缓存命中。缓存虽好但也不能乱开。3.4 日志与观测出了问题至少有据可查litellm 的日志功能虽然低调但很实用。控制台会打印每次请求的模型名、请求 ID、提示词 token 数、生成 token 数、预估费用。这些字段是排查成本问题的重要依据。你要是有监控平台litellm 也支持把指标暴露出来。官方支持对接 Prometheus也支持发送到主流日志采集平台。生产环境我建议至少做三件事把请求日志汇总到一个统一日志系统里方便按时间、按用户、按模型检索对错误率和 P95 延迟做基础监控延迟突增时能第一时间感知对单日成本和累计成本做看板防止预算超支而不自知。我在实际项目中花了一个下午把 litellm 的日志接到了现有的监控体系里之后发生线上问题时少了很多“猜”的成分。多花半小时做观测能省下后面几天的排查时间这笔账很划算。4. 实测从零接入一个 LLM 应用把模型切换变成改配置4.1 我的测试环境准备光看文档不够我实际搭建了一个最小测试工程来验证 litellm 的完整链路。测试环境是三台虚拟主机级别的配置具体机器配置不重要重要的是流程。我准备了一个config.yamlmodel_list: - model_name: my-llm litellm_params: model: provider-one/gpt-4o api_key: os.environ/PROVIDER_ONE_API_KEY - model_name: my-llm litellm_params: model: provider-two/model-b api_key: os.environ/PROVIDER_TWO_API_KEY说明一下上面的provider-one/gpt-4o是我替换过的写法实际要填你购买的供应商前缀和模型 ID。model_name统一叫my-llm这样应用侧只认my-llm后端怎么换都行。然后启动 litellmexport PROVIDER_ONE_API_KEYxxx export PROVIDER_TWO_API_KEYyyy litellm --config config.yaml --port 40004.2 验证协议转换用 OpenAI SDK 请求非 OpenAI 服务测试应用我用 Python 的 OpenAI SDK 来写因为 litellm 对外兼容 OpenAI 格式所以不需要引入任何 litellm 的客户端代码。from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000, api_keysk-1234 ) response client.chat.completions.create( modelmy-llm, messages[{role: user, content: 请用一句话解释缓存的作用}], ) print(response.choices[0].message.content)运行这段代码时litellm 会把my-llm路由到第一个后端去执行再把结果映射成 OpenAI 格式返回。我在测试里故意把真实请求转发到一家“非 OpenAI 原生格式”的服务商应用侧完全无感知返回结构和字段都能对上。这里也提醒一句上面的api_key填的是 litellm 生成的虚拟 key不是上游供应商的原始 key。客户端永远不应该持有上游的原始密钥这是集中管控的核心。如果你发现某个现场环境把原始 key 硬编码在客户端配置里建议尽快改掉。4.3 验证故障转移让主模型“临时故障”为了测试故障转移我故意在第一个后端配置里填了一个不存在的模型 ID模拟“模型下线”的状况。然后重新运行上面的 Python 脚本。litellm 收到请求后会先尝试用第一个后端调用发现返回错误然后自动切换第二个后端最终把第二个后端的正常响应返回给应用。整个过程在应用侧来看就是一次普通的请求只是响应可能慢了一点点。我观察了 litellm 的日志能明显看到错误记录和重试记录。这一步验证让我对“多模型冗余”真正有了信心就算某个上游深夜抽风只要第二个后端可用服务就不至于直接中断。需要说明的是fallback 的触发条件、重试次数都可以配置并不是所有错误都必须 fallback。你需要在配置里明确定义哪些错误码是可重试的避免把“参数写错”这种问题也默默吞掉否则会掩盖 bug。4.4 实测结论开销与延迟这次实测里我重点观察了 litellm 本身带来的额外延迟。在本地局域网环境下litellm 只是做协议转发和路由额外增加的时间基本在个位数毫秒级别和上游模型动辄一两秒的生成时间相比完全不是瓶颈。有一个细节值得注意如果开流式输出litellm 会逐块转发上游返回的内容你的应用侧仍然是标准的流式事件流。实际测试下来流式场景下首包延迟略有增加但幅度可以接受。我在一个问答机器人项目里长时间使用 litellm 作为网关用户体验几乎没有变化。如果你做的是实时性极强的应用建议部署后自己压测一遍确认可接受再切换。5. 常见问题与避坑手册5.1 密钥和鉴权配置不当最多人踩的坑就是密钥管理。默认的sk-1234只是一个 dev 默认值很多人启动完忘了配置 master key结果任何拿到端口权限的人都能直接使用你的上游模型额度。生产环境务必显式配置 master key并且通过虚拟 key 给下游调用方签发受限凭证。另外os.environ/环境变量名的写法只负责“读取”环境变量而不是“设置”。很多新手以为在配置里写了这个变量名它就自动有值了结果启动后一直报 401。正确做法是确保启动 litellm 的进程环境里真的 export 了这个变量或者在 systemd / Compose 文件里把环境变量注入进去。5.2 模型映射与供应商前缀的坑在litellm_params.model里供应商前缀不是随便写的。它决定 litellm 使用哪个接入逻辑、如何构造请求、如何解析响应。如果你把模型 ID 写对了但供应商前缀写错了litellm 要么报错说找不到这个提供商要么解析响应失败。我的建议是新接入一个供应商时先直接看官方文档确认它支持哪些前缀然后先用 curl 调用一次确认能跑通再继续加路由规则。不要一次性写好十几个模型映射然后一起启动出错了也不知道是哪个写错。5.3 代理稳定性与性能开销litellm 是单进程 Python 服务常规请求量下没问题但高并发场景需要提前评估。我建议在生产环境至少跑两个实例前面用负载均衡器把流量分发到不同副本避免单点故障。同时给 litellm 配置连接池合理复用与上游的连接可以有效降低延迟和系统开销。还有一个容易忽略的点如果你给同一个逻辑模型配置了多个真实后端一定要保证它们的响应风格基本一致。不同模型的默认输出格式、拒绝回答倾向、温度敏感度都可能不同。故障转移本来是用来保命的要是切换后备模型输出风格完全不一样用户会立刻感知到“机器人好像换了个人”。所以我在落地时会让选作备胎的模型尽量是同一档次的模型。5.4 常见问题速查表这里整理一份快查表是我在实际操作中反复用到的现象可能原因排查方式401 Unauthorized上游密钥没设置或 master key 错误检查环境变量、检查 litellm 启动日志404 Model Not Found逻辑模型名不在配置里确认model_name拼写刷新配置上游报格式错误供应商前缀写错对照文档确认前缀与模型 ID请求成功但返回空缓存命中旧结果检查缓存 TTL 设置响应太慢多次故障转移触发查看日志中的重试记录控制台没有日志日志级别设置太安静启动时加--detailed_debug等调试参数如果你在产品环境已经跑了很久突然发现某些问题“之前好好的现在不行了”先确认 litellm 有没有被自动升级过。这个项目升级有时会调整默认行为忽略版本变化直接排查业务代码效率很低。最后再分享一点个人体会我正式把 litellm 放进生产环境是因为一次线上事故凌晨主模型供应商接口大面积不稳定业务方的告警响个不停。当时如果逐个服务去改模型供应商配置影响面会非常大。好在那时候我们已经把模型调用收敛到了 litellm只需要把路由顺序调一下让备选模型顶上大概几分钟内业务就恢复了。那次之后我对“模型接入层”这个设计的价值有了切身的认识。当然litellm 不是银弹。它不解决 prompt 质量问题也不解决模型效果问题它解决的是“模型接入和使用过程中的工程管理问题”。我见过不少团队在还没有多模型需求时就跟风引入网关结果多了一层服务要维护收益却很有限。我的建议是小步快跑先在非核心业务上用起来等团队对它足够熟悉、日志监控都到位了再逐步把核心链路切换过来。模型的世界还在飞速变化给自己留一个灵活切换的接入层总归是件划算的事。