维护过几个同时使用大模型API的项目之后我最深的体会是模型本身不是瓶颈模型的接入方式才是。今天接这家服务明天换那家模型每个平台的鉴权方式不一样、请求结构不一样、错误码含义不一样SDK风格也各不相同。业务代码里塞满了一家一家的适配逻辑换模型就像做一次小规模重构。后来我把所有模型的调用统一收敛到一个网关服务里团队内部只管调一个接口底层用哪个模型、怎么切流量、怎么记成本全部由网关负责。这个方案我选用的核心组件就是LiteLLM。这篇文章不打算写成官方文档的翻译。我会按自己的实践路径来讲先说明我为什么觉得需要这样一层统一入口再讲LiteLLM的工作原理是什么然后从零开始跑通逐步落到生产环境最后把我踩过的坑和一些进阶玩法一起分享出来。适合正在被多模型API接入折腾的开发者也适合想在团队里搭一个模型调用统一入口的同学参考。1. 为什么需要统一模型接口我的网关选型思路1.1 模型碎片化带来的日常麻烦先还原一下没有网关时的真实工作场景。假设一个项目里上线了智能客服功能最开始接了厂商A的对话模型。过了一段时间厂商B推出了效果更好的模型我们想切换过去对比效果。麻烦来了厂商A的请求体可能是messages数组 max_tokens厂商B可能是prompt字符串 max_length错误码含义也完全不同。为了切模型至少得改调用层、改参数映射、改错误处理还要在代码里维护两套SDK依赖。如果只是单模型替换还好。可怕的是同一个产品里同时用了聊天模型、向量模型、图片理解模型每类模型又有不同服务商。这种情况下业务代码里很快会长出大量if provider A: ... elif provider B: ...的分支。每次新接一家都要把所有分支遍历一遍。还有一个隐性问题密钥管理。多家服务商的API密钥散落在不同服务的环境变量里谁在用哪个密钥、每月花了多少钱基本靠Excel表格人工记录。账单出来之后对不上账排查成本极高。1.2 自研适配层与现成网关的取舍我第一反应是自己写一个适配层毕竟需求看起来不复杂统一鉴权、统一请求格式、统一输出结构。真动手才发现工作量不小——每个服务商都要写一套参数映射、错误码翻译、超时重试逻辑还要处理流式输出差异、并发限制、计费字段规范化。这些细节写起来少说也要一两千行而且后续服务商接口更新还得持续维护。于是我开始看现成方案。LiteLLM进入视线是因为它的思路和我的需求高度吻合对比维度自研适配层使用LiteLLM接入新服务商成本需要自己写一套映射逻辑已内置全部主流模型服务商参数统一自己定义一套业务方需要学习业界通用的消息结构迁移成本低密钥管理自己做配置中心配置文件和网关密钥统一托管成本统计与限额自己写账单采集自带花费记录、预算限制流式输出/重试/限流全部手写内置支持维护成本永远跟着上游接口变化走上游社区统一维护我的结论很明确这种通用能力没必要从零造轮子。团队真正需要花精力的是业务本身而不是维护一套到处是边角情况的适配代码。2. LiteLLM的核心原理SDK封装与网关服务2.1 两层架构各管什么LiteLLM有两种使用形态理解它们的差异是上手的关键。第一种是Python SDK形态。在代码里直接import litellm调用统一的litellm.completion或litellm.embedding方法底层由SDK负责把请求转发给对应厂商。这种方式适合单个服务内部使用改造成本低把原先调用具体SDK的代码换成LiteLLM的调用即可。第二种是网关服务形态。它启动一个独立服务对外暴露一套标准REST接口。业务系统不需要安装LiteLLM的Python包只要按标准格式发HTTP请求就行。所有模型请求经过网关统一转发、记录日志、控制费用。这种形态适合团队统一入口、多服务共享也是我在生产环境选择的方式。这两层本身就是同一个项目里的两套路线SDK适合嵌入型使用网关适合集中式管理。实际项目中不需要二选一可以先在代码里用SDK快速验证模型效果跑通之后再决定是否把流量收敛到网关。2.2 格式统一到底统一了什么LiteLLM做的最核心的一件事是把各家模型服务商的各种请求风格统一成一套业界通用的标准格式。输出侧也是同理。不管底层模型返回结构差异多大LiteLLM都会整理成统一的对象结构比如choices数组、message.content字段、usage统计。业务代码只需要面向这一套结构写逻辑不再关心底层响应长什么样。参数映射是这里最容易出问题的地方。不同服务商对同一个概念叫法不同比如控制随机性的参数某家叫temperature另一家可能直接忽略控制最大生成长度的参数有的叫max_tokens有的叫max_new_tokens。LiteLLM在中间做了大量兼容转换你在调用层写的是一套通用参数它会按目标服务商的要求做翻译。这里值得注意一个细节虽然入参统一但各家模型的能力边界不同。你传一个某模型不支持的参数LiteLLM不会替你屏蔽而是按目标服务商的实际接受范围去处理。所以做参数映射时还是要清楚底层模型支持哪些能力不能因为接口统一就忽视模型自身的限制。2.3 路由、重试与失败转移网关形态下LiteLLM不只是“转发请求”它还负责“决定把请求发给谁”。在配置里可以声明一组模型每个模型可以有自己的权重、优先级、最大并发等参数。请求进来后网关根据路由策略选择具体底层模型。常用策略包括简单轮询、按服务器负载选择、按成本选择等等。某个模型超时或者返回错误网关可以自动重试甚至临时把请求切换到备用模型上避免业务侧直接看到失败。我实际使用中最常用的是“主模型 备用模型”模式正常流量走主力模型主力模型不可用时自动切到备用模型。这种能力在业务侧完全无感知对线上稳定性帮助很大。3. 从零到一安装、最小调用与首次启动网关3.1 环境准备LiteLLM本质是Python项目建议准备一个干净的虚拟环境再安装。我本地的环境是Python 3.9以上版本虚拟环境使用venv管理。python -m venv litellm-env source litellm-env/bin/activate安装时我会直接带上网关相关的扩展依赖pip install litellm[proxy]如果你只需要在代码里调用SDK不打算跑网关服务装基础版就够pip install litellm装完之后可以用下面这行命令确认环境正常python -c import litellm; print(litellm.__version__)这里提醒一句我见过有人直接在全局环境里装结果和项目里其他依赖产生冲突尤其是pydantic、openai这类库的版本互相打架。建议从第一天就养成用虚拟环境的习惯。3.2 SDK方式的最小调用先看一个最简单的调用示例import litellm resp litellm.completion( modelyour-provider/your-model, messages[ {role: user, content: 你好请用一句话介绍自己} ], api_keyyour-api-key ) print(resp.choices[0].message.content)这里model参数的写法是服务商名/模型名的格式。LiteLLM靠这个拼接出来的前缀识别请求要发给谁然后自动套用对应的适配逻辑。api_key可以直接传也可以不传让它从环境变量里读。跑通这个示例意味着你已经会用SDK。实际业务里可以直接在项目里替换原有的模型调用代码把原先面向具体厂商SDK的调用改成面向LiteLLM的统一调用。3.3 网关服务的首次启动SDK用顺手之后网关模式基本没有额外学习成本。我习惯先用配置文件启动因为后续所有模型、密钥、限流配置都放在一个文件里方便维护。准备一个config.yamlmodel_list: - model_name: my-chat-model litellm_params: model: your-provider/your-model api_key: os.environ/LLM_PROVIDER_KEY general_settings: master_key: sk-your-gateway-master-key启动网关export LLM_PROVIDER_KEYyour-api-key litellm --config config.yaml --port 4000然后直接发一个请求验证curl -X POST http://localhost:4000/chat/completions \ -H Authorization: Bearer sk-your-gateway-master-key \ -H Content-Type: application/json \ -d { model: my-chat-model, messages: [{role: user, content: 你好}] }如果返回正常的响应数据说明网关已经跑通了。注意请求里的model传的是配置里自定义的model_name而不是底层实际的模型名。这个环节对外部调用方完全透明——他们只知道my-chat-model不需要关心底层是什么模型。3.4 两种方式怎么选我自己的经验是小项目、快速验证、单人开发优先用SDK几乎零运维成本多人团队、多个服务共享模型资源、需要控制成本和密钥集中管理直接上网关模式。网关模式还有一个容易被忽略的优势业务代码里不再需要安装各家模型服务的SDK依赖只要请求标准接口就行。这意味着语言栈也不再被锁死不管是Java、Go还是Python写的小工具都能通过同一个HTTP接口使用模型能力。4. 接入生产模型路由、密钥托管与成本限额的落地配置4.1 配置一个可用的多模型列表进入生产环境后配置文件不再像上面那样只有一个模型。我一般会同时配置主模型和备用模型并且用自定义名称做一层屏蔽model_list: - model_name: chat-main litellm_params: model: your-provider/model-a api_key: os.environ/PROVIDER_A_KEY rpm: 100 - model_name: chat-backup litellm_params: model: your-provider/model-b api_key: os.environ/PROVIDER_B_KEY - model_name: embedding-main litellm_params: model: your-provider/embedding-a api_key: os.environ/PROVIDER_A_KEY router_settings: routing_strategy: simple-shuffle fallbacks: [{chat-main: [chat-backup]}]这段配置的核心信息有三个第一model_name是业务侧看到的模型名。未来底层换模型只要改这里的映射业务代码完全不用动。第二rpm限制了每分钟请求数避免单模型被打爆。第三fallbacks配置了失败转移主模型不可用时自动把请求切换到备用模型。4.2 密钥托管设计密钥管理是网关对外提供的最重要价值之一。没有网关时每个业务服务的环境变量里都要配置各家模型服务商的API密钥。这些密钥通常直接绑定个人账号或团队账号权限边界模糊轮换密钥时需要到处改配置很容易遗漏。有了网关之后模型服务商的真实密钥只存在于网关配置里。业务侧访问网关只需要一个gateway key这个key可以按需生成做成只读或绑定具体预算。配合环境变量引用方式general_settings: master_key: os.environ/GATEWAY_MASTER_KEY database_url: postgresql://user:passwordlocalhost:5432/litellm_db这里把管理员密钥放到环境变量里避免明文写在配置文件中。database_url指向Postgres用来持久化调用日志和费用数据具体原因后面讲坑的时候会展开。4.3 成本追踪和限额控制成本控制是团队规模上来之后一定会碰到的需求。没有网关时各家平台的后台账单各看各的月底汇总全靠手工。用LiteLLM网关后每次请求的模型、输入token数、输出token数、费用都会被记录下来按团队、按项目、按key维度都能查。更实用的是预算设置。我通常会按团队划分预算某个团队一个月的模型调用费用到了上限网关直接拒绝新的请求避免“月底才发现超支”的尴尬。限速层面除了前面提到的每分钟请求数限制还可以设置每分钟token数限制。后者对成本控制更直接毕竟计费跟token关系更大。4.4 配置热加载与健康检查生产环境里配置改完不需要重启网关。LiteLLM支持配置热加载我改完配置文件后网关会自动读取新配置。这个特性对灰度调整权重非常有用后面第6章会细说。另外建议给网关配一个健康检查探活接口挂到基础设施的监控体系里。这个接口不仅能确认服务存活还能顺带检查各个底层模型的可达状态。曾经有一回厂商模型服务波动就是靠健康检查的异常提前发现了问题避免了用户侧的大面积报错。5. 我在真实环境里踩过的坑超时、流式与统计误差5.1 超时与重试的默认行为不是万能的第一次把网关接入线上时我天真地以为“内置重试”就够了结果当天就收到了业务方的超时告警。问题出在默认超时时间上。部分模型服务在高峰期的响应时间会明显变长尤其是长上下文场景首字延迟可能超过默认超时值。请求被提前判定为超时触发重试又因为重试请求同样处理很慢导致整体耗时翻倍甚至出现双重计费。后来我在配置里显式调整了超时时间并且只对确定性错误开启重试router_settings: timeout: 120 retry_policy: num_retries: 2 retry_on_timeout: false经验是不要无脑重试超时请求。模型服务超时往往说明它已经过载或网络链路不稳定这时候重试大概率还是失败反而放大了压力。我更倾向于把超时时间调到合理范围让请求有足够时间完成不做或少做超时重试。5.2 流式输出的异常处理另一个非常容易疏忽的点是流式输出。非流式模式下请求失败会返回一个明确的错误对象日志也好排查。但流式模式下错误可能在输出过程中才发生表现为流中途断开。业务侧如果对“流已经启动但突然中断”处理不当用户会看到一半内容后卡住体验非常差。我后来统一做了两件事第一在网关层对流式请求记录完整状态区分“正常结束”和“异常中断”第二业务侧对不完整流做兜底提示至少让用户知道内容生成异常而不是卡在原地。如果你刚开始用LiteLLM建议对流式输出的测试加大覆盖尤其是模型不可用时的表现否则很容易把线上问题留到用户投诉后才暴露。5.3 成本统计为什么对不上有一段时间我发现网关记录的费用和厂商后台查到的费用对不上相差还不小。排查后发现两个原因。第一个原因是配置里的模型名和厂商实际账单里的模型名不一致。当时我为了统一命名在配置里把多个模型都叫了同一个自定义名称结果网关记录时只能按这个统一名称记账但底层实际调用的模型不同单价也不同账单自然对不上。第二个原因是部分请求走了备用模型但备用模型的使用没有被单独归类而是并到了主模型的统计下面。解决方案是在配置里为每个实际模型单独建一条记录并给每条记录设置对应的单价。这样网关在记账时才能准确计算每条请求的花费。模型命名的规范程度直接决定了成本统计的准确性这点建议在一开始就约定好。5.4 并发上来之后数据库要先换掉我最初直接用默认的本地文件数据库存储日志和费用数据单机小流量用着没问题。后来流量涨上来发现网关的日志写入出现了明显的性能瓶颈偶尔还有锁冲突导致部分请求日志丢失。排查之后确认是默认的本地文件数据库并发写能力不足。LiteLLM官方在生产环境也是推荐使用Postgres这类独立数据库。我迁移到Postgres之后写入瓶颈问题彻底消失费用数据和调用日志也可以跨实例共享了。如果你的网关会部署多个实例或者打算做高可用这一步基本上绕不开。数据库选型和部署细节建议在搭建网关时就纳入规划而不是等出了问题再补。遇到的问题根因我的处理办法请求超时频繁默认超时设置偏短显式调整timeout关闭超时重试流式输出中断处理不当对流异常缺少兜底策略区分正常结束与异常中断业务侧加提示费用统计对不上模型命名不规范、单价未配置每个实际模型单独建记录并配置单价并发高时日志写入慢默认数据库并发能力不足生产环境迁移到Postgres6. 再进一步灰度切换、多租户与自定义回调6.1 流量灰度与模型切换网关模式让模型切换从“发版更新代码”变成了“动态调整配置”。新模型要上线时我先在配置里加一条新模型记录初始权重设为0不发流量。通过健康检查和手工测试确认没问题后把权重逐步调大比如先放5%的流量试跑观察错误率和生成质量再逐步加到10%、50%直到全量切换。这个过程不需要业务方配合改代码也不需要停机随时可以回滚。我实际用下来感觉这是模型灰度上线最舒服的一种方式。6.2 多租户隔离与预算分配团队内部不同业务线共用一个网关时多租户能力就派上用场了。我按业务线生成不同的gateway key每个key绑定一个团队标识可以单独设置预算上限和限速策略。某个业务线调用量异常增长时只会影响它自己的key不会拖累其他业务线。费用统计也天然分团队月底出账单时直接从网关后台拉数据就行再也不用重复对账。这里有一个小细节值得注意生成key时一定要把命名规范想清楚。比如用业务线-环境-用途的格式命名后期维护起来会省很多事。6.3 自定义回调与监控集成LiteLLM提供回调机制可以在请求成功或失败时把数据推送到自定义系统。我把回调接到团队自己的监控面板上这样一来模型调用的QPS、错误率、延迟分布、token消耗趋势都能和我们现有的运维看板整合在一起。下面的例子是自定义回调的基本思路import litellm from litellm.integrations.custom_logger import CustomLogger class MyMonitor(CustomLogger): async def log_success_event(self, kwargs, response_obj, start_time, end_time): # 这里把请求时间、模型名、token数写入自己的监控系统 pass async def log_failure_event(self, kwargs, response_obj, start_time, end_time): # 这里处理异常请求的采集 pass litellm.callbacks [MyMonitor()]回调能力看着不起眼但在生产环境里几乎是刚需。没有统一监控的话网关就像一个黑盒出了问题只能靠用户反馈才后知后觉。最后再分享一个我个人的使用体会。LiteLLM这类模型网关工具最值得投入时间的地方不是安装配置而是把路由策略、成本模型和监控体系一次想清楚。这些东西越早定好后面模型迭代、服务商切换、预算管控就越省力。如果你正被多模型接入搞得焦头烂额不妨先花半天时间把网关搭起来把调用集中到一个入口再慢慢丰富策略。多数情况下这一步的投入回报比会远超预期。 
长河君 · 2026/10/13 5:20:10 · 阅读 1.2k 用LiteLLM构建大模型网关：统一接口、路由与成本管理实战
维护过几个同时使用大模型API的项目之后我最深的体会是模型本身不是瓶颈模型的接入方式才是。今天接这家服务明天换那家模型每个平台的鉴权方式不一样、请求结构不一样、错误码含义不一样SDK风格也各不相同。业务代码里塞满了一家一家的适配逻辑换模型就像做一次小规模重构。后来我把所有模型的调用统一收敛到一个网关服务里团队内部只管调一个接口底层用哪个模型、怎么切流量、怎么记成本全部由网关负责。这个方案我选用的核心组件就是LiteLLM。这篇文章不打算写成官方文档的翻译。我会按自己的实践路径来讲先说明我为什么觉得需要这样一层统一入口再讲LiteLLM的工作原理是什么然后从零开始跑通逐步落到生产环境最后把我踩过的坑和一些进阶玩法一起分享出来。适合正在被多模型API接入折腾的开发者也适合想在团队里搭一个模型调用统一入口的同学参考。1. 为什么需要统一模型接口我的网关选型思路1.1 模型碎片化带来的日常麻烦先还原一下没有网关时的真实工作场景。假设一个项目里上线了智能客服功能最开始接了厂商A的对话模型。过了一段时间厂商B推出了效果更好的模型我们想切换过去对比效果。麻烦来了厂商A的请求体可能是messages数组 max_tokens厂商B可能是prompt字符串 max_length错误码含义也完全不同。为了切模型至少得改调用层、改参数映射、改错误处理还要在代码里维护两套SDK依赖。如果只是单模型替换还好。可怕的是同一个产品里同时用了聊天模型、向量模型、图片理解模型每类模型又有不同服务商。这种情况下业务代码里很快会长出大量if provider A: ... elif provider B: ...的分支。每次新接一家都要把所有分支遍历一遍。还有一个隐性问题密钥管理。多家服务商的API密钥散落在不同服务的环境变量里谁在用哪个密钥、每月花了多少钱基本靠Excel表格人工记录。账单出来之后对不上账排查成本极高。1.2 自研适配层与现成网关的取舍我第一反应是自己写一个适配层毕竟需求看起来不复杂统一鉴权、统一请求格式、统一输出结构。真动手才发现工作量不小——每个服务商都要写一套参数映射、错误码翻译、超时重试逻辑还要处理流式输出差异、并发限制、计费字段规范化。这些细节写起来少说也要一两千行而且后续服务商接口更新还得持续维护。于是我开始看现成方案。LiteLLM进入视线是因为它的思路和我的需求高度吻合对比维度自研适配层使用LiteLLM接入新服务商成本需要自己写一套映射逻辑已内置全部主流模型服务商参数统一自己定义一套业务方需要学习业界通用的消息结构迁移成本低密钥管理自己做配置中心配置文件和网关密钥统一托管成本统计与限额自己写账单采集自带花费记录、预算限制流式输出/重试/限流全部手写内置支持维护成本永远跟着上游接口变化走上游社区统一维护我的结论很明确这种通用能力没必要从零造轮子。团队真正需要花精力的是业务本身而不是维护一套到处是边角情况的适配代码。2. LiteLLM的核心原理SDK封装与网关服务2.1 两层架构各管什么LiteLLM有两种使用形态理解它们的差异是上手的关键。第一种是Python SDK形态。在代码里直接import litellm调用统一的litellm.completion或litellm.embedding方法底层由SDK负责把请求转发给对应厂商。这种方式适合单个服务内部使用改造成本低把原先调用具体SDK的代码换成LiteLLM的调用即可。第二种是网关服务形态。它启动一个独立服务对外暴露一套标准REST接口。业务系统不需要安装LiteLLM的Python包只要按标准格式发HTTP请求就行。所有模型请求经过网关统一转发、记录日志、控制费用。这种形态适合团队统一入口、多服务共享也是我在生产环境选择的方式。这两层本身就是同一个项目里的两套路线SDK适合嵌入型使用网关适合集中式管理。实际项目中不需要二选一可以先在代码里用SDK快速验证模型效果跑通之后再决定是否把流量收敛到网关。2.2 格式统一到底统一了什么LiteLLM做的最核心的一件事是把各家模型服务商的各种请求风格统一成一套业界通用的标准格式。输出侧也是同理。不管底层模型返回结构差异多大LiteLLM都会整理成统一的对象结构比如choices数组、message.content字段、usage统计。业务代码只需要面向这一套结构写逻辑不再关心底层响应长什么样。参数映射是这里最容易出问题的地方。不同服务商对同一个概念叫法不同比如控制随机性的参数某家叫temperature另一家可能直接忽略控制最大生成长度的参数有的叫max_tokens有的叫max_new_tokens。LiteLLM在中间做了大量兼容转换你在调用层写的是一套通用参数它会按目标服务商的要求做翻译。这里值得注意一个细节虽然入参统一但各家模型的能力边界不同。你传一个某模型不支持的参数LiteLLM不会替你屏蔽而是按目标服务商的实际接受范围去处理。所以做参数映射时还是要清楚底层模型支持哪些能力不能因为接口统一就忽视模型自身的限制。2.3 路由、重试与失败转移网关形态下LiteLLM不只是“转发请求”它还负责“决定把请求发给谁”。在配置里可以声明一组模型每个模型可以有自己的权重、优先级、最大并发等参数。请求进来后网关根据路由策略选择具体底层模型。常用策略包括简单轮询、按服务器负载选择、按成本选择等等。某个模型超时或者返回错误网关可以自动重试甚至临时把请求切换到备用模型上避免业务侧直接看到失败。我实际使用中最常用的是“主模型 备用模型”模式正常流量走主力模型主力模型不可用时自动切到备用模型。这种能力在业务侧完全无感知对线上稳定性帮助很大。3. 从零到一安装、最小调用与首次启动网关3.1 环境准备LiteLLM本质是Python项目建议准备一个干净的虚拟环境再安装。我本地的环境是Python 3.9以上版本虚拟环境使用venv管理。python -m venv litellm-env source litellm-env/bin/activate安装时我会直接带上网关相关的扩展依赖pip install litellm[proxy]如果你只需要在代码里调用SDK不打算跑网关服务装基础版就够pip install litellm装完之后可以用下面这行命令确认环境正常python -c import litellm; print(litellm.__version__)这里提醒一句我见过有人直接在全局环境里装结果和项目里其他依赖产生冲突尤其是pydantic、openai这类库的版本互相打架。建议从第一天就养成用虚拟环境的习惯。3.2 SDK方式的最小调用先看一个最简单的调用示例import litellm resp litellm.completion( modelyour-provider/your-model, messages[ {role: user, content: 你好请用一句话介绍自己} ], api_keyyour-api-key ) print(resp.choices[0].message.content)这里model参数的写法是服务商名/模型名的格式。LiteLLM靠这个拼接出来的前缀识别请求要发给谁然后自动套用对应的适配逻辑。api_key可以直接传也可以不传让它从环境变量里读。跑通这个示例意味着你已经会用SDK。实际业务里可以直接在项目里替换原有的模型调用代码把原先面向具体厂商SDK的调用改成面向LiteLLM的统一调用。3.3 网关服务的首次启动SDK用顺手之后网关模式基本没有额外学习成本。我习惯先用配置文件启动因为后续所有模型、密钥、限流配置都放在一个文件里方便维护。准备一个config.yamlmodel_list: - model_name: my-chat-model litellm_params: model: your-provider/your-model api_key: os.environ/LLM_PROVIDER_KEY general_settings: master_key: sk-your-gateway-master-key启动网关export LLM_PROVIDER_KEYyour-api-key litellm --config config.yaml --port 4000然后直接发一个请求验证curl -X POST http://localhost:4000/chat/completions \ -H Authorization: Bearer sk-your-gateway-master-key \ -H Content-Type: application/json \ -d { model: my-chat-model, messages: [{role: user, content: 你好}] }如果返回正常的响应数据说明网关已经跑通了。注意请求里的model传的是配置里自定义的model_name而不是底层实际的模型名。这个环节对外部调用方完全透明——他们只知道my-chat-model不需要关心底层是什么模型。3.4 两种方式怎么选我自己的经验是小项目、快速验证、单人开发优先用SDK几乎零运维成本多人团队、多个服务共享模型资源、需要控制成本和密钥集中管理直接上网关模式。网关模式还有一个容易被忽略的优势业务代码里不再需要安装各家模型服务的SDK依赖只要请求标准接口就行。这意味着语言栈也不再被锁死不管是Java、Go还是Python写的小工具都能通过同一个HTTP接口使用模型能力。4. 接入生产模型路由、密钥托管与成本限额的落地配置4.1 配置一个可用的多模型列表进入生产环境后配置文件不再像上面那样只有一个模型。我一般会同时配置主模型和备用模型并且用自定义名称做一层屏蔽model_list: - model_name: chat-main litellm_params: model: your-provider/model-a api_key: os.environ/PROVIDER_A_KEY rpm: 100 - model_name: chat-backup litellm_params: model: your-provider/model-b api_key: os.environ/PROVIDER_B_KEY - model_name: embedding-main litellm_params: model: your-provider/embedding-a api_key: os.environ/PROVIDER_A_KEY router_settings: routing_strategy: simple-shuffle fallbacks: [{chat-main: [chat-backup]}]这段配置的核心信息有三个第一model_name是业务侧看到的模型名。未来底层换模型只要改这里的映射业务代码完全不用动。第二rpm限制了每分钟请求数避免单模型被打爆。第三fallbacks配置了失败转移主模型不可用时自动把请求切换到备用模型。4.2 密钥托管设计密钥管理是网关对外提供的最重要价值之一。没有网关时每个业务服务的环境变量里都要配置各家模型服务商的API密钥。这些密钥通常直接绑定个人账号或团队账号权限边界模糊轮换密钥时需要到处改配置很容易遗漏。有了网关之后模型服务商的真实密钥只存在于网关配置里。业务侧访问网关只需要一个gateway key这个key可以按需生成做成只读或绑定具体预算。配合环境变量引用方式general_settings: master_key: os.environ/GATEWAY_MASTER_KEY database_url: postgresql://user:passwordlocalhost:5432/litellm_db这里把管理员密钥放到环境变量里避免明文写在配置文件中。database_url指向Postgres用来持久化调用日志和费用数据具体原因后面讲坑的时候会展开。4.3 成本追踪和限额控制成本控制是团队规模上来之后一定会碰到的需求。没有网关时各家平台的后台账单各看各的月底汇总全靠手工。用LiteLLM网关后每次请求的模型、输入token数、输出token数、费用都会被记录下来按团队、按项目、按key维度都能查。更实用的是预算设置。我通常会按团队划分预算某个团队一个月的模型调用费用到了上限网关直接拒绝新的请求避免“月底才发现超支”的尴尬。限速层面除了前面提到的每分钟请求数限制还可以设置每分钟token数限制。后者对成本控制更直接毕竟计费跟token关系更大。4.4 配置热加载与健康检查生产环境里配置改完不需要重启网关。LiteLLM支持配置热加载我改完配置文件后网关会自动读取新配置。这个特性对灰度调整权重非常有用后面第6章会细说。另外建议给网关配一个健康检查探活接口挂到基础设施的监控体系里。这个接口不仅能确认服务存活还能顺带检查各个底层模型的可达状态。曾经有一回厂商模型服务波动就是靠健康检查的异常提前发现了问题避免了用户侧的大面积报错。5. 我在真实环境里踩过的坑超时、流式与统计误差5.1 超时与重试的默认行为不是万能的第一次把网关接入线上时我天真地以为“内置重试”就够了结果当天就收到了业务方的超时告警。问题出在默认超时时间上。部分模型服务在高峰期的响应时间会明显变长尤其是长上下文场景首字延迟可能超过默认超时值。请求被提前判定为超时触发重试又因为重试请求同样处理很慢导致整体耗时翻倍甚至出现双重计费。后来我在配置里显式调整了超时时间并且只对确定性错误开启重试router_settings: timeout: 120 retry_policy: num_retries: 2 retry_on_timeout: false经验是不要无脑重试超时请求。模型服务超时往往说明它已经过载或网络链路不稳定这时候重试大概率还是失败反而放大了压力。我更倾向于把超时时间调到合理范围让请求有足够时间完成不做或少做超时重试。5.2 流式输出的异常处理另一个非常容易疏忽的点是流式输出。非流式模式下请求失败会返回一个明确的错误对象日志也好排查。但流式模式下错误可能在输出过程中才发生表现为流中途断开。业务侧如果对“流已经启动但突然中断”处理不当用户会看到一半内容后卡住体验非常差。我后来统一做了两件事第一在网关层对流式请求记录完整状态区分“正常结束”和“异常中断”第二业务侧对不完整流做兜底提示至少让用户知道内容生成异常而不是卡在原地。如果你刚开始用LiteLLM建议对流式输出的测试加大覆盖尤其是模型不可用时的表现否则很容易把线上问题留到用户投诉后才暴露。5.3 成本统计为什么对不上有一段时间我发现网关记录的费用和厂商后台查到的费用对不上相差还不小。排查后发现两个原因。第一个原因是配置里的模型名和厂商实际账单里的模型名不一致。当时我为了统一命名在配置里把多个模型都叫了同一个自定义名称结果网关记录时只能按这个统一名称记账但底层实际调用的模型不同单价也不同账单自然对不上。第二个原因是部分请求走了备用模型但备用模型的使用没有被单独归类而是并到了主模型的统计下面。解决方案是在配置里为每个实际模型单独建一条记录并给每条记录设置对应的单价。这样网关在记账时才能准确计算每条请求的花费。模型命名的规范程度直接决定了成本统计的准确性这点建议在一开始就约定好。5.4 并发上来之后数据库要先换掉我最初直接用默认的本地文件数据库存储日志和费用数据单机小流量用着没问题。后来流量涨上来发现网关的日志写入出现了明显的性能瓶颈偶尔还有锁冲突导致部分请求日志丢失。排查之后确认是默认的本地文件数据库并发写能力不足。LiteLLM官方在生产环境也是推荐使用Postgres这类独立数据库。我迁移到Postgres之后写入瓶颈问题彻底消失费用数据和调用日志也可以跨实例共享了。如果你的网关会部署多个实例或者打算做高可用这一步基本上绕不开。数据库选型和部署细节建议在搭建网关时就纳入规划而不是等出了问题再补。遇到的问题根因我的处理办法请求超时频繁默认超时设置偏短显式调整timeout关闭超时重试流式输出中断处理不当对流异常缺少兜底策略区分正常结束与异常中断业务侧加提示费用统计对不上模型命名不规范、单价未配置每个实际模型单独建记录并配置单价并发高时日志写入慢默认数据库并发能力不足生产环境迁移到Postgres6. 再进一步灰度切换、多租户与自定义回调6.1 流量灰度与模型切换网关模式让模型切换从“发版更新代码”变成了“动态调整配置”。新模型要上线时我先在配置里加一条新模型记录初始权重设为0不发流量。通过健康检查和手工测试确认没问题后把权重逐步调大比如先放5%的流量试跑观察错误率和生成质量再逐步加到10%、50%直到全量切换。这个过程不需要业务方配合改代码也不需要停机随时可以回滚。我实际用下来感觉这是模型灰度上线最舒服的一种方式。6.2 多租户隔离与预算分配团队内部不同业务线共用一个网关时多租户能力就派上用场了。我按业务线生成不同的gateway key每个key绑定一个团队标识可以单独设置预算上限和限速策略。某个业务线调用量异常增长时只会影响它自己的key不会拖累其他业务线。费用统计也天然分团队月底出账单时直接从网关后台拉数据就行再也不用重复对账。这里有一个小细节值得注意生成key时一定要把命名规范想清楚。比如用业务线-环境-用途的格式命名后期维护起来会省很多事。6.3 自定义回调与监控集成LiteLLM提供回调机制可以在请求成功或失败时把数据推送到自定义系统。我把回调接到团队自己的监控面板上这样一来模型调用的QPS、错误率、延迟分布、token消耗趋势都能和我们现有的运维看板整合在一起。下面的例子是自定义回调的基本思路import litellm from litellm.integrations.custom_logger import CustomLogger class MyMonitor(CustomLogger): async def log_success_event(self, kwargs, response_obj, start_time, end_time): # 这里把请求时间、模型名、token数写入自己的监控系统 pass async def log_failure_event(self, kwargs, response_obj, start_time, end_time): # 这里处理异常请求的采集 pass litellm.callbacks [MyMonitor()]回调能力看着不起眼但在生产环境里几乎是刚需。没有统一监控的话网关就像一个黑盒出了问题只能靠用户反馈才后知后觉。最后再分享一个我个人的使用体会。LiteLLM这类模型网关工具最值得投入时间的地方不是安装配置而是把路由策略、成本模型和监控体系一次想清楚。这些东西越早定好后面模型迭代、服务商切换、预算管控就越省力。如果你正被多模型接入搞得焦头烂额不妨先花半天时间把网关搭起来把调用集中到一个入口再慢慢丰富策略。多数情况下这一步的投入回报比会远超预期。