做 LLM 应用开发这一年多我最大的感受是换模型厂商绝对是痛苦排行榜前三。今天用了某家的接口明天想换另一家试试SDK 不同、参数结构不同、鉴权方式不同甚至连“几句话能返回”这种基础体验都不一样。直到我遇到了 litellm准确说是遇到了“模型网关”这个思路之后这一切才开始变得顺起来。litellm 是一个开源的模型网关项目它的核心作用只有一个让你的后端服务只面对一套统一的接口而把背后十几个厂商、几十个模型、几百个 API Key 的差异全部屏蔽掉。这不是一个“多一个依赖”的轮子而是一个能直接改变你项目架构方式的基础设施组件。如果你正在做 AI 应用开发或者你有好几个模型厂商的 Key 在手、想让团队统一接入模型能力又或者你想把“换模型”这件事从改代码变成改配置这篇文章就是写给你的。1. 为什么要关注 litellm从“模型切换噩梦”说起1.1 一个每天都在发生的场景先说一个我特别常见的经历。项目早期选了一家模型服务商跑了两周发现另一家模型在特定任务上更猛于是改了十几处 SDK 调用代码重新对接、重新测试。又过了两周老板说“要不咱们试试本地部署一个开源模型省点费用”。好又是一轮新的对接。这种痛苦不是某一家厂商的问题而是所有模型服务商都没法统一。有的厂商返回字段是choices有的返回字段是content有的传max_tokens有的传max_output_tokens有的要你带很长的签名有的只要一个简单 Header。更别提各家对“上下文长度怎么算”“函数调用怎么传”这种深水区的差异了。你项目里每接入一个供应商就要多写一套适配代码这套代码通常还很脆弱接口一升级就崩。更深层的问题其实是你把业务逻辑和某个厂商的协议绑死了。以后每次谈价格、每换一个供应商、每接入一个新模型都是整个后端团队的连带改动。这种“切换成本”会直接阻碍你的技术选型和商务谈判因为你根本不敢换。1.2 网关这个思路从哪来如果你写过微服务一定知道 API 网关前端只跟一个网关打交道网关再帮你路由到后面的订单服务、用户服务、支付服务。litellm 做的事情本质上就是给“大模型调用”这件事装了一个同样的网关。业务端只需要按一套格式把请求发给 litellmlitellm 负责把请求转成目标厂商真正要的格式转发出去拿回结果再翻译成统一格式扔回给业务端。所以 litellm 不是模型聚合工具也不是某个模型客户端的替代品它介于“业务应用”和“模型服务商”之间。对于业务代码来说它就是一个普通的接口地址对于模型服务商来说它就是一个普通调用方。中间这一层很薄但价值极大它把你和具体厂商解耦了。这个架构思路并不难理解难的是有人把它做成了通用产品。litellm 做出来的东西不是只适配一两家而是覆盖了市面上主流的闭源模型服务、开源模型框架和本地推理运行时。这意味着你换供应商、加本地模型往往只是一个配置项的事。1.3 谁最适合在这上面投入时间我盘点了一下这几类人获益最大独立开发者手里好几家厂商的 Key每个 Key 都用一点点想要一个统一入口不再维护一堆 SDK 胶水代码。后端团队几个人共用一套模型接入层接口统一、日志统一、费用统计统一省去大量重复开发。有成本管控需求的公司希望通过一个入口掌握每个团队、每个应用、每个模型的实际消费能配上预算告警而不是到月底看总账单。如果你只是在自己电脑上跑一个小脚本随便用哪个 SDK 直接调都行那确实不需要 litellm。但只要你的模型调用开始变得多、变得散或者需要多人协作这个网关的收益会立刻显示出来。2. 核心功能拆解这个网关到底在管什么2.1 统一接口最核心的“翻译层”litellm 暴露的接口是一套业界主流的 chat/completions 结构也就是大多数模型厂商 SDK 都兼容的那种标准请求格式。你发一个请求里面包含模型名、消息列表、温度、最大 token 数等参数litellm 拿到之后会做这么几件事根据模型名找到配置中对应的真实目标模型和鉴权信息把标准格式请求翻译成目标服务商自己的请求结构通过网络把请求真正发出去把目标服务商返回的结果再翻译回统一格式交还给你。这个翻译层就是这个项目的灵魂。它把所有厂商之间的“方言差异”吸收掉了。你在业务代码里写一次请求结构之后不管 litellm 后面挂了多少个模型你的代码都不用再动。这里有个细节容易忽略不同模型对参数的处理很不一样。比如 A 模型不支持temperatureB 模型对top_p敏感C 模型要求max_tokens必须传整数。如果你自己封装通常是一大堆if model ...的特判。litellm 提供了drop_params这类开关当某个参数不被目标模型支持时自动帮你把它丢掉而不是报错。配置开启后这些差异就会被“吞掉”。2.2 模型命名空间与路由策略litellm 里的模型名是一个独立的命名空间。什么意思你在配置里可以把你后台的真实模型定义成任意的名字。比如你的业务端想用一个统一的chat-main名字来调用litellm 配置里把chat-main分别映射到两个真实模型当chat-main对应厂商 A 时它就是 A 的模型对应厂商 B 时它就是 B 的模型。业务端完全不需要知道这个。你甚至可以配置同一个业务模型名下按优先级排列多个真实模型实例实现“挂了自动切换”的效果。这个机制非常实用。想想这样的场景你的应用里有很多模块在用同一个模型某天你想把其中 80% 的流量切到另一个厂商的新模型上体验效果但又不想立刻全量切。如果不做网关你可能要去改好几个服务的代码有网关你只需要调整路由权重配置然后发版一个新的配置即可。再说负载均衡。同一个厂商的同一个模型你可以配置多个 API Keylitellm 会按轮询或优先级把请求分散到这些 Key 上。多 Key 一方面是为了提高并发上限另一方面也是因为某些服务商对单个 Key 有速率限制多个 Key 可以显著降低触发限流的概率。2.3 用量、成本与团队配额管理对技术负责人来说litellm 最大的吸引力大概率是“总算能算清楚钱花哪去了”。网关每转发一次请求都会记录模型名、输入 token 数、输出 token 数、对应的服务商单价、请求发起时间、调用者的身份标识等信息。这些数据是自动累积的你不需要在业务侧打任何埋点。基于这些数据litellm 还能做两件很有价值的事按团队、按应用、按虚拟密钥统计消耗。比如 A 小组负责客服机器人B 小组负责内容生成两个小组各自用自己的密钥月底账单一拉各自花了多少清清楚楚。设置预算上限与速率限制。每个密钥可以绑定“每分钟最多 N 次请求”和“每月最多 N 美元”之类的限制。到达上限后请求会被拒绝你可以再决定是断掉还是人工扩容。这个能力在企业场景下特别重要。很多公司不敢放开让所有业务线直接接外部模型就是因为“失控风险”太大——谁用了、用了多少、有没有人能偷偷拿公司 Key 出去跑。在 litellm 前面加一层这些问题就都收口了。2.4 缓存、重试、限流与安全网关的另一个隐藏价值是能把一些“非业务功能”下沉到公共层。缓存是其中最有意思的一个。不用自己写复杂逻辑。litellm 支持把相同请求的返回结果缓存起来下一次相同请求到达时直接返回缓存结果而不去真实调用。缓存对重复性高的查询场景非常有效比如一段固定文档的摘要、一个高频的问答模板。命中缓存之后你省的不只是 token 费用还有响应时间。不过要注意缓存是把双刃剑后面我会讲避坑点。重试机制也很重要。厂商服务偶尔会抽风直接报 5xx 或网络超时。litellm 可以配置失败重试次数和重试策略关键是可以配合路由策略在主模型失败后自动把请求切给备用模型。对生产环境来说这个“多一层保障”的价值可能比省钱还大。安全层面litellm 用两个维度的机制保护你的密钥一是所有真实厂商 Key 只存在于配置文件或环境变量中业务端永远接触不到二是业务端访问 litellm 时使用独立的“虚拟密钥”这些虚拟密钥由 litellm 管理可以随时吊销可以绑定预算限额。即使某个虚拟密钥泄露了也不会暴露你的真实 Key你只需要在网关里吊销它即可。3. 从零部署动手把 litellm 跑起来3.1 安装与环境准备先明确一点litellm 有两个使用形态。第一种是作为 Python 库直接在代码里调用统一接口第二种是作为独立网关服务让其他服务通过 HTTP 调用。本文主要讲第二种因为网关形态才最能体现它的价值。安装很直接。建议在干净的 Python 3.9 以上环境执行pip install litellm[proxy]注意那个[proxy]后缀好多新手第一次栽在这里。如果你只执行pip install litellm装的是核心库不带proxy相关依赖后面你会发现根本没有litellm命令行工具或者启动代理时缺一堆模块。我建议直接用[proxy]版本功能全。装好之后创建项目目录在里面放一个.env文件。不要把真实密钥直接写进config.yaml提交到代码仓库里这是一个安全习惯。.env里定义各家服务商的密钥例如MODEL_PROVIDER_A_KEYsk-xxxxxxxx MODEL_PROVIDER_B_KEYsk-yyyyyyyy DATABASE_URLpostgresql://user:passlocalhost:5432/litellm如果你只是本地试用可以先不配数据库litellm 支持内存模式重启后数据丢失而已正式使用再接入数据库。3.2 一个最小可用的配置文件litellm 的配置是一个 YAML 文件。我用一个覆盖三类的示例来说明邮件里我只用占位符代表具体厂商和模型名实际用的时候替换为你自己真正在用的服务商标识即可。model_list: - model_name: chat-main litellm_params: model: provider_a/chat-main-4 api_key: os.environ/MODEL_PROVIDER_A_KEY - model_name: chat-backup litellm_params: model: provider_b/backup-chat api_key: os.environ/MODEL_PROVIDER_B_KEY - model_name: local-chat litellm_params: model: local_llm/local-model-8b api_base: http://127.0.0.1:8000/v1 api_key: local litellm_settings: drop_params: true set_verbose: true general_settings: master_key: sk-litellm-master逐段说明一下model_list是核心列表每项包含model_name和litellm_params。model_name是你业务端要用的名字客户端只能看到这个litellm_params才是真正发给目标服务商所需的参数包括厂商标识、模型名、密钥。后面的os.environ/前缀表示从环境变量读值避免明文。第三个条目演示了本地开源模型怎么接。local_llm/前缀代表“任何兼容标准接口的本地推理服务”配合api_base指向本地服务地址。很多本地推理框架都支持这种接入方式你只要保证本地服务先起来就行。litellm_settings里的drop_params: true表示丢弃目标模型不支持的参数强烈建议开启set_verbose: true是为了调试时能看到日志正式环境可以关掉。general_settings里配置了一个master_key这是 litellm 自身的管理员密钥用于后续创建虚拟密钥、管理配置等操作。3.3 启动网关与健康检查配置文件准备好了就可以启动。命令行进入项目目录litellm --config config.yaml --port 4000看到类似Uvicorn running on http://0.0.0.0:4000的日志说明服务起来了。这时可以先做两个健康检查curl http://localhost:4000/health/liveliness curl http://localhost:4000/health/readiness前者返回进程存活状态后者还会检查 litellm 的内部依赖是否就绪。两个接口都返回ok之类的状态就可以进行下一步了。生产环境建议用容器方式部署用官方提供的容器镜像启动并做好端口映射。容器部署时尤其注意把.env通过环境变量传进去而不是打包进镜像否则密钥就泄露给所有能看到镜像的人了。3.4 客户端接入与第一个请求网关跑起来之后业务端的接入极其简单把你原来请求模型服务商的地址改成 litellm 的地址鉴权改成 litellm 的密钥。此时你的客户端并不需要安装任何 SDK直接用一个标准 HTTP 请求就能完成curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-litellm-master \ -d { model: chat-main, messages: [ {role: user, content: 用一句话介绍你自己} ] }如果配置没问题返回体结构就是你熟悉的标准结构choices数组里有模型生成的文本。如果你原来用的是厂商 A 的 SDK现在只需要把base_url改成http://localhost:4000把 api_key 改成 master_key 或之后创建的虚拟密钥业务代码基本不用动。这里会有一个很多人问的问题model参数填什么填的是你在配置里定义的model_name不是厂商的真实模型名。这也是我为什么把命名空间单独拿出来讲的原因它在接入阶段很容易踩坑。4. 进阶实战把它用出生产级效果4.1 主备模型与自动降级光是把接口统一还不够真正生产环境的价值在于“故障降级”。比如某个主流厂商突然限流了你的服务不能跟着挂。配置里可以这么定义model_list: - model_name: chat-prod litellm_params: model: provider_a/chat-main-4 api_key: os.environ/MODEL_PROVIDER_A_KEY model_info: mode: complete - model_name: chat-prod litellm_params: model: provider_b/backup-chat api_key: os.environ/MODEL_PROVIDER_B_KEY model_info: mode: complete注意两个配置项用了同一个model_name。litellm 会把这些条目视为同一业务模型的多个候选实例默认按顺序尝试。当第一个实例请求失败或超时它会自动切换到第二个实例。你可以再调整路由策略设置冷却时间、最大重试次数等参数。我实际使用中最受益的一个场景是把本地开源模型当备用。平时主模型用收费的商业能力一旦它不可用自动切到本地模型顶上。虽然本地模型在当前需求上效果略差但至少服务没有中断用户体验是连续的。这种“高可用成本可控”的组合是单点调模型完全做不到的。4.2 缓存配置与命中率优化litellm 的缓存分为本地内存缓存和基于 Redis 的分布式缓存。本地内存适合单机试用Redis 适合多实例部署因为多个网关实例共享同一份缓存命中率会高很多。配置示例litellm_settings: cache: true cache_params: type: redis ttl: 3600开启后你可以观察缓存命中情况。如果发现命中率很低大概率是请求里的参数太“个性化”了。最常见的原因就是同一个请求里带了不同的随机 user id 或时间戳字段导致 litellm 认为这是两个完全不同的请求没法复用缓存。所以缓存设计的时候要想清楚哪些请求可以缓存哪些不能。不是所有场景都适合开缓存对话类应用通常不适合因为用户输入千奇百怪缓存价值有限但文本分类、固定模板、摘要生成这种输入模式比较固定的场景缓存效果立竿见影能省下一大笔 token 费用。还有一个容易忽略的点流式响应默认不适合缓存。如果你的前端代码用的是流式输出缓存命中时 litellm 会把结果一次性返回你的流式逻辑可能直接被搞挂。我在配置缓存后前端出现过偶发“对话突然停顿一下再全部出现”的现象排查到最后就是缓存命中导致的。给这些场景加一个缓存开关或者把用户 ID 加进缓存 key 的考虑范围之外会稳妥很多。4.3 成本追踪与预算告警litellm 会把每一次请求的 token 用量、模型单价、估算费用都记录下来。在本地试用时你可以通过它的内置接口查看日志比如curl http://localhost:4000/spend/logs \ -H Authorization: Bearer sk-litellm-master返回内容里包含请求时间、模型名、输入/输出 token 数、估算费用等信息。生产环境我强烈建议接一个数据库比如 PostgreSQL。这样无论你什么时候想查数据都在可以按日期、按用户、按密钥维度做聚合分析。预算控制是在general_settings里配置的。你可以为一个密钥设定上限比如某团队密钥“每月最大 200 美元”到达阈值之后 litellm 会拒绝该密钥的后续请求。这里有一个小教训预算上限不能只设一个总金额最好还要配速率限制否则某个业务方的一个 bug 可能在几小时内把整月预算打光。给每个虚拟密钥设置“每分钟最大请求数”和“每月的请求总次数”双重保险更稳。4.4 虚拟密钥与多团队管理虚拟密钥是 litellm 在安全层面最值得称赞的设计。你可以通过命令创建一个虚拟密钥并绑定额度和使用范围curl http://localhost:4000/key/generate \ -H Authorization: Bearer sk-litellm-master \ -H Content-Type: application/json \ -d { name: team-a-key, models: [chat-prod], max_budget: 200, rpm_limit: 60 }返回的 JSON 里会有一个key字段把这个 key 发给团队 A 的程序员让他们用它来访问网关。这个 key 看起来也是sk-开头但它和真实厂商的密钥完全不同。团队 A 只能用chat-prod这个模型每个月最多花 200 美元每分钟最多 60 个请求。如果团队 A 的人离职了你只需要在网关里吊销这个虚拟 key 即可不需要去任何厂商后台做任何操作。多团队管理在真实公司场景下特别好用。销售组、研发组、数据组的请求都走同一个 litellm但各自拿各自的虚拟 key配额各自独立、账单各自清晰团队成员流动也不会影响厂商 Key 安全。设置虚拟密钥时要注意命名规范否则一个月之后看到几十个 key 根本分不清谁是谁。5. 常见问题与排查实录5.1 模型 404 与命名不匹配现象调用 litellm 返回 404提示模型不存在。原因绝大多数情况是model参数没有匹配上配置里的model_name。比如配置里写的是chat-main请求里却传了chat_main或真实厂商模型名。另一个常见原因是你在model_list里没配置这个业务模型名但虚拟密钥的models配置项里又没有把它加进去key 就没有权限调用它。处理顺序先用curl直接请求chat-main试试然后检查虚拟密钥的模型白名单最后看 litellm 启动日志它会打印配置加载了哪些模型名对照看看有没有拼写差异。5.2 环境变量没有生效现象启动 litellm 时报错提示找不到某个 Key或者请求时返回 401。原因最常见的是.env文件放错位置了。litellm 是从当前工作目录加载.env的如果你在别的目录执行启动命令它根本读不到这个文件。另一个原因是使用了 Docker 部署但容器启动时没有把宿主机环境变量传进去。处理顺序确认.env在启动命令的工作目录下确认.env里的变量名和配置里的os.environ/XXXX完全一致容器部署的话检查-e参数或--env-file是否传了正确的文件。注意.env里值不要加引号有些解析器会把引号也当作值的一部分。5.3 超时、流式响应与并发问题现象请求发出去litellm 日志显示已经转发给上游但客户端等很久才返回或者干脆超时。原因首要是目标模型本身响应慢。有些本地模型在无 GPU 环境下生成很长文本响应时间轻松超过默认超时时间会让人误以为 litellm 卡住了。其次是 litellm 默认有一个进程内并发限制如果同时有大量请求进来超出部分会排队此时响应延迟会明显上升。流式请求场景下这个问题更容易暴露。处理顺序先直接调目标模型测一下真实耗时。如果模型本身慢就调大 litellm 的超时设置如果并发高就调整网关实例数和 Python 进程的并发 worker 数。日志里能看到每个请求的耗时和排队情况这一点对定位问题帮助非常大。5.4 本地开源模型接入避坑现象配置了本地模型请求时提示无法解析模型名或者提示连接被拒绝。原因本地模型接入有两个高频坑。第一个是model前缀没写对。如果你想接入一个本地推理服务必须在模型名前加local_llm/前缀否则 litellm 会以为你要连一个云端服务商然后去找一个不存在的提供商。第二个是api_base地址写错。127.0.0.1和0.0.0.0不能随便混用本地服务只监听在某个具体地址时127.0.0.1没问题但从容器里访问宿主机服务时要借助特殊地址而不是127.0.0.1。处理顺序先单独 curl 一下本地服务的/v1/models接口确认它真是可访问状态再检查配置里的前缀和地址最后看 litellm 日志里实际发往的目标 URL。整个链路中最容易出错的就是地址和前缀这两处检查到位基本就通了。5.5 常见错误速查表错误现象可能原因处理方式404 Model Not Found请求模型名与配置不一致核对model_name与配置中定义的名字401 Unauthorized虚拟 Key 未创建或已吊销重新生成虚拟 Key并确认绑定权限KeyError: XXXX_API_KEY.env未加载或变量名不一致检查工作目录、变量名、容器环境变量504 Gateway Timeout上游模型响应超时调大超时时间或改用响应更快的模型Rate Limit Exceeded虚拟 Key 超出速率限制提升限制或等待配额恢复Local Model Connection Refused本地服务未启动或地址错误先单独验证本地服务可访问Streaming Output Broken缓存命中了流式请求关闭该场景缓存或跳过缓存逻辑速查表里最后一条尤其值得多说一句。如果你发现开启缓存后原本正常流动的输出变得“一坨一坨”地出现先怀疑是不是缓存命中了。我一开始以为是我的代码问题排查了很久最后才发现是缓存把流式响应变成了非流式的整段返回。从此我给自己定了一条纪律凡是要开缓存的模型必须先确认它对应的场景是否允许非流式返回。结尾讲到这里关于 litellm 的核心用法已经都覆盖了。我个人的体会是它最值钱的地方不是“省代码”而是它改变了你对模型供应商的认知模型厂商变成了你业务里的可替换组件而不是难以动摇的底座。这种自由感只有当你把网关层真正搭起来之后才能体会到。最后分享两条我自己踩过坑之后的沉淀第一生产环境部署 litellm 一定要和业务服务放在同一个内网不要让请求跨公网多跳一次否则网络抖动会被指数放大。第二缓存功能别一上来就全局开先确认业务场景允许缓存再针对具体路由配置开启。 litellm 帮你把模型接入层统一了但每一条路由策略背后仍然需要你对业务需求有足够清晰的判断。 
长河君 · 2026/10/21 19:27:12 · 阅读 1.2k litellm：用模型网关统一大模型调用，告别切换厂商噩梦
做 LLM 应用开发这一年多我最大的感受是换模型厂商绝对是痛苦排行榜前三。今天用了某家的接口明天想换另一家试试SDK 不同、参数结构不同、鉴权方式不同甚至连“几句话能返回”这种基础体验都不一样。直到我遇到了 litellm准确说是遇到了“模型网关”这个思路之后这一切才开始变得顺起来。litellm 是一个开源的模型网关项目它的核心作用只有一个让你的后端服务只面对一套统一的接口而把背后十几个厂商、几十个模型、几百个 API Key 的差异全部屏蔽掉。这不是一个“多一个依赖”的轮子而是一个能直接改变你项目架构方式的基础设施组件。如果你正在做 AI 应用开发或者你有好几个模型厂商的 Key 在手、想让团队统一接入模型能力又或者你想把“换模型”这件事从改代码变成改配置这篇文章就是写给你的。1. 为什么要关注 litellm从“模型切换噩梦”说起1.1 一个每天都在发生的场景先说一个我特别常见的经历。项目早期选了一家模型服务商跑了两周发现另一家模型在特定任务上更猛于是改了十几处 SDK 调用代码重新对接、重新测试。又过了两周老板说“要不咱们试试本地部署一个开源模型省点费用”。好又是一轮新的对接。这种痛苦不是某一家厂商的问题而是所有模型服务商都没法统一。有的厂商返回字段是choices有的返回字段是content有的传max_tokens有的传max_output_tokens有的要你带很长的签名有的只要一个简单 Header。更别提各家对“上下文长度怎么算”“函数调用怎么传”这种深水区的差异了。你项目里每接入一个供应商就要多写一套适配代码这套代码通常还很脆弱接口一升级就崩。更深层的问题其实是你把业务逻辑和某个厂商的协议绑死了。以后每次谈价格、每换一个供应商、每接入一个新模型都是整个后端团队的连带改动。这种“切换成本”会直接阻碍你的技术选型和商务谈判因为你根本不敢换。1.2 网关这个思路从哪来如果你写过微服务一定知道 API 网关前端只跟一个网关打交道网关再帮你路由到后面的订单服务、用户服务、支付服务。litellm 做的事情本质上就是给“大模型调用”这件事装了一个同样的网关。业务端只需要按一套格式把请求发给 litellmlitellm 负责把请求转成目标厂商真正要的格式转发出去拿回结果再翻译成统一格式扔回给业务端。所以 litellm 不是模型聚合工具也不是某个模型客户端的替代品它介于“业务应用”和“模型服务商”之间。对于业务代码来说它就是一个普通的接口地址对于模型服务商来说它就是一个普通调用方。中间这一层很薄但价值极大它把你和具体厂商解耦了。这个架构思路并不难理解难的是有人把它做成了通用产品。litellm 做出来的东西不是只适配一两家而是覆盖了市面上主流的闭源模型服务、开源模型框架和本地推理运行时。这意味着你换供应商、加本地模型往往只是一个配置项的事。1.3 谁最适合在这上面投入时间我盘点了一下这几类人获益最大独立开发者手里好几家厂商的 Key每个 Key 都用一点点想要一个统一入口不再维护一堆 SDK 胶水代码。后端团队几个人共用一套模型接入层接口统一、日志统一、费用统计统一省去大量重复开发。有成本管控需求的公司希望通过一个入口掌握每个团队、每个应用、每个模型的实际消费能配上预算告警而不是到月底看总账单。如果你只是在自己电脑上跑一个小脚本随便用哪个 SDK 直接调都行那确实不需要 litellm。但只要你的模型调用开始变得多、变得散或者需要多人协作这个网关的收益会立刻显示出来。2. 核心功能拆解这个网关到底在管什么2.1 统一接口最核心的“翻译层”litellm 暴露的接口是一套业界主流的 chat/completions 结构也就是大多数模型厂商 SDK 都兼容的那种标准请求格式。你发一个请求里面包含模型名、消息列表、温度、最大 token 数等参数litellm 拿到之后会做这么几件事根据模型名找到配置中对应的真实目标模型和鉴权信息把标准格式请求翻译成目标服务商自己的请求结构通过网络把请求真正发出去把目标服务商返回的结果再翻译回统一格式交还给你。这个翻译层就是这个项目的灵魂。它把所有厂商之间的“方言差异”吸收掉了。你在业务代码里写一次请求结构之后不管 litellm 后面挂了多少个模型你的代码都不用再动。这里有个细节容易忽略不同模型对参数的处理很不一样。比如 A 模型不支持temperatureB 模型对top_p敏感C 模型要求max_tokens必须传整数。如果你自己封装通常是一大堆if model ...的特判。litellm 提供了drop_params这类开关当某个参数不被目标模型支持时自动帮你把它丢掉而不是报错。配置开启后这些差异就会被“吞掉”。2.2 模型命名空间与路由策略litellm 里的模型名是一个独立的命名空间。什么意思你在配置里可以把你后台的真实模型定义成任意的名字。比如你的业务端想用一个统一的chat-main名字来调用litellm 配置里把chat-main分别映射到两个真实模型当chat-main对应厂商 A 时它就是 A 的模型对应厂商 B 时它就是 B 的模型。业务端完全不需要知道这个。你甚至可以配置同一个业务模型名下按优先级排列多个真实模型实例实现“挂了自动切换”的效果。这个机制非常实用。想想这样的场景你的应用里有很多模块在用同一个模型某天你想把其中 80% 的流量切到另一个厂商的新模型上体验效果但又不想立刻全量切。如果不做网关你可能要去改好几个服务的代码有网关你只需要调整路由权重配置然后发版一个新的配置即可。再说负载均衡。同一个厂商的同一个模型你可以配置多个 API Keylitellm 会按轮询或优先级把请求分散到这些 Key 上。多 Key 一方面是为了提高并发上限另一方面也是因为某些服务商对单个 Key 有速率限制多个 Key 可以显著降低触发限流的概率。2.3 用量、成本与团队配额管理对技术负责人来说litellm 最大的吸引力大概率是“总算能算清楚钱花哪去了”。网关每转发一次请求都会记录模型名、输入 token 数、输出 token 数、对应的服务商单价、请求发起时间、调用者的身份标识等信息。这些数据是自动累积的你不需要在业务侧打任何埋点。基于这些数据litellm 还能做两件很有价值的事按团队、按应用、按虚拟密钥统计消耗。比如 A 小组负责客服机器人B 小组负责内容生成两个小组各自用自己的密钥月底账单一拉各自花了多少清清楚楚。设置预算上限与速率限制。每个密钥可以绑定“每分钟最多 N 次请求”和“每月最多 N 美元”之类的限制。到达上限后请求会被拒绝你可以再决定是断掉还是人工扩容。这个能力在企业场景下特别重要。很多公司不敢放开让所有业务线直接接外部模型就是因为“失控风险”太大——谁用了、用了多少、有没有人能偷偷拿公司 Key 出去跑。在 litellm 前面加一层这些问题就都收口了。2.4 缓存、重试、限流与安全网关的另一个隐藏价值是能把一些“非业务功能”下沉到公共层。缓存是其中最有意思的一个。不用自己写复杂逻辑。litellm 支持把相同请求的返回结果缓存起来下一次相同请求到达时直接返回缓存结果而不去真实调用。缓存对重复性高的查询场景非常有效比如一段固定文档的摘要、一个高频的问答模板。命中缓存之后你省的不只是 token 费用还有响应时间。不过要注意缓存是把双刃剑后面我会讲避坑点。重试机制也很重要。厂商服务偶尔会抽风直接报 5xx 或网络超时。litellm 可以配置失败重试次数和重试策略关键是可以配合路由策略在主模型失败后自动把请求切给备用模型。对生产环境来说这个“多一层保障”的价值可能比省钱还大。安全层面litellm 用两个维度的机制保护你的密钥一是所有真实厂商 Key 只存在于配置文件或环境变量中业务端永远接触不到二是业务端访问 litellm 时使用独立的“虚拟密钥”这些虚拟密钥由 litellm 管理可以随时吊销可以绑定预算限额。即使某个虚拟密钥泄露了也不会暴露你的真实 Key你只需要在网关里吊销它即可。3. 从零部署动手把 litellm 跑起来3.1 安装与环境准备先明确一点litellm 有两个使用形态。第一种是作为 Python 库直接在代码里调用统一接口第二种是作为独立网关服务让其他服务通过 HTTP 调用。本文主要讲第二种因为网关形态才最能体现它的价值。安装很直接。建议在干净的 Python 3.9 以上环境执行pip install litellm[proxy]注意那个[proxy]后缀好多新手第一次栽在这里。如果你只执行pip install litellm装的是核心库不带proxy相关依赖后面你会发现根本没有litellm命令行工具或者启动代理时缺一堆模块。我建议直接用[proxy]版本功能全。装好之后创建项目目录在里面放一个.env文件。不要把真实密钥直接写进config.yaml提交到代码仓库里这是一个安全习惯。.env里定义各家服务商的密钥例如MODEL_PROVIDER_A_KEYsk-xxxxxxxx MODEL_PROVIDER_B_KEYsk-yyyyyyyy DATABASE_URLpostgresql://user:passlocalhost:5432/litellm如果你只是本地试用可以先不配数据库litellm 支持内存模式重启后数据丢失而已正式使用再接入数据库。3.2 一个最小可用的配置文件litellm 的配置是一个 YAML 文件。我用一个覆盖三类的示例来说明邮件里我只用占位符代表具体厂商和模型名实际用的时候替换为你自己真正在用的服务商标识即可。model_list: - model_name: chat-main litellm_params: model: provider_a/chat-main-4 api_key: os.environ/MODEL_PROVIDER_A_KEY - model_name: chat-backup litellm_params: model: provider_b/backup-chat api_key: os.environ/MODEL_PROVIDER_B_KEY - model_name: local-chat litellm_params: model: local_llm/local-model-8b api_base: http://127.0.0.1:8000/v1 api_key: local litellm_settings: drop_params: true set_verbose: true general_settings: master_key: sk-litellm-master逐段说明一下model_list是核心列表每项包含model_name和litellm_params。model_name是你业务端要用的名字客户端只能看到这个litellm_params才是真正发给目标服务商所需的参数包括厂商标识、模型名、密钥。后面的os.environ/前缀表示从环境变量读值避免明文。第三个条目演示了本地开源模型怎么接。local_llm/前缀代表“任何兼容标准接口的本地推理服务”配合api_base指向本地服务地址。很多本地推理框架都支持这种接入方式你只要保证本地服务先起来就行。litellm_settings里的drop_params: true表示丢弃目标模型不支持的参数强烈建议开启set_verbose: true是为了调试时能看到日志正式环境可以关掉。general_settings里配置了一个master_key这是 litellm 自身的管理员密钥用于后续创建虚拟密钥、管理配置等操作。3.3 启动网关与健康检查配置文件准备好了就可以启动。命令行进入项目目录litellm --config config.yaml --port 4000看到类似Uvicorn running on http://0.0.0.0:4000的日志说明服务起来了。这时可以先做两个健康检查curl http://localhost:4000/health/liveliness curl http://localhost:4000/health/readiness前者返回进程存活状态后者还会检查 litellm 的内部依赖是否就绪。两个接口都返回ok之类的状态就可以进行下一步了。生产环境建议用容器方式部署用官方提供的容器镜像启动并做好端口映射。容器部署时尤其注意把.env通过环境变量传进去而不是打包进镜像否则密钥就泄露给所有能看到镜像的人了。3.4 客户端接入与第一个请求网关跑起来之后业务端的接入极其简单把你原来请求模型服务商的地址改成 litellm 的地址鉴权改成 litellm 的密钥。此时你的客户端并不需要安装任何 SDK直接用一个标准 HTTP 请求就能完成curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-litellm-master \ -d { model: chat-main, messages: [ {role: user, content: 用一句话介绍你自己} ] }如果配置没问题返回体结构就是你熟悉的标准结构choices数组里有模型生成的文本。如果你原来用的是厂商 A 的 SDK现在只需要把base_url改成http://localhost:4000把 api_key 改成 master_key 或之后创建的虚拟密钥业务代码基本不用动。这里会有一个很多人问的问题model参数填什么填的是你在配置里定义的model_name不是厂商的真实模型名。这也是我为什么把命名空间单独拿出来讲的原因它在接入阶段很容易踩坑。4. 进阶实战把它用出生产级效果4.1 主备模型与自动降级光是把接口统一还不够真正生产环境的价值在于“故障降级”。比如某个主流厂商突然限流了你的服务不能跟着挂。配置里可以这么定义model_list: - model_name: chat-prod litellm_params: model: provider_a/chat-main-4 api_key: os.environ/MODEL_PROVIDER_A_KEY model_info: mode: complete - model_name: chat-prod litellm_params: model: provider_b/backup-chat api_key: os.environ/MODEL_PROVIDER_B_KEY model_info: mode: complete注意两个配置项用了同一个model_name。litellm 会把这些条目视为同一业务模型的多个候选实例默认按顺序尝试。当第一个实例请求失败或超时它会自动切换到第二个实例。你可以再调整路由策略设置冷却时间、最大重试次数等参数。我实际使用中最受益的一个场景是把本地开源模型当备用。平时主模型用收费的商业能力一旦它不可用自动切到本地模型顶上。虽然本地模型在当前需求上效果略差但至少服务没有中断用户体验是连续的。这种“高可用成本可控”的组合是单点调模型完全做不到的。4.2 缓存配置与命中率优化litellm 的缓存分为本地内存缓存和基于 Redis 的分布式缓存。本地内存适合单机试用Redis 适合多实例部署因为多个网关实例共享同一份缓存命中率会高很多。配置示例litellm_settings: cache: true cache_params: type: redis ttl: 3600开启后你可以观察缓存命中情况。如果发现命中率很低大概率是请求里的参数太“个性化”了。最常见的原因就是同一个请求里带了不同的随机 user id 或时间戳字段导致 litellm 认为这是两个完全不同的请求没法复用缓存。所以缓存设计的时候要想清楚哪些请求可以缓存哪些不能。不是所有场景都适合开缓存对话类应用通常不适合因为用户输入千奇百怪缓存价值有限但文本分类、固定模板、摘要生成这种输入模式比较固定的场景缓存效果立竿见影能省下一大笔 token 费用。还有一个容易忽略的点流式响应默认不适合缓存。如果你的前端代码用的是流式输出缓存命中时 litellm 会把结果一次性返回你的流式逻辑可能直接被搞挂。我在配置缓存后前端出现过偶发“对话突然停顿一下再全部出现”的现象排查到最后就是缓存命中导致的。给这些场景加一个缓存开关或者把用户 ID 加进缓存 key 的考虑范围之外会稳妥很多。4.3 成本追踪与预算告警litellm 会把每一次请求的 token 用量、模型单价、估算费用都记录下来。在本地试用时你可以通过它的内置接口查看日志比如curl http://localhost:4000/spend/logs \ -H Authorization: Bearer sk-litellm-master返回内容里包含请求时间、模型名、输入/输出 token 数、估算费用等信息。生产环境我强烈建议接一个数据库比如 PostgreSQL。这样无论你什么时候想查数据都在可以按日期、按用户、按密钥维度做聚合分析。预算控制是在general_settings里配置的。你可以为一个密钥设定上限比如某团队密钥“每月最大 200 美元”到达阈值之后 litellm 会拒绝该密钥的后续请求。这里有一个小教训预算上限不能只设一个总金额最好还要配速率限制否则某个业务方的一个 bug 可能在几小时内把整月预算打光。给每个虚拟密钥设置“每分钟最大请求数”和“每月的请求总次数”双重保险更稳。4.4 虚拟密钥与多团队管理虚拟密钥是 litellm 在安全层面最值得称赞的设计。你可以通过命令创建一个虚拟密钥并绑定额度和使用范围curl http://localhost:4000/key/generate \ -H Authorization: Bearer sk-litellm-master \ -H Content-Type: application/json \ -d { name: team-a-key, models: [chat-prod], max_budget: 200, rpm_limit: 60 }返回的 JSON 里会有一个key字段把这个 key 发给团队 A 的程序员让他们用它来访问网关。这个 key 看起来也是sk-开头但它和真实厂商的密钥完全不同。团队 A 只能用chat-prod这个模型每个月最多花 200 美元每分钟最多 60 个请求。如果团队 A 的人离职了你只需要在网关里吊销这个虚拟 key 即可不需要去任何厂商后台做任何操作。多团队管理在真实公司场景下特别好用。销售组、研发组、数据组的请求都走同一个 litellm但各自拿各自的虚拟 key配额各自独立、账单各自清晰团队成员流动也不会影响厂商 Key 安全。设置虚拟密钥时要注意命名规范否则一个月之后看到几十个 key 根本分不清谁是谁。5. 常见问题与排查实录5.1 模型 404 与命名不匹配现象调用 litellm 返回 404提示模型不存在。原因绝大多数情况是model参数没有匹配上配置里的model_name。比如配置里写的是chat-main请求里却传了chat_main或真实厂商模型名。另一个常见原因是你在model_list里没配置这个业务模型名但虚拟密钥的models配置项里又没有把它加进去key 就没有权限调用它。处理顺序先用curl直接请求chat-main试试然后检查虚拟密钥的模型白名单最后看 litellm 启动日志它会打印配置加载了哪些模型名对照看看有没有拼写差异。5.2 环境变量没有生效现象启动 litellm 时报错提示找不到某个 Key或者请求时返回 401。原因最常见的是.env文件放错位置了。litellm 是从当前工作目录加载.env的如果你在别的目录执行启动命令它根本读不到这个文件。另一个原因是使用了 Docker 部署但容器启动时没有把宿主机环境变量传进去。处理顺序确认.env在启动命令的工作目录下确认.env里的变量名和配置里的os.environ/XXXX完全一致容器部署的话检查-e参数或--env-file是否传了正确的文件。注意.env里值不要加引号有些解析器会把引号也当作值的一部分。5.3 超时、流式响应与并发问题现象请求发出去litellm 日志显示已经转发给上游但客户端等很久才返回或者干脆超时。原因首要是目标模型本身响应慢。有些本地模型在无 GPU 环境下生成很长文本响应时间轻松超过默认超时时间会让人误以为 litellm 卡住了。其次是 litellm 默认有一个进程内并发限制如果同时有大量请求进来超出部分会排队此时响应延迟会明显上升。流式请求场景下这个问题更容易暴露。处理顺序先直接调目标模型测一下真实耗时。如果模型本身慢就调大 litellm 的超时设置如果并发高就调整网关实例数和 Python 进程的并发 worker 数。日志里能看到每个请求的耗时和排队情况这一点对定位问题帮助非常大。5.4 本地开源模型接入避坑现象配置了本地模型请求时提示无法解析模型名或者提示连接被拒绝。原因本地模型接入有两个高频坑。第一个是model前缀没写对。如果你想接入一个本地推理服务必须在模型名前加local_llm/前缀否则 litellm 会以为你要连一个云端服务商然后去找一个不存在的提供商。第二个是api_base地址写错。127.0.0.1和0.0.0.0不能随便混用本地服务只监听在某个具体地址时127.0.0.1没问题但从容器里访问宿主机服务时要借助特殊地址而不是127.0.0.1。处理顺序先单独 curl 一下本地服务的/v1/models接口确认它真是可访问状态再检查配置里的前缀和地址最后看 litellm 日志里实际发往的目标 URL。整个链路中最容易出错的就是地址和前缀这两处检查到位基本就通了。5.5 常见错误速查表错误现象可能原因处理方式404 Model Not Found请求模型名与配置不一致核对model_name与配置中定义的名字401 Unauthorized虚拟 Key 未创建或已吊销重新生成虚拟 Key并确认绑定权限KeyError: XXXX_API_KEY.env未加载或变量名不一致检查工作目录、变量名、容器环境变量504 Gateway Timeout上游模型响应超时调大超时时间或改用响应更快的模型Rate Limit Exceeded虚拟 Key 超出速率限制提升限制或等待配额恢复Local Model Connection Refused本地服务未启动或地址错误先单独验证本地服务可访问Streaming Output Broken缓存命中了流式请求关闭该场景缓存或跳过缓存逻辑速查表里最后一条尤其值得多说一句。如果你发现开启缓存后原本正常流动的输出变得“一坨一坨”地出现先怀疑是不是缓存命中了。我一开始以为是我的代码问题排查了很久最后才发现是缓存把流式响应变成了非流式的整段返回。从此我给自己定了一条纪律凡是要开缓存的模型必须先确认它对应的场景是否允许非流式返回。结尾讲到这里关于 litellm 的核心用法已经都覆盖了。我个人的体会是它最值钱的地方不是“省代码”而是它改变了你对模型供应商的认知模型厂商变成了你业务里的可替换组件而不是难以动摇的底座。这种自由感只有当你把网关层真正搭起来之后才能体会到。最后分享两条我自己踩过坑之后的沉淀第一生产环境部署 litellm 一定要和业务服务放在同一个内网不要让请求跨公网多跳一次否则网络抖动会被指数放大。第二缓存功能别一上来就全局开先确认业务场景允许缓存再针对具体路由配置开启。 litellm 帮你把模型接入层统一了但每一条路由策略背后仍然需要你对业务需求有足够清晰的判断。