2. 多模型切换的真实痛点不引入LiteLLM之前我经历了什么这两年LLM接入的项目做得多了最让我头疼的从来不是某个模型本身的效果问题而是API格式的差异。今天业务方说换个模型试试听起来一句话的事落到代码里就是重写一遍客户端、改鉴权方式、调参数映射、解决那些奇奇怪怪的报错字段。几个项目叠下来我的代码库里堆了至少三套不同的SDK封装维护成本越来越高。直到我用上了LiteLLM这个问题才算是被彻底解决。它的思路很直接把几乎所有主流大模型厂商的API接口统一转换成OpenAI风格的接口。也就是说你只需要用OpenAI SDK的写法就能调用Anthropic、Google、Azure、AWS Bedrock等等不同平台的模型底层的格式差异全由LiteLLM帮你抹平。这篇文章我就结合自己实际接入项目的经历从痛点、安装、调用、部署到踩坑完整捋一遍。适合谁看正在做LLM应用开发、被多模型切换折磨过的开发者想搭一个统一的模型网关供团队内部使用的后台工程师以及技术上想搞明白API统一层到底值不值得引入的技术负责人。本文所有代码均基于常见的Python环境LiteLLM当前主版本为v1.x如果你拿到的版本更新个别参数可能需要微调。先说清楚一件事LiteLLM不是用来绕过或替换各家模型的工具它是站在你和大模型提供商之间的一层适配器。你要的模型能力还是来自各厂商但你和厂商之间的对话方式被LiteLLM规整成了同一套语言。这层统一的价值在实际工程里远比你想象的大。2.1 换一次模型重写一次客户端的日子我给自己做过一个统计最早做的一个问答机器人项目最初只接了一家模型提供商的API。后来因为成本考虑要切换服务商光是改造调用层就花了将近两天。不是改代码逻辑而是改那些看似简单但处处是坑的接口差异。举几个最典型的例子。各家超参数的名字完全不一样有的叫temperature有的叫top_p还有的叫nu同一个概念换个平台就换个叫法鉴权方式更是各搞一套有的是Bearer Token有的是API-Key放在自定义Header里有的要走签名流程返回结构也天差地别有的把对话内容嵌在好几层嵌套字段里有的直接给你一个choices[0].message.content你以为都是这样写的结果换一家发现字段路径完全对不上。更麻烦的是流式输出的格式。同样是打字机效果有的平台输出data: {json}带特定前缀有的平台直接吐字符串有的还会在流中间插入心跳包。这些细枝末节一旦对接过就知道有多浪费时间。每换一次模型就要把这些坑重新踩一遍。2.2 我一查市面上还真没有更好的解法被折腾几次之后我认真找过替代方案。当时有几个思路一个是自己写一层抽象接口把所有厂商API都封装成自己的统一格式。想法挺好但维护量巨大——厂商一更新接口你就得跟着改。而且每家SDK的依赖冲突、版本兼容问题都得自己扛。另一个思路是直接用各厂商自家的SDK然后在上层做适配。但这样代码里还是会混着各种SDK的调用方式团队新成员上手成本高排查问题时候也得在多个SDK文档之间来回跳。LiteLLM能胜出的原因很简单它把适配这个苦力活做成了标准化模块。你不必自己维护一堆适配器也不必关心各家SDK的版本演进LiteLLM社区在不断跟进更新。你只需要对着OpenAI风格的接口写代码底层的事交给它。这对于小团队和独立开发者来说省下的不是一点点功夫。3. LiteLLM核心用法从零开始用OpenAI写法调用各家模型LiteLLM的用法几乎不需要额外学习成本。只要你会用OpenAI的Python SDK你就能用LiteLLM调用几乎所有主流模型。它的设计哲学非常明确把所有模型的调用方式收敛为OpenAI格式。3.1 安装与环境准备安装没什么特殊的直接pip装就行pip install litellm如果你打算运行带UI的代理服务后面会讲可能还需要另外装一些额外依赖比如用于密钥管理的数据库模块。具体看官方文档即可我这里只讲最核心的用法。装好之后建议先验证一下是否正常python -c import litellm; print(litellm.__version__)能看到版本号就说明安装成功了。注意LiteLLM的版本更新很快用最新版通常不会错但升级前要留意breaking change这个我在踩坑章节会细讲。3.2 三步完成第一次跨模型调用接下来是重头戏。假设我要用OpenAI的GPT模型只需要这样import litellm response litellm.completion( modelgpt-4o-mini, messages[{role: user, content: 你好请介绍一下你自己}] ) print(response.choices[0].message.content)熟悉吧这就是OpenAI SDK的写法。那我要切换到Anthropic的Claude模型呢只需要改model参数response litellm.completion( modelclaude-3-5-sonnet-20240620, messages[{role: user, content: 你好请介绍一下你自己}] )其他代码一行都不用动。这就是LiteLLM最吸引人的地方业务层代码对模型是无感的。你今天用GPT明天换Claude后天换Gemini调用层只需要改一个字符串。当然要使用各家模型你得先在环境变量里配置好对应的API密钥。比如export OPENAI_API_KEYsk-... export ANTHROPIC_API_KEYsk-ant-... export GEMINI_API_KEYAIza...这些密钥LiteLLM会自动从环境变量读取当然你也可以在代码里显式传入api_key参数。3.3 异步调用和流式输出这两件事是生产级的命门真实项目里几乎没有同步调用的场景。在线接口动辄几秒钟延迟同步等着会阻塞线程池。LiteLLM提供了一整套异步接口写法也很贴合现有的异步生态import asyncio import litellm async def main(): response await litellm.acompletion( modelgpt-4o-mini, messages[{role: user, content: 给我讲个笑话}] ) print(response.choices[0].message.content) asyncio.run(main())把completion换成acompletion同步变异步就这么简单。这个设计对FastAPI这类异步框架尤其友好可以直接在async路由函数里调用不会阻塞事件循环。流式输出也是生产环境的刚需。用户看到的打字机效果本质上就是流式响应。LiteLLM的流式调用同样对齐了OpenAI的用法response litellm.completion( modelclaude-3-5-sonnet-20240620, messages[{role: user, content: 写一段100字左右的科技短文}], streamTrue ) for chunk in response: content chunk[choices][0][delta].get(content, ) print(content, end, flushTrue)注意看即使是Anthropic的模型streamTrue之后返回的chunk结构也是OpenAI风格的choices[0].delta.content。所有底层厂商的流式格式差异在这里都被隐藏掉了。这一点在实际工程里价值极高——你不用再为不同厂商写不同的流式解析逻辑。3.4 提前帮大家避一个坑消息格式的统一处理用过OpenAI的开发者都知道messages参数是一个列表里面有role和content字段。但不同模型对role的支持其实不一样。比如有些模型不支持system角色有些模型对多条历史消息的长度有限制。LiteLLM虽然做了很多自动映射但遇到复杂的消息格式时还是可能出现偏差。我的建议是始终按OpenAI的消息格式写这是最通用的。role字段在system、user、assistant之间切换基本不会出错。如果换了模型后出现报错优先检查是不是你传入的消息里有特殊字段比如某些模型支持tool_calls另一些不支持。这一块LiteLLM帮你处理了大部分但边界情况还是得靠经验去填。4. 把它当成网关用搭建LiteLLM Proxy做多模型路由与API密钥管理在单机脚本里直接用LiteLLM很方便但在团队协作或者生产环境里你迟早需要一个统一入口。LiteLLM Proxy就是干这个的它把LiteLLM变成一个独立部署的服务你的应用只需要访问这个服务的HTTP接口让服务去负责调用各家模型。4.1 Proxy模式到底解决了什么问题想象一个场景你的团队里有好几个后端服务每个服务都要调用大模型API。没上Proxy之前每个服务里都要配置各家厂商的API密钥都要写一遍调用逻辑。密钥散落各处安全风险高出问题了也不知道是哪个服务在疯狂调用消耗费用。上了Proxy之后所有服务只需要访问同一个HTTP地址密钥只存在Proxy配置里。你想在多个模型之间做负载均衡、切换主模型、限制每个服务或每个用户的调用量改配置文件就行不用动业务代码。这就是网关的价值。4.2 最快搭建方式一份config.yaml加一条命令搭建Proxy非常简单。你先写一个配置文件比如叫config.yamlmodel_list: - model_name: gpt-4o-mini litellm_params: model: gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: claude-3-5-sonnet litellm_params: model: claude-3-5-sonnet-20240620 api_key: os.environ/ANTHROPIC_API_KEY这里每个条目定义了对外暴露的模型名和实际调用的模型规格。你可以在model_name字段里起一个自己的别名比如统一叫gpt-4o-mini但实际上背后指向的是某个Claude模型。这样前端应用根本没有感知后端换了哪个厂商的模型前端代码都不用改。然后一行命令启动服务litellm --config config.yaml --port 4000默认情况下服务会启动在localhost:4000。你的应用就可以用OpenAI SDK的姿势来请求它了只不过把base_url指到本地from openai import OpenAI client OpenAI( api_keysk-anything, base_urlhttp://localhost:4000 ) response client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 你好}] )看到没有你的应用代码可以完全不感知LiteLLM的存在它以为自己只是在跟OpenAI对话但实际上背后是Proxy在代替它做模型路由。这个兼容性设计非常巧妙。4.3 团队协作视角API密钥管理不再是头疼的事多个人共用一个Proxy时单独给每个人发厂商密钥显然不合适。LiteLLM Proxy提供了自己的虚拟密钥机制——你可以生成多个虚拟密钥分发给不同的团队成员或不同服务每个虚拟密钥可以挂不同的模型访问权限和预算限制。生成方式也很简洁。在启动Proxy后直接调用HTTP接口生成虚拟密钥curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-1234 \ -H Content-Type: application/json \ -d { models: [gpt-4o-mini], max_budget: 10 }得到一串以sk-开头的虚拟密钥。然后你就可以把这把钥匙给某个同事或某个服务用。他以为自己在用OpenAI的密钥但实际上使用的是你的Proxy生成的受限密钥——不能直接访问厂商只能通过你的网关调用。这一套机制对团队管理特别有用谁用了多少额度、哪个模型被频繁调用全都一目了然。结合管理后台界面你能直观地看到每个虚拟密钥的调用量、花费情况甚至能实时撤销某把钥匙。4.4 多个模型之间怎么做负载均衡很多项目里同一个模型会有多个部署比如同一个模型在多家云厂商都有部署或者你需要把流量分摊到不同模型上以降低成本。LiteLLM Proxy配置文件里的model_list和router_settings就派上用场了。一个简单的配置示例model_list: - model_name: gpt-4o-mini litellm_params: model: gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: gpt-4o-mini litellm_params: model: azure/gpt-4o-mini api_key: os.environ/AZURE_API_KEY api_base: os.environ/AZURE_API_BASE两个条目都用了model_name: gpt-4o-mini但背后一个指向OpenAI官方一个指向Azure上的OpenAI模型。当你的应用请求gpt-4o-mini时LiteLLM会按照负载均衡策略在两个上游之间分发请求。如果你配置了router_settings里的routing_strategyleast-busy它会优先选择当前负载更低的上游实测下来在高峰期确实能明显降低响应时延。5. 预算控制、限流、重试优化这些生产级细节值得稳扎稳打对一个个人项目来说能调通LiteLLM已经够了。但如果是在企业环境或者高并发场景你还需要考虑预算、限流、错误重试这几件事。LiteLLM在这些方面同样提供了相对完善的机制。5.1 给虚拟密钥绑定预算让每个业务方都量化我在前面的/key/generate示例里已经传了max_budget参数。这个参数是按美元计算的。你可以给一台开发用的测试密钥设置max_budget5当月度消费达到5美元后这把钥匙直接失效请求返回403。更细的预算粒度也有。你可以在config.yaml里给某个模型设置预算上限、给某个API Key设置每日/每周/每月限额。它们会组合生效。这意味着你可以在团队维度、项目维度、甚至模型维度上都建立量化的成本控制。我的经验是把预算控制明确到个人或项目级别。很多公司是用一个共享的公司账户在调用模型一旦某个人在调试时候产生失控循环调用整个团队的成本都在涨。给每把虚拟密钥设好上限相当于上了一层保险丝。出问题时候只是某一把钥匙失效不会波及整个账户。5.2 限流配置防止单模型被打爆限流在多模型网关里尤其重要。有些模型提供方对单账号有严格的每分钟请求数RPM和每分钟Token数TPM限制一旦超限会导致大量429错误而且某些厂商的429报错会重重打断你的使用体验。LiteLLM Proxy支持限流配置可以在router_settings里做请求级别的控制。例如router_settings: rpm_limit: 500 tpm_limit: 100000 max_parallel_requests: 50rpm_limit限制每分钟请求数tpm_limit限制每分钟消耗的Token总量max_parallel_requests限制同时处理的并发请求数。如果有上游频繁报429我建议把max_parallel_requests调小同时打开重试机制下一节细说这样比硬扛流量更稳。5.3 重试机制让抖动不再直接打到用户脸上大模型API的抖动是常态尤其是高峰期各家厂商都偶尔会返回5xx或者429。LiteLLM内置了重试机制默认情况下会在遇到特定错误码时自动重试。你也可以手动配置import litellm litellm.num_retries 3 litellm.retry_after 5 # 重试间隔秒 litellm.allowed_fails 2 # 连续失败几次后放弃这里有个小技巧重试的间隔最好设置成递增的而不是固定值。因为上游报429说明它真的忙固定间隔重试很容易在恢复瞬间继续撞到限流。LiteLLM虽然没有直接暴露指数退避参数但retry_after配合num_retries再结合你根据自己的调用历史调整间隔就能得到不错的效果。另一个容易被忽略的点是流式请求的重试比普通请求更麻烦。因为流式请求可能已经吐了一半内容才报错这时候重试会导致用户看到重复内容。我建议对线上流式请求做两层保护一是LiteLLM的自动重试要设置较短的重试上限二是业务层自己记录已发送的token数流式中断后提示用户重试而不是自动拼接。这个坑我在实际项目中踩过现在说出来也是希望大家少走弯路。5.4 降级策略主模型挂了备胎模型顶上最后说说降级。LiteLLM支持把多个模型配置成同组当一个模型不可用时自动切换到另一个。这在稳定性要求高的场景很管用。配置方式也简单在config.yaml里给多个模型打相同的路由组标签。比如model_list: - model_name: gpt-4o-mini litellm_params: model: gpt-4o-mini model_info: mode: completion - model_name: gpt-4o-mini litellm_params: model: claude-3-5-sonnet-20240620 model_info: mode: completion虽然名字都叫gpt-4o-mini但实际一个指向GPT一个指向Claude。调用时候LiteLLM会按配置顺序尝试第一个失败就切到第二个。这个方案在某些场景下会带来一定体验差异毕竟不同模型输出风格不同但总比服务宕机强太多。6. 我踩过的坑和最后的几条建议LiteLLM功能确实强大但也不是完全无坑。这一章写写我在使用过程中遇到的典型问题以及解决问题的心得。6.1 版本更新较快小心breaking changeLiteLLM迭代速度很快有时候小版本更新就会改掉某些方法签名。我之前在一个项目里用了一个比较旧的版本配置里写的参数在新的v1.x版本里已经更名为其他说法启动时直接报错。解决方式很简单上线前固定版本号。在requirements.txt或者Dockerfile里写死版本不要用litellm或litellm*这种开放式约束。每次要升级时先在测试环境跑一遍完整的回归用例再决定是否更新。6.2 各模型对参数的支持程度不一样不能无脑透传LiteLLM的定位是统一接口但各家模型的能力边界还是不同的。比如response_format{type: json_object}并不是所有模型都支持。你传了某些模型不支持的参数LiteLLM虽然不会报错但参数会被悄悄忽略。看起来一切正常实际模型并没有按你的要求输出JSON。我的处理方法是在业务层对模型能力做一份额外清单按模型名判断是否支持某些高级参数。虽然这么做稍显繁琐但能避免你以为传了、实际没传的隐蔽问题。6.3 用Docker部署时环境变量别写在镜像里这点也是老生常谈但确实是生产环境最常见的失误。config.yaml里引用了os.environ/OPENAI_API_KEY这样的写法意味着服务启动时必须从环境变量里读。很多人图省事直接把密钥写死在镜像里结果镜像一旦外泄密钥就全泄露了。我用的方案是密钥统一放在部署平台的安全配置项里比如Kubernetes的Secret或者Docker的--env-file参数镜像本身保持无密钥状态。这样不管镜像分发到哪密钥都不会跟着走。另外虚拟密钥的管理也是同理不要写死在配置仓库里。6.4 最后说点实在话LiteLLM解决了我将近两年的多模型适配问题。它不是一个非常复杂的组件但它在工程上的意义很大——把模型提供商和应用代码彻底解耦开。哪怕你目前只用了单一的模型我也建议从第一天起就用LiteLLM做接入层因为需求说变就变技术债越早还不越痛。个人经验是小型项目直接引入LiteLLM成本很低收益立竿见影中大型项目用Proxy模式统一入口、控制预算团队协作效率会明显提升。如果你正在被多模型API差异折磨建议照着本文的步骤先跑通一个最小案例剩下的事水到渠成。 
长河君 · 2026/10/14 8:02:00 · 阅读 1.2k LiteLLM实操：统一多模型API接口，实现OpenAI风格调用的网关方案
2. 多模型切换的真实痛点不引入LiteLLM之前我经历了什么这两年LLM接入的项目做得多了最让我头疼的从来不是某个模型本身的效果问题而是API格式的差异。今天业务方说换个模型试试听起来一句话的事落到代码里就是重写一遍客户端、改鉴权方式、调参数映射、解决那些奇奇怪怪的报错字段。几个项目叠下来我的代码库里堆了至少三套不同的SDK封装维护成本越来越高。直到我用上了LiteLLM这个问题才算是被彻底解决。它的思路很直接把几乎所有主流大模型厂商的API接口统一转换成OpenAI风格的接口。也就是说你只需要用OpenAI SDK的写法就能调用Anthropic、Google、Azure、AWS Bedrock等等不同平台的模型底层的格式差异全由LiteLLM帮你抹平。这篇文章我就结合自己实际接入项目的经历从痛点、安装、调用、部署到踩坑完整捋一遍。适合谁看正在做LLM应用开发、被多模型切换折磨过的开发者想搭一个统一的模型网关供团队内部使用的后台工程师以及技术上想搞明白API统一层到底值不值得引入的技术负责人。本文所有代码均基于常见的Python环境LiteLLM当前主版本为v1.x如果你拿到的版本更新个别参数可能需要微调。先说清楚一件事LiteLLM不是用来绕过或替换各家模型的工具它是站在你和大模型提供商之间的一层适配器。你要的模型能力还是来自各厂商但你和厂商之间的对话方式被LiteLLM规整成了同一套语言。这层统一的价值在实际工程里远比你想象的大。2.1 换一次模型重写一次客户端的日子我给自己做过一个统计最早做的一个问答机器人项目最初只接了一家模型提供商的API。后来因为成本考虑要切换服务商光是改造调用层就花了将近两天。不是改代码逻辑而是改那些看似简单但处处是坑的接口差异。举几个最典型的例子。各家超参数的名字完全不一样有的叫temperature有的叫top_p还有的叫nu同一个概念换个平台就换个叫法鉴权方式更是各搞一套有的是Bearer Token有的是API-Key放在自定义Header里有的要走签名流程返回结构也天差地别有的把对话内容嵌在好几层嵌套字段里有的直接给你一个choices[0].message.content你以为都是这样写的结果换一家发现字段路径完全对不上。更麻烦的是流式输出的格式。同样是打字机效果有的平台输出data: {json}带特定前缀有的平台直接吐字符串有的还会在流中间插入心跳包。这些细枝末节一旦对接过就知道有多浪费时间。每换一次模型就要把这些坑重新踩一遍。2.2 我一查市面上还真没有更好的解法被折腾几次之后我认真找过替代方案。当时有几个思路一个是自己写一层抽象接口把所有厂商API都封装成自己的统一格式。想法挺好但维护量巨大——厂商一更新接口你就得跟着改。而且每家SDK的依赖冲突、版本兼容问题都得自己扛。另一个思路是直接用各厂商自家的SDK然后在上层做适配。但这样代码里还是会混着各种SDK的调用方式团队新成员上手成本高排查问题时候也得在多个SDK文档之间来回跳。LiteLLM能胜出的原因很简单它把适配这个苦力活做成了标准化模块。你不必自己维护一堆适配器也不必关心各家SDK的版本演进LiteLLM社区在不断跟进更新。你只需要对着OpenAI风格的接口写代码底层的事交给它。这对于小团队和独立开发者来说省下的不是一点点功夫。3. LiteLLM核心用法从零开始用OpenAI写法调用各家模型LiteLLM的用法几乎不需要额外学习成本。只要你会用OpenAI的Python SDK你就能用LiteLLM调用几乎所有主流模型。它的设计哲学非常明确把所有模型的调用方式收敛为OpenAI格式。3.1 安装与环境准备安装没什么特殊的直接pip装就行pip install litellm如果你打算运行带UI的代理服务后面会讲可能还需要另外装一些额外依赖比如用于密钥管理的数据库模块。具体看官方文档即可我这里只讲最核心的用法。装好之后建议先验证一下是否正常python -c import litellm; print(litellm.__version__)能看到版本号就说明安装成功了。注意LiteLLM的版本更新很快用最新版通常不会错但升级前要留意breaking change这个我在踩坑章节会细讲。3.2 三步完成第一次跨模型调用接下来是重头戏。假设我要用OpenAI的GPT模型只需要这样import litellm response litellm.completion( modelgpt-4o-mini, messages[{role: user, content: 你好请介绍一下你自己}] ) print(response.choices[0].message.content)熟悉吧这就是OpenAI SDK的写法。那我要切换到Anthropic的Claude模型呢只需要改model参数response litellm.completion( modelclaude-3-5-sonnet-20240620, messages[{role: user, content: 你好请介绍一下你自己}] )其他代码一行都不用动。这就是LiteLLM最吸引人的地方业务层代码对模型是无感的。你今天用GPT明天换Claude后天换Gemini调用层只需要改一个字符串。当然要使用各家模型你得先在环境变量里配置好对应的API密钥。比如export OPENAI_API_KEYsk-... export ANTHROPIC_API_KEYsk-ant-... export GEMINI_API_KEYAIza...这些密钥LiteLLM会自动从环境变量读取当然你也可以在代码里显式传入api_key参数。3.3 异步调用和流式输出这两件事是生产级的命门真实项目里几乎没有同步调用的场景。在线接口动辄几秒钟延迟同步等着会阻塞线程池。LiteLLM提供了一整套异步接口写法也很贴合现有的异步生态import asyncio import litellm async def main(): response await litellm.acompletion( modelgpt-4o-mini, messages[{role: user, content: 给我讲个笑话}] ) print(response.choices[0].message.content) asyncio.run(main())把completion换成acompletion同步变异步就这么简单。这个设计对FastAPI这类异步框架尤其友好可以直接在async路由函数里调用不会阻塞事件循环。流式输出也是生产环境的刚需。用户看到的打字机效果本质上就是流式响应。LiteLLM的流式调用同样对齐了OpenAI的用法response litellm.completion( modelclaude-3-5-sonnet-20240620, messages[{role: user, content: 写一段100字左右的科技短文}], streamTrue ) for chunk in response: content chunk[choices][0][delta].get(content, ) print(content, end, flushTrue)注意看即使是Anthropic的模型streamTrue之后返回的chunk结构也是OpenAI风格的choices[0].delta.content。所有底层厂商的流式格式差异在这里都被隐藏掉了。这一点在实际工程里价值极高——你不用再为不同厂商写不同的流式解析逻辑。3.4 提前帮大家避一个坑消息格式的统一处理用过OpenAI的开发者都知道messages参数是一个列表里面有role和content字段。但不同模型对role的支持其实不一样。比如有些模型不支持system角色有些模型对多条历史消息的长度有限制。LiteLLM虽然做了很多自动映射但遇到复杂的消息格式时还是可能出现偏差。我的建议是始终按OpenAI的消息格式写这是最通用的。role字段在system、user、assistant之间切换基本不会出错。如果换了模型后出现报错优先检查是不是你传入的消息里有特殊字段比如某些模型支持tool_calls另一些不支持。这一块LiteLLM帮你处理了大部分但边界情况还是得靠经验去填。4. 把它当成网关用搭建LiteLLM Proxy做多模型路由与API密钥管理在单机脚本里直接用LiteLLM很方便但在团队协作或者生产环境里你迟早需要一个统一入口。LiteLLM Proxy就是干这个的它把LiteLLM变成一个独立部署的服务你的应用只需要访问这个服务的HTTP接口让服务去负责调用各家模型。4.1 Proxy模式到底解决了什么问题想象一个场景你的团队里有好几个后端服务每个服务都要调用大模型API。没上Proxy之前每个服务里都要配置各家厂商的API密钥都要写一遍调用逻辑。密钥散落各处安全风险高出问题了也不知道是哪个服务在疯狂调用消耗费用。上了Proxy之后所有服务只需要访问同一个HTTP地址密钥只存在Proxy配置里。你想在多个模型之间做负载均衡、切换主模型、限制每个服务或每个用户的调用量改配置文件就行不用动业务代码。这就是网关的价值。4.2 最快搭建方式一份config.yaml加一条命令搭建Proxy非常简单。你先写一个配置文件比如叫config.yamlmodel_list: - model_name: gpt-4o-mini litellm_params: model: gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: claude-3-5-sonnet litellm_params: model: claude-3-5-sonnet-20240620 api_key: os.environ/ANTHROPIC_API_KEY这里每个条目定义了对外暴露的模型名和实际调用的模型规格。你可以在model_name字段里起一个自己的别名比如统一叫gpt-4o-mini但实际上背后指向的是某个Claude模型。这样前端应用根本没有感知后端换了哪个厂商的模型前端代码都不用改。然后一行命令启动服务litellm --config config.yaml --port 4000默认情况下服务会启动在localhost:4000。你的应用就可以用OpenAI SDK的姿势来请求它了只不过把base_url指到本地from openai import OpenAI client OpenAI( api_keysk-anything, base_urlhttp://localhost:4000 ) response client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 你好}] )看到没有你的应用代码可以完全不感知LiteLLM的存在它以为自己只是在跟OpenAI对话但实际上背后是Proxy在代替它做模型路由。这个兼容性设计非常巧妙。4.3 团队协作视角API密钥管理不再是头疼的事多个人共用一个Proxy时单独给每个人发厂商密钥显然不合适。LiteLLM Proxy提供了自己的虚拟密钥机制——你可以生成多个虚拟密钥分发给不同的团队成员或不同服务每个虚拟密钥可以挂不同的模型访问权限和预算限制。生成方式也很简洁。在启动Proxy后直接调用HTTP接口生成虚拟密钥curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-1234 \ -H Content-Type: application/json \ -d { models: [gpt-4o-mini], max_budget: 10 }得到一串以sk-开头的虚拟密钥。然后你就可以把这把钥匙给某个同事或某个服务用。他以为自己在用OpenAI的密钥但实际上使用的是你的Proxy生成的受限密钥——不能直接访问厂商只能通过你的网关调用。这一套机制对团队管理特别有用谁用了多少额度、哪个模型被频繁调用全都一目了然。结合管理后台界面你能直观地看到每个虚拟密钥的调用量、花费情况甚至能实时撤销某把钥匙。4.4 多个模型之间怎么做负载均衡很多项目里同一个模型会有多个部署比如同一个模型在多家云厂商都有部署或者你需要把流量分摊到不同模型上以降低成本。LiteLLM Proxy配置文件里的model_list和router_settings就派上用场了。一个简单的配置示例model_list: - model_name: gpt-4o-mini litellm_params: model: gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: gpt-4o-mini litellm_params: model: azure/gpt-4o-mini api_key: os.environ/AZURE_API_KEY api_base: os.environ/AZURE_API_BASE两个条目都用了model_name: gpt-4o-mini但背后一个指向OpenAI官方一个指向Azure上的OpenAI模型。当你的应用请求gpt-4o-mini时LiteLLM会按照负载均衡策略在两个上游之间分发请求。如果你配置了router_settings里的routing_strategyleast-busy它会优先选择当前负载更低的上游实测下来在高峰期确实能明显降低响应时延。5. 预算控制、限流、重试优化这些生产级细节值得稳扎稳打对一个个人项目来说能调通LiteLLM已经够了。但如果是在企业环境或者高并发场景你还需要考虑预算、限流、错误重试这几件事。LiteLLM在这些方面同样提供了相对完善的机制。5.1 给虚拟密钥绑定预算让每个业务方都量化我在前面的/key/generate示例里已经传了max_budget参数。这个参数是按美元计算的。你可以给一台开发用的测试密钥设置max_budget5当月度消费达到5美元后这把钥匙直接失效请求返回403。更细的预算粒度也有。你可以在config.yaml里给某个模型设置预算上限、给某个API Key设置每日/每周/每月限额。它们会组合生效。这意味着你可以在团队维度、项目维度、甚至模型维度上都建立量化的成本控制。我的经验是把预算控制明确到个人或项目级别。很多公司是用一个共享的公司账户在调用模型一旦某个人在调试时候产生失控循环调用整个团队的成本都在涨。给每把虚拟密钥设好上限相当于上了一层保险丝。出问题时候只是某一把钥匙失效不会波及整个账户。5.2 限流配置防止单模型被打爆限流在多模型网关里尤其重要。有些模型提供方对单账号有严格的每分钟请求数RPM和每分钟Token数TPM限制一旦超限会导致大量429错误而且某些厂商的429报错会重重打断你的使用体验。LiteLLM Proxy支持限流配置可以在router_settings里做请求级别的控制。例如router_settings: rpm_limit: 500 tpm_limit: 100000 max_parallel_requests: 50rpm_limit限制每分钟请求数tpm_limit限制每分钟消耗的Token总量max_parallel_requests限制同时处理的并发请求数。如果有上游频繁报429我建议把max_parallel_requests调小同时打开重试机制下一节细说这样比硬扛流量更稳。5.3 重试机制让抖动不再直接打到用户脸上大模型API的抖动是常态尤其是高峰期各家厂商都偶尔会返回5xx或者429。LiteLLM内置了重试机制默认情况下会在遇到特定错误码时自动重试。你也可以手动配置import litellm litellm.num_retries 3 litellm.retry_after 5 # 重试间隔秒 litellm.allowed_fails 2 # 连续失败几次后放弃这里有个小技巧重试的间隔最好设置成递增的而不是固定值。因为上游报429说明它真的忙固定间隔重试很容易在恢复瞬间继续撞到限流。LiteLLM虽然没有直接暴露指数退避参数但retry_after配合num_retries再结合你根据自己的调用历史调整间隔就能得到不错的效果。另一个容易被忽略的点是流式请求的重试比普通请求更麻烦。因为流式请求可能已经吐了一半内容才报错这时候重试会导致用户看到重复内容。我建议对线上流式请求做两层保护一是LiteLLM的自动重试要设置较短的重试上限二是业务层自己记录已发送的token数流式中断后提示用户重试而不是自动拼接。这个坑我在实际项目中踩过现在说出来也是希望大家少走弯路。5.4 降级策略主模型挂了备胎模型顶上最后说说降级。LiteLLM支持把多个模型配置成同组当一个模型不可用时自动切换到另一个。这在稳定性要求高的场景很管用。配置方式也简单在config.yaml里给多个模型打相同的路由组标签。比如model_list: - model_name: gpt-4o-mini litellm_params: model: gpt-4o-mini model_info: mode: completion - model_name: gpt-4o-mini litellm_params: model: claude-3-5-sonnet-20240620 model_info: mode: completion虽然名字都叫gpt-4o-mini但实际一个指向GPT一个指向Claude。调用时候LiteLLM会按配置顺序尝试第一个失败就切到第二个。这个方案在某些场景下会带来一定体验差异毕竟不同模型输出风格不同但总比服务宕机强太多。6. 我踩过的坑和最后的几条建议LiteLLM功能确实强大但也不是完全无坑。这一章写写我在使用过程中遇到的典型问题以及解决问题的心得。6.1 版本更新较快小心breaking changeLiteLLM迭代速度很快有时候小版本更新就会改掉某些方法签名。我之前在一个项目里用了一个比较旧的版本配置里写的参数在新的v1.x版本里已经更名为其他说法启动时直接报错。解决方式很简单上线前固定版本号。在requirements.txt或者Dockerfile里写死版本不要用litellm或litellm*这种开放式约束。每次要升级时先在测试环境跑一遍完整的回归用例再决定是否更新。6.2 各模型对参数的支持程度不一样不能无脑透传LiteLLM的定位是统一接口但各家模型的能力边界还是不同的。比如response_format{type: json_object}并不是所有模型都支持。你传了某些模型不支持的参数LiteLLM虽然不会报错但参数会被悄悄忽略。看起来一切正常实际模型并没有按你的要求输出JSON。我的处理方法是在业务层对模型能力做一份额外清单按模型名判断是否支持某些高级参数。虽然这么做稍显繁琐但能避免你以为传了、实际没传的隐蔽问题。6.3 用Docker部署时环境变量别写在镜像里这点也是老生常谈但确实是生产环境最常见的失误。config.yaml里引用了os.environ/OPENAI_API_KEY这样的写法意味着服务启动时必须从环境变量里读。很多人图省事直接把密钥写死在镜像里结果镜像一旦外泄密钥就全泄露了。我用的方案是密钥统一放在部署平台的安全配置项里比如Kubernetes的Secret或者Docker的--env-file参数镜像本身保持无密钥状态。这样不管镜像分发到哪密钥都不会跟着走。另外虚拟密钥的管理也是同理不要写死在配置仓库里。6.4 最后说点实在话LiteLLM解决了我将近两年的多模型适配问题。它不是一个非常复杂的组件但它在工程上的意义很大——把模型提供商和应用代码彻底解耦开。哪怕你目前只用了单一的模型我也建议从第一天起就用LiteLLM做接入层因为需求说变就变技术债越早还不越痛。个人经验是小型项目直接引入LiteLLM成本很低收益立竿见影中大型项目用Proxy模式统一入口、控制预算团队协作效率会明显提升。如果你正在被多模型API差异折磨建议照着本文的步骤先跑通一个最小案例剩下的事水到渠成。