作为一个天天跟各种大模型接口打交道的开发者我第一次见到“litellm”这个名字时还以为是又一个什么轻量级的小工具库。真正用进去之后才发现这玩意儿对我的工作方式的改变远比想象中大得多。如果你也经历过那种“同一个需求、七八套API格式”的酸爽写代码时在不同服务商的SDK之间来回横跳解析结构完全不同的响应体那这篇文章就是给你写的。litellm做的事非常简单却又非常关键把市面上几乎所有主流大模型的API调用方式统一成一套最通用的标准。你可以用完全一样的Python代码只改一个模型名字符串就能在GPT、Claude、Llama之间无缝切换你还可以把它跑成一个独立的代理服务部署在你们团队的API网关位置统一管理所有模型的调用、限额、成本、日志。这篇文章我会从“为什么需要它”开始一步步讲到单点调用、代理模式、虚拟密钥和预算控制最后附上我在实际部署中踩过的一堆坑。1. 为什么大家都在用一个统一的模型网关1.1 模型API碎片化带来的日常崩溃先聊一下我自己的真实场景。我之前在某个数据团队做内部工具功能很简单根据用户输入生成一段结构化信息。最开始用的是某家闭源模型它的SDK封装得不错代码写起来挺顺。后来领导说要对比测试另一家模型看看效果哪个好我当时想都没想以为只是改改API地址的事。结果一上手才发现完全不是这么回事。第二家模型的请求体结构跟第一家的差异极其明显连最基础的字段命名都不一致流式输出的格式更是天差地别。第三方模型的响应体里没有现成的“content”字段而是嵌套在好几层里。我整整花了两天时间写了一堆适配代码才让同一套业务逻辑能跑在两个模型上。后来这个项目越做越大陆续要接开源的、自部署的、国内厂商的模型我意识到一个严重的问题每加一个模型我就要多维护一套适配层。业务逻辑本身没什么变化但大量的时间都花在“翻译”不同的API格式上。更麻烦的是不同服务商的SDK版本还在频繁更新动不动就破坏我的代码。这种“模型通胀”带来的维护成本已经快压过模型本身带来的收益了。1.2 litellm到底做了什么后来我接触到了litellm第一反应是这不就是我需要的那个“翻译层”吗。它的核心思路非常简单粗暴统一用OpenAI风格的接口格式由litellm在底层自动把请求转换成各家模型服务商要求的格式再把返回的响应统一成OpenAI格式。你可以理解为它就是一个“万能插座转换器”。你家电器插头是国标但墙上的插座可能是美标、欧标、英标转换器帮你把电压、插脚形状统统适配好。你只需要关心电器本身永远不用在意身后那面墙上是什么规格的插座。这个库用起来也异常简单装好之后直接调用from litellm import completion response completion( modelgpt-4o, messages[{role: user, content: 你好介绍一下自己}] ) print(response[choices][0][message][content])关键点来了当我想换成某款口碑不错的另一家闭源模型时只需要改一行response completion( modelclaude-sonnet-20241022, messages[{role: user, content: 你好介绍一下自己}] )代码结构几乎没动响应解析逻辑也可以沿用。这个体验真的太舒服了相当于你学会了手波现在开什么车都是一样的操作逻辑不管引擎盖底下是几缸发动机。2. 先从单点调用开始一行代码切换模型2.1 安装和最简单的completion调用litellm是纯Python包安装起来没什么坑pip install litellm装完之后最基础的使用方式就是一个函数搞定一次对话补全。但你千万别小看这个简单的调用背后处理的事情真的不少。不同模型要求不同的鉴权方式有的需要放在Header里用指定前缀有的要放在query参数里这些细节litellm全都替你处理了。对于API Key的传递我一开始也很懵不知道key该放在哪里。官方给了几种方式最省事的做法是设置环境变量export OPENAI_API_KEYsk-... export ANTHROPIC_API_KEYsk-ant-... export GEMINI_API_KEY...设置好之后直接调用completion什么都不用传litellm会自动从环境变量里找对应的模型厂商Key。如果你不想用环境变量也可以在调用时显式传参response completion( modelgpt-4o, messages[{role: user, content: hello}], api_keysk-xxx )不过我建议在真实的项目里还是走环境变量或配置管理平台把密钥跟代码隔离尤其是在多人协作的仓库里硬编码API Key迟早会被不小心推上去。异步调用同样支持写法跟同步很像from litellm import acompletion async def test(): response await acompletion( modelgpt-4o, messages[{role: user, content: hello}], ) print(response[choices][0][message][content])我建议高并发的Python服务都优先用异步同样的资源能压榨出更高的吞吐量。litellm对异步的支持比较成熟不是那种包一层线程池的伪异步所以可以放心使用。2.2 参数映射和模型别名的坑点用了一段时间之后我发现虽然调用方统一了格式但不同模型之间的参数语义还是有细微差异。比如max_tokens这个参数大部分服务商都认识可有一两家更偏爱max_completion_tokens如果你不管不顾地只传max_tokens它也能正常工作因为litellm会做一层参数翻译。再比如temperature对方为0到2某家开源模型要求0到1你传个1.5可能不报错但行为会变得非常奇怪。在遇到这类参数越界问题的时候litellm会尽力帮你做clip处理但有些情况下它无能为力还是需要使用者自己对目标模型的参数范围有个大致认知。还有一个非常实用的特性是模型别名。你可以把一串复杂的模型名映射成一个简单易懂的别名import litellm litellm.model_alias_map { main: gpt-4o, fast: claude-sonnet-20241022, local: ollama/llama3 }这样业务代码里只用main、fast这样的业务语义名称底层用哪个模型完全由配置来决定。万一哪天觉得某个模型不好直接把映射关系改掉就能全局切换业务代码一行都不需要动。这个机制在多人协作和实验对比场景下非常实用A/B测试的时候尤其香。但这里有个点必须提醒不同模型的response结构虽然被统一成了OpenAI格式但细节字段的完整性还是略有差异。比如有的模型支持返回token用量明细有的则没有如果你写代码时强依赖某些特定字段还是要先在真实模型上跑一把确认。这个不是litellm的bug而是模型本身的差异它最多只能做到尽可能兼容。3. 进阶玩法把litellm跑成团队网关3.1 配置文件model_list是核心单点调用只是开胃菜litellm真正让我觉得“这工具是认真做的”的地方是它的Proxy Server模式。说人话就是你单独起一个litellm服务所有人都去访问这个服务再由它来转发到各种大模型服务商。这样一来你的团队项目里不再需要每个人自己折腾API Key和SDK而是统一通过这个代理网关访问模型。这个模式下的灵魂是config.yaml配置文件。我第一次看到它的model_list结构时觉得很简单真正配过之后发现这里面的门道还挺多。一个典型的最小配置长这样model_list: - model_name: gpt-4o litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude-sonnet litellm_params: model: claude-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY - model_name: llama3 litellm_params: model: ollama/llama3 api_base: http://localhost:11434启动脚本很简单一行命令litellm --config config.yaml --port 8000网关跑起来之后客户端接入方式就跟调用OpenAI一样用任何支持OpenAI格式的SDK就行。我用Python的openai包测过from openai import OpenAI client OpenAI( base_urlhttp://localhost:8000/v1, api_key任意字符串网关会自己校验 ) resp client.chat.completions.create( modelclaude-sonnet, messages[{role: user, content: 你好}], ) print(resp.choices[0].message.content)注意上面这个model字段传的是claude-sonnet这个字符串是你在config.yaml里定义的别名不是真实的模型名。网关会找到对应配置再去请求真正的模型。这就回到了我们之前在别名机制里说的业务侧只认别名底层可以随便换。3.2 负载均衡与自动降级如果你在model_list里给同一个别名配置了多个模型就自动获得了负载均衡和故障转移能力。这个特性我非常喜欢拿它做一个简单的容灾架构model_list: - model_name: gpt-4o litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY rpm: 1000 - model_name: gpt-4o litellm_params: model: claude-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY rpm: 500 - model_name: gpt-4o litellm_params: model: ollama/llama3 api_base: http://localhost:11434这样配置之后客户端依然只会用“gpt-4o”这个名字来发请求但网关会在三家服务商之间做流量分配请求量大的时候甚至会使用你本地部署的Llama来做兜底。当其中一家服务商返错或者响应超时litellm会自动帮你尝试下一个候选模型。体验下来这个机制很可靠我故意掐断其中一个API Key来测试客户端几乎感知不到失败。这里要夸一下litellm的路由策略设计。它内置了好几种路由算法默认的simple策略是简单的轮询如果你希望按模型实际负载来做更聪明的分配可以改用usage-based-routingrouter_settings: routing_strategy: usage-based-routing这个策略会依据最近一段时间的请求量和token消耗情况做动态分配有效避免某个模型被压垮而另一个模型闲置的情况。不过启动后要跑一段时间等统计窗口积累了数据才比较准确刚部署那会儿跟默认策略差别不大。3.3 长文本输入和流式输出的代理实现团队网关场景还有一个容易被忽视的点流式输出。很多客户端都期望SSE流式响应像打字机一样逐字返回。litellm对streamTrue的支持做得不错只要你调用时传入stream参数它就会把底层模型的流式响应原样转发给客户端。不过这里要提醒一下不同模型的流式事件格式不一样litellm会统一成OpenAI的chunk格式但某些边缘字段比如usage统计有可能仅在最后一个chunk里带出来。前端如果依赖这个做token统计一定要用真实环境测一把。另外一个很实用的功能是prompt格式转换。各家的system prompt、few-shot示例在底层格式有区别但litellm代理会自动做转换。比如某模型的系统消息不支持独立的system角色litellm会帮你把system内容折叠进第一条user消息里。这类细节看着不起眼真对接起来会发现省了太多工作量。4. 团队网关的安全与预算管理4.1 虚拟密钥和统一认证网关部署好之后摆在面前的下一个问题就是怎么让团队其他人安全地使用这个网关。你不能把各个模型服务商的原生API Key直接给每个开发那样既无法追踪每个Key的花费又存在泄露风险。litellm提供了一套虚拟密钥机制思路类似给你发了一个“代币”所有人用的都是网关生成的新密钥网关内部再映射到真实模型厂商的Key。用API的方式可以快速生成curl -X POST http://localhost:8000/key/generate \ -H Authorization: Bearer sk-master-key \ -H Content-Type: application/json \ -d { models: [gpt-4o], max_budget: 50, expires: 2025-12-31 }生成的虚拟密钥长这样sk-xxxxx。客户端把它当普通OpenAI Key用就行但它的有效范围完全由你掌控。你可以给测试组发一个限额50美元的Key给线上服务发一个没有额度的Key还可以设置60天有效期。所有人都不知道自己背后真正调的是哪家模型也不知道原来服务商的Key长什么样。我自己比较喜欢的用法是把虚拟密钥按“项目”和“环境”双维度切分。比如为某个业务线的预售环境生成一个单独的Key预算调低同时把可访问的模型限制在便宜的那几款到正式发布时用另一个Key预算不设限但把模型列表调整成生产级的高质量模型。这样业务团队不需要感知网关策略的细节做不做得到全看密钥的配置。4.2 预算与速率限制配置详解预算控制是网关场景里最容易被忽略但又最重要的功能。大模型接口不像传统API它的收费跟token数额强相关一个死循环的请求逻辑几分钟就能烧掉几十美元。没有预算限制的模型网关等于在裸奔。litellm提供了一个比较完善的分层预算控制体系。最基本的是在虚拟密钥创建时指定max_budget单位是美元。当这个Key的累计消耗触顶后后续请求会直接被拒绝返回一个预算超限的错误。你还可以对每个模型设置速率限制。比如某个模型本身价格很高又特别慢你希望它每分钟最多被调用50次可以在配置里写model_list: - model_name: gpt-4o litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY model_info: mode: completion rpm: 100 tpm: 10000rpm控制每分钟请求次数tpm控制每分钟token的消耗总量。加上这层限制以后就不怕某个团队的上线活动把整个模型的额度给冲垮了其他团队的业务不会受到拖累。实际测试中我发现预算限制的生效并不是精确到request级别的它有一定的同步延迟如果你设置了每天50美元的限额实际消耗可能会跑到50出头甚至更多。放在生产环境下我会建议把预算上限设成目标值的80%给系统留出缓冲空间。4.3 日志审计和成本追踪团队网关的另一个隐藏好处是所有模型请求都会经过网关这意味着你可以在这个位置记录下所有的调用日志和token用量。litellm会在本地维护一份日志数据你随时可以查某个Key、某个模型在某个时间段内花了多少钱。如果你有合规要求建议把日志也对接到自己已有的监控系统。litellm本身提供了一些可观测性接口也可以把数据同步给外部日志平台。不要把日志只存在本地文件因为网关前面就是所有业务线的流量入口日志量上来之后本地文件很快会被冲掉。我现在的习惯是配置好日志导出并用一套简单的看板来观察模型成本趋势每个月各团队消耗一目了然。出现费用异常波动时也能按Key维度去定位到底是谁在疯狂调用。另外我建议给重要请求加个metadata参数。litellm允许在调用时附带一个可选的metadata对象比如放上用户的ID之后在日志里就能按用户维度追踪。这个功能在客服场景下特别有效比如某个用户反馈响应太慢或者内容不对你可以通过他ID精确锁定到具体的那条请求记录查看它用的是哪个模型、处理的耗时多长、上下文中包含什么内容而不至于淹没在茫茫日志里。5. 几个高频问题和我的排查记录5.1 环境变量冲突导致的“模型错乱”这是我第一个在项目里遇到的坑也最值得说。我同时配置了OpenAI和Anthropic两家的环境变量当时只是想在代码里快速对比两个模型于是写了两个脚本一个传gpt-4o一个传claude-sonnet。诡异的是跑出来之后两个请求都返回了同样的结果而且速度完全一致。后来我仔细检查才发现是因为两个环境变量里的Key都暴露了而litellm在某种情况下会用同一套Key去请求不同的服务商。正确的做法是在调用时用api_key参数显式指定或者确保环境变量具备明确的隔离。这里我也建议团队在封装SDK的时候强制显式传递密钥来源而不是依赖全局环境变量否则出问题的时候排查起来特别痛苦。5.2 长文本输出时的超时问题代理模式下跑一些长文档生成任务客户端的等待时间一长网关就会报超时。一开始我以为是模型响应慢导致后来排查发现是litellm自身的请求超时设置太保守了。解决办法是在配置里调大request_timeoutlitellm_settings: request_timeout: 600这里还牵扯到连接池方面的参数如果你的并发量很高我也建议先把超时调大再把并发调高否则两者互相制约容易让某个慢请求占用大量连接。5.3 本地模型接入时的address写法很多人第一次把Ollama或者vLLM模型接入网关时都会在配置上卡住。以我实际测试的经验来看本地模型的配置需要注意以下几点第一api_base要带端口而且不要加多余的路径格式要精确到端口层级第二如果你用的是Ollamamodel名要写完整的ollama/llama3这种带前缀的形式第三本地服务启动之后一定要先用原生命令测试一下能不能通再去配litellm否则出了问题你根本不知道是哪个环节坏了。我比较推荐的路径是先直接用Ollama的命令行验证本地模型能正常对话然后用Python SDK直连测试最后再把地址填到litellm配置里。每一步都通了再进下一步这个排查套路很值得分享。5.4 常见坑点速查表症状可能原因解决方案404错误路由没匹配到model_list别名检查配置文件里的model_name是否一致401错误虚拟密钥失效或主密钥不对用主密钥重新生成子密钥长时间无响应后超时request_timeout过小调大timeout参数或优化模型选择返回内容为空但无报错某类模型对空system消息敏感减少空消息清空messages里的history所有请求都路由到同一模型路由策略默认是simple轮询更换为usage-based-routing日消耗超出预算预算同步有延迟预算上限设为预期的80%甚至更低这个表格是我从自己几个项目里沉淀出来的高频问题清单你可以保存下来真遇到问题翻出来看一眼大概率能少走很多弯路。5.5 别让代理网关变成新的单点故障最后说一个架构层面值得关注的问题。代理模式带来了统一管理的好处但代价是litellm服务本身成了一个新的依赖点。如果它挂了所有团队都没法再调用大模型。我的建议是如果你所在团队对稳定性有要求网关至少要部署两个实例前面再用负载均衡把流量分散千万不要把一个实例裸奔在线上。这个道理很多人都懂但真正出事之后才会意识到网关从来不是一个“可有可无”的转发层它其实是你服务架构里的关键节点。另外litellm本身还在持续更新遇到版本升级不要看到新版本就立刻上生产先在预发环境拿真实流量压一遍重点看模型兼容性有没有变。这类基础组件稳定压倒一切。我自己的体会是如果你只是做个人实验直接用单点调用就够了完全没必要上代理模式。但一旦你的项目发展到多人协作、多个业务线共用模型资源的时候litellm这种统一网关带来的收益就会非常明显。它不只是节省了代码量更重要的是把模型调用的治理权集中起来了从密钥管理、预算控制到日志审计所有原本散落在各处的麻烦事都有了统一处理的抓手。如果你的团队马上也要做类似的大模型平台我建议你跟我一样先用单点调用跑通流程再花半天时间把代理模式搭起来整个体验会完全不同。 
长河君 · 2026/10/14 9:53:20 · 阅读 1.2k 大模型API统一调用与网关代理实战：litellm从零配置到成本管控
作为一个天天跟各种大模型接口打交道的开发者我第一次见到“litellm”这个名字时还以为是又一个什么轻量级的小工具库。真正用进去之后才发现这玩意儿对我的工作方式的改变远比想象中大得多。如果你也经历过那种“同一个需求、七八套API格式”的酸爽写代码时在不同服务商的SDK之间来回横跳解析结构完全不同的响应体那这篇文章就是给你写的。litellm做的事非常简单却又非常关键把市面上几乎所有主流大模型的API调用方式统一成一套最通用的标准。你可以用完全一样的Python代码只改一个模型名字符串就能在GPT、Claude、Llama之间无缝切换你还可以把它跑成一个独立的代理服务部署在你们团队的API网关位置统一管理所有模型的调用、限额、成本、日志。这篇文章我会从“为什么需要它”开始一步步讲到单点调用、代理模式、虚拟密钥和预算控制最后附上我在实际部署中踩过的一堆坑。1. 为什么大家都在用一个统一的模型网关1.1 模型API碎片化带来的日常崩溃先聊一下我自己的真实场景。我之前在某个数据团队做内部工具功能很简单根据用户输入生成一段结构化信息。最开始用的是某家闭源模型它的SDK封装得不错代码写起来挺顺。后来领导说要对比测试另一家模型看看效果哪个好我当时想都没想以为只是改改API地址的事。结果一上手才发现完全不是这么回事。第二家模型的请求体结构跟第一家的差异极其明显连最基础的字段命名都不一致流式输出的格式更是天差地别。第三方模型的响应体里没有现成的“content”字段而是嵌套在好几层里。我整整花了两天时间写了一堆适配代码才让同一套业务逻辑能跑在两个模型上。后来这个项目越做越大陆续要接开源的、自部署的、国内厂商的模型我意识到一个严重的问题每加一个模型我就要多维护一套适配层。业务逻辑本身没什么变化但大量的时间都花在“翻译”不同的API格式上。更麻烦的是不同服务商的SDK版本还在频繁更新动不动就破坏我的代码。这种“模型通胀”带来的维护成本已经快压过模型本身带来的收益了。1.2 litellm到底做了什么后来我接触到了litellm第一反应是这不就是我需要的那个“翻译层”吗。它的核心思路非常简单粗暴统一用OpenAI风格的接口格式由litellm在底层自动把请求转换成各家模型服务商要求的格式再把返回的响应统一成OpenAI格式。你可以理解为它就是一个“万能插座转换器”。你家电器插头是国标但墙上的插座可能是美标、欧标、英标转换器帮你把电压、插脚形状统统适配好。你只需要关心电器本身永远不用在意身后那面墙上是什么规格的插座。这个库用起来也异常简单装好之后直接调用from litellm import completion response completion( modelgpt-4o, messages[{role: user, content: 你好介绍一下自己}] ) print(response[choices][0][message][content])关键点来了当我想换成某款口碑不错的另一家闭源模型时只需要改一行response completion( modelclaude-sonnet-20241022, messages[{role: user, content: 你好介绍一下自己}] )代码结构几乎没动响应解析逻辑也可以沿用。这个体验真的太舒服了相当于你学会了手波现在开什么车都是一样的操作逻辑不管引擎盖底下是几缸发动机。2. 先从单点调用开始一行代码切换模型2.1 安装和最简单的completion调用litellm是纯Python包安装起来没什么坑pip install litellm装完之后最基础的使用方式就是一个函数搞定一次对话补全。但你千万别小看这个简单的调用背后处理的事情真的不少。不同模型要求不同的鉴权方式有的需要放在Header里用指定前缀有的要放在query参数里这些细节litellm全都替你处理了。对于API Key的传递我一开始也很懵不知道key该放在哪里。官方给了几种方式最省事的做法是设置环境变量export OPENAI_API_KEYsk-... export ANTHROPIC_API_KEYsk-ant-... export GEMINI_API_KEY...设置好之后直接调用completion什么都不用传litellm会自动从环境变量里找对应的模型厂商Key。如果你不想用环境变量也可以在调用时显式传参response completion( modelgpt-4o, messages[{role: user, content: hello}], api_keysk-xxx )不过我建议在真实的项目里还是走环境变量或配置管理平台把密钥跟代码隔离尤其是在多人协作的仓库里硬编码API Key迟早会被不小心推上去。异步调用同样支持写法跟同步很像from litellm import acompletion async def test(): response await acompletion( modelgpt-4o, messages[{role: user, content: hello}], ) print(response[choices][0][message][content])我建议高并发的Python服务都优先用异步同样的资源能压榨出更高的吞吐量。litellm对异步的支持比较成熟不是那种包一层线程池的伪异步所以可以放心使用。2.2 参数映射和模型别名的坑点用了一段时间之后我发现虽然调用方统一了格式但不同模型之间的参数语义还是有细微差异。比如max_tokens这个参数大部分服务商都认识可有一两家更偏爱max_completion_tokens如果你不管不顾地只传max_tokens它也能正常工作因为litellm会做一层参数翻译。再比如temperature对方为0到2某家开源模型要求0到1你传个1.5可能不报错但行为会变得非常奇怪。在遇到这类参数越界问题的时候litellm会尽力帮你做clip处理但有些情况下它无能为力还是需要使用者自己对目标模型的参数范围有个大致认知。还有一个非常实用的特性是模型别名。你可以把一串复杂的模型名映射成一个简单易懂的别名import litellm litellm.model_alias_map { main: gpt-4o, fast: claude-sonnet-20241022, local: ollama/llama3 }这样业务代码里只用main、fast这样的业务语义名称底层用哪个模型完全由配置来决定。万一哪天觉得某个模型不好直接把映射关系改掉就能全局切换业务代码一行都不需要动。这个机制在多人协作和实验对比场景下非常实用A/B测试的时候尤其香。但这里有个点必须提醒不同模型的response结构虽然被统一成了OpenAI格式但细节字段的完整性还是略有差异。比如有的模型支持返回token用量明细有的则没有如果你写代码时强依赖某些特定字段还是要先在真实模型上跑一把确认。这个不是litellm的bug而是模型本身的差异它最多只能做到尽可能兼容。3. 进阶玩法把litellm跑成团队网关3.1 配置文件model_list是核心单点调用只是开胃菜litellm真正让我觉得“这工具是认真做的”的地方是它的Proxy Server模式。说人话就是你单独起一个litellm服务所有人都去访问这个服务再由它来转发到各种大模型服务商。这样一来你的团队项目里不再需要每个人自己折腾API Key和SDK而是统一通过这个代理网关访问模型。这个模式下的灵魂是config.yaml配置文件。我第一次看到它的model_list结构时觉得很简单真正配过之后发现这里面的门道还挺多。一个典型的最小配置长这样model_list: - model_name: gpt-4o litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude-sonnet litellm_params: model: claude-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY - model_name: llama3 litellm_params: model: ollama/llama3 api_base: http://localhost:11434启动脚本很简单一行命令litellm --config config.yaml --port 8000网关跑起来之后客户端接入方式就跟调用OpenAI一样用任何支持OpenAI格式的SDK就行。我用Python的openai包测过from openai import OpenAI client OpenAI( base_urlhttp://localhost:8000/v1, api_key任意字符串网关会自己校验 ) resp client.chat.completions.create( modelclaude-sonnet, messages[{role: user, content: 你好}], ) print(resp.choices[0].message.content)注意上面这个model字段传的是claude-sonnet这个字符串是你在config.yaml里定义的别名不是真实的模型名。网关会找到对应配置再去请求真正的模型。这就回到了我们之前在别名机制里说的业务侧只认别名底层可以随便换。3.2 负载均衡与自动降级如果你在model_list里给同一个别名配置了多个模型就自动获得了负载均衡和故障转移能力。这个特性我非常喜欢拿它做一个简单的容灾架构model_list: - model_name: gpt-4o litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY rpm: 1000 - model_name: gpt-4o litellm_params: model: claude-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY rpm: 500 - model_name: gpt-4o litellm_params: model: ollama/llama3 api_base: http://localhost:11434这样配置之后客户端依然只会用“gpt-4o”这个名字来发请求但网关会在三家服务商之间做流量分配请求量大的时候甚至会使用你本地部署的Llama来做兜底。当其中一家服务商返错或者响应超时litellm会自动帮你尝试下一个候选模型。体验下来这个机制很可靠我故意掐断其中一个API Key来测试客户端几乎感知不到失败。这里要夸一下litellm的路由策略设计。它内置了好几种路由算法默认的simple策略是简单的轮询如果你希望按模型实际负载来做更聪明的分配可以改用usage-based-routingrouter_settings: routing_strategy: usage-based-routing这个策略会依据最近一段时间的请求量和token消耗情况做动态分配有效避免某个模型被压垮而另一个模型闲置的情况。不过启动后要跑一段时间等统计窗口积累了数据才比较准确刚部署那会儿跟默认策略差别不大。3.3 长文本输入和流式输出的代理实现团队网关场景还有一个容易被忽视的点流式输出。很多客户端都期望SSE流式响应像打字机一样逐字返回。litellm对streamTrue的支持做得不错只要你调用时传入stream参数它就会把底层模型的流式响应原样转发给客户端。不过这里要提醒一下不同模型的流式事件格式不一样litellm会统一成OpenAI的chunk格式但某些边缘字段比如usage统计有可能仅在最后一个chunk里带出来。前端如果依赖这个做token统计一定要用真实环境测一把。另外一个很实用的功能是prompt格式转换。各家的system prompt、few-shot示例在底层格式有区别但litellm代理会自动做转换。比如某模型的系统消息不支持独立的system角色litellm会帮你把system内容折叠进第一条user消息里。这类细节看着不起眼真对接起来会发现省了太多工作量。4. 团队网关的安全与预算管理4.1 虚拟密钥和统一认证网关部署好之后摆在面前的下一个问题就是怎么让团队其他人安全地使用这个网关。你不能把各个模型服务商的原生API Key直接给每个开发那样既无法追踪每个Key的花费又存在泄露风险。litellm提供了一套虚拟密钥机制思路类似给你发了一个“代币”所有人用的都是网关生成的新密钥网关内部再映射到真实模型厂商的Key。用API的方式可以快速生成curl -X POST http://localhost:8000/key/generate \ -H Authorization: Bearer sk-master-key \ -H Content-Type: application/json \ -d { models: [gpt-4o], max_budget: 50, expires: 2025-12-31 }生成的虚拟密钥长这样sk-xxxxx。客户端把它当普通OpenAI Key用就行但它的有效范围完全由你掌控。你可以给测试组发一个限额50美元的Key给线上服务发一个没有额度的Key还可以设置60天有效期。所有人都不知道自己背后真正调的是哪家模型也不知道原来服务商的Key长什么样。我自己比较喜欢的用法是把虚拟密钥按“项目”和“环境”双维度切分。比如为某个业务线的预售环境生成一个单独的Key预算调低同时把可访问的模型限制在便宜的那几款到正式发布时用另一个Key预算不设限但把模型列表调整成生产级的高质量模型。这样业务团队不需要感知网关策略的细节做不做得到全看密钥的配置。4.2 预算与速率限制配置详解预算控制是网关场景里最容易被忽略但又最重要的功能。大模型接口不像传统API它的收费跟token数额强相关一个死循环的请求逻辑几分钟就能烧掉几十美元。没有预算限制的模型网关等于在裸奔。litellm提供了一个比较完善的分层预算控制体系。最基本的是在虚拟密钥创建时指定max_budget单位是美元。当这个Key的累计消耗触顶后后续请求会直接被拒绝返回一个预算超限的错误。你还可以对每个模型设置速率限制。比如某个模型本身价格很高又特别慢你希望它每分钟最多被调用50次可以在配置里写model_list: - model_name: gpt-4o litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY model_info: mode: completion rpm: 100 tpm: 10000rpm控制每分钟请求次数tpm控制每分钟token的消耗总量。加上这层限制以后就不怕某个团队的上线活动把整个模型的额度给冲垮了其他团队的业务不会受到拖累。实际测试中我发现预算限制的生效并不是精确到request级别的它有一定的同步延迟如果你设置了每天50美元的限额实际消耗可能会跑到50出头甚至更多。放在生产环境下我会建议把预算上限设成目标值的80%给系统留出缓冲空间。4.3 日志审计和成本追踪团队网关的另一个隐藏好处是所有模型请求都会经过网关这意味着你可以在这个位置记录下所有的调用日志和token用量。litellm会在本地维护一份日志数据你随时可以查某个Key、某个模型在某个时间段内花了多少钱。如果你有合规要求建议把日志也对接到自己已有的监控系统。litellm本身提供了一些可观测性接口也可以把数据同步给外部日志平台。不要把日志只存在本地文件因为网关前面就是所有业务线的流量入口日志量上来之后本地文件很快会被冲掉。我现在的习惯是配置好日志导出并用一套简单的看板来观察模型成本趋势每个月各团队消耗一目了然。出现费用异常波动时也能按Key维度去定位到底是谁在疯狂调用。另外我建议给重要请求加个metadata参数。litellm允许在调用时附带一个可选的metadata对象比如放上用户的ID之后在日志里就能按用户维度追踪。这个功能在客服场景下特别有效比如某个用户反馈响应太慢或者内容不对你可以通过他ID精确锁定到具体的那条请求记录查看它用的是哪个模型、处理的耗时多长、上下文中包含什么内容而不至于淹没在茫茫日志里。5. 几个高频问题和我的排查记录5.1 环境变量冲突导致的“模型错乱”这是我第一个在项目里遇到的坑也最值得说。我同时配置了OpenAI和Anthropic两家的环境变量当时只是想在代码里快速对比两个模型于是写了两个脚本一个传gpt-4o一个传claude-sonnet。诡异的是跑出来之后两个请求都返回了同样的结果而且速度完全一致。后来我仔细检查才发现是因为两个环境变量里的Key都暴露了而litellm在某种情况下会用同一套Key去请求不同的服务商。正确的做法是在调用时用api_key参数显式指定或者确保环境变量具备明确的隔离。这里我也建议团队在封装SDK的时候强制显式传递密钥来源而不是依赖全局环境变量否则出问题的时候排查起来特别痛苦。5.2 长文本输出时的超时问题代理模式下跑一些长文档生成任务客户端的等待时间一长网关就会报超时。一开始我以为是模型响应慢导致后来排查发现是litellm自身的请求超时设置太保守了。解决办法是在配置里调大request_timeoutlitellm_settings: request_timeout: 600这里还牵扯到连接池方面的参数如果你的并发量很高我也建议先把超时调大再把并发调高否则两者互相制约容易让某个慢请求占用大量连接。5.3 本地模型接入时的address写法很多人第一次把Ollama或者vLLM模型接入网关时都会在配置上卡住。以我实际测试的经验来看本地模型的配置需要注意以下几点第一api_base要带端口而且不要加多余的路径格式要精确到端口层级第二如果你用的是Ollamamodel名要写完整的ollama/llama3这种带前缀的形式第三本地服务启动之后一定要先用原生命令测试一下能不能通再去配litellm否则出了问题你根本不知道是哪个环节坏了。我比较推荐的路径是先直接用Ollama的命令行验证本地模型能正常对话然后用Python SDK直连测试最后再把地址填到litellm配置里。每一步都通了再进下一步这个排查套路很值得分享。5.4 常见坑点速查表症状可能原因解决方案404错误路由没匹配到model_list别名检查配置文件里的model_name是否一致401错误虚拟密钥失效或主密钥不对用主密钥重新生成子密钥长时间无响应后超时request_timeout过小调大timeout参数或优化模型选择返回内容为空但无报错某类模型对空system消息敏感减少空消息清空messages里的history所有请求都路由到同一模型路由策略默认是simple轮询更换为usage-based-routing日消耗超出预算预算同步有延迟预算上限设为预期的80%甚至更低这个表格是我从自己几个项目里沉淀出来的高频问题清单你可以保存下来真遇到问题翻出来看一眼大概率能少走很多弯路。5.5 别让代理网关变成新的单点故障最后说一个架构层面值得关注的问题。代理模式带来了统一管理的好处但代价是litellm服务本身成了一个新的依赖点。如果它挂了所有团队都没法再调用大模型。我的建议是如果你所在团队对稳定性有要求网关至少要部署两个实例前面再用负载均衡把流量分散千万不要把一个实例裸奔在线上。这个道理很多人都懂但真正出事之后才会意识到网关从来不是一个“可有可无”的转发层它其实是你服务架构里的关键节点。另外litellm本身还在持续更新遇到版本升级不要看到新版本就立刻上生产先在预发环境拿真实流量压一遍重点看模型兼容性有没有变。这类基础组件稳定压倒一切。我自己的体会是如果你只是做个人实验直接用单点调用就够了完全没必要上代理模式。但一旦你的项目发展到多人协作、多个业务线共用模型资源的时候litellm这种统一网关带来的收益就会非常明显。它不只是节省了代码量更重要的是把模型调用的治理权集中起来了从密钥管理、预算控制到日志审计所有原本散落在各处的麻烦事都有了统一处理的抓手。如果你的团队马上也要做类似的大模型平台我建议你跟我一样先用单点调用跑通流程再花半天时间把代理模式搭起来整个体验会完全不同。