1. 从一个真实困境说起多模型调用的碎片化之痛如果你正在做AI应用开发大概率遇到过这样的场景项目初期用OpenAI的接口跑通了原型效果不错上线后老板说“能不能换成国产模型降降成本”或者“某个任务用Claude效果更好能不能混着用”。这时候你打开代码一看每个模型的SDK调用方式、参数命名、返回结构、流式输出格式全都不一样光是适配层就够写一个礼拜。更别提还有那些细碎但致命的差异有的模型用max_tokens有的用max_output_tokens有的返回choices[0].message.content有的返回content[0].text流式输出的chunk结构更是五花八门。你写了一套又一套的适配代码测试用例翻了三倍维护成本直线上升。这就是litellm要解决的核心问题。它做的事情用一句话概括用一套OpenAI格式的接口调用市面上几乎所有主流大模型。你只需要把base_url和api_key换一下代码几乎不用动就能在GPT、Claude、Gemini、通义千问、DeepSeek、Moonshot等模型之间自由切换。对于需要做模型对比、成本优化、多模型路由的团队来说这个价值是实打实的。这篇文章我会从实际使用角度出发把litellm的安装配置、核心用法、代理模式、成本追踪、踩坑经验全部讲清楚。不管你是刚接触多模型调用的新手还是已经在做AI应用架构的老手都能从中找到可以直接抄作业的内容。2. litellm到底解决了什么问题核心价值拆解2.1 统一接口背后的设计哲学litellm最核心的设计思路是协议转换。它把各家模型的API协议统一映射到OpenAI的Chat Completions格式上。你调用litellm.completion()的时候传入的是OpenAI风格的参数litellm在内部做三件事第一根据模型名前缀识别目标提供商。比如gpt-4o走OpenAIclaude-3-5-sonnet走Anthropicgemini/gemini-1.5-pro走Googledeepseek/deepseek-chat走DeepSeek。这个前缀路由机制是litellm的基石。第二把统一的参数翻译成各家API能理解的格式。比如你传max_tokens1000litellm会根据目标提供商转换成对应的参数名。你传messages数组它会处理成Anthropic需要的system分离格式或者Gemini需要的contents结构。第三把各家返回的结果统一成OpenAI的响应对象。不管你调的是哪个模型拿到的都是ModelResponse对象有统一的.choices[0].message.content、.usage.total_tokens等属性。这个设计的好处在于你的业务代码只依赖一套接口模型切换变成配置层面的操作而不是代码重构。2.2 和直接调用SDK相比的取舍有人会问我直接用各家官方SDK不行吗当然行但你要接受几个现实学习成本叠加每接一个新模型就要读一遍它的文档理解它的参数体系和返回结构。代码分支膨胀业务逻辑里到处是if model gpt else if model claude的判断。测试矩阵爆炸每加一个模型回归测试的组合数就翻倍。成本追踪困难不同模型的计费方式不同想统一统计花了多少钱得自己写一套聚合逻辑。litellm的取舍是牺牲一点点“原生SDK的独有特性”比如某些模型特有的高级参数换取开发效率和维护成本的显著降低。对于绝大多数应用场景来说这个交换是划算的。而且litellm也支持通过extra_body或provider_specific_params传入各家特有的参数灵活性并没有完全丧失。2.3 谁最适合用litellm根据我的观察以下几类场景用litellm收益最大做模型对比评测的团队同一套测试集切换模型名就能跑省去大量适配工作。需要成本优化的产品简单任务走便宜模型复杂任务走贵模型litellm的路由能力让这件事变得简单。多模型容灾的系统主模型挂了自动切备用模型litellm的fallback机制开箱即用。快速原型验证不想在适配层浪费时间想快速验证产品逻辑的开发者。反过来如果你的项目只用一家模型且不打算换或者你需要用到某个模型非常底层的独有功能那直接调原生SDK可能更合适。3. 环境搭建与第一行代码从零跑通3.1 安装与依赖管理litellm的安装非常直接pip install litellm如果你需要用到代理服务器功能建议装完整版pip install litellm[proxy]这里有个经验强烈建议在虚拟环境里安装。litellm的依赖树不算浅它需要兼容多家SDK的HTTP客户端和数据处理库直接装在全局环境容易和其他项目冲突。我一般用python -m venv venv建一个干净环境或者用conda单独开一个。另外litellm的版本迭代比较快建议在requirements.txt里锁定版本号比如litellm1.52.0避免某天自动升级后接口行为变化导致线上问题。我就遇到过一个小版本升级后流式输出的chunk结构微调导致前端解析报错的情况。3.2 API Key的配置方式litellm读取API Key的方式很灵活优先级从高到低大致是调用时直接传参api_keysk-xxx环境变量os.environ[OPENAI_API_KEY] sk-xxx配置文件通过litellm.set_key()或代理模式的config.yaml对于多模型场景我建议统一用环境变量管理命名规则遵循litellm的约定export OPENAI_API_KEYsk-xxx export ANTHROPIC_API_KEYsk-ant-xxx export GEMINI_API_KEYxxx export DEEPSEEK_API_KEYsk-xxx注意不要把API Key硬编码在代码里提交到版本库。我见过太多因为Key泄露导致账单暴涨的案例。用.env文件配合python-dotenv是更稳妥的做法。3.3 最简调用示例与参数解读跑通第一个调用的代码短得让人意外from litellm import completion response completion( modelgpt-4o-mini, messages[ {role: system, content: 你是一个简洁的助手。}, {role: user, content: 用一句话解释什么是向量数据库。} ] ) print(response.choices[0].message.content)换成Claude只需要改model参数response completion( modelclaude-3-5-sonnet-20241022, messages[{role: user, content: 你好}] )这里有几个参数值得展开说model支持前缀路由比如anthropic/claude-3-5-sonnet、gemini/gemini-1.5-flash。有些模型名不带前缀litellm也能识别但带上更稳妥。messages标准OpenAI格式system消息会被litellm自动转换成目标模型需要的形式。temperature、top_p、max_tokens这些通用参数litellm会做映射但注意不同模型对取值范围的限制不同。stream设为True时返回生成器流式输出的处理方式见下一节。3.4 流式输出的统一处理流式输出是多模型调用里最容易出问题的地方因为各家的chunk结构差异很大。litellm帮你抹平了这些差异response completion( modelclaude-3-5-sonnet-20241022, messages[{role: user, content: 写一首关于秋天的短诗}], streamTrue ) for chunk in response: delta chunk.choices[0].delta if delta.content: print(delta.content, end, flushTrue)不管你调的是哪个模型拿到的chunk都是统一的ModelResponse结构delta.content就是增量文本。这个统一化处理省去了大量前端适配工作。但有个坑要注意不是所有模型的流式输出都包含usage信息。OpenAI默认在最后一个chunk里带usage但有些模型需要额外参数才返回。如果你需要精确统计token消耗建议在流式场景下用litellm的stream_options{include_usage: True}或者干脆用非流式调用做统计。4. 代理模式把litellm变成团队的基础设施4.1 为什么需要代理层直接在代码里调litellm库适合个人开发但团队协作场景下代理模式Proxy的价值就体现出来了统一入口所有模型调用走同一个网关方便做鉴权、限流、日志。Key集中管理API Key放在服务端客户端不需要知道真实Key。配置热更新改模型路由规则不用重新部署业务代码。成本可视化代理层天然适合做用量统计和费用追踪。litellm的代理模式本质上是一个FastAPI服务对外暴露OpenAI兼容的接口。你的业务代码把base_url指向这个代理就像调OpenAI一样调所有模型。4.2 config.yaml的编写要点启动代理需要一个配置文件典型结构如下model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude-sonnet litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY - model_name: deepseek-chat litellm_params: model: deepseek/deepseek-chat api_key: os.environ/DEEPSEEK_API_KEY general_settings: master_key: sk-your-master-key database_url: postgresql://user:passlocalhost:5432/litellm几个关键点model_name是对外暴露的别名客户端用这个名字调用。你可以起一个业务友好的名字比如fast-model、smart-model底层具体用哪个模型由配置决定。litellm_params.model是实际的目标模型带提供商前缀。api_key用os.environ/前缀表示从环境变量读取避免明文写在配置文件里。master_key是代理的访问密钥客户端需要带上它才能调用。database_url是可选的配了之后才能用用量追踪、预算控制等高级功能。4.3 启动服务与客户端对接启动命令litellm --config config.yaml --port 4000客户端调用方式from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000, api_keysk-your-master-key ) response client.chat.completions.create( modelclaude-sonnet, messages[{role: user, content: 你好}] )注意这里用的是官方OpenAI SDK不是litellm库。因为代理层暴露的就是OpenAI兼容接口任何支持自定义base_url的OpenAI客户端都能直接用。这意味着你现有的代码几乎不用改只需要把base_url和api_key换掉。4.4 多实例部署与负载均衡生产环境下单个代理实例可能扛不住高并发。litellm支持在config里配置多个同名的模型实例自动做负载均衡model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY_1 - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY_2两个实例用同一个model_namelitellm会在它们之间轮询。这个机制在做多Key轮换或者多区域部署时很有用。提示负载均衡策略可以通过routing_strategy参数调整支持simple-shuffle、least-busy、usage-based-routing等。高并发场景建议用least-busy避免请求堆积在某个实例上。5. 成本追踪与预算控制让每一分钱都花得明白5.1 token计费的基本逻辑多模型调用最让人头疼的问题之一就是成本不透明。不同模型的计费单价不同输入输出价格还不一样想算清楚一个月花了多少钱手工统计几乎不可能。litellm内置了主流模型的价格表每次调用后可以通过response.usage拿到token消耗再结合价格表算出费用from litellm import completion, completion_cost response completion( modelgpt-4o, messages[{role: user, content: 你好}] ) cost completion_cost(completion_responseresponse) print(f本次调用花费: ${cost:.6f})completion_cost会自动根据模型名和token用量计算费用。这个功能在代理模式下更强大所有经过代理的调用都会被记录可以在数据库里做聚合分析。5.2 预算与限流的配置方法在代理模式的config里可以给每个Key或每个用户设置预算上限general_settings: master_key: sk-master litellm_settings: max_budget: 100 budget_duration: 30d更细粒度的控制可以通过虚拟Key实现。给每个团队成员或每个应用分配一个虚拟Key设置独立的预算和速率限制curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-master \ -d {max_budget: 10, budget_duration: 7d, models: [gpt-4o-mini]}这样每个Key最多花10美元7天重置一次且只能调指定的模型。对于控制团队成本来说这个功能非常实用。5.3 用量数据的查询与导出配了数据库之后所有调用记录都会落库。litellm提供了一些内置的查询接口也可以直接查数据库表SELECT model, SUM(total_tokens) as total_tokens, SUM(spend) as total_spend FROM LiteLLM_SpendLogs WHERE startTime NOW() - INTERVAL 30 days GROUP BY model ORDER BY total_spend DESC;这个查询能告诉你过去30天每个模型花了多少钱、用了多少token。对于做成本优化决策来说这是最直接的数据支撑。我自己的经验是每周看一次用量报表重点关注那些单价高但调用量大的模型评估是否有更便宜的替代方案。很多时候把一些简单任务从旗舰模型切到轻量模型成本能降一个数量级效果差异却很小。6. 踩坑实录那些文档里不会写的经验6.1 模型名映射的常见错误litellm的模型名路由依赖前缀识别但有些模型的命名规则容易搞混。比如claude-3-5-sonnet和claude-3-5-sonnet-20241022是两个不同的标识前者可能指向最新版本后者是固定版本。生产环境建议用带日期的固定版本避免模型更新导致行为变化。Gemini的模型名需要gemini/前缀比如gemini/gemini-1.5-pro漏掉前缀会报模型找不到。有些国产模型在litellm里的命名和官方文档不完全一致建议先用litellm.model_list查一下支持的模型名。我踩过的一个坑把deepseek-chat写成了deepseek/deepseek-chat结果litellm把它当成了自定义提供商报了一个很模糊的连接错误。排查了半天才发现是前缀问题。6.2 流式输出中断的处理流式输出在网络不稳定时容易中断litellm默认不会自动重试流式请求。如果你的应用对稳定性要求高建议在客户端做重试逻辑import time def stream_with_retry(model, messages, max_retries3): for attempt in range(max_retries): try: response completion(modelmodel, messagesmessages, streamTrue) for chunk in response: yield chunk return except Exception as e: if attempt max_retries - 1: raise time.sleep(2 ** attempt)指数退避重试是个好习惯但要注意流式请求重试可能导致重复输出。如果已经输出了部分内容再重试用户会看到重复文本。更稳妥的做法是在重试前记录已输出的位置或者干脆在流式场景下不做自动重试而是提示用户重新发起。6.3 超时与并发限制的调优litellm的默认超时时间可能不适合所有场景。对于推理型模型比如o1系列响应时间可能长达几分钟默认超时会导致请求被切断response completion( modelo1-mini, messages[{role: user, content: 解一道复杂的数学题}], timeout300 )并发方面litellm本身没有硬性限制但各家API都有速率限制。代理模式下可以通过router_settings配置并发控制router_settings: num_retries: 3 timeout: 300 allowed_fails: 3 cooldown_time: 60allowed_fails和cooldown_time的配合很关键当某个模型连续失败3次后会被冷却60秒期间请求自动路由到其他可用模型。这个机制在多模型容灾场景下非常有用。6.4 不同模型参数兼容性对照下面这张表是我在实际使用中总结的常见参数差异供参考参数OpenAIAnthropicGemini注意事项max_tokens支持必填支持Claude必须显式指定temperature0-20-10-2范围不同litellm会截断system消息messages中独立参数独立参数litellm自动转换流式usage需显式开启默认返回默认返回统计时注意多模态输入image_urlbase64inline_datalitellm统一为image_url这张表不是让你背而是提醒你切换模型时先小流量验证参数行为别直接全量切。7. 进阶玩法路由策略与多模型协作7.1 基于任务复杂度的模型路由litellm支持在代理层配置路由规则根据请求特征自动选择模型。最简单的做法是按模型名路由但更高级的玩法是根据token数量或关键词做动态路由。一个实用的模式是简单任务走便宜模型复杂任务走旗舰模型。可以通过在客户端做初步判断然后调用不同的model_name来实现。比如def smart_completion(user_input): if len(user_input) 50: model gpt-4o-mini else: model gpt-4o return completion(modelmodel, messages[{role: user, content: user_input}])这个逻辑放在客户端还是代理层取决于你的架构。放在代理层的好处是业务代码无感知但需要litellm支持自定义路由函数通过custom_routing_strategy实现。7.2 fallback机制保障服务可用性多模型容灾是litellm的强项。在config里配置fallback链litellm_settings: fallbacks: [{gpt-4o: [claude-sonnet, deepseek-chat]}]当gpt-4o调用失败时自动依次尝试claude-sonnet和deepseek-chat。这个机制对于保障服务可用性非常关键尤其是当某个提供商出现区域性故障时。但要注意fallback不是万能的。不同模型的输出风格和能力有差异fallback后的结果可能和预期不一致。建议在fallback时记录日志方便后续分析。7.3 缓存策略降低重复调用成本对于重复性高的查询开启缓存能显著降低成本。litellm支持内存缓存和Redis缓存import litellm litellm.cache litellm.Cache(typeredis, hostlocalhost, port6379) response completion( modelgpt-4o, messages[{role: user, content: 什么是机器学习}], cachingTrue )同样的请求第二次调用时直接返回缓存结果不消耗token。对于FAQ类应用或者测试环境这个功能能省下不少钱。注意缓存key默认基于请求参数生成如果模型版本更新了但缓存没失效可能返回旧结果。建议设置合理的TTL或者在模型切换时手动清理缓存。8. 我个人的使用体会用litellm快一年了最大的感受是它把多模型调用的复杂度从O(n)降到了O(1)。以前每接一个新模型都要写适配层、改测试、调参数现在改一行配置就能跑。对于快速迭代的AI应用来说这种效率提升是实实在在的。但litellm也不是银弹。它的抽象层在某些场景下会带来额外的调试成本——当调用出错时你看到的是litellm包装后的错误信息有时候需要翻源码才能定位到是哪个环节出了问题。我的建议是先用litellm快速跑通遇到疑难问题再深入底层不要一上来就试图理解所有内部机制。另外litellm的社区很活跃版本更新频繁。建议关注它的release notes但不要盲目升级。生产环境锁定版本测试环境先行验证这个原则在litellm上尤其适用。最后分享一个小技巧如果你在代理模式下遇到性能瓶颈可以试试把litellm_settings里的drop_params设为True。这个选项会自动丢弃目标模型不支持的参数避免因为参数不兼容导致的报错同时减少不必要的参数转换开销。我在几个项目里开了这个选项后错误率明显下降。