LiteLLM：统一大模型API的代理网关与模型路由实战指南

做LLM应用开发，不管你是在写一个智能客服、内容生成工具，还是内部的知识库问答系统，跑不了要接大模型API。但做到后半程大家都会撞上一个尴尬现实：模型越来越多，等你的不是某一个接口，而是一堆格式不同、限流策略不同、计费规则也不同的第三方服务。今天上线一个模型，明天想切另一个模型试试效果，结果发现每家都要单独写一套调用逻辑，SDK、鉴权、错误处理全都不一样。这种时候，LiteLLM就能派上用场。

LiteLLM是一个开源项目，核心做两件事：一是把各家模型API的差异统一成一个接口，让你用同样的代码格式去请求不同的模型服务；二是提供一个可以自己部署的代理网关，统一接收请求、转发到背后的模型服务，顺带把密钥管理、预算控制、路由切换、调用日志这些脏活累活集中处理掉。这篇文章我会把LiteLLM的核心设计思路、关键功能、实际配置流程，以及我在生产环境里踩过的坑一次性讲清楚，适合正在做LLM应用开发、需要在多个模型之间做切换和管控的开发者参考。

1. 项目定位与设计思路

1.1 被大多数人低估的“API碎片化”问题

在聊LiteLLM之前，我想先掰扯一下为什么会有这种工具存在的必要。很多人最初接模型API的时候感觉很轻松：拿个SDK、填个key、发个请求，返回回来就能用。但一旦你开始认真做产品，问题就来了。

首先是接口差异。你换一家模型服务商，请求体里参数的命名可能完全不一样。有的叫max_tokens，有的叫max_output_tokens；有的支持temperature，有的根本不理你。返回结构也不同，有的把token用量放在usage字段，有的塞在meta里面。你想把这些差异都抹平，就得在业务代码里套一层又一层的适配逻辑，写出来的东西全是if分支和字段映射，看着都头疼。

其次是多模型、多供应商的切换逻辑。产品上线之后，几乎一定会遇到这几个需求：模型A出故障了要自动切到模型B；某个供应商限流了要换备用通道；不同客户要用不同的模型。这些需求如果靠业务代码自己实现，每一次切换都是一次发布上线，灰度验证也麻烦，风险全堆在应用层。

再就是密钥和计费管理。团队里每个人写代码都要用自己的key，密钥散落在本地环境和代码仓库里，出了问题根本查不到是谁调了哪个接口、花了多少钱。一套可统一配置、统一审计的入口，对大一点的团队几乎是刚需。

LiteLLM解决的就是这堆问题。它把不同模型服务的差异收敛到一层网关后面，对上层暴露一个统一接口，同时把路由、容灾、限流、预算、日志这些非业务逻辑全部下沉到网关层处理。这么设计的好处很明显：业务代码只跟一个SDK打交道，模型怎么切换、密钥怎么管理，跟上层完全解耦。

1.2 LiteLLM的两种使用形态：SDK与代理服务

LiteLLM的使用方式有两种，理解这个对后续配置很重要。

第一种是直接当成一个Python库来用，也就是SDK形态。你在代码里import litellm，然后调用litellm.completion()或者litellm.acompletion()，通过model参数指定模型位置，同一个函数签名就能调用不同的模型服务。这种形态适合单体项目或者不想额外部署服务的场景，个人开发者、原型项目用这个最方便。

第二种是代理服务形态，也是我在正式项目里更推荐的方式。你部署一个LiteLLM代理服务，它对外暴露一个/chat/completions之类的HTTP接口，背后通过配置文件把请求分发到真实模型服务。这种形态本质上就是一个托管的API网关，团队所有人、所有服务都通过这个网关访问模型。它的好处是集中：密钥统一收口，预算统一控制，日志统一收集，切换模型只需要改配置文件，不需要动业务代码。

两种形态可以配合使用：开发环境直接用SDK跑得快，生产环境用代理服务统一管控。我自己比较习惯的做法是本地调试时直接import，部署到测试环境就起一个代理，业务代码里把base_url指向代理服务即可，这样能提前暴露网关层的配置问题，不至于上了生产才发现模型路由不通。

1.3 选型时我会反复权衡的三个点

如果你也在考虑搭建自己的模型管理中间层，选型的时候有几个点建议认真对比。

第一，是不是真的需要代理？如果你的项目只有单机、单模型、一个人开发，直接调用官方SDK就够了，引入网关纯属增加复杂度。但是如果多人协作、多个服务共用模型资源，或者你预见到未来会做多模型切换，那网关的价值就会显现出来。

第二，功能覆盖是否匹配你的真实痛点。比如有的团队最痛的是成本控制，那就要重点看预算功能；有的团队最痛的是供应商故障切换，那就要看路由和fallback能力。LiteLLM的优势在于这几个功能都能在一个项目里打通，而不是每个需求都要接一个独立系统。

第三，技术栈和维护成本。LiteLLM是Python写的，依赖的组件也不复杂，核心服务和配置都是声明式的。如果你的团队不熟悉Python也没关系，因为它对外暴露的标准HTTP接口，你用任何语言都能调用。这一点我还是比较看重的——很多内部工具的落地障碍不在功能，在于团队能否持续维护。

2. 核心功能拆解

2.1 统一接口：用一套代码调不同的模型

LiteLLM最基础的能力，就是统一接口。它把各家模型服务的请求参数、返回格式做了标准化，对外暴露的是统一的函数签名和数据结构。你在SDK层面传model="supplier/model"这种格式，就能定位到具体的模型服务。比如某个头部闭源模型、某个云厂商的托管模型、或者某个开源自部署模型，只要在配置里对应好，调用层完全不用关心背后是谁在提供算力。

这一个“统一”的能力，省掉的不只是几行适配代码。它让你的业务层能够真正做到模型无关。我见过不少团队因为切换成本太高，哪怕市面上出现了效果更好、价格更低的模型，也不敢轻易尝试，因为底层代码已经跟某一家供应商深度绑死了。用了LiteLLM之后，切换模型变成了配置层面的事情，灰度对比也简单得多。

2.2 模型路由与故障容灾

代理形态下，路由能力才是真正值钱的部分。你可以告诉LiteLLM：主模型用A服务，如果A超时、限流或者返回错误，就自动切换到备用模型B。这个能力在对接真实业务时非常实用——模型服务也是服务，也会抖动、也会挂，重要的是你的系统不能跟着挂。

LiteLLM支持配置请求级别和模型级别的fallback。比如我配置了primary-chat和backup-chat两个模型，当主模型返回429限流错误、5xx服务器错误或者超时的时候，代理会自动把请求转发到备用模型，业务方甚至感知不到这次切换。如果想做得更细，还可以按用户、按团队分组配置不同的路由策略，或者按权重在多个等价的模型之间做负载均衡。

这里有一个需要留意的设计细节：路由和fallback不只是一个开关，它需要跟超时时间、重试次数配合起来。如果超时设得太短，模型还在正常思考就被你中断了，白白浪费一次请求；如果超时设得太长，故障切换的响应就慢得让用户无法接受。实际项目里要根据模型平均响应时间去调，一般我建议初始设为50秒到60秒，动态超时也是一个思路。

2.3 预算控制与密钥权限管理

做企业内部应用的时候，模型成本管控经常是老板最关心的问题。LiteLLM的预算体系可以做到：为每个API key设置最大消费金额、设置每分钟/每天的请求数上限、按团队或项目维度拆分预算。

这意味着你可以给A部门发一个key，限制它每个月最多消耗一定金额；给B项目发另一个key，限制每分钟最多请求多少次。当一个key的用量达到设定阈值，代理会直接拒绝新的请求，返回明确的错误说明。这个机制对于防止失控调用、隔离不同业务线成本非常有帮助。

密钥管理上，你只需要在代理层配置真实的供应商密钥，给团队成员或者下游服务发虚拟key。团队成员的请求不直接接触底层供应商，就算某一个虚拟key泄露了，也能通过撤销该key控制影响范围，而不是把底层所有密钥全部更换一遍。在生产环境里，我强烈建议开启这个能力，成本控制是其次，安全审计才是重点。

2.4 日志与用量追踪

最后是观测性。网关层天然是所有流量的必经之路，所以在日志方面有天然优势。LiteLLM可以记录每一次调用的模型、供应商、请求时间、响应耗时、token消耗和错误信息，这些数据既能用来排查问题，也能反过来统计成本。

我在做模型对比的时候会用这个数据：同一批请求分别走了哪个模型、平均响应时长多少、token花费多少，拉出来一算就知道该留谁、该砍谁。配合外部日志系统，还可以把调用链路串起来，到时候排查问题就能直接定位到具体某次请求而不是全靠猜。

3. 实操配置与核心环节

3.1 安装与启动代理服务

LiteLLM的安装比较直接，建议用虚拟环境管理依赖，避免污染系统环境。如果你要用代理功能，直接装完整版本：

pip install 'litellm[proxy]'

装完之后，在命令行启动代理：

litellm --config config.yaml --port 4000

默认监听4000端口，和很多本地服务都不冲突。启动成功后，浏览器访问http://localhost:4000能看到一个简单的控制台页面，也可以直接往/chat/completions发请求测试。

这里有一个小建议：第一次跑的时候，先用SDK模式确认模型配置正确，再起代理。因为代理层会把问题包在HTTP响应里，排查时多一层转换，不如先在代码里验证直连通路，再验证代理转发。

3.2 config.yaml配置文件的写法

代理服务的核心是配置文件。这里我用一个简单但不失典型性的例子，说明里面几个关键字段的意思：

model_list: - model_name: primary-chat litellm_params: model: provider/model-a api_key: ${MODEL_A_KEY} rpm: 60 timeout: 60 - model_name: backup-chat litellm_params: model: provider/model-b api_key: ${MODEL_B_KEY} rpm: 30 litellm_settings: drop_params: true set_verbose: true general_settings: master_key: sk-your-master-key database_url: postgresql://user:password@host:5432/litellm

你看到model_name是给上层请求用的逻辑名，调用方传的是primary-chat而不是真实的供应商模型ID。这么做的好处是，后面我不管把primary-chat指向哪个真实模型，上层服务完全不用改。litellm_params里指定真实模型、API key和请求限制。rpm是每分钟最大请求数，这个参数能防止某个下游服务把模型打爆。

drop_params这个配置我特别说明一下。不同模型支持的参数不一样，比如某个模型支持top_p，另一个模型可能不支持，如果不加这个开关，请求传了不认识的参数对方会报错。打开之后，LiteLLM会自动过滤掉目标模型不支持的参数，兼容性会好很多，代价是某些参数可能被静默忽略，调试的时候要注意。

3.3 密钥注入与多环境配置

把API key直接写在config文件里的做法千万不要用。我在多个环境之间切换的时候，习惯用环境变量注入密钥。你在启动之前设置好环境变量，config里用${MODEL_A_KEY}引用，这样配置文件可以提交到代码仓库，密钥仍然留在部署环境里。

如果你用的是容器化部署，也建议用密钥管理工具把敏感信息注入容器的环境变量，而不是把密钥打包进镜像。很多上线事故都是因为密钥藏在了镜像里，换了环境或者镜像被分享出去，密钥跟着泄露。

另外，master_key建议设一个足够复杂的随机串，生成之后放到环境变量里。它是你管理整个代理的超级权限，丢了等于把模型资源都交给别人了。

3.4 业务应用如何接入代理服务

配置好之后，业务接入就很简单了。假设你有一个Python服务，原本直接调用官方SDK，现在只需改两处：把api_base改成代理地址，把api_key改成master_key或者给这个服务分配的虚拟key。

import litellm response = litellm.completion( model="primary-chat", messages=[{"role": "user", "content": "你好"}], api_base="http://localhost:4000", api_key="sk-your-virtual-key" ) print(response.choices[0].message.content)

如果项目不是Python写的，直接用HTTP请求也可以。代理暴露的是兼容标准格式的接口，你用任何语言发HTTP POST请求，都能正常调用。

这里要提醒的是，既然你的业务代码已经不再直连供应商，那么对上游模型服务故障的处理逻辑就要从代码层迁移到网关层，比如fallback配置。业务层尽量只面向primary-chat这个逻辑名，不要在应用里自己写一套切换逻辑，不然又回到了各路代码各自为政的老路上。

3.5 路由策略与参数调优实操

路由策略的配置是一个迭代过程，不可能一上来就完美。我的建议是从简单的fallback开始。假设某种闭源模型效果好、贵一点，开源模型效果略差、便宜很多，你可以让闭源模型作主路，开源模型作兜底。这么配至少保证服务不会因为单一供应商的故障而中断。

参数上，你还需要关注等待超时和重试次数。LiteLLM支持cooldown_time，当一个模型连续失败达到阈值，会自动把它暂时移出可用列表，过一段时间再让它回来。这个机制有点像服务熔断，能在故障期间保护用户体验，同时给故障模型恢复的机会。

字段配置示例如下：

router_settings: retry_policy: Timeout: 2 RateLimitError: 3 cooldown_time: 30

retry_policy按错误类型设置重试次数。限流错误我可以重试3次，超时错误只重试2次，因为超时很多时候是请求本身太久，重试意义不大。这些参数没有绝对值，完全看你的供应链稳定性和产品对延迟的容忍度。

4. 常见问题与排查实录

4.1 一张速查表定位高频问题

我把实际用LiteLLM过程中遇到的高频问题整理成了一个表，基本覆盖了80%的日常故障场景：

排查这类问题的规律一般是：先看错误码，再看代理日志，最后看上游供应商的状态。代理日志会记录每个请求的入参、出参和耗时，基本能还原整个链路。如果错误不是代理层产生的，日志里会透传上游服务的原始错误，这个信息尤其重要。

4.2 超时调优的真实案例分析

我之前遇到过一类诡异问题：看起来所有请求都成功返回了，但应用层的超时错误比较多。后来排查发现，代理默认把超时设得偏保守，上游模型稍微多思考一会儿就超过了应用层设置的阈值。应用等不到响应，就直接报错断开，但上游服务确实还在正常生成内容。这时候如果你只盯着代理看，会觉得一切正常，但用户实际感知到的就是“动不动就失败”。

调整思路是分层设置超时。应用层的超时要大于代理层超时，代理层超时大于等于供应商真实模型服务承诺的最大响应时间。如果业务对实时性要求不高，那就把超时放宽，尽可能保证请求完整返回；如果你需要快速失败然后走fallback，那就把代理层超时设短，让故障切换尽快生效。这套逻辑不只在LLM网关适用，任何中间层服务都适用。

4.3 一定不要忽视的成本失控信号

模型成本失控是我观察到的最普遍的生产事故，而且它通常不是突然发生的。比如某天有人写了一个批量脚本，循环调用模型处理数据，结果每个循环都触发几十次的自动重试，成本瞬间翻了几十倍。LiteLLM的预算功能可以拦截这种问题，但它只能在达到阈值后阻止新请求，预先防护还是需要靠合理配置rpm和tpm。

我给团队定的规矩是：上线初期预算阈值设得比预期低一点，宁可误拦截，也不要让账单超预期。等跑一段时间，拿到真实用量数据，再把阈值调整到合理范围。成本这东西，弹性上调永远比事后追认轻松得多。

5. 生产部署的经验建议

5.1 容量规划与并发模型

LiteLLM代理本身是一个Python异步服务，在正常配置下，单实例能支撑几百个并发请求。但生产环境要把它当作正式服务来规划，而不是本地调试工具。如果并发预计会很高，就要考虑多实例部署，在代理上层加负载均衡。

配置数据库也建议从默认的SQLite切换到正式关系型数据库，比如PostgreSQL。因为生产环境的key、预算记录、调用日志会有比较强的写入压力，SQLite在小流量时没问题，数据量大了容易写锁竞争，直接影响响应速度。

5.2 高可用部署的基本形态

生产部署时我建议的最小可用方案是：两个LiteLLM实例，共用同一个数据库实例，前面挂一个负载均衡，业务请求打到负载均衡上。当一个实例故障或重启，流量自动切换到另一个实例，实现基本的高可用。配置文件的版本要保证一致，可以放到配置中心或者镜像构建时统一打包。

如果某个供应商模型服务需要特定区域或特殊网络环境，比如私有化部署的模型服务只允许内网访问，可以把LiteLLM实例部署在与该模型同一内网，或者通过路由配置限制只能通过某个网关转发到该模型。早期就要想清楚网络拓扑，不然部署完了发现连不通才来改，成本不小。

5.3 监控与告警怎么搭

模型网关这种基础设施，必须有监控。指标层面，重点看QPS、错误率、P95延迟、token消耗速率、限流次数。这些指标配好之后，还要加上告警。

告警阈值我是这么定义的：错误率超过5%持续5分钟，发出警告；超过10%持续5分钟，触发紧急告警。P95延迟超过设定值，意味着用户体验已经在下降，也要触发。成本类的告警比较容易忽视但更重要，建议按天设置消耗预算，如果当天消耗已经超过前一天同时间段的50%，就发出提醒，看看是不是有什么异常任务在跑。

LiteLLM对外提供了一些健康检查和指标端点，你可以用监控工具定时拉取。如果你用的不是同一技术栈，也可以用进程守护工具做基本的存活检查，至少保证代理挂了能自动拉起，这是最底线的高可用。

5.4 安全基线设置

安全方面有几个底线要提前设好。第一，代理必须加鉴权，不能用无鉴权的方式暴露在网络上，否则等于给别人开了个免费模型通道。第二，若对外提供服务，一定要放在反向代理之后，用标准加密方式传输，并且处理好跨域策略。第三，虚拟key要定期轮换，发现泄露的key要立即在代理层禁用。

我推荐的做法是，所有真实供应商的key都放在密钥管理服务或者环境变量里，所有下游服务统一使用虚拟key。虚拟key可以设置有效期，到期自动失效，这样可以防止一些长期无人维护的遗留服务一直在偷偷消耗预算。

6. 我在实际使用中的一些体会

用了大半年LiteLLM，我最明显的感受是：它把一个让人头疼的“接各种模型”问题，从业务代码里剥离出来了。以前开发同学接到需求要先问“用哪个模型的SDK”，现在基本上只需要关心逻辑模型名和需求本身。基础设施的活已经有人干了，这种解耦带来的效率提升是实打实的。

最后想分享一个技巧：在刚开始搭建的时候，不要急着把所有功能都加上，先把统一接口跑通，让业务代码通过代理调用一个模型。稳定之后再逐步开路由、预算、日志。功能加得太快，遇到问题都分不清是配置错了还是代码错了。稳扎稳打，LiteLLM会是你模型管理这条路上非常顺手的工具。