做AI应用开发这几年我最大的感受是模型本身没那么难调真正烦人的是“接模型”这件事。今天业务方说要接入A公司的对话模型做效果对比明天又说B公司的轻量模型成本更低后天还要考虑某个云平台上的托管模型。每接一个SDK不一样、鉴权方式不一样、错误码不一样代码里全是if-else和适配逻辑。后来我在一个跨平台系统里引入了litellm把它架在所有大模型服务方和业务代码之间这一层统一掉的问题远比我想象中多。这篇文章就把我的实战经验拆开讲从部署到排障适合正在被“多模型接入”折磨的开发者参考。1. litellm是什么解决的是真实的工程痛点1.1 先看看业务代码里的混乱从哪来我接过不少项目最初的调用方式往往都是直接写死某一家大模型服务方的SDK。代码看起来很简单创建客户端、填API Key、发请求、拿结果。可一旦业务要求支持第二家、第三家服务方麻烦就来了。每家服务方的请求体结构不同有的用顶层prompt字段有的用messages数组响应结构也不同有的返回choices数组有的返回别的结果字段鉴权方式更是五花八门有的用请求头带Key有的用查询参数。业务代码里很快就长满了这样的逻辑if provider company_a: payload build_payload_for_a(messages, temperature) elif provider company_b: payload build_payload_for_b(messages, temperature) else: raise NotImplementedError这种代码最大的问题不是丑是每次增删服务方都要动业务代码而且要重新测试、重新发布。更麻烦的是错误处理没法统一A公司限流返回的JSON和B公司限流返回的JSON完全不一样状态码也各有各的习惯排查问题的时候特别痛苦。1.2 litellm在整个架构里的位置litellm本质上是一个大模型API网关或者说是一个统一代理层。它的核心思路是业务代码只面向一套API接口所有上游大模型服务方的差异都由litellm在网关层处理掉。你在业务里只需要维护一个base_url指向litellm暴露出来的统一端点。业务继续用熟悉的对话补全接口格式发请求model字段传的是你在litellm里定义的别名比如company-a-chat、company-b-fast这种。litellm收到请求后会根据配置找到对应的上游服务方完成协议转换、鉴权注入、请求转发、响应转换最后把统一格式的结果返回给你的业务。这个架构很像支付网关的模式你在商城只对接一个支付接口后端是微信、支付宝还是银行卡商城不需要关心。litellm在AI应用里扮演的就是这个“支付网关”角色。1.3 适合谁用什么阶段引入最合适如果你属于下面几种情况litellm能带来的收益会非常明显业务同时对接多个大模型服务方比如正在做A/B效果对比或者要根据业务场景选不同的模型。需要对上游调用做统一管控预算、限流、密钥、日志都要集中管理。团队要隔离开发环境和生产环境不同环境走不同Key、不同预算、不同上游配置。做平台型系统需要给多个内部业务线发不同的虚拟密钥并统计各自用量。至于引入时机我个人的建议是只要出现了第二次对接模型的诉求就可以考虑上litellm。不要等到代码里写了五六套适配再动手那时候迁移成本反而高。2. 快速部署从零到一跑通一个代理服务2.1 环境准备与安装litellm的部署方式很灵活。它首先是Python包同时也提供了容器镜像可以跑在服务器、开发机、内网环境的任何角落。最基本的环境要求是Python 3.10及以上版本建议用一个干净的虚拟环境来装避免污染系统Python。安装命令是pip install litellm[proxy]这里要装带proxy的版本因为我们需要起一个网关服务而不只是用它的Python SDK能力。安装完成后终端里会多出一个litellm命令。我在本地和服务器上都装过流程是一致的。如果你主要在容器里跑可以直接用官方发布的Docker镜像配合docker-compose管理后面我会给一个生产化的配置。2.2 最小配置与启动litellm通过一个YAML配置文件来声明上游模型、路由策略、鉴权方式、缓存等。最小可用的配置大概长这样model_list: - model_name: company-a-chat litellm_params: model: company-a/chat-model-1 api_key: os.environ/COMPANY_A_API_KEY - model_name: company-b-chat litellm_params: model: company-b/chat-model-1 api_key: os.environ/COMPANY_B_API_KEY这里有两个关键点第一model_name是你对外暴露的别名业务代码里传的就是这个名字。好处是上游真实型号更换时只要改配置里的映射业务代码一行都不用动。第二model字段的写法是“服务方前缀/模型名”litellm靠这个前缀识别应该走哪个适配器。api_key可以通过os.environ/环境变量名的方式引用也可以直接写值但强烈建议用环境变量方式避免密钥写在配置文件里被提交到仓库。启动服务非常简单export COMPANY_A_API_KEYsk-xxx export LITELLM_MASTER_KEYsk-litellm-master-key litellm --config config.yaml --port 8000启动后litellm会在8000端口监听请求。2.3 业务侧的接入与验证跑通后业务侧接入几乎不用改代码。我用curl直接验证过代理是否正常工作curl http://localhost:8000/chat/completions \ -H Authorization: Bearer sk-litellm-master-key \ -H Content-Type: application/json \ -d { model: company-a-chat, messages: [{role: user, content: 你好}] }这个请求的格式和直接调用某一家的官方接口非常接近但model字段已经换成了我们自定义的别名。litellm会去查配置找到company-a-chat对应的上游服务方然后自动完成协议转换、鉴权注入和响应转换。如果你用的是Python也可以直接用官方的对话补全客户端把base_url指向litellm的地址密钥用主密钥或后面创建的虚拟密钥。这意味着原有的调用代码基本可以无缝迁移只需要调整base_url这一行。2.4 生产化部署的关键改动本地验证通过后别急着就上线生产环境至少要做这几件事设置主密钥。我见过不少人在本地跑起来就忘了设LITELLM_MASTER_KEY结果服务对完全没鉴权的请求也放行。生产环境必须设置主密钥并且用强随机值。所有管理端点都需要这个密钥才能访问。配置持久化数据库。默认情况下litellm把密钥、日志、用量信息放在本地SQLite里这对单机测试没问题但生产环境多副本部署时数据不一致。我建议至少接一个PostgreSQL把密钥、预算、日志落库。配置方式是在general_settings里增加database_urlgeneral_settings: database_url: os.environ/DATABASE_URL启用Redis做缓存和限流。如果有多实例部署Redis可以用来做统一的响应缓存和限流计数。没有Redis的话限流数据在单实例内有效水平扩容以后会失效。用容器编排管理。下面这个docker-compose是精简模板实际使用需要替换密钥、数据库地址和配置挂载路径services: litellm: image: litellm-proxy:latest ports: - 8000:8000 environment: LITELLM_MASTER_KEY: sk-litellm-master-key DATABASE_URL: postgresql://user:passwordpostgres:5432/litellm REDIS_HOST: redis volumes: - ./config.yaml:/app/config.yaml depends_on: - postgres - redis postgres: image: postgres:16 environment: POSTGRES_USER: user POSTGRES_PASSWORD: password POSTGRES_DB: litellm redis: image: redis:7提示生产环境不要把数据库密码直接写在compose文件里用环境变量或密钥管理工具注入。加一层反向代理。litellm本身可以处理请求但生产环境建议在前面加一层TLS终止比如用nginx或者云平台的负载均衡器把证书管理和流量入口收口。3. 核心能力拆解统一网关不只是转发请求3.1 出站适配器上游差异在网关层被消灭litellm最核心的机制就是出站适配器。每接入一个大模型服务方litellm都会提供对应的适配器它负责把统一的内部请求格式转换成该服务方期望的格式再把它返回的响应转换回统一格式。这意味着不管是文本对话、流式输出还是工具调用业务侧看到的始终是统一的接口结构。流式推送在这里是个容易忽略的点不同服务方的流式事件格式不一样有的字段名完全不同litellm帮我们把这些差异全部抹平了。我在项目里从非流式切换到流式时业务代码几乎没改只换了一个参数。这个设计带来的直接好处是你的业务代码可以长期稳定不跟着上游厂商的版本迭代走。上游改API了你只需要在网关层更新适配器或者调整配置。3.2 负载均衡与自动降级在config.yaml里可以把多个上游服务方映射到同一个对外别名。比如company-a-chat可以同时指向A公司的旗舰模型和B公司的轻量模型litellm会根据策略分配流量。常见的路由策略有这么几种策略行为说明简单轮询请求轮流发往不同上游适合无状态、无偏好场景加权轮询按权重分配流量适合大部分流量走主力模型、少量走备用模型最少连接动态选择当前负载最低的上游适合上游性能不均匀的场景故障切换上游连续失败时自动切换到备用模型我做跨平台系统的时候就把文本生成这个入口配了三个上游一个主力模型一个备用模型还有一个低成本的兜底模型。只要主力模型连续报错达到阈值litellm会自动把流量切到备用模型上业务方很多时候根本感知不到上游故障。这种容灾能力如果自己写代码实现要考虑健康检查、失败计数、冷却时间、切换后的恢复策略工作量不小。网关层直接提供等于省掉了一大块基础设施开发。3.3 密钥体系与预算控制多团队共用一套网关时密钥管理是刚需。litellm支持给不同项目、不同环境生成各自的虚拟密钥每一把密钥可以设置独立的预算上限和额度周期。比如我给某内部项目A发的虚拟密钥预算上限是每月1000元项目B是测试环境只给100元。某个密钥跑到上限以后litellm会直接拒绝使用该密钥的新请求而其他密钥不受影响。这个机制对企业支出管控的价值很大。以前团队各自拿上游厂商的API Key直接调用月底账单出来才知道花了多少现在每一笔消耗都能归因到具体密钥、具体项目。3.4 用量统计与缓存优化litellm会在请求日志里记录每次调用的token数量、模型、密钥、耗时并且可以估算出对应的成本。配合管理后台可以直接拉出“某个项目某一天在某个模型上花了多少钱”这种粒度非常细的数据。我实际用下来给财务对账提供了很大的便利不再需要自己在业务层埋点统计。缓存这块也值得一说。litellm支持把完全相同的请求响应缓存起来建议用Redis作为缓存后端。比如某些系统提示词加固定问题的高频请求命中缓存以后响应延迟从秒级降到毫秒级上游调用量也显著下降。注意使用缓存时要格外小心动态请求。人坐在那里手动测试还好线上系统如果带了用户ID、时间戳之类的动态内容缓存命中率很低意义不大。一定要给带随机参数的请求做好缓存隔离。4. 配置进阶把代理调教成适合自己业务的样子4.1 模型组、别名与路由策略我在上一个项目里把模型们组织成了三组文本主力组日常对话、总结、改写用效果最好的中大型模型。轻量快线组意图识别、分类、信息抽取用低成本模型。兜底降级组主力模型不可用时切换到的备选模型。在litellm里这三个组就是三条model_list配置。业务方在代码里传入的model字段分别是main-chat、fast-chat、fallback-chat这样的别名。这样业务团队根本不关心上游到底用的什么型号也不需要知道哪天换过型号。路由策略我选的是加权轮询加故障切换。主力组让80%流量走A公司旗舰模型20%走B公司同档模型既能压测对比又能分摊风险。model_list: - model_name: main-chat litellm_params: model: company-a/chat-model-large api_key: os.environ/COMPANY_A_API_KEY rpm: 300 - model_name: main-chat litellm_params: model: company-b/chat-model-large api_key: os.environ/COMPANY_B_API_KEY weight: 0.2 rpm: 1004.2 重试、超时与限流参数网关上配好重试和超时策略可以省掉很多运维精力。litellm支持对每个模型设置独立的请求超时时间、最大重试次数、每分钟请求数上限等。我遇到过这样的情况上游某个模型偶尔响应特别慢业务方请求超时以后直接报错给用户。后来我在litellm里把超时时间调大加上两次重试并且配了故障切换。即便某个上游实例不稳定用户侧也只是感觉到偶尔慢了一点而不是直接失败。从原理上说重试策略并不是无限重试。通常只在连接错误、超时、5xx这类可恢复错误上重试4xx这种业务错误重试没有意义。litellm在这一点上的处理比较符合预期错误分类做得比较细不会把鉴权失败也拿去重试浪费上游资源。4.3 管理接口与日常运维litellm自带一个管理后台可以通过 /ui 地址访问。在后台里可以查看请求日志、密钥列表、预算用量也可以创建新的虚拟密钥、配置上游路由。运维层面我建议重点看这四样东西请求成功率按小时维度看趋势突然下降通常意味着某个上游出了问题。平均响应耗时稳定上升说明上游过载可能需要调整路由权重或者扩容。预算消耗速度结合业务活动节奏判断异常飙高往往是某个项目密钥被滥用。错误码分布401、403、429分别对应鉴权、权限、限流问题快速定位方向。提示litellm的详细日志可以通过环境变量开启遇到线上诡异问题先打开debug日志看网关层是怎么转发的再判断问题是出在上游还是出在配置。5. 踩坑实录常见问题与排查思路5.1 鉴权类错误401、403我最初排查这类问题最多的原因就两个一是请求里没有带Bearer Token二是带的密钥不对或者已经被撤销。如果你用虚拟密钥还要注意这个密钥是否被创建在与当前环境匹配的项目里。有些团队会在网关上做环境隔离测试环境的虚拟密钥在生产环境是无效的。403还有一个常见原因是密钥的预算超限了litellm会拒绝继续服务这时候后台里看到的是权限拒绝而不是限流。遇到这类问题先看请求头里有没有Authorization字段再看后台密钥状态是否正常最后确认预算。排查路径很清晰不太会走弯路。5.2 限流类错误429429的本质是上游认为你请求太频繁。litellm层面可以做两件事一是给某个模型设置rpm/tpm限制从源头控制频率二是配置重试和降级让请求在遇到限流时自动转到另一个模型或稍后重试。我遇到过一种情况同一把虚拟密钥被多个业务模块共用其中一个模块的突发流量把配额打满导致其他模块也跟着限流。后来我把模块拆成不同的虚拟密钥各自设置配额互不干扰。重要经验限流不只是上游的事情。你自己配了缓存和限流以后网关层本身也会成为瓶颈单实例部署时尤其明显。有条件就提前规划多实例部署加Redis共享状态。5.3 超时与上游抖动线上出现超时先别急着骂上游。我用调试日志追踪过几次发现有的是配置里超时时间设得太短有的是重试策略没生效还有的是网关到上游的网络链路本身有延迟。处理顺序建议是确认是不是上游稳定性的问题看上游健康状态。调大request_timeout给慢模型留出余量。开启合理的重试策略并配置故障切换模型。如果上游持续恶化直接把路由权重切到健康的上游。这套流程下来绝大多数抖动都能被兜住。5.4 数据持久化与迁移问题从SQLite切到PostgreSQL时我第一次就吃了亏启动以后发现虚拟密钥全部消失日志也读不到。原因很简单数据库配置没生效litellm仍然在用本地文件。这类问题通过查看启动日志里的database信息就能确认。另外升级litellm版本时要记得对数据库做迁移。社区版迭代比较快升级前先看变更说明和迁移脚本别直接跳到新版本再回头处理数据问题。最后分享一点我自己的运维体会我在实际使用中发现litellm带来的最大改变不是省了写适配层的代码而是改变了团队的工作方式。“模型”从一个需要发版才能变更的硬依赖变成了一个改配置就能切换的软参数。业务方提需求说“想试另一家模型”我只需要在config.yaml里加一行映射刷新Key再观察后台的用量和延迟数据整个流程用不了一小时。如果你现在正处于多模型混用、代码里堆满适配逻辑的阶段我建议先花半小时把litellm跑起来亲手发一个请求看看再决定要不要深入集成。等真正把这层网关用起来你会发现后面很多问题都不再需要自己造轮子了。 
长河君 · 2026/10/13 5:14:09 · 阅读 1.2k LiteLLM实战：用统一API网关解决多模型接入与部署排障全攻略
做AI应用开发这几年我最大的感受是模型本身没那么难调真正烦人的是“接模型”这件事。今天业务方说要接入A公司的对话模型做效果对比明天又说B公司的轻量模型成本更低后天还要考虑某个云平台上的托管模型。每接一个SDK不一样、鉴权方式不一样、错误码不一样代码里全是if-else和适配逻辑。后来我在一个跨平台系统里引入了litellm把它架在所有大模型服务方和业务代码之间这一层统一掉的问题远比我想象中多。这篇文章就把我的实战经验拆开讲从部署到排障适合正在被“多模型接入”折磨的开发者参考。1. litellm是什么解决的是真实的工程痛点1.1 先看看业务代码里的混乱从哪来我接过不少项目最初的调用方式往往都是直接写死某一家大模型服务方的SDK。代码看起来很简单创建客户端、填API Key、发请求、拿结果。可一旦业务要求支持第二家、第三家服务方麻烦就来了。每家服务方的请求体结构不同有的用顶层prompt字段有的用messages数组响应结构也不同有的返回choices数组有的返回别的结果字段鉴权方式更是五花八门有的用请求头带Key有的用查询参数。业务代码里很快就长满了这样的逻辑if provider company_a: payload build_payload_for_a(messages, temperature) elif provider company_b: payload build_payload_for_b(messages, temperature) else: raise NotImplementedError这种代码最大的问题不是丑是每次增删服务方都要动业务代码而且要重新测试、重新发布。更麻烦的是错误处理没法统一A公司限流返回的JSON和B公司限流返回的JSON完全不一样状态码也各有各的习惯排查问题的时候特别痛苦。1.2 litellm在整个架构里的位置litellm本质上是一个大模型API网关或者说是一个统一代理层。它的核心思路是业务代码只面向一套API接口所有上游大模型服务方的差异都由litellm在网关层处理掉。你在业务里只需要维护一个base_url指向litellm暴露出来的统一端点。业务继续用熟悉的对话补全接口格式发请求model字段传的是你在litellm里定义的别名比如company-a-chat、company-b-fast这种。litellm收到请求后会根据配置找到对应的上游服务方完成协议转换、鉴权注入、请求转发、响应转换最后把统一格式的结果返回给你的业务。这个架构很像支付网关的模式你在商城只对接一个支付接口后端是微信、支付宝还是银行卡商城不需要关心。litellm在AI应用里扮演的就是这个“支付网关”角色。1.3 适合谁用什么阶段引入最合适如果你属于下面几种情况litellm能带来的收益会非常明显业务同时对接多个大模型服务方比如正在做A/B效果对比或者要根据业务场景选不同的模型。需要对上游调用做统一管控预算、限流、密钥、日志都要集中管理。团队要隔离开发环境和生产环境不同环境走不同Key、不同预算、不同上游配置。做平台型系统需要给多个内部业务线发不同的虚拟密钥并统计各自用量。至于引入时机我个人的建议是只要出现了第二次对接模型的诉求就可以考虑上litellm。不要等到代码里写了五六套适配再动手那时候迁移成本反而高。2. 快速部署从零到一跑通一个代理服务2.1 环境准备与安装litellm的部署方式很灵活。它首先是Python包同时也提供了容器镜像可以跑在服务器、开发机、内网环境的任何角落。最基本的环境要求是Python 3.10及以上版本建议用一个干净的虚拟环境来装避免污染系统Python。安装命令是pip install litellm[proxy]这里要装带proxy的版本因为我们需要起一个网关服务而不只是用它的Python SDK能力。安装完成后终端里会多出一个litellm命令。我在本地和服务器上都装过流程是一致的。如果你主要在容器里跑可以直接用官方发布的Docker镜像配合docker-compose管理后面我会给一个生产化的配置。2.2 最小配置与启动litellm通过一个YAML配置文件来声明上游模型、路由策略、鉴权方式、缓存等。最小可用的配置大概长这样model_list: - model_name: company-a-chat litellm_params: model: company-a/chat-model-1 api_key: os.environ/COMPANY_A_API_KEY - model_name: company-b-chat litellm_params: model: company-b/chat-model-1 api_key: os.environ/COMPANY_B_API_KEY这里有两个关键点第一model_name是你对外暴露的别名业务代码里传的就是这个名字。好处是上游真实型号更换时只要改配置里的映射业务代码一行都不用动。第二model字段的写法是“服务方前缀/模型名”litellm靠这个前缀识别应该走哪个适配器。api_key可以通过os.environ/环境变量名的方式引用也可以直接写值但强烈建议用环境变量方式避免密钥写在配置文件里被提交到仓库。启动服务非常简单export COMPANY_A_API_KEYsk-xxx export LITELLM_MASTER_KEYsk-litellm-master-key litellm --config config.yaml --port 8000启动后litellm会在8000端口监听请求。2.3 业务侧的接入与验证跑通后业务侧接入几乎不用改代码。我用curl直接验证过代理是否正常工作curl http://localhost:8000/chat/completions \ -H Authorization: Bearer sk-litellm-master-key \ -H Content-Type: application/json \ -d { model: company-a-chat, messages: [{role: user, content: 你好}] }这个请求的格式和直接调用某一家的官方接口非常接近但model字段已经换成了我们自定义的别名。litellm会去查配置找到company-a-chat对应的上游服务方然后自动完成协议转换、鉴权注入和响应转换。如果你用的是Python也可以直接用官方的对话补全客户端把base_url指向litellm的地址密钥用主密钥或后面创建的虚拟密钥。这意味着原有的调用代码基本可以无缝迁移只需要调整base_url这一行。2.4 生产化部署的关键改动本地验证通过后别急着就上线生产环境至少要做这几件事设置主密钥。我见过不少人在本地跑起来就忘了设LITELLM_MASTER_KEY结果服务对完全没鉴权的请求也放行。生产环境必须设置主密钥并且用强随机值。所有管理端点都需要这个密钥才能访问。配置持久化数据库。默认情况下litellm把密钥、日志、用量信息放在本地SQLite里这对单机测试没问题但生产环境多副本部署时数据不一致。我建议至少接一个PostgreSQL把密钥、预算、日志落库。配置方式是在general_settings里增加database_urlgeneral_settings: database_url: os.environ/DATABASE_URL启用Redis做缓存和限流。如果有多实例部署Redis可以用来做统一的响应缓存和限流计数。没有Redis的话限流数据在单实例内有效水平扩容以后会失效。用容器编排管理。下面这个docker-compose是精简模板实际使用需要替换密钥、数据库地址和配置挂载路径services: litellm: image: litellm-proxy:latest ports: - 8000:8000 environment: LITELLM_MASTER_KEY: sk-litellm-master-key DATABASE_URL: postgresql://user:passwordpostgres:5432/litellm REDIS_HOST: redis volumes: - ./config.yaml:/app/config.yaml depends_on: - postgres - redis postgres: image: postgres:16 environment: POSTGRES_USER: user POSTGRES_PASSWORD: password POSTGRES_DB: litellm redis: image: redis:7提示生产环境不要把数据库密码直接写在compose文件里用环境变量或密钥管理工具注入。加一层反向代理。litellm本身可以处理请求但生产环境建议在前面加一层TLS终止比如用nginx或者云平台的负载均衡器把证书管理和流量入口收口。3. 核心能力拆解统一网关不只是转发请求3.1 出站适配器上游差异在网关层被消灭litellm最核心的机制就是出站适配器。每接入一个大模型服务方litellm都会提供对应的适配器它负责把统一的内部请求格式转换成该服务方期望的格式再把它返回的响应转换回统一格式。这意味着不管是文本对话、流式输出还是工具调用业务侧看到的始终是统一的接口结构。流式推送在这里是个容易忽略的点不同服务方的流式事件格式不一样有的字段名完全不同litellm帮我们把这些差异全部抹平了。我在项目里从非流式切换到流式时业务代码几乎没改只换了一个参数。这个设计带来的直接好处是你的业务代码可以长期稳定不跟着上游厂商的版本迭代走。上游改API了你只需要在网关层更新适配器或者调整配置。3.2 负载均衡与自动降级在config.yaml里可以把多个上游服务方映射到同一个对外别名。比如company-a-chat可以同时指向A公司的旗舰模型和B公司的轻量模型litellm会根据策略分配流量。常见的路由策略有这么几种策略行为说明简单轮询请求轮流发往不同上游适合无状态、无偏好场景加权轮询按权重分配流量适合大部分流量走主力模型、少量走备用模型最少连接动态选择当前负载最低的上游适合上游性能不均匀的场景故障切换上游连续失败时自动切换到备用模型我做跨平台系统的时候就把文本生成这个入口配了三个上游一个主力模型一个备用模型还有一个低成本的兜底模型。只要主力模型连续报错达到阈值litellm会自动把流量切到备用模型上业务方很多时候根本感知不到上游故障。这种容灾能力如果自己写代码实现要考虑健康检查、失败计数、冷却时间、切换后的恢复策略工作量不小。网关层直接提供等于省掉了一大块基础设施开发。3.3 密钥体系与预算控制多团队共用一套网关时密钥管理是刚需。litellm支持给不同项目、不同环境生成各自的虚拟密钥每一把密钥可以设置独立的预算上限和额度周期。比如我给某内部项目A发的虚拟密钥预算上限是每月1000元项目B是测试环境只给100元。某个密钥跑到上限以后litellm会直接拒绝使用该密钥的新请求而其他密钥不受影响。这个机制对企业支出管控的价值很大。以前团队各自拿上游厂商的API Key直接调用月底账单出来才知道花了多少现在每一笔消耗都能归因到具体密钥、具体项目。3.4 用量统计与缓存优化litellm会在请求日志里记录每次调用的token数量、模型、密钥、耗时并且可以估算出对应的成本。配合管理后台可以直接拉出“某个项目某一天在某个模型上花了多少钱”这种粒度非常细的数据。我实际用下来给财务对账提供了很大的便利不再需要自己在业务层埋点统计。缓存这块也值得一说。litellm支持把完全相同的请求响应缓存起来建议用Redis作为缓存后端。比如某些系统提示词加固定问题的高频请求命中缓存以后响应延迟从秒级降到毫秒级上游调用量也显著下降。注意使用缓存时要格外小心动态请求。人坐在那里手动测试还好线上系统如果带了用户ID、时间戳之类的动态内容缓存命中率很低意义不大。一定要给带随机参数的请求做好缓存隔离。4. 配置进阶把代理调教成适合自己业务的样子4.1 模型组、别名与路由策略我在上一个项目里把模型们组织成了三组文本主力组日常对话、总结、改写用效果最好的中大型模型。轻量快线组意图识别、分类、信息抽取用低成本模型。兜底降级组主力模型不可用时切换到的备选模型。在litellm里这三个组就是三条model_list配置。业务方在代码里传入的model字段分别是main-chat、fast-chat、fallback-chat这样的别名。这样业务团队根本不关心上游到底用的什么型号也不需要知道哪天换过型号。路由策略我选的是加权轮询加故障切换。主力组让80%流量走A公司旗舰模型20%走B公司同档模型既能压测对比又能分摊风险。model_list: - model_name: main-chat litellm_params: model: company-a/chat-model-large api_key: os.environ/COMPANY_A_API_KEY rpm: 300 - model_name: main-chat litellm_params: model: company-b/chat-model-large api_key: os.environ/COMPANY_B_API_KEY weight: 0.2 rpm: 1004.2 重试、超时与限流参数网关上配好重试和超时策略可以省掉很多运维精力。litellm支持对每个模型设置独立的请求超时时间、最大重试次数、每分钟请求数上限等。我遇到过这样的情况上游某个模型偶尔响应特别慢业务方请求超时以后直接报错给用户。后来我在litellm里把超时时间调大加上两次重试并且配了故障切换。即便某个上游实例不稳定用户侧也只是感觉到偶尔慢了一点而不是直接失败。从原理上说重试策略并不是无限重试。通常只在连接错误、超时、5xx这类可恢复错误上重试4xx这种业务错误重试没有意义。litellm在这一点上的处理比较符合预期错误分类做得比较细不会把鉴权失败也拿去重试浪费上游资源。4.3 管理接口与日常运维litellm自带一个管理后台可以通过 /ui 地址访问。在后台里可以查看请求日志、密钥列表、预算用量也可以创建新的虚拟密钥、配置上游路由。运维层面我建议重点看这四样东西请求成功率按小时维度看趋势突然下降通常意味着某个上游出了问题。平均响应耗时稳定上升说明上游过载可能需要调整路由权重或者扩容。预算消耗速度结合业务活动节奏判断异常飙高往往是某个项目密钥被滥用。错误码分布401、403、429分别对应鉴权、权限、限流问题快速定位方向。提示litellm的详细日志可以通过环境变量开启遇到线上诡异问题先打开debug日志看网关层是怎么转发的再判断问题是出在上游还是出在配置。5. 踩坑实录常见问题与排查思路5.1 鉴权类错误401、403我最初排查这类问题最多的原因就两个一是请求里没有带Bearer Token二是带的密钥不对或者已经被撤销。如果你用虚拟密钥还要注意这个密钥是否被创建在与当前环境匹配的项目里。有些团队会在网关上做环境隔离测试环境的虚拟密钥在生产环境是无效的。403还有一个常见原因是密钥的预算超限了litellm会拒绝继续服务这时候后台里看到的是权限拒绝而不是限流。遇到这类问题先看请求头里有没有Authorization字段再看后台密钥状态是否正常最后确认预算。排查路径很清晰不太会走弯路。5.2 限流类错误429429的本质是上游认为你请求太频繁。litellm层面可以做两件事一是给某个模型设置rpm/tpm限制从源头控制频率二是配置重试和降级让请求在遇到限流时自动转到另一个模型或稍后重试。我遇到过一种情况同一把虚拟密钥被多个业务模块共用其中一个模块的突发流量把配额打满导致其他模块也跟着限流。后来我把模块拆成不同的虚拟密钥各自设置配额互不干扰。重要经验限流不只是上游的事情。你自己配了缓存和限流以后网关层本身也会成为瓶颈单实例部署时尤其明显。有条件就提前规划多实例部署加Redis共享状态。5.3 超时与上游抖动线上出现超时先别急着骂上游。我用调试日志追踪过几次发现有的是配置里超时时间设得太短有的是重试策略没生效还有的是网关到上游的网络链路本身有延迟。处理顺序建议是确认是不是上游稳定性的问题看上游健康状态。调大request_timeout给慢模型留出余量。开启合理的重试策略并配置故障切换模型。如果上游持续恶化直接把路由权重切到健康的上游。这套流程下来绝大多数抖动都能被兜住。5.4 数据持久化与迁移问题从SQLite切到PostgreSQL时我第一次就吃了亏启动以后发现虚拟密钥全部消失日志也读不到。原因很简单数据库配置没生效litellm仍然在用本地文件。这类问题通过查看启动日志里的database信息就能确认。另外升级litellm版本时要记得对数据库做迁移。社区版迭代比较快升级前先看变更说明和迁移脚本别直接跳到新版本再回头处理数据问题。最后分享一点我自己的运维体会我在实际使用中发现litellm带来的最大改变不是省了写适配层的代码而是改变了团队的工作方式。“模型”从一个需要发版才能变更的硬依赖变成了一个改配置就能切换的软参数。业务方提需求说“想试另一家模型”我只需要在config.yaml里加一行映射刷新Key再观察后台的用量和延迟数据整个流程用不了一小时。如果你现在正处于多模型混用、代码里堆满适配逻辑的阶段我建议先花半小时把litellm跑起来亲手发一个请求看看再决定要不要深入集成。等真正把这层网关用起来你会发现后面很多问题都不再需要自己造轮子了。