做AI应用开发的人多多少少都会遇到同一个问题大模型服务越来越多各家接口的请求格式、鉴权方式、计费逻辑却一个比一个不一样。早期接到一两家还好等真上了生产既要用这个模型处理问答又用那个模型做结构化抽取还要留着备用模型防止服务抖动……这时候如果每个调用都在代码里单独适配改需求就得动业务代码真的很痛苦。litellm这个项目就是用来解决这类问题的。它本质上是一个统一的大模型API代理层对外暴露一套标准接口对内帮你对接不同模型服务顺便把路由、重试、限流、成本统计这些脏活累活一起包了。这篇文章从实际使用角度出发讲讲litellm能做什么、怎么快速搭起来、以及我踩过的一些坑。不管你是在做RAG应用、agent工具链还是给团队搭一个模型接入网关都可以参考。1. 为什么需要litellm多模型时代的接口混乱问题1.1 多服务接入的三大痛点先说一个最直观的场景你的应用需要同时使用两家以上的模型服务。每个服务都有自己的SDK、自己的鉴权方式、自己的超时和重试逻辑。A服务用“输入消息列表模型名”的方式B服务可能要在Header里传不同的认证头C服务干脆连token计量方式都不一样。业务代码里到处是if-else和模型类型判断每接入一个新服务就要把整个调用链改一遍。第二个痛点是计费。不同服务的定价模型差别很大有的按输入输出总token计费有的按字符数计费还有的按请求次数包月。如果没有一个统一的地方记录每个请求到底花了多少钱到了月底对账就是一场灾难。第三个痛点是故障处理。模型服务不是永远稳定偶发超时、限流、内部错误都很常见。你要是每个模型单独写重试逻辑代码量至少翻一倍更麻烦的是某些厂商的备用模型和主模型还不是一个体系失败后手动切换运维压力很大。1.2 litellm的解决方案代理层思路litellm的核心思路很简单在应用和模型服务之间加一层代理。应用只跟这个代理说话代理再替你去找对应的模型服务拿到响应后再按统一格式返回给你。这就像你在办公室装了一个前台。来客不需要知道哪个部门在几楼、谁负责什么只需要跟前台说“我要找谁”前台自然帮你把人叫下来。litellm就是这个前台它把各家模型请求转成它们各自能听懂的格式再把响应整理成应用熟悉的格式还回来。这样做最大的好处是解耦。业务代码只需要维护一套请求逻辑模型选型、切换、灰度、降级都在代理层配置。以后哪怕把主力模型从A换成B业务代码一行都不用改。2. 核心能力拆解路由、重试、限流与成本控制2.1 模型路由按规则把请求分到不同模型litellm支持配置多个模型并给它们设置不同的权重或优先级。比如你配置了两个模型服务想让70%的请求走主模型、30%走辅助模型可以通过权重实现。如果主要是为了高可用可以让litellm优先使用列表里的第一个模型万一它不可用再自动切换后续模型。路由的配置在YAML文件里的model_list中完成。每个模型都有一个逻辑名称和对应的实际服务信息。逻辑名称是给应用看的应用始终请求同一个名字实际服务信息是给litellm用的它知道该把请求转给谁。这种“逻辑名与实际模型分离”的设计决定了路由策略可以随时调整不用通知调用方。2.2 自动重试与故障转移模型挂了也能扛生产环境中单模型服务很容易出现偶发超时或者限流。litellm里可以为每个模型配置fallbacks也就是备用模型。当主模型连续失败到一定次数或者返回特定的错误状态码时litellm会自动把请求转给备用模型。需要注意的是重试不是简单的“报错再来一次”。litellm会对不同错误类型做区分有些错误比如参数格式错误重试多少次都没用就不该重试有些错误比如限流等几秒再试一次可能就好了可以配置短延迟重试。这个区分做得越细线上表现越稳定。2.3 限流与并发控制别被上游限流打懵模型服务都有各自的速率限制你在代理层如果不管控一旦并发打上去很容易触发上游的429限流。litellm支持给每个模型设置RPM每分钟请求数和TPM每分钟token数超过阈值时会把请求排队或直接拒绝避免实际请求同时涌到上游。我在实际使用中一般会把RPM设置成上游限制的80%左右留出余量。因为上游的限制有时候是动态的加上网络重试等因素设置得太满容易在高峰期平白多出很多限流错误。2.4 Token用量与成本追踪让每一分钱都有记录litellm会记录每次请求的输入token、输出token和总token数还可以根据你配置的单价自动算出这次请求的费用。除了总额外它还能按维度拆分按用户、按项目、按API Key甚至按模型。这个能力在团队内部做成本分摊时特别好用。成本统计这一块建议从一开始就打开别等业务量大了再补救。litellm支持将日志写入数据库后续可以接上自己的报表系统做分析。如果不做这一步你永远只能得到“上个月花了大概多少钱”这种模糊结论。3. 实操十分钟搭一个litellm代理服务3.1 安装方式与前置准备litellm是一个Python包可以通过pip直接安装官方也提供Docker镜像。我最常用的是pip方式因为方便本地调试部署到服务器时再用Docker封装。# 建议在虚拟环境里安装 python -m venv .venv source .venv/bin/activate pip install litellm安装完成后确认一下Python版本。litellm对Python版本有要求实测在较新的Python 3.10以上版本上运行最稳。如果用的是比较老的系统内置Python建议先升级环境再继续。3.2 编写第一个配置文件litellm的配置是一个YAML文件。下面是一个最简示例包含两个模型服务逻辑名都叫chat-model这样应用传这个逻辑名litellm会根据路由策略决定实际打到哪个服务。model_list: - model_name: chat-model litellm_params: model: provider-a/model-1 api_key: sk-provider-a-key-xxx - model_name: chat-model litellm_params: model: provider-b/model-2 api_key: sk-provider-b-key-xxx api_base: https://api.provider-b.example.com litellm_settings: drop_params: true set_verbose: true general_settings: master_key: sk-your-master-key database_url: sqlite:///litellm.db配置里几个关键字段拆开说model_name逻辑名称应用请求时用的名字。model实际模型的完整标识。litellm要求用“服务商/模型名”的格式因为不同服务商可能有同名模型必须带前缀区分。api_key对应服务的密钥建议用环境变量替代别直接写死在文件里。master_key管理端口的访问密钥保护你后续调用管理接口时不会裸奔。database_url用来存储日志和成本数据sqlite最简单生产环境建议换成PostgreSQL。3.3 启动服务并用标准SDK验证配置文件写好后启动服务只需要一条命令litellm --config config.yaml --port 4000启动成功后日志里会显示监听地址。这时就可以拿你熟悉的HTTP客户端去请求了。litellm对外提供的是标准的chat/completions接口格式所以你可以直接用项目里现有的SDK只把base_url指到本地代理。curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-your-master-key \ -d { model: chat-model, messages: [ {role: system, content: 你是一个测试助手}, {role: user, content: 你好介绍一下你自己} ] }如果配置没问题你会收到和模型服务直接返回几乎一致的响应结构但请求已经经过litellm转发、记录和成本统计了。3.4 验证路由与故障转移是否生效这一步很多人会跳过但我建议务必做一下。你可以临时把一个模型的api_key改成错误值再请求一次观察litellm是否自动切到另一个模型。同时看日志里从发起请求到最终返回的过程中是否存在一次失败后的重试记录。这个测试能验证两件事一是配置里的fallback规则真的生效了二是确认重试间隔不会导致接口响应时间过长。万一发现默认重试策略给你的请求增加了好几秒延迟就要在配置里调整重试次数和退避参数。4. 落地实践生产环境中的关键决策4.1 自建代理还是托管服务litellm本身是开源项目你可以完全自建。自建的好处是数据不出内网所有请求和日志都留在自己的基础设施里合规压力小。坏处是你需要自己维护实例、数据库、监控和升级相当于又多了一个基础组件。如果团队已经有完善的容器化环境部署litellm其实不重。一个实例加一个数据库就能跑通。但如果你的体量很小只有几个内部工具在用也不太在意日志留存那直接用官方托管服务可能更省心。我的建议是只要涉及到生产客户数据和成本敏感场景优先自建数据可控性比省那点运维时间重要得多。4.2 与现有应用框架集成这个是我最喜欢litellm的地方。你的应用如果是用Python写的大模型应用大概率已经习惯了“base_url api_key model”这套调用方式。litellm完全能无缝替代。只需要把SDK里的base_url改成litellm服务地址api_key改成你在litellm里分配的某个Keymodel改成配置里的model_name就完成了。其他逻辑什么都不动。我在一个项目里就是这么干的原来业务代码直接对接某模型服务后来想换成另一家做对比测试。如果没有这层代理至少要改好几处模型名称和SDK实例化逻辑现在只需要改YAML配置把model指向新服务业务代码完全没碰。4.3 权限控制给下游同学发虚拟卡多团队共用同一个代理时不可能让每个人都拿上游模型服务的真实Key。litellm支持生成虚拟Key每个虚拟Key可以绑定特定模型、设置预算上限、限制并发数。这相当于给每个团队或每个应用发一张“虚拟卡”。上游真实Key只需要配置在代理服务里下游拿到的是受限的虚拟Key即使泄露了风险也可控。我在团队里一般按照“应用维度”发Key每个应用一套虚拟Key预算单独设置月底看成本报表时每个应用花了多少钱一目了然。4.4 成本分摊与用量统计litellm的成本统计不只是一个总数它可以做到按虚拟Key维度、按用户ID维度、按模型维度分别统计。这要求你在请求时把对应的metadata信息传过来。from litellm import completion resp completion( modelchat-model, messages[{role: user, content: 统计一下这段话的token}], metadata{user: u_12345, project: search_agent} )这样litellm在记录日志时会把user和project身份一起写进数据库。后续无论对接哪套可视化大盘都有了统一维度的成本数据。这个机制越早用上后面做预算管控越轻松。5. 常见问题与排查技巧实录5.1 模型路由没生效都是模型命名惹的祸症状请求到了litellm但日志显示实际调用的模型总是同一个自己配置的权重似乎完全没起作用。排查思路先确认model_list里每一项的model_name是否一致。应用请求时用的是model_name如果你把多个模型配成了不同逻辑名而请求时只传第一个名字那自然只会走第一个。另一个坑是“模型名带不带前缀”。litellm要求model字段写“服务商/模型名”但具体格式因服务而异。有些服务商在模型名前要加特定前缀漏了之后即使路由配置正确转发出去也是非法请求。5.2 重试机制为什么一直不触发症状模型服务已经返回5xx了但litellm没有按预期切到备用模型。典型原因有几种。最常见的是fallbacks配置格式不对备用模型必须出现在model_list中并且要单独声明成可用的model_name。其次是触发条件判断问题litellm对某些异常类型可能不会执行fallback需要看一下日志中具体的异常类型是否在可重试范围内。还有一个细节如果主模型定义了较高的RPM/TPM限流而备选模型没有配置那么在流量高峰时请求可能还没到达备用模型就被限流拦下了。所以建议给每个备用模型也设置合理的限流参数。5.3 成本统计不准怎么办症状litellm记录的费用和你从模型服务后台看到的费用对不上。先查一下计费单价配置是否正确。每个模型在不同时间可能价格不同litellm配置里的单价是静态的需要定期维护。另外有些模型存在缓存命中、特殊计费规则litellm默认按照输入输出token分别计算如果模型服务后台对缓存token有折扣价统计口径就会不一致。还有提示词缓存的问题。某些模型会缓存历史请求的前缀被缓存命中的token计价比普通输入token便宜很多。litellm基础版本可能不会单独区分缓存token这会让你统计出来的成本偏高或偏低。现场排查时先拉一条具体的原始日志人工核算一次token和费用就能定位是单价问题还是token口径问题。5.4 日志与监控别等线上出问题再翻日志litellm本身提供了日志接口和监控指标最基础的做法是看进程日志但生产环境建议把日志接入统一日志平台同时采集metrics到监控系统。我习惯在代理层把这些指标加进看板请求成功率、上游平均延迟、每分钟请求数、每分钟token数、累计成本趋势。这几个指标能最直接反映代理的健康程度。尤其是上游延迟异常升高的时候通常不是litellm的问题而是某个模型服务在流协议或排队上出了状况提前看到曲线变化能避免业务方被动感知异常。顺便提醒一句生产环境不要忘记给litellm出口的网络地址设置单独的防火墙规则。因为它会代替应用访问各模型服务任何能访问代理的人理论上都能借助代理去请求模型master_key和虚拟Key都得妥善保管定期轮换。最后分享一个我自己的习惯每次调整litellm配置之后我都会先做一轮小的冒烟测试覆盖“正常请求”“携带错误模型名”“触发限流”“主模型故障切备用”这四种情况。这整套验证下来不到十分钟却能避免很多线上问题。踩了几次配置“看起来没问题、一到大流量就出岔子”的坑之后我越来越觉得litellm这类代理层的调试核心不是把服务跑通而是把异常路径一条条验证到位。