1. 从一个真实困境说起多模型调用的碎片化之痛如果你正在做AI应用开发大概率遇到过这样的场景项目初期用OpenAI的接口跑通了原型效果不错上线后老板说能不能换成国产模型降本或者产品经理要求同时接入三家模型做A/B测试。这时候你打开代码一看每个模型的SDK调用方式、参数命名、返回结构、错误码全都不一样光是写适配层就能耗掉一周。我自己就踩过这个坑。去年做一个智能客服的Demo前后对接了四个不同厂商的大模型接口每个厂商的鉴权方式不同、流式输出的解析逻辑不同、连temperature的取值范围都有差异。代码里到处是if-else分支维护成本极高。后来接触到LiteLLM这个工具才算是找到了一个相对优雅的解法。LiteLLM的核心价值用一句话概括用一套OpenAI格式的接口调用市面上几乎所有主流大模型。你只需要把API Key和模型名称传进去剩下的格式转换、异常处理、重试逻辑它帮你搞定。对于需要快速切换模型、做多模型对比、或者构建模型无关的AI应用的开发者来说这是一个能实实在在省时间的工具。这篇文章我会从实际使用角度出发把LiteLLM的安装配置、核心用法、多模型路由策略、代理服务部署、以及我在使用过程中踩过的坑完整地梳理一遍。不管你是刚接触大模型API的新手还是已经在做多模型集成的老手应该都能从中找到有用的东西。2. LiteLLM到底解决了什么问题拆解它的核心设计思路2.1 统一接口层的本质格式转换与协议适配LiteLLM做的事情本质上是在你的代码和各个大模型厂商的API之间加了一个中间层。这个中间层对外暴露的是OpenAI风格的接口格式对内则负责把请求翻译成各个厂商能理解的格式再把返回结果翻译回OpenAI的格式。为什么选择OpenAI格式作为统一标准原因很实际OpenAI的Chat Completions接口是目前事实上的行业标准绝大多数开发者对它最熟悉大量的开源工具和框架也都默认支持这个格式。LiteLLM选择它作为通用语言学习成本最低。具体来说当你调用completion(model某模型, messages[...])的时候LiteLLM内部会做这几件事根据模型名称判断属于哪个厂商比如gpt-4走OpenAI、claude-3-opus走Anthropic、gemini-pro走Google把统一的messages格式转换成目标厂商要求的格式比如Anthropic要求system prompt单独传LiteLLM会自动拆分处理参数映射比如OpenAI的max_tokens在某些厂商那里叫max_output_tokens发送请求并接收响应把响应转换回OpenAI的格式包括choices、usage等字段这个过程对调用方完全透明你不需要关心底层发生了什么。2.2 支持的模型范围从闭源商业模型到本地部署LiteLLM支持的模型列表相当长我按类别梳理一下常见的类别代表模型接入方式商业闭源GPT系列、Claude系列、Gemini系列官方API Key国产大模型通义千问、智谱GLM、月之暗面、百川各自API Key开源托管Llama系列、Mistral系列Together AI、Replicate等平台本地部署任意兼容OpenAI格式的本地服务自定义base_url云平台各大云厂商的模型服务对应SDK或API这个覆盖面基本能满足绝大多数场景。我实测下来主流模型的支持都比较稳定小众模型偶尔会有参数映射不完整的情况但社区更新很活跃遇到问题提Issue通常很快能得到响应。2.3 和直接调用SDK相比多了一层会不会有性能损失这是很多人关心的问题。我的实测结论是网络请求本身的耗时远大于格式转换的耗时LiteLLM带来的额外开销基本可以忽略。格式转换是纯内存操作微秒级别。真正耗时的是网络往返这部分不管你用不用LiteLLM都一样。我用同一个模型做了对比测试直接调用SDK和通过LiteLLM调用端到端延迟差异在5%以内大部分时候在统计误差范围内。唯一需要注意的是如果你用了LiteLLM的代理模式后面会讲多了一次本地HTTP转发会多几毫秒但相比大模型动辄几秒的推理时间这点开销不值一提。3. 环境搭建与基础调用从零跑通第一个例子3.1 安装与API Key配置的几种方式安装很简单pip install litellm如果你需要用到代理服务功能建议装完整版pip install litellm[proxy]API Key的配置方式有好几种我按推荐程度排序方式一环境变量最推荐export OPENAI_API_KEY你的key export ANTHROPIC_API_KEY你的keyLiteLLM会自动读取对应厂商的环境变量代码里不用传key干净利落。方式二代码中显式传入import litellm response litellm.completion( modelgpt-4, messages[{role: user, content: 你好}], api_key你的key )这种方式适合快速测试但key硬编码在代码里有泄露风险不建议在生产环境用。方式三配置文件LiteLLM支持用YAML配置文件管理多个模型的key和参数适合模型数量多的场景。配置文件里可以给每个模型起别名调用时用别名就行。注意不管用哪种方式key都不要提交到代码仓库。我见过有人把key写在代码里推到公开仓库结果被扫到后产生大量异常调用这个教训很深刻。3.2 第一次调用用三行代码跑通装好之后最简单的调用长这样from litellm import completion response completion( modelgpt-3.5-turbo, messages[{role: user, content: 用一句话解释什么是机器学习}] ) print(response.choices[0].message.content)如果你之前用过OpenAI的SDK会发现这个调用方式几乎一模一样。区别只在于model参数可以填其他厂商的模型名。换成Claude试试response completion( modelclaude-3-sonnet-20240229, messages[{role: user, content: 用一句话解释什么是机器学习}] )代码结构完全没变只改了模型名。这就是LiteLLM最直观的价值。3.3 流式输出与异步调用实际项目中的必备技能做聊天类应用流式输出是刚需。LiteLLM的流式用法response completion( modelgpt-4, messages[{role: user, content: 写一首关于秋天的诗}], streamTrue ) for chunk in response: content chunk.choices[0].delta.content if content: print(content, end, flushTrue)异步版本用acompletionimport asyncio from litellm import acompletion async def main(): response await acompletion( modelgpt-4, messages[{role: user, content: 你好}] ) print(response.choices[0].message.content) asyncio.run(main())异步在高并发场景下非常关键。我之前做一个批量内容生成的工具同步调用100条要等好几分钟改成异步并发后缩短到十几秒。4. 多模型路由与降级策略让应用更稳的关键配置4.1 模型别名让代码和具体模型解耦实际项目中我强烈建议用模型别名。原因很简单今天用GPT-4明天可能因为成本或合规原因换成别的如果代码里到处写死模型名切换时改起来很痛苦。配置方式import litellm litellm.model_alias { default: gpt-4, fast: gpt-3.5-turbo, cheap: claude-3-haiku-20240307 } response completion( modeldefault, messages[{role: user, content: 你好}] )这样代码里只用别名切换模型时改配置就行。4.2 降级与重试一个模型挂了自动切下一个这是LiteLLM很实用的一个功能。生产环境中某个厂商的API偶尔会抽风如果只有一个模型服务就挂了。用fallback配置可以自动切换response completion( modelgpt-4, messages[{role: user, content: 你好}], fallbacks[claude-3-sonnet-20240229, gpt-3.5-turbo] )当gpt-4调用失败时会自动尝试claude再失败就试gpt-3.5-turbo。重试配置response completion( modelgpt-4, messages[{role: user, content: 你好}], num_retries3, timeout30 )num_retries控制重试次数timeout控制超时时间。我的经验是对于推理类任务timeout设60秒比较稳妥太短容易误杀正常请求。4.3 负载均衡多个key轮询分摊压力如果你有多个API Key比如团队共用可以用轮询方式分摊response completion( modelgpt-4, messages[{role: user, content: 你好}], api_key[key1, key2, key3] )LiteLLM会自动轮询使用这些key。这在做压测或者key有速率限制时很有用。实操心得fallback的顺序有讲究。我一般把质量最好的放第一位性价比高的放第二位最便宜的放最后兜底。这样正常情况用最好的出问题时降级到能用的不至于服务中断。5. 代理服务模式把LiteLLM变成一个统一的API网关5.1 为什么需要代理模式前面讲的都是Python代码里调用LiteLLM。但如果你团队里有多个项目有的用Python、有的用Node.js、有的用Go总不能每个语言都集成一遍LiteLLM。代理模式解决的就是这个问题把LiteLLM跑成一个HTTP服务对外暴露OpenAI兼容的API。任何语言、任何工具只要能发HTTP请求就能通过它调用所有模型。5.2 配置文件详解与启动步骤先写一个配置文件config.yamlmodel_list: - model_name: gpt-4 litellm_params: model: gpt-4 api_key: os.environ/OPENAI_API_KEY - model_name: claude litellm_params: model: claude-3-sonnet-20240229 api_key: os.environ/ANTHROPIC_API_KEY general_settings: master_key: sk-你的管理密钥启动服务litellm --config config.yaml --port 4000启动后你就可以用任何HTTP客户端调用curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的管理密钥 \ -d { model: gpt-4, messages: [{role: user, content: 你好}] }5.3 代理模式下的用量追踪与成本控制代理模式自带用量记录功能可以在配置里开启general_settings: master_key: sk-你的管理密钥 database_url: postgresql://user:passlocalhost:5432/litellm配上数据库后每次调用的token消耗、费用、延迟都会被记录可以在管理界面查看。对于需要控制成本的团队来说这个功能很实用。我自己的用法是给每个项目分配一个虚拟key设置月度预算上限超了就拒绝请求。这样能有效防止某个项目意外跑飞导致账单爆炸。6. 踩坑实录那些文档里没写的注意事项6.1 参数映射的坑不是所有参数都能通用LiteLLM虽然做了参数映射但不同厂商支持的参数集不完全一样。比如OpenAI的logit_bias、presence_penalty这些参数很多国产模型根本不支持。传了不支持的参数有的厂商会忽略有的会直接报错。我的做法是只传最通用的参数model、messages、temperature、max_tokens、stream其他参数按厂商分别处理。如果确实需要某个厂商特有的功能用extra_body传response completion( model某国产模型, messages[{role: user, content: 你好}], extra_body{某厂商特有参数: 值} )6.2 流式输出的边界情况空chunk和异常中断流式输出时偶尔会遇到chunk里delta.content为None的情况直接拼接会报错。稳妥的写法是加判断for chunk in response: if chunk.choices and chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end)另外网络中断时流可能突然断掉要做好异常捕获和重连逻辑。我在生产环境里加了一层包装记录已经输出的内容断掉后从断点继续。6.3 版本升级带来的兼容性问题LiteLLM更新很频繁偶尔会有breaking change。我有一次升级后原来能跑的fallback配置突然不生效了排查半天发现是新版本改了参数名。建议生产环境锁定版本号升级前先在测试环境验证。用pip install litellm指定版本来锁定。6.4 本地模型接入的常见问题接入本地部署的模型时最常见的问题是base_url配置。如果你本地跑了一个兼容OpenAI格式的服务配置方式response completion( modelopenai/你的模型名, messages[{role: user, content: 你好}], api_basehttp://localhost:8000/v1, api_key随便填一个 )注意model前面要加openai/前缀告诉LiteLLM用OpenAI兼容协议。api_key本地服务通常不校验但有些实现要求非空随便填一个就行。7. 几个典型场景的完整实现思路7.1 场景一多模型A/B测试框架做模型对比时可以用LiteLLM快速搭建测试框架import litellm from litellm import completion models [gpt-4, claude-3-sonnet-20240229, 通义千问模型名] prompt 解释一下什么是注意力机制 results {} for model in models: try: response completion( modelmodel, messages[{role: user, content: prompt}], timeout60 ) results[model] { content: response.choices[0].message.content, tokens: response.usage.total_tokens, cost: litellm.completion_cost(response) } except Exception as e: results[model] {error: str(e)}completion_cost能直接算出这次调用的费用做成本对比很方便。7.2 场景二成本敏感的智能路由根据问题复杂度自动选择模型def smart_route(question): # 简单问题用便宜模型 if len(question) 50: model gpt-3.5-turbo else: model gpt-4 return completion( modelmodel, messages[{role: user, content: question}] )实际实现可以更精细比如先用小模型判断问题类型再路由到合适的模型。这套逻辑配合LiteLLM的别名机制切换底层模型时上层代码完全不用动。7.3 场景三带缓存的重复请求优化LiteLLM支持缓存相同请求直接返回缓存结果import litellm litellm.cache litellm.Cache(typelocal) response completion( modelgpt-4, messages[{role: user, content: 你好}], cachingTrue )对于FAQ类场景缓存能大幅降低成本。不过要注意缓存key是基于请求内容的如果temperature不为0相同请求可能期望不同结果这时候要谨慎使用。8. 我个人的使用建议与选型参考用了一年多LiteLLM说几点真实体会。适合用的场景需要快速切换模型做验证、多模型fallback保证可用性、团队多语言项目需要统一网关、想低成本做模型对比测试。这些场景下LiteLLM能省掉大量适配工作。不太适合的场景只需要调用单一模型且不打算换、对延迟极度敏感虽然差异很小但确实存在、需要用到某厂商非常底层的特有功能。这些情况下直接调SDK可能更合适。版本选择生产环境建议用稳定版不要追最新。我一般等新版本发布两周后再升级让社区先踩踩坑。监控不能省不管用不用代理模式都要记录每次调用的模型、耗时、token数、是否成功。这些数据是后续优化和排查问题的依据。最后说一个容易被忽略的点LiteLLM的异常类型做了统一封装捕获litellm.exceptions下的异常比捕获各厂商原生异常方便得多。建议在代码里统一处理RateLimitError、Timeout、APIError这几类配合重试和fallback服务的稳定性会有明显提升。