LiteLLM统一接入多模型：从SDK到代理网关的工程实践-北京尧图网络

做LLM应用最烦的一件事不是模型效果不够好而是“接模型”这件事本身太零碎。前阵子一个朋友跟我聊他的AI助手项目默认对话想用一个模型复杂推理想切到另一个平台的长上下文模型批量总结又要走便宜一点的模型。听起来只是切换几个API的事等他真动手才发现每个服务商的SDK不一样鉴权方式不一样连报错格式都各说各话。他在代码里堆了好几套SDK每接一个新的模型就要重新读一遍文档痛苦得不行。后来他试了LiteLLM算是把这个问题解决得比较干净。LiteLLM做的事情说白了就是给你一个统一的调用入口不管你背后用的是OpenAI系、Anthropic系、Gemini系还是本地的模型服务业务代码都只写一套。它既可以作为Python库直接被调用也可以作为一个代理服务跑起来让所有业务方把自己当成连了一个“OpenAI兼容端点”。我下面写的东西适合正在被多模型接入折磨的人也适合那些想把密钥、成本、重试这些OPS层面的事情统一管起来的人。这篇不会讲太虚的东西直接说清楚它解决什么问题、原理是什么、怎么上手、生产环境要留什么心眼。1. 先从一次“三套SDK在手”的接模型经历说起1.1 最初的乱象代码里堆三套SDK朋友的第一个版本其实是用一个模型做所有事情所以代码很干净一个服务商SDK搞定。后来产品经理提需求有些任务要用不同模型的特性有些任务要对比效果还有些任务得走成本更低的模型。于是模型从一个变成三个代码开始失控。第一个是OpenAI格式的接口用官方Python包client.chat.completions.create(...)返回对象里用choices[0].message.content取文本。第二个是另一家的SDK调用方式完全不同参数里要显式写max_tokens消息结构也略有区别。第三个最麻烦它只提供裸HTTP接口鉴权用的是另一套签名方式返回结果也不是标准的JSON结构。他当时的代码长这样from openai import OpenAI client_a OpenAI(api_keysk-...) resp_a client_a.chat.completions.create( modelgpt-4o, messages[{role: user, content: 你好}], ) answer_a resp_a.choices[0].message.content import anthropic client_b anthropic.Anthropic(api_keysk-ant-...) resp_b client_b.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens1024, messages[{role: user, content: 你好}], ) answer_b resp_b.content[0].text这还只是两个模型如果再来两个整个业务代码里会到处是if provider xxx的分支。更烦的是错误处理一个服务商限流返回429另一个返回RateLimitError还有一个可能直接断连。每一个都要单独写重试逻辑否则线上偶发失败就只能靠人工盯日志。这是多模型接入最真实的痛点不是模型本身难用而是“接入”这件事一点都不标准。1.2 LiteLLM给出的答案一个入口一个返回格式LiteLLM的思路很简单既然各个平台不可能统一格式那就找一个大家都认可的事实标准。当前事实标准就是OpenAI兼容格式很多主流服务商自己都提供了OpenAI兼容端点即使没有LiteLLM也帮你在适配层做转换。于是业务代码只需要认识一种格式就可以了。用LiteLLM之后代码长这样import litellm resp litellm.completion( modelanthropic/claude-3-5-sonnet-20241022, messages[{role: user, content: 你好}], ) answer resp.choices[0].message.content不管是OpenAI、Claude还是Gemini也不管是云服务还是本地Ollama调用方看到的都是同一个choices[0].message.content。model参数里的前缀告诉LiteLLM这个请求要走哪个适配器后面的模型名才是真正的上游模型名。它的角色像一个万能转接头把所有电源插头都转成同一种规格你的设备就再也不用关心插座长什么样了。这个设计对于AI应用开发者特别友好。因为你的核心业务逻辑应该是“输入提示词、拿到输出、做后处理”而不是花时间维护各家SDK的兼容层。LiteLLM帮你把兼容层集中收编了。1.3 它覆盖的能力范围很多人以为LiteLLM只是个“聊天补全转发器”其实它覆盖的能力比你想的多。下面这个表是我实际用过的部分列出来方便你判断够不够用能力类型统一接口形态典型场景对话补全litellm.completion聊天、生成、Agent主流程流式输出streamTrue打字机效果、长回答实时展示函数/工具调用tools参数透传Agent调用外部工具、结构化抽取多模态输入content数组传图片图文理解、OCR、截图问答向量嵌入litellm.embeddingRAG检索、语义相似度模型路由/重试Router/ Proxy配置多后端负载均衡、故障转移密钥与预算管理Proxy虚拟Key团队协作、成本管控实际项目里最常用的还是对话补全和工具调用但如果你做检索增强生成embedding统一接口也能省不少事。以前每接一个Embedding服务就要写一遍调用代码现在同样用litellm.embedding(modelxxx, input[...])就完事了。2. LiteLLM不是SDK封装器而是一个适配层请求流转原理解读2.1 “OpenAI兼容”到底兼容了什么要理解LiteLLM先得理解“OpenAI兼容”这四个字。它不是说你必须用OpenAI官方SDK而是说请求和响应的形状是固定的主要包括四块请求体一个model字段标识模型名一个messages数组表示多轮对话可选参数比如temperature、max_tokens、stream、tools等。响应体choices数组里嵌套messagemessage.content就是文本另外还有usage对象里面有prompt_tokens、completion_tokens。鉴权方式HTTP Header里加Authorization: Bearer key简单直接。错误格式JSON对象里包含错误类型和消息方便代码统一处理。LiteLLM干的事就是让几乎所有主流上游模型都“长成”这个样子。你连的是Claude它把Claude本身的调用协议转换成OpenAI协议你连的是Gemini它同样在中间做一层转换。因为转换发生在LiteLLM内部你的业务代码完全无感。2.2 一次请求在LiteLLM内部怎么走我把一次调用拆开来看方便你理解这个适配层到底做了哪些事客户端调用litellm.completion(modelanthropic/claude-3-5-sonnet-20241022, messages[...])。LiteLLM解析model字符串看到前缀anthropic/知道这一单要走Anthropic适配器。适配器读取配置好的api_key、api_base等参数把OpenAI格式的messages转换成Anthropic协议要求的消息结构。适配器调用上游HTTP接口拿到上游响应。适配器把上游响应转换成OpenAI格式补上choices[0].message.content和usage。返回到业务代码整个调用过程看起来就是一次标准OpenAI调用。如果是Proxy模式步骤里还要多几件事。请求先打到LiteLLM代理服务器服务器检查这个虚拟Key有没有权限、有没有超预算然后决定是继续转发还是直接拒绝。转发过程中如果配置了路由策略还会选择具体用哪个后端实例如果配置了重试遇到可重试错误会自动换一个后端再试一次。这些都发生在你的业务系统和上游模型之间你不需要在自己的代码里实现。2.3 为什么不让厂商“统一协议”而是自己做翻译官有一种思路是“让上游厂商统一协议”但现实里这不可能。商业模型各有各的接口设计有的原生就用流式协议有的是纯HTTP轮询有的消息结构差异很大。指望所有服务商改接口还不如自己找一层适配。适配器模式是最务实的选择。你可以把它想象成插座转换头世界各地的插座标准不统一你不可能要求每个国家都改成同一个标准但只要手上有几个转换头就能带一个万能插头走天下。LiteLLM就是一个大盒子里面装满了各种转换头。它自己暴露一个OpenAI兼容接口因为这是目前生态最通用的“插头规格”几乎所有AI应用开发框架、前端组件、运维工具都已经适配了这一套。理解了这一点你就知道为什么LiteLLM值得被放在基础设施层而不是当成某个“SDK封装器”随便用用。SDK封装器通常只是把某个HTTP接口包成好看的方法而LiteLLM是在请求协议层面做双向转换并且额外承担了路由、预算、审计这些原本属于网关的职责。3. 两条接入路线实测Python直连与代理网关3.1 路线APython SDK直连最小改动接入如果你的项目本身就是Python并且只有少数几个服务需要接入最快的方式就是直接用LiteLLM的SDK模式。安装只要一条命令pip install litellm然后设置环境变量。不同服务商走不同变量名export OPENAI_API_KEYsk-... export ANTHROPIC_API_KEYsk-ant-... export GEMINI_API_KEY...接着就可以调用了。我个人的建议是先开调试日志看清楚请求到底长什么样import litellm litellm.set_verbose True resp litellm.completion( modelopenai/gpt-4o, messages[{role: user, content: 用一句话介绍LiteLLM}], ) print(resp.choices[0].message.content)set_verbose True会打印请求和响应的完整细节第一次调试时特别有用能让你直观看到LiteLLM是怎么做转换的。等确认没问题了再关掉避免生产日志被刷爆。注意model参数里的openai/其实可以省略因为默认前缀就是OpenAI。但如果你调用的是别的平台前缀不能省例如anthropic/claude-3-5-sonnet-20241022、gemini/gemini-1.5-pro、ollama/llama3.1。前缀的作用是告诉LiteLLM走哪个适配器它跟后面的真实模型名是通过一条斜杠拼在一起的。3.2 路线B代理模式把LiteLLM变成团队网关SDK模式适合单机项目但一旦你有多套服务、多个团队都要调用模型SDK模式就不够了。你不可能在每个服务里都维护一份API Key更不可能让每个后端都直接连上游服务。这时候用Proxy模式更合适LiteLLM跑成一个独立服务大家把base_url指向它。创建一个配置文件config.yamlmodel_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude-3-5-sonnet litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY启动代理litellm --config config.yaml --port 4000客户端那边不需要安装额外的SDK只要是你熟悉的OpenAI SDK就能连from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000, api_keysk-1234, ) resp client.chat.completions.create( modelgpt-4o, messages[{role: user, content: 你好}], ) print(resp.choices[0].message.content)这里有个很重要的点客户端的api_key在开发环境可以随便填生产环境则要用LiteLLM生成的虚拟Key。后面我会细说。Proxy模式的价值是“语言无关”。你的微服务可能有的用Go、有的用Java但只要语言有OpenAI SDK就能直接连LiteLLM。这样模型相关的能力被收敛到一个独立服务里升级、切换、故障排查都不需要改业务代码。3.3 模型别名与多模型配置的关键细节我第一次配model_list的时候犯过一个错以为model_name就是上游模型名。其实不是。model_name是暴露给调用方的名字你可以随便起但客户端传过来的model字段必须和它完全一致。litellm_params里的model字段才是真正要请求的上游模型名。举两个场景。第一个我想让客户端无感切换Claude于是配置- model_name: claude-3-5-sonnet litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY客户端调用时传modelclaude-3-5-sonnet请求就被转发到Anthropic。第二个同一个model_name可以配置多个后端形成一个小池子- model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY model_info: ...当model_name重复出现多次时LiteLLM会认为这些是同一个模型的不同部署配合路由策略做负载均衡或故障转移。这是实现高可用的基础。后面我讲Router的时候会再回到这里。4. 上线前必须处理的四件事路由、重试、成本、密钥4.1 高可用路由把同一个模型接到多个后端如果你只在代码里配了一个模型上游服务一抖动你的线上应用就跟着抖动。LiteLLM的Router能帮你把同一个模型请求分散到多个后端甚至在不同模型之间做故障转移。用SDK模式可以这样from litellm import Router model_list [ { model_name: gpt-4o, litellm_params: { model: openai/gpt-4o, api_key: os.environ[OPENAI_API_KEY], }, }, ] router Router( model_listmodel_list, fallbacks[{gpt-4o: [claude-3-5-sonnet]}], ) resp router.completion(modelgpt-4o, messages[{role: user, content: 你好}])fallbacks的意思是当gpt-4o这个模型连续失败时自动改走claude-3-5-sonnet。注意这个策略不是无限重试它更像是一种兜底主模型挂了切备用模型顶上。生产环境里这个能力可以救急因为云厂商或模型服务偶尔故障是常态与其让用户看到报错不如自动切换。如果用的是Proxy模式在config.yaml里可以加router_settingsrouter_settings: routing_strategy: simple-shuffle fallbacks: - {gpt-4o: [claude-3-5-sonnet]}routing_strategy有几种选择比如simple-shuffle随机轮询、least-busy选择当前并发最少的后端。默认的simple-shuffle够用如果你希望更均衡地分配压力可以试试least-busy。4.2 按错误类型设计重试很多人会犯一个错误任何错误都重试。这不是好习惯。重试需要区分错误类型错误类型是否值得重试原因429 限流值得过一会儿再试大概率能成功5xx 服务端错误值得服务端临时故障连接超时 / 网络抖动值得网络瞬断常见400 参数错误不值得重试一万次都一样401/403 鉴权失败不值得要修配置而不是重试上下文长度超限不值得需要改提示词或换模型为什么这个区分很重要因为如果你把所有错误都当成可重试错误一个超长上下文的请求可能会被反复打到所有后端白白消耗配额。后面我在踩坑部分会讲真实例子。重试间隔方面不要用固定间隔建议用指数退避加抖动。比如第一次等1秒第二次等2秒第三次等4秒再加上一个随机偏移避免所有实例同时重试把上游打崩。4.3 成本追踪与用量统计多模型接入之后成本账是最容易乱的地方。每个平台都有自己的用量统计页面但你要把多个平台的账单汇总到一个维度看手工算非常痛苦。LiteLLM在Proxy模式下会记录每次请求的token用量和估算成本前提是你配置了数据库。开发环境可以直接用SQLite起步database_url: sqlite:///litellm.db生产环境建议用PostgreSQL因为查询性能和并发写入更好。开了数据库之后LiteLLM会把请求日志、token统计都写进去你可以按模型、按部门、按项目去看消耗。我个人习惯是定期拉一下用量报表看看哪个模型占了大部分成本哪个团队在某个模型上烧钱比预期快。没有这个数据你连优化方向都找不到。4.4 虚拟密钥与预算限制直接在上游平台创建Key然后把Key配置到每个后端服务是非常危险的做法。一旦某个服务被攻破攻击者就能直接用你的Key去调模型成本全算你头上。最好的方式是让上游Key只存在于LiteLLM服务端客户端统一使用LiteLLM生成的虚拟Key。在Proxy模式下用主Key登录管理接口给每个团队、每个项目生成一个虚拟Key。这个Key可以指定只允许调用哪些模型也可以设置预算上限。比如给A团队一个Key限制每个月底预算不超过1000元超过之后自动拒绝请求直到下一个周期重置。这样做还有个好处审计。某个Key被大量调用你能定位到是哪个团队哪个项目在消耗。如果换作所有人共用同一个上游Key出了问题根本没法追溯。5. 我在LiteLLM上踩过的一些坑含具体排查过程5.1 Model Name不匹配路由不生效请求落到别处第一次用Proxy模式时我在config.yaml里配了一个模型- model_name: gpt-4o-prod litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY客户端调用时传的却是modelgpt-4o。结果LiteLLM返回404日志里显示找不到这个模型。我当时一度以为是LiteLLM坏了后来才反应过来model_name是你自己定义的“入口名”客户端传的model字段必须严格等于这个入口名。配置文件里根本没定义gpt-4o这个入口自然匹配不到。解决方式很简单要么把客户端传的模型名改成gpt-4o-prod要么把配置文件里的model_name改成gpt-4o。这里给个建议model_name最好不要带环境后缀统一用上游模型名比如gpt-4o、claude-3-5-sonnet。环境信息应该通过不同的配置或不同的Proxy实例来区分不要混在模型名里。5.2 默认超时撞上长思考任务有段时间我负责一个文档总结服务输入动辄几万字。上游模型处理起来要一两分钟但客户端经常报超时错误。一开始我怀疑是模型服务不稳定后来抓日志才发现LiteLLM在共享逻辑里有一个默认超时机制超过一定时间就断掉连接。这个“一定时间”对普通对话够用但对长文档总结完全不够。解法是在配置里给具体模型单独调大超时- model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY timeout: 300把timeout提高到300秒。这里要注意超时这个词其实包含两层意思一是建立连接的超时二是等待响应首字的超时。长思考任务的问题是后者也就是“首字延迟很高”。如果业务上允许另一种方案是改用流式输出把“等待完整结果”变成“持续接收中间结果”客户端体感会好很多。5.3 流式响应被“吞”成一次性输出另一个让我困惑的问题是流式输出。某个上游服务本身支持SSE流式返回但经过LiteLLM之后前端等了好一会儿才一次性拿到全部内容打字机效果完全没了。后来排查发现问题的根因在于上游返回的流式数据格式和标准SSE不完全一致LiteLLM的流式转发逻辑没能逐块透传只能等数据累积到一定程度再统一返回。这种问题排查起来比较费劲因为它不是完全不能用而是表现不符合预期。我的经验是第一确认客户端请求里确实传了streamTrue有时候框架层会把stream参数吞掉第二检查LiteLLM版本流式兼容性在版本之间修过很多次第三如果上游是一个比较小众的服务优先看看官方文档里是否提到流式兼容注意事项。实在不行可以退回非流式方案至少稳定性有保障。5.4 重试策略太激进配额被刷爆有一次配置了一个Router同时挂了多个后端。有个请求因为上下文长度超过模型限制不断返回400错误。按我的路由配置这个错误被当成“可重试错误”结果请求在多个后端之间来回跳动每个后端都尝试调用几个小时内消耗了不少配额。虽然LiteLLM本身不会把所有错误都当重试但如果你配置了比较宽松的fallbacks和重试次数就可能会放大这种问题。后来我吸取教训先从逻辑上把错误分成两类一类是明确的用户输入问题比如400、上下文超限这类错误应该直接返回给调用方另一类是临时性问题比如限流、服务端繁忙这类才值得重试和转移。最关键的是给团队Key设置预算上限这样就算策略出错损失也是可控的。5.5 几个值得坚持的配置习惯踩过这些坑之后我总结了几条配置习惯现在做新项目基本都会遵守先用SDK模式跑通单个模型的调用链路再上Proxy不要一上来就搞完整网关。模型命名从第一天就统一model_name用通俗易懂的上游模型名不要加环境后缀。打开日志审计记录谁在什么时候调了哪个模型这对定位线上问题至关重要。每个团队Key都设置预算上限哪怕你不觉得会超也要设。LiteLLM迭代速度很快升级前先看变更日志特别是路由和流式相关的选项。这些习惯不一定能让你完全避开所有坑但至少能把问题的发生范围缩小。尤其多模型接入这个场景坑往往藏在“差不多能用”和“真正稳定”之间的细节里没有统一入口和日志排查起来会非常痛苦。我现在做多模型接入基本默认先看LiteLLM能不能直接支持。能支持就统一入口不能支持的再单独写适配逻辑。它有它的学习成本特别是Proxy模式、虚拟Key、路由策略这一套但相比在一堆SDK和HTTP适配器里挣扎这点成本不算什么。如果你也正被多模型接入整得焦头烂额不妨先从最简单的SDK模式开始试跑通一个模型之后你就能感受到统一接口带来的清爽感了。

LiteLLM统一接入多模型：从SDK到代理网关的工程实践

相关推荐

AI辅助App开发全流程：从想法到上架的实战指南

iOS 17游客内购失败原因与StoreKit 2账户声明方案

PDF分布式处理实战：轻量级架构与工程落地

更多资讯

智能体记忆系统横评与治理

Hermes agent 贡献指南：从环境搭建到 PR 合并的完整实操

WPF中ObservableCollection排序的正确姿势：ICollectionView实战指南

SAR点目标指标计算：sinc函数到分辨率、PSLR与ISLR的工程实践

课堂行为识别系统实战拆解：YOLO检测、行为分类与评价规则

【AI大模型进阶】微调中的过拟合表现：训练集 loss 降了，测试集降了吗？

今日更新

小波包能量谱原理与MATLAB实现：从频带分解到故障特征提取

基于LSTM的网易云音乐评论情感分析：数据清洗与模型调优实战

Alpha-Beta剪枝与极大极小值算法：博弈树搜索原理与实战优化

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？