litellm 是我最近半年里在生产环境反复折腾的一个开源项目它的定位很直接把各家大模型的 API 统一成一个网关。过去我们要接多个模型服务商得分别记各自的接口地址、鉴权方式、请求格式、限流规则代码里写一堆 if-else 或者适配层维护成本高得离谱。litellm 做的事情就是把这些差异全部收口对外暴露一个稳定的接口内部帮你路由到不同的模型后端。这篇文章我会从原理到实操把 litellm 怎么用、怎么配、怎么避坑讲清楚适合正在做 LLM 应用接入、想统一管理多模型调用的开发者参考。1. 为什么你需要一个统一的LLM网关1.1 各家大模型接口的碎片化有多烦如果你只接了一家模型服务商你可能体会不到这种痛苦。但是一旦你的应用需要同时调用多个模型比如一个问答系统里简单问题走便宜的小模型复杂推理走贵的大模型或者同一个功能要在不同服务商之间做 AB 测试你会发现每个服务商的 API 都是独立的生态。有的服务商用chat/completions风格有的用messages数组有的要塞system角色有的不认system只认prompt鉴权方式也五花八门有的是Authorization: Bearer有的是自定义 header还有的是通过 query 参数传 key。这还不算完返回的格式可能都不同有的返回choices[0].message.content有的返回generated_text有的把 token 用量藏在一个奇怪的字段里。这种情况下你的业务代码会慢慢被这些 SDK 的差异蚕食。今天要换一个模型可能要改几十处调用某个服务商接口升级了导致一处解析崩溃。我见过不少项目模型调用逻辑散落在各个模块里根本没法统一排查问题和核算成本。这就是为什么需要一层网关把所有模型的调用收口到一个地方。1.2 网关到底解决了什么问题litellm 本质上是做了一个模型路由代理。核心价值可以概括成三点第一统一接口。对外提供一套一致的请求格式和返回格式业务代码只需要面向这一套格式开发不需要关心背后是哪个服务商、哪个模型。第二集中管理。所有的 API Key、模型配置、路由策略、成本记录全部放在一个地方。团队其他人不需要拿到各家服务商的原始 key只需要访问 litellm 开放出来的网关地址。第三弹性调度。网关可以根据配置做负载均衡、故障转移、重试甚至在某些模型不可用的时候自动切换到备用的同能力模型。打个比方litellm 就像是一个翻译中介。你只需要跟这个中介说标准普通话中介会根据你的意图把话翻译成各地方言递给对应的服务方再把对方的答复翻译成普通话返回给你。2. litellm 的核心机制与关键设计2.1 统一输入输出层一次适配到处调用litellm 的底层思路其实不复杂它维护了一个很大的适配器集合每一个模型服务商都对应一套请求转换逻辑。你在配置里写model: 某前缀/模型名litellm 会识别前缀然后调用对应的适配逻辑把你的标准请求转换成目标服务商需要的格式。对外暴露的默认接口风格主要是大家都熟悉的聊天补全接口格式传一个model参数、一个messages数组带上temperature、max_tokens这类可选参数。返回结果也会统一转换成类似的格式包括choices、usage这些字段。这件事的好处非常明显。你的业务代码从没直接接触过各个服务商的原始 SDK将来增加新的模型只要在 litellm 配置里多写一条记录业务代码一行都不用改。这相当于把模型接入和应用开发这两个关注点彻底解耦了。除了 HTTP 网关方式litellm 本身也提供了 Python SDK可以直接在代码里调用litellm.completion()走同样的适配逻辑。不过我自己更推荐生产环境用代理模式因为代理模式把配置和代码分离运维调整更灵活。2.2 模型路由、重试与故障转移的逻辑litellm 的请求处理流程大致是这样的收到请求后根据model参数找到配置里对应的模型条目然后根据路由策略选出一个实际的后端模型进行调用如果调用失败根据重试策略决定是否重试或切换到其他模型。路由策略不是简单的随机选择。litellm 支持多种策略比如最简单的simple按顺序轮流使用还有least-busy优先选择当前并发请求数最少的模型以及基于权重的路由你可以给每个模型配一个权重让流量按比例分配。故障转移更实用。你可以在一个模型组里配多个模型主模型挂了或者返回特定错误码的时候litellm 会自动调用下一个备选模型。这个能力在生产环境非常关键因为外部模型服务商偶尔会限流、超时甚至出故障如果不做兜底你的应用就直接报错了。重试也不是盲目重试。litellm 允许你设置最大重试次数、重试间隔还能根据错误类型决定是否重试。比如鉴权失败就不要重试了重试多少次都是白搭而网络超时、限流这类问题重试往往能救回来。2.3 Token统计与成本追踪是怎么实现的litellm 另一个我很喜欢的功能是预算与成本追踪。很多团队接入多个模型后根本说不清每个月在模型调用上花了多少钱因为不同服务商的计费方式不一样token 口径也不同。litellm 在每个请求结束之后会从响应中提取 token 用量然后根据配置里预设的模型单价计算出这次请求的成本。这些数据可以通过回调函数发送到监控平台也可以存到内置的数据库中通过管理接口查询。成本追踪的意义不只是记账。你在做模型选型的时候如果能看到同一类任务模型 A 每天花 20 块模型 B 只花 5 块但效果差不多那决策就很清晰了。litellm 还支持按 API Key 划分预算比如给某个测试同学发一个 key只允许他每月最多消费 10 块钱超过就直接拒绝这个对控制失控调用非常有用。3. 从零部署本地搭建一个litellm代理服务3.1 安装与启动最小可用配置litellm 的部署方式很轻量我最常用的是通过 Python 包安装。官方提供了一个代理模式的入口一条命令就能启动服务。pip install litellm[proxy]启动代理服务只需要指定一个配置文件或者不指定配置也可以跑起来litellm --config config.yaml --port 4000如果你的环境里没有litellm命令也可以用下面这种方式启动python -m litellm --config config.yaml --port 4000启动之后litellm 会监听在 4000 端口对外提供兼容聊天补全接口的 HTTP 服务。你可以先用浏览器访问http://localhost:4000/看看存活状态或者直接发一个请求测试。3.2 用config.yaml定义模型池litellm 的配置文件就是一个 YAML 文件核心内容是model_list。先看一个最基本的例子model_list: - model_name: demo-chat litellm_params: model: provider-one/demo-chat api_key: os.environ/PROVIDER_ONE_KEY这个配置的意思是对外暴露一个叫demo-chat的模型名所有请求带modeldemo-chat时litellm 会把请求转发给provider-one/demo-chat对应的实际模型。api_key指定从环境变量读取密钥避免把密钥写死在文件里。如果你想加多个后端只需要继续在model_list下增加条目model_list: - model_name: demo-chat litellm_params: model: provider-one/demo-chat api_key: os.environ/PROVIDER_ONE_KEY - model_name: demo-chat litellm_params: model: provider-two/demo-chat-v2 api_key: os.environ/PROVIDER_TWO_KEY这里有两个值得注意的点。第一model_name可以相同litellm 会自动把相同名字的多个后端当作一组做负载均衡和故障转移。第二litellm_params里的model字段前缀对应具体的服务商适配器后面是服务商那边的真实模型标识。实际使用的时候你需要根据 litellm 文档里每个服务商的前缀格式来写。3.3 通过HTTP接口调用测试配置好了之后我们先用curl验证一下整个链路通不通。curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: demo-chat, messages: [ {role: user, content: 你好请简单介绍一下你自己。} ] }如果一切正常你会收到一个标准的聊天补全响应里面包含模型返回的内容和 token 用量。这时候你可以连续发几个请求再观察 litellm 的日志能看到每个请求实际路由到了哪个后端耗时多少成本多少。在 Python 代码里调用也是一样的直观只需要把 base_url 指向 litellm 代理from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000/v1, api_keyany-non-empty-string ) response client.chat.completions.create( modeldemo-chat, messages[{role: user, content: 你好}] ) print(response.choices[0].message.content)这一步跑通之后你的业务项目里就不需要再装各种不同服务商的 SDK 了所有模型调用都走这一个客户端。4. 进阶玩法多模型容灾、缓存与权限控制4.1 多模型故障转移策略配置生产环境最怕的就是单点依赖。如果你只接了一个模型服务商他那边一抖动你的业务就跟着抖。litellm 配置故障转移的方式其实就是在同一个对外模型名下配置多个不同的实际模型。我之前在模拟项目 X 里是这样配的model_list: - model_name: reliable-chat litellm_params: model: provider-a/reliable-chat-v1 api_key: os.environ/PROVIDER_A_KEY model_info: mode: completion - model_name: reliable-chat litellm_params: model: provider-b/reliable-chat-v2 api_key: os.environ/PROVIDER_B_KEY这样任何请求modelreliable-chat的流量litellm 会在两个后端之间做负载均衡。当一个后端返回错误或者超时的时候litellm 会自动尝试另一个后端。你还可以在router_settings里设置更细的规则router_settings: retry_policy: Timeout: 1 RateLimitError: 2 fallbacks: []这里的retry_policy是指定哪些错误类型需要重试、最多重试几次。Timeout这个错误类型我一般只重试 1 次因为连续超时往往说明服务端已经忙不过来了RateLimitError可以多试两次限流通常是短暂的。还有一个很实用的配置叫cooldown。当某个后端连续失败多次后litellm 会把它临时标记为不可用过一段时间再放进来。这个机制避免了每次都先撞一次坏节点的尴尬。4.2 启用请求缓存降低开销如果你做的应用对响应实时性要求没那么高比如知识库问答、摘要生成或者用户经常问相似的问题那么强烈建议开启 litellm 的缓存功能。缓存能大幅降低模型调用费用也能减少外部 API 的限流触发概率。litellm 支持两种缓存一种是语义缓存一种是精确缓存。精确缓存很好理解就是相同的请求内容直接返回之前的响应。语义缓存更聪明一点它会把请求向量化然后根据相似度判断是否命中。比如用户问介绍一下你们的定价和你们怎么收费意思差不多语义缓存可以直接命中。配置缓存很简单在 config.yaml 里加上general_settings: cache: true cache_params: type: redis host: localhost port: 6379如果你只是本地测试不想引入 Redis也可以直接用内存缓存只需要把type改成local并设置一下max_memory。需要提醒的是缓存要小心用在动态场景。如果模型的输出跟时间、用户状态强相关比如现在几点了请帮我查一下订单状态这类请求一定不能开缓存否则会返回过期的旧数据。4.3 限流与Key管理给团队开接口多模型网关部署好之后你可能希望让团队里的其他成员也来调用。这时候你肯定不想把各家服务商的原始 API Key 发给大家一是安全性不可控二是成本无法追踪。litellm 内置了一个虚拟 API Key 的概念。你可以先配置一个主 key然后用管理接口生成多个虚拟 key每个 key 可以设置独立的预算、速率限制、允许访问的模型列表。生成虚拟 key 的接口类似这样curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer master-key \ -H Content-Type: application/json \ -d { models: [reliable-chat], max_budget: 10.0, rpm_limit: 60 }返回的结果里就是一个虚拟 key。把虚拟 key 给到业务方业务方拿它请求 litellm 网关。你可以在管理后台看到每一个 key 的调用量、token 用量、消费金额。哪天某个 key 跑出了异常流量你可以直接删除或禁用不影响别人。这个机制让我想到一个很实用的场景给不同环境分配不同 key。开发环境 key 预算低一点测试环境 key 允许调用的模型范围窄一点生产环境 key 才有完整权限。这样即使某一个 key 泄露了攻击面也被控制住了。5. 常见问题与避坑实录5.1 模型名映射混乱怎么办我在配置 litellm 的时候踩过最大的坑就是model_name和实际后端模型名的关系没搞清楚。model_name是暴露给业务方的名字你可以随便起litellm_params.model才是真正决定请求发到哪里的关键。举个例子业务方希望在代码里写modelchat不关心后端具体是什么。你完全可以把model_name设成chat然后把litellm_params.model指向某个真实模型。如果哪天你想换掉后端模型只需要改配置文件里的映射业务代码完全不用动。但麻烦的是如果你配置了多个同名model_namelitellm 会默认做轮询。这个行为有时候不是你想要的效果。如果你只是想把同一个名字映射到多个后端做故障转移那没问题但如果你的本意是不同参数走不同模型那就要用更细的路由规则而不能简单重复model_name。我个人的建议是model_name一定要起得语义化、稳定化不要直接挪用某个服务商的真实模型名。否则你换了供应商还得逼着业务方改代码那这个网关就失去意义了。5.2 密钥安全与配置拆分litellm 的配置里涉及大量 API Key我非常不建议直接写在 config.yaml 里。你可能会因为图省事把 key 硬编码进去然后配置文件被不小心提交到代码仓库那问题就大了。最稳妥的做法是用环境变量引用。比如litellm_params: model: provider-one/demo-chat api_key: os.environ/PROVIDER_ONE_KEY然后在启动 litellm 的环境里设置对应的环境变量。另一个方法是利用 litellm 的自定义密钥管理接口从远程加载密钥。不过对于大多数团队来说环境变量已经够用了。还有一个小细节litellm 的代理接口本身需要一个主密钥来保护管理接口。建议启动时强制设置export LITELLM_MASTER_KEYyour-master-key litellm --config config.yaml --port 4000没有这个主密钥任何人都可以访问管理接口生成虚拟 key那就等于把网关完全暴露了。如果入口网关外部可达还应该配合一层额外的访问认证或者放在内网。5.3 性能与并发踩过的坑litellm 本身是一个 Python 服务默认情况下并发能力不是无上限的。我在测试模拟项目 X 的时候用压测工具打了 100 个并发请求出现过一些连接超时和 CPU 飙高的情况。后来我总结了几点经验。第一生产环境一定要用 gunicorn 或者 uvicorn 等多进程方式启动 litellm而不是直接裸跑litellm命令。多进程能充分利用多核 CPU。第二外部模型服务的响应时间本身就是瓶颈。litellm 在等待上游返回时进程内会有很多协程挂起。如果你的客户端连接数很多可能需要调整进程数和超时时间不要让长时间挂起的请求占满所有工作进程。第三外部服务的限流比想象中更容易触发。你通过 litellm 统一转发请求后所有业务方共享同一个后端配额。如果不做本地限流一个大的突发流量就可能把整个模型池打到限流。建议在 litellm 前面再加一层速率限制或者给关键 key 设置rpm_limit。另外也要注意 litellm 的日志量。在高并发下默认日志级别会输出大量请求信息非常占磁盘。我通常会把日志调整成 WARNING 级别只在出错时记录。还有一个很容易踩的坑是超时设置。litellm 默认的外部请求超时比较保守如果模型推理时间比较长比如一些多步推理或长文本生成很容易触发超时重试导致重复计费。你需要在配置里根据自己的模型延迟合理设置timeout参数否则用户会经常看到超时错误。最后分享一个小技巧对 litellm 做生产升级之前一定要留一个旧版本的配置文件备份。这个项目迭代速度很快偶尔会有 Breaking Change特别是配置字段的改动。我吃过一次亏升级后某个general_settings字段不再生效结果缓存策略静默失效成本飙了一截。后来我养成了升级前先做 diff、升级后观察一段时间的习惯。这个项目本身的价值是确定的但要用好它还是得花点心思在设计路由策略和配置管理上。