1. 从一个真实困境说起多模型调用的碎片化之痛如果你正在做AI应用开发大概率遇到过这样的场景项目初期用OpenAI的接口跑通了原型效果不错上线后老板说“能不能加个Claude做对比”你硬着头皮写了一套Anthropic的调用逻辑过了两周产品经理又说“国内用户访问不稳定加个国产模型兜底”于是你又去翻某国产大模型的文档发现参数命名、返回结构、流式格式全都不一样。最后你的代码里散落着四五套SDK的调用代码每套都有自己的鉴权方式、错误码体系和重试逻辑维护成本高得离谱。这就是litellm要解决的核心问题。它本质上是一个统一的LLM调用中间层——用一套OpenAI格式的接口去调用市面上几乎所有主流大模型服务。你不需要为每个模型单独装SDK、单独写适配代码只需要把模型名改一下其余调用方式完全不变。对于需要做多模型对比、模型路由、成本优化的团队来说这东西能省掉大量重复劳动。这篇文章适合三类人看一是正在做AI应用、被多模型适配折磨的开发者二是想快速对比不同模型效果、但不想写一堆胶水代码的技术选型人员三是对LLM工程化感兴趣、想了解统一调用层设计思路的从业者。我会从实际使用角度出发把litellm的核心机制、接入方式、踩坑经验和进阶玩法讲透尽量做到看完就能上手。2. litellm到底做了什么统一接口的底层逻辑2.1 核心设计思路把差异吃掉只暴露标准格式litellm最核心的价值用一句话概括就是输入标准化输出标准化中间的差异由它来消化。你调用的时候请求体格式跟调OpenAI的ChatCompletion一模一样——model、messages、temperature、stream这些字段然后litellm在内部做三件事第一根据model参数识别你要调哪家服务。比如gpt-4o走OpenAIclaude-3-5-sonnet走Anthropicgemini/gemini-1.5-pro走Googledeepseek/deepseek-chat走DeepSeek。它内置了一个模型映射表把模型名和对应的Provider绑定起来。第二把标准格式的请求翻译成目标服务的原生格式。不同厂商的API差异其实很大——Anthropic要求system消息单独放在顶层参数里而不是塞在messages数组里Google的Gemini用contents而不是messages角色名也不一样有些国产模型对temperature的取值范围要求不同。这些细节litellm都帮你处理了。第三把目标服务的返回结果再翻译回OpenAI格式。不管你调的是哪家拿到的response结构都是choices[0].message.content这种标准形态流式返回的chunk格式也统一成delta.content。这意味着你的上层业务代码完全不需要改。这种设计的好处很直接你的业务逻辑和具体模型解耦了。今天用GPT-4明天想换成Claude改一个字符串就行。想做A/B测试循环里换个模型名就完事。2.2 支持的模型范围与Provider覆盖litellm目前支持的Provider数量已经超过100个覆盖了几乎所有你能想到的主流服务。我按类别梳理一下常见的类别代表模型/服务调用前缀示例国际主流OpenAI GPT系列、Anthropic Claude系列、Google Gemini系列gpt-4o、claude-3-5-sonnet、gemini/gemini-1.5-pro开源托管Together AI、Fireworks、Replicatetogether_ai/...、fireworks_ai/...云厂商Azure OpenAI、AWS Bedrock、Vertex AIazure/...、bedrock/...、vertex_ai/...国产模型DeepSeek、通义千问、智谱、Moonshot等deepseek/...、dashscope/...本地部署Ollama、vLLM、LM Studioollama/...、openai/...兼容接口这里有个细节值得注意很多国产模型和本地部署方案都提供了OpenAI兼容接口所以litellm对这类服务的支持本质上是通过openai/前缀加上自定义api_base来实现的。比如你本地用Ollama跑了个qwen2.5调用时写modelopenai/qwen2.5然后设置api_basehttp://localhost:11434/v1就行。提示模型名前缀不是必须的litellm会尝试自动识别。但在多Provider混用的场景下显式加前缀能避免歧义尤其是当不同厂商有同名模型时。2.3 与直接装各家SDK的方案对比很多人会问我直接装openai、anthropic、google-generativeai这几个包自己写个if-else分发不就行了为什么要多引入一层litellm这个问题我实际对比过结论是小项目自己写分发没问题但一旦涉及三个以上Providerlitellm的优势就非常明显了。具体差异看下表对比维度自己写分发用litellm新增一个Provider装SDK、读文档、写适配、测返回格式改模型名字符串流式输出统一每家chunk格式不同要分别处理统一为OpenAI chunk格式错误重试每家异常类型不同要分别捕获统一异常体系内置重试成本追踪需要自己解析各家的usage字段内置token计数和成本计算降级容灾自己写fallback逻辑配置fallback列表即可维护成本随Provider数量线性增长基本恒定当然litellm也不是没有代价——它多了一层抽象极端情况下会有轻微的性能开销而且当某家Provider出了新特性时litellm需要时间跟进。但对于绝大多数应用场景来说这些代价远小于它带来的便利。3. 从零接入环境准备与第一个可跑通的调用3.1 安装与最小依赖配置litellm的安装非常轻量核心包不强制依赖任何厂商的SDKpip install litellm就这一条命令。它不会把openai、anthropic这些包全给你装上而是按需导入——你调哪家它才去import对应的库。如果你确定要用某几家可以装带extra的版本pip install litellm[openai,anthropic]环境变量方面各家API Key的命名规则litellm已经约定好了你只需要按规范设置export OPENAI_API_KEYsk-... export ANTHROPIC_API_KEYsk-ant-... export DEEPSEEK_API_KEYsk-...注意API Key千万不要硬编码在代码里。litellm会自动从环境变量读取这是最安全的做法。如果要做多租户可以用api_key参数在调用时动态传入。3.2 第一个调用三行代码跑通GPT-4o装好之后最简单的调用长这样from litellm import completion response completion( modelgpt-4o, messages[{role: user, content: 用一句话解释什么是统一调用层}] ) print(response.choices[0].message.content)如果你之前用过OpenAI的SDK会发现这几乎一模一样——只是把openai.chat.completions.create换成了litellm.completion。返回对象的结构也完全兼容response.choices[0].message.content、response.usage.prompt_tokens这些字段都能直接用。3.3 切换到其他模型只改一个字符串现在把模型换成Clauderesponse completion( modelclaude-3-5-sonnet-20241022, messages[{role: user, content: 用一句话解释什么是统一调用层}] )再换成Geminiresponse completion( modelgemini/gemini-1.5-pro, messages[{role: user, content: 用一句话解释什么是统一调用层}] )再换成DeepSeekresponse completion( modeldeepseek/deepseek-chat, messages[{role: user, content: 用一句话解释什么是统一调用层}] )除了model参数其他代码一个字都不用改。这就是litellm最直观的价值。你可以在一个循环里遍历模型列表批量跑对比测试代码量极少。3.4 流式输出的统一处理流式输出是很多应用的刚需litellm在这块也做了统一。开启方式跟OpenAI一致response completion( modelclaude-3-5-sonnet-20241022, messages[{role: user, content: 写一段200字的产品介绍}], streamTrue ) for chunk in response: content chunk.choices[0].delta.content if content: print(content, end, flushTrue)不管你调的是哪家模型拿到的chunk结构都是chunk.choices[0].delta.content。这一点非常关键——如果你自己写分发Anthropic的流式事件类型和OpenAI完全不同处理起来要写两套逻辑。litellm把这层差异抹平了。实操心得流式场景下有些Provider的首包延迟明显高于其他家。如果你做的是实时对话产品建议在litellm之上再加一层超时控制比如设置timeout10超时后自动切到备用模型。4. 进阶玩法路由、降级与成本控制4.1 用Router做多模型负载均衡当你的应用有一定规模后单一模型往往不够用——可能因为限流、成本、可用性等原因需要多模型配合。litellm提供了Router类来做这件事from litellm import Router router Router( model_list[ { model_name: gpt-4, litellm_params: { model: gpt-4o, api_key: sk-... } }, { model_name: gpt-4, litellm_params: { model: claude-3-5-sonnet-20241022, api_key: sk-ant-... } } ], routing_strategysimple-shuffle ) response router.completion( modelgpt-4, messages[{role: user, content: 你好}] )这里的关键设计是多个实际模型可以映射到同一个model_name。上层业务只管调gpt-4Router在底层按策略选择一个实际模型。routing_strategy支持多种模式simple-shuffle随机打散适合负载均衡least-busy选当前并发最低的usage-based-routing按token用量做均衡latency-based-routing按历史延迟选最快的这个设计的好处是业务代码完全不需要感知底层有几个模型在跑。你想加一个新模型进来分担流量只需要在model_list里加一条配置。4.2 Fallback机制主模型挂了自动切换生产环境最怕的就是某个模型服务突然不可用。litellm的fallback机制可以在主模型调用失败时自动切到备用模型response completion( modelgpt-4o, messages[{role: user, content: 你好}], fallbacks[claude-3-5-sonnet-20241022, deepseek/deepseek-chat] )当gpt-4o调用抛出异常时litellm会依次尝试fallback列表里的模型。这个机制配合Router使用效果更好——你可以给每个模型配置多个fallback形成一张容灾网。注意fallback不是万能的。如果主模型是因为内容审核拒绝而失败切到备用模型可能同样被拒。建议在业务层区分“技术性失败”和“内容性失败”只对前者做fallback。4.3 成本追踪与预算控制litellm内置了成本计算功能每次调用后可以从response里拿到本次消耗的美元成本response completion( modelgpt-4o, messages[{role: user, content: 你好}] ) cost response._hidden_params.get(response_cost, 0) print(f本次调用成本: ${cost:.6f})它维护了一张各模型的单价表会根据prompt_tokens和completion_tokens自动算出费用。对于需要做成本核算的团队来说这个功能省去了自己维护价格表的麻烦。更进一步你可以用max_budget参数做预算控制from litellm import completion response completion( modelgpt-4o, messages[{role: user, content: 你好}], max_budget0.01 # 单次调用最多花1美分 )超过预算会直接抛异常。这个在给用户提供免费额度、或者做内部成本管控时很有用。5. 踩坑实录那些文档里不会写的细节5.1 模型名写错时的报错信息不够直观litellm的模型名映射表虽然覆盖很广但如果你写了一个它不认识的模型名报错信息有时候比较模糊。比如你写modelgpt4少了横杠它可能不会直接告诉你“模型名不存在”而是抛一个Provider相关的异常。我的经验是先用litellm的get_supported_openai_params或者直接查它的模型映射文件确认模型名。另外对于OpenAI兼容的第三方服务统一用openai/前缀加api_base的方式最稳妥不要指望litellm能自动识别所有小众服务。5.2 不同Provider对参数的支持程度不一致这是实际使用中最容易踩的坑。OpenAI支持的某些参数其他Provider可能不支持。比如response_format{type: json_object}OpenAI支持但很多国产模型不支持seed参数部分模型支持部分忽略logprobs支持范围更窄tool_choice的取值各家实现有差异litellm的策略是不支持的参数会被静默忽略而不是报错。这看起来友好但实际上很危险——你以为传了response_format就会返回JSON结果模型返回了一堆自然语言解析直接崩掉。实操建议如果你的业务依赖某个特定参数一定要在目标模型上单独验证。不要假设“litellm统一了接口”就等于“所有模型行为一致”。接口统一了能力并没有统一。5.3 流式场景下的异常处理流式调用时异常可能发生在两个阶段建立连接阶段和流式传输中途。litellm对前者的处理比较完善但后者——也就是流到一半Provider突然断开——需要你自己在业务层做处理。我遇到过的情况是流式输出到一半网络抖动导致连接断开litellm抛出一个APIError但此时已经有一部分内容输出给用户了。如果直接重试会导致内容重复。正确的做法是记录已输出的内容长度重试时用messages把已输出部分带上让模型接着写。5.4 超时设置要区分连接超时和读取超时litellm的timeout参数控制的是整体超时但实际使用中你会发现有些模型首包很慢但后续流式输出很快有些则相反。建议的做法是response completion( modelclaude-3-5-sonnet-20241022, messages[...], timeout30, # 整体超时 streamTrue )对于流式场景30秒的整体超时通常够用。但如果你调的是推理型模型比如o1系列首包可能要等几十秒这时候需要把timeout调大。不要用同一个超时值套所有模型这是很多人容易忽略的点。6. 代理服务模式把litellm变成团队的基础设施6.1 启动一个统一的API网关litellm除了作为Python库使用还提供了一个代理服务模式——启动一个HTTP服务对外暴露OpenAI兼容的API。这样团队里不同语言、不同项目的成员都可以通过这个统一入口调用各种模型litellm --model gpt-4o --port 8000或者用配置文件启动# config.yaml model_list: - model_name: gpt-4o litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude litellm_params: model: claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEYlitellm --config config.yaml --port 8000启动后任何支持OpenAI接口的客户端都可以连上来把base_url指向http://localhost:8000即可。这意味着团队里用LangChain的、用LlamaIndex的、甚至用curl的都能共用一套模型接入配置。6.2 虚拟Key与权限管理代理模式下litellm支持生成虚拟Key来做权限控制和用量追踪curl -X POST http://localhost:8000/key/generate \ -H Authorization: Bearer master-key \ -d {models: [gpt-4o], max_budget: 10}生成的虚拟Key可以限制能访问哪些模型、总预算多少、速率上限多少。这对于团队内部管理非常实用——每个人拿自己的Key用量和费用一目了然不用担心某个人的Key泄露导致账单爆炸。6.3 日志与可观测性接入litellm支持把调用日志推送到多种可观测性平台比如Langfuse、Helicone、OTEL等。配置方式通常是在环境变量里设置对应的回调export LANGFUSE_PUBLIC_KEYpk-... export LANGFUSE_SECRET_KEYsk-...然后在调用时加上success_callback参数。这样每次调用的输入输出、token用量、延迟、成本都会自动上报方便做分析和告警。实操心得生产环境强烈建议开启日志上报。多模型场景下不同Provider的延迟和稳定性差异很大没有数据支撑你根本不知道哪个模型在什么时段表现好。我见过太多团队凭感觉选模型结果实际数据一拉出来结论完全相反。7. 我个人的使用体会litellm这个工具我用了大概半年多最大的感受是它把“多模型适配”这件事从工程问题变成了配置问题。以前加一个新模型要改代码、测试、发版现在改一行配置就行。对于快速迭代的AI应用来说这种灵活性价值很大。但它也不是银弹。抽象层带来的问题是当你想用某个模型的独有特性时可能会被这层抽象挡住。比如Anthropic的prompt caching、OpenAI的structured output这些特性litellm虽然部分支持但用起来不如原生SDK直接。我的建议是日常调用走litellm需要深度使用某家独有特性时直接调原生SDK。两者并不冲突可以在同一个项目里共存。另外一个小技巧如果你做的是需要频繁切换模型的对比测试可以写一个简单的封装函数把模型名、API Key、base_url做成配置字典配合litellm的completion批量跑。我自己的对比测试脚本就是这么写的跑十几个模型的效果对比代码不到50行。