1. 这不是一个“模型”而是一个“总闸”——用一分钟认识 LiteLLM如果你和我一样过去一年里被各种大模型 API 折腾到头秃你应该能秒懂我在说什么OpenAI 的接口长一个样子Anthropic 的接口是另一个样子Google 的 Gemini 又是一套写法还有 Azure OpenAI、本地部署的 vLLM、各类国产模型……每个服务商的鉴权方式、请求格式、返回结构、超时策略都各玩各的。业务代码里塞满了 if-else 分支去适配不同厂商SDK 换了一个又一个prompt 模板在不同系统间复制粘贴密钥散落在各种环境文件里。说实话这不是“技术选型”问题这是“接口地狱”问题。LiteLLM 就是来收拾这个烂摊子的。一句话概括它是一个开源的 LLM 网关/代理层让你用 OpenAI 那套统一的请求格式去调用市面上几乎主流的大模型接口不管是闭源商业模型、云厂商模型还是自建的开源模型。它既可以直接作为 Python 库在你的服务里调用也可以作为一个独立的代理服务跑起来团队所有人把base_url指到它上面就算接入完成。内部的真实后端是谁、密钥怎么管理、模型怎么路由、失败怎么重试全部由这一层替你消化。LiteLLM 不是又一个新模型也不是一个“提示词管理工具”。它站在你和模型提供商之间解决的是接口标准化、模型路由、成本控制、故障转移这一整类问题。适合谁来用如果你的团队同时接了好几家模型经常做模型之间的对比评测或者需要在生产环境里给多个业务线分配模型调用预算那这篇文章就是写给你看的。哪怕你只是一个人在做 Side Project用 LiteLLM 也能让你换模型的时候不再改代码。2. 核心设计思路拆解网关为什么能解决“接口混乱”2.1 先搞懂它的最小认知模型路由层 转换层 管控层我刚接触 LiteLLM 的时候第一反应是“这不就是一个 API 转发器吗”。用了一段时间才意识到转发只是表象它真正的价值在于把一大坨非标准化的事情藏在了后面。你可以把 LiteLLM 想象成机场的中转柜台。乘客你的应用请求只需要在柜台办一次登机手续柜台背后是不同航空公司OpenAI、Anthropic、Azure、本地模型的航班。LiteLLM 做的事情有三层第一层是协议转换。你发给它的请求是 OpenAI 风格的chat.completions格式它内部会把你这个请求翻译成目标厂商真正认识的格式。比如 Anthropic 的消息结构跟 OpenAI 差别很大LiteLLM 会做字段映射、系统提示词拼接、参数换算。这一层做得越扎实用户就越感觉不到后端差异。第二层是路由决策。请求到了以后到底转给哪个厂商这取决于你的配置可以按模型名直接转发也可以配置成一组模型做负载均衡还可以在主模型报错时自动切换备用模型。LiteLLM 会根据你定义的model_list和策略决定这一单“派给”谁。第三层是管控与观测。记录每个请求花多少钱、谁在调、响应速度怎么样、是不是该限流了、预算额度还剩多少。这些信息不是锦上添花而是生产环境里的刚需。没有这一层账单出来的时候你根本不知道钱花哪了。这个“三层结构”的价值在于你的业务代码只需要认识 OpenAI 格式其他所有复杂度都被挡在网关外面。这不是什么高深技术但它对工程效率的提升非常直观。2.2 为什么偏偏是 OpenAI 格式而不是搞一套“万能格式”很多人会问既然要做标准化为什么不能定义一个所有人都认同的“标准格式”让各家模型都来适配它理论上可以但现实中行不通。因为 OpenAI 的接口格式实际上已经成了事实标准——所有主流 SDK、开源工具、Agent 框架、评测系统默认都按 OpenAI 风格调用。你随便打开一个 LangChain 项目或者一个开源 Agent 项目它内部描述 LLM 接口的方式大概率就是base_url加api_key请求体就是messages数组。LiteLLM 选择兼容 OpenAI 格式意味着它不需要发明新生态而是无缝接入现有生态。这个决策非常务实。对我这种用惯了 OpenAI SDK 的人来说接入 LiteLLM 的代理服务只需要改两行配置把base_url指到 LiteLLM 地址把api_key换成虚拟密钥。其余代码一行都不用动。这意味着团队切换模型根本不需要做大规模代码重构风险直线下降。2.3 两种使用姿势库模式还是网关模式LiteLLM 提供了两种集成方式很多人一开始分不清这里我给你捋清楚。第一种是库模式在 Python 代码里直接import litellm调用litellm.completion()或者litellm.embedding()。这时候 LiteLLM 是运行在你进程里的一个函数库你把参数传进去它帮你完成格式转换、调用 API、返回结果。这种方式适合写脚本、做批处理、快速跑实验也适合在单体应用里不想多维护一个服务的场景。第二种是网关模式把 LiteLLM 跑成一个独立的 HTTP 服务默认端口 4000。你用它加载一份配置文件启动后它就对外暴露一个/chat/completions端点。你的应用、你的同事、你的微服务全都把这个端点当成 OpenAI 来调用。密钥、模型路由、预算策略都在服务端统一管理。这种方式适合团队协作、生产部署、多业务复用——网关模式才是 LiteLLM 真正拉开差距的地方。这两种模式不是互斥的很多团队是先库模式验证再切网关模式上生产。我建议你直接按最终形态来规划避免后面返工。3. 动手落地从安装到跑通你的第一个代理接口3.1 最小环境准备开始之前先把环境准备利索。LiteLLM 是 Python 生态Python 3.8 以上基本都能跑但要上生产我建议至少 Python 3.10 以上。安装很简单pip install litellm[proxy]注意这里不是pip install litellm那么简单[proxy]这个 extra 会额外带上代理服务需要的依赖比如 FastAPI、uvicorn 这些。如果你只想用库模式装裸包就行但如果要启动代理一定别漏掉[proxy]。装完以后可以先验证一下版本litellm --version能输出版本号就说明装好了。这里很多人第一步就会踩坑装完litellm敲litellm --help却发现命令找不到。原因通常就是那个[proxy]没带或者环境变量 PATH 出了问题解决方式就是重装一次带 extra 的包。3.2 写第一份 config.yaml网关模式的核心是配置文件。你可以理解为所有路由规则、密钥指向、策略参数都写在 YAML 里启动的时候加载一次。先看一个最简配置model_list: - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: claude-3-5-sonnet litellm_params: model: anthropic/claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY这里面有几种关键写法需要解释。model_list是路由表每一项是一条路由。model_name是对外暴露的名字你的同事写代码时用的是这个名字litellm_params是内部真正要传给后端的参数。model字段的写法是提供商/模型名比如openai/gpt-4o-mini、anthropic/claude-3-5-sonnet。这个前缀不能乱写LiteLLM 靠它识别该走哪套转换逻辑。api_key直接写明文并不推荐更稳妥的是用os.environ/环境变量名这种写法让 LiteLLM 从进程环境变量里读密钥。这样配置文件可以进版本库密钥不会泄露。3.3 启动代理服务的两种路径有了配置启动服务有两种方式。第一种是把配置写到默认位置然后直接启动litellm --config ./config.yaml --port 4000第二种是用config.yaml作为主配置再把模型通过环境变量临时补充进去litellm --model gpt-4o-mini --port 4000第二种适合极简场景你不想写配置文件只想飞快跑一个代理出来。但如果你准备认真用我建议统一走配置文件路线。因为后续加预算、加 fallback、加负载均衡全部都是在config.yaml里扩展命令行参数只是便捷入口不是完整方案。启动之后你会看到服务监听在 4000 端口日志输出模型路由表。看到Uvicorn running on http://0.0.0.0:4000就算成功了。注意默认只监听本机如果要给局域网其他同事用启动参数里记得加上--host 0.0.0.0。3.4 用 curl 验证代理是否真的通了服务起来了先用 curl 打一发试试curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-your-virtual-key \ -d { model: gpt-4o-mini, messages: [{role: user, content: 你好用一句话介绍你自己}] }这里有几个细节要注意路径是/v1/chat/completions不是/chat/completions鉴权头是Authorization: Bearer xxxmodel字段传的是你在model_list里定义的model_name不是真实后端模型名。如果返回的 JSON 里有choices[0].message.content说明整条链路已经通了。3.5 把现有 OpenAI SDK 客户端指到 LiteLLM验证之后更爽的一步来了在你现有的 Python 项目里不用改业务代码只需要改一下客户端配置from openai import OpenAI client OpenAI( api_keysk-your-virtual-key, base_urlhttp://localhost:4000/v1 ) response client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 讲个冷笑话}] ) print(response.choices[0].message.content)这段代码对很多人来说再熟悉不过了唯一变的是base_url和api_key。你现在请求的不是 OpenAI 官方而是 LiteLLM但代码层面的心智负担一点没增加。如果以后想从 GPT 换成 Claude你只需要把model参数改成claude-3-5-sonnet其他都不用动——前提是 LiteLLM 配置文件里已经定义了这个路由。4. 模型路由与密钥管理从单模型过渡到多模型调度4.1 环境变量管理密钥别再往代码里塞 Key密钥管理是很多团队最容易翻车的地方。见过不少人把 API Key 直接写在 Python 文件里或者写进 Docker 镜像的环境变量文件里密钥一泄露账就跑得像流水一样。LiteLLM 的标准做法是用环境变量引用。YAML 里写os.environ/OPENAI_API_KEY然后启动前在 shell 里导出export OPENAI_API_KEYsk-xxxx export ANTHROPIC_API_KEYsk-ant-xxxx如果你用 docker-compose 部署可以在environment字段里传。如果你用 Kubernetes把密钥放到 Secret 里再挂载成环境变量。这样配置文件本身是可以提交到代码仓库的密钥永远留在部署环境里。LiteLLM 还支持从.env文件加载变量它内部会调用 dotenv 的逻辑。你可以在项目目录放一个.env里面写OPENAI_API_KEYsk-xxxx启动时自动加载。但注意.env文件一定不要提交到 Git要在.gitignore里加一条。4.2 model_list 与 model_group路由表才是真正的灵魂很多人把model_list当成一个简单的“模型名映射表”用起来是够的但理解不透会导致后面配置负载均衡一塌糊涂。这里我给你一个更准确的认知model_list里的每一条其实是注册了一个“路由条目”而model_name相当于一个逻辑名字LiteLLM 内部通过这个名字去做查找。举个例子你可以给同一个model_name配置多个真实后端这样可以实现负载均衡和故障转移model_list: - model_name: my-chat-model litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: my-chat-model litellm_params: model: anthropic/claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY表面上看你对外只暴露了一个my-chat-model但请求会在 OpenAI 和 Anthropic 之间轮询分发。这样做有什么好处第一某个厂商出故障时流量可以自动转移到另一家第二你可以按价格或者按性能去调权重让便宜的模型多承接一些请求第三业务方完全感知不到后端换了一家。这就是网关的“总闸”价值——业务方只认一个名字背后的风控、调度、冗余全部由平台层负责。4.3 fallback 策略与重试生产环境不能裸奔只配置路由列表但没有故障转移策略在生产环境就是裸奔。模型厂商接口偶尔 5xx、超时、限流都是家常便饭。尤其 OpenAI 的高峰期429 错误太常见了。在config.yaml里配置 fallback 有两种方式。一种是model_list里的隐式 fallback——把同一个model_name指向多个后端LiteLLM 默认就有重试逻辑当主模型抛错时会尝试列表里的下一个前提是错误类型允许重试。这个隐式行为方便但不好精细控制因为它会对所有模型条目一视同仁地轮询。另一种是显式配置router_settings的 fallback 参数。我常用的是在请求参数里临时指定 fallback 模型response litellm.completion( modelopenai/gpt-4o-mini, messages[{role: user, content: Hello}], fallbacks[anthropic/claude-3-5-sonnet] )生产环境的建议是主备要分清楚。你可以在model_list里只配主模型再通过代码或请求参数指定备选。这样逻辑更清晰不会出现“明明是主备关系结果全混在一起轮询”的问题。另外要留意cooldown参数。LiteLLM 对刚失败的模型有冷却机制在冷却时间内不会把流量打过去。默认的冷却时间可能不适合所有场景如果某个模型故障恢复很快你可以调整cooldown_time比如设成 60 秒。参数太小会频繁触发抖动太大又会让恢复后的模型闲着这个需要观察实际故障频次来调。4.4 虚拟密钥与多租户隔离网关模式下LiteLLM 会生成一个默认的管理密钥你用它通过/key/generate接口给不同业务方生成虚拟密钥。每个虚拟密钥可以绑定不同的模型、不同的预算上限、不同的速率限制。举个例子A 业务线你给一个虚拟密钥模型只允许gpt-4o-mini月度预算 100 美元B 业务线你给另一个虚拟密钥模型可以访问gpt-4o和claude-3-5-sonnet月度预算 500 美元。两个人拿到的 Key 长得很像但权限完全不同。这块功能对于团队协作特别有价值但要注意虚拟密钥是存在 SQLite 或者 Postgres 里的默认 SQLite 适合单机测试多实例部署一定要切到 Postgres否则你启动多个 LiteLLM 实例时虚拟密钥和数据会互相不同步。5. 进阶能力盘点缓存、限速、预算与观测5.1 响应缓存真的能省不少钱大模型调用有个特点很多请求其实是重复或者高度相似的比如同样的系统提示词、同样的知识库问题。如果每次都花真金白银去调用厂商接口成本其实是很浪费的。LiteLLM 提供缓存功能可以基于请求内容计算哈希命中缓存就直接返回结果不再往后端转发。配置很简单litellm_settings: cache: true cache_params: type: redistype可以选redis或者s3本地开发也可以用内存缓存但生产环境几乎必须上 Redis。因为内存缓存在多实例下各存各的命中率低而且进程一重启缓存全丢。设置缓存之后响应里会带有缓存命中标志你可以据此监控命中率。这里有一个坑如果业务对实时性要求很高比如聊天助手要感知用户最新状态那缓存反而会导致回答陈旧。建议只对明显幂等的请求开缓存或者在请求参数里动态加上时间戳等唯一字段来绕过缓存。5.2 速率限制与并发控制别让一个业务把额度烧光团队共用网关的时候最怕的就是某个业务线写了个死循环瞬间把厂商配额打满其他业务全被连带限流。LiteLLM 的速率限制可以在虚拟密钥级别和全局级别分别配置。比如你给某个调用方设一个速率上限litellm.rate_limit (每分钟请求数, 每分钟 token 数)更细的做法是在生成密钥时直接指定max_parallel_requests或者tpm_limit。这样即使某个调用方失控影响也能被限制在它自己的额度里。这里我想强调一个容易忽略的点速率限制不只防别人也防自己。如果你接的模型厂商有严格的 RPM/TPM 配额你可以在网关层把速率限制设得比厂商配额低一点让流量平滑而不是频繁触发厂商侧的 429。这比自己写重试机制优雅得多。5.3 预算控制让每一分钱都有归属预算管理是 LiteLLM 一个非常亮眼的功能。你不只能看总花费还能给每个虚拟密钥、每个业务线、每个用户组设置预算上限。当花销达到预警线或上限时请求会被拒绝或者告警。我建议的做法是预算要设两层。第一层是虚拟密钥级预算防止单个调用方超支第二层是全局预算防止整体失控。比如给密钥设 100 美元硬上限给全局设 1000 美元硬上限双保险。预算数据存在数据库中自带定时任务去聚合统计。配置方式是在config.yaml里启用general_settings: database_url: postgresql://user:passhost:5432/litellm这里再次体现 Postgres 的重要性如果你用 SQLite多实例并发写预算记录时会有锁问题统计还会出现延迟。上生产、上正式团队协作直接上 Postgres省心。5.4 可观测性日志、追踪和告警一个都不能少可观测性的价值只有线上出过问题才会真正懂。LiteLLM 提供了丰富的日志和追踪能力。你可以把每次调用的模型名、耗时、token 消耗、成本、缓存命中情况记录到日志系统里。常用的集成是 Langfuse、Prometheus、自定义 Webhook。我自己的习惯是开 Prometheus 指标配合 Grafana 看板看几个关键指标请求量、错误率、p95 延迟、成本增速、缓存命中率。一旦某个模型错误率超过阈值告警就能拉起来。有一点需要注意默认日志级别是 INFO生产环境如果你存所有请求内容要注意脱敏。如果 messages 里包含用户隐私或者敏感数据日志里必须做字段过滤或者只记录元数据不记录 message 内容。这个细节很多人忽略等出安全问题就来不及了。6. 踩坑实录我在落地 LiteLLM 时遇到的 5 个典型问题6.1 环境变量不生效配置文件里一片报错有一次我启动代理日志疯狂报api_key缺失。检查了.env文件明明写对了。后来才发现LiteLLM 启动时确实会读.env但它读的是当前工作目录下的.env。如果你在别的目录执行litellm --config它就找不到那个文件。解决方式是显式指定环境变量文件路径或者干脆在 shell 里 source 一下.env再启动。这类问题很难排查因为报错信息并不直接说“找不到 .env 文件”而是表现成“key 不存在”。6.2 模型名带前缀不带前缀傻傻分不清这也是一个高频问题。LiteLLM 的模型名有“内部名”和“路由名”之分。配置文件里litellm_params.model要写成openai/gpt-4o-mini带上提供商前缀而请求参数里的model要写model_list.model_name也就是你起的逻辑名gpt-4o-mini。把这两个搞混的结果是要么后端不知道你是哪家厂商要么网关找不到对应的路由条目直接 404。6.3 fallback 没有按预期触发我遇到过配置了 fallback但主模型报错后直接返回错误、没有切换的情况。后来查文档发现fallback 不是对所有异常都生效。比如某些 4xx 错误像是请求参数错误LiteLLM 判定为“重试也没有意义”就不会触发 fallback。只有 429、5xx、超时这类可恢复错误才会切换。这个设计本身合理但一开始确实容易误解。建议你在测试 fallback 时故意用错误 API Key 或者超时请求来验证不要用“故意传错参数”来验证。6.4 OpenAI SDK 传了网关不认识的自定义参数OpenAI SDK 新版本更新很快经常会带一些额外参数比如extra_body或者工具相关的字段。LiteLLM 的兼容层虽然做得不错但不是所有厂商都支持 OpenAI 的全部参数。当 Anthropic 后端收到某些 OpenAI 专属参数时可能直接报错或者静默忽略。这个问题最好在测试环境充分跑一遍“同一套代码不同目标模型”的用例矩阵把不兼容的参数提前找出来。6.5 并发稍微上来请求开始堆积超时某个版本我用默认参数部署压测到 50 并发就出现大量超时。排查发现是 LiteLLM 默认的连接池大小不够而且 SQLite 数据库在统计请求时成了瓶颈。解决方式是连接池参数调大数据库切 Postgres并给代理服务加多实例和负载均衡。LiteLLM 本身是可以水平扩展的但底层的数据库必须跟上。6.6 问题排查速查表整理一个速查表方便你遇到问题时快速对号入座。症状可能原因排查方向启动报 api_key 缺失环境变量未加载检查工作目录、.env路径确认变量名请求返回 404路由名写错核对请求里的 model 是否等于model_name请求返回 401虚拟密钥无效确认密钥生成记录检查是否有黑名单fallback 不触发错误类型不受支持区分 4xx/5xx用 429 或超时测试并发一高就超时连接池小或 DB 锁切 Postgres调大连接池上多实例部分模型返回乱码提供商前缀错误检查litellm_params.model前缀是否匹配7. 要不要上 LiteLLM我的判断与一些实话7.1 什么情况下我很推荐如果你的团队同时接入了两个以上模型提供商或者你希望未来能在不同模型之间低成本切换LiteLLM 能带来的收益是压倒性的。它减少了业务代码里的厂商适配层让密钥管理、预算控制、故障转移有了统一的落点。我见过一个项目原本代码里硬编码了五六个 SDK 的调用逻辑接入 LiteLLM 后整个调用层被压缩成几十行配置后端从三套减成一套。这个收益是实打实的。7.2 什么情况下你要三思LiteLLM 也不是万金油。如果你的业务极其依赖某个模型的独有高级特性比如某些 platform 特有的多模态参数、不明文暴露的推理能力或者流式传输细节被厂商频繁调整那么经过一层网关转换后这些特性有可能会失真。还有一种情况是团队很小、只有一个模型、也没有预算管控需求那直接调官方 SDK 反而更简单。网关是好东西但不要为了用而用。另外如果你对数据隐私要求极高请求内容完全不允许经过任何中间层那么自建网关本身就是合规风险。这种情况下要么不做代理层要么对 LiteLLM 做深度的私有化定制确保日志、缓存、追踪全链路不落盘敏感信息。7.3 最后一个经验之谈我自己的经验是不要把 LiteLLM 当成一个“部署完就不管”的工具。它的配置文件、数据库表、监控指标都是需要持续运营的。模型厂商的接口在变、价格在变、限流策略在变你的路由表和预算参数也一定要跟着变。建议至少每个月审视一次哪些模型的实际成本超出了预期哪些路由该调整权重哪些虚拟密钥已经不再有人使用。还有一个小技巧分享给你在测试环境里可以故意配置一个不存在的模型名让所有请求都失败用它来验证你的告警链路通不通。这种“故障演练”比等着线上出故障再去复盘要舒服得多。LiteLLM 这类工具的出现本质上说明一个趋势大模型技术的使用正在从“会调用 API”走向“规范地管理 API”。先把网关搭好后面再换模型、加模型、调预算你都会感谢当初这个决定。
1. 这不是一个“模型”而是一个“总闸”——用一分钟认识 LiteLLM如果你和我一样过去一年里被各种大模型 API 折腾到头秃你应该能秒懂我在说什么OpenAI 的接口长一个样子Anthropic 的接口是另一个样子Google 的 Gemini 又是一套写法还有 Azure OpenAI、本地部署的 vLLM、各类国产模型……每个服务商的鉴权方式、请求格式、返回结构、超时策略都各玩各的。业务代码里塞满了 if-else 分支去适配不同厂商SDK 换了一个又一个prompt 模板在不同系统间复制粘贴密钥散落在各种环境文件里。说实话这不是“技术选型”问题这是“接口地狱”问题。LiteLLM 就是来收拾这个烂摊子的。一句话概括它是一个开源的 LLM 网关/代理层让你用 OpenAI 那套统一的请求格式去调用市面上几乎主流的大模型接口不管是闭源商业模型、云厂商模型还是自建的开源模型。它既可以直接作为 Python 库在你的服务里调用也可以作为一个独立的代理服务跑起来团队所有人把base_url指到它上面就算接入完成。内部的真实后端是谁、密钥怎么管理、模型怎么路由、失败怎么重试全部由这一层替你消化。LiteLLM 不是又一个新模型也不是一个“提示词管理工具”。它站在你和模型提供商之间解决的是接口标准化、模型路由、成本控制、故障转移这一整类问题。适合谁来用如果你的团队同时接了好几家模型经常做模型之间的对比评测或者需要在生产环境里给多个业务线分配模型调用预算那这篇文章就是写给你看的。哪怕你只是一个人在做 Side Project用 LiteLLM 也能让你换模型的时候不再改代码。2. 核心设计思路拆解网关为什么能解决“接口混乱”2.1 先搞懂它的最小认知模型路由层 转换层 管控层我刚接触 LiteLLM 的时候第一反应是“这不就是一个 API 转发器吗”。用了一段时间才意识到转发只是表象它真正的价值在于把一大坨非标准化的事情藏在了后面。你可以把 LiteLLM 想象成机场的中转柜台。乘客你的应用请求只需要在柜台办一次登机手续柜台背后是不同航空公司OpenAI、Anthropic、Azure、本地模型的航班。LiteLLM 做的事情有三层第一层是协议转换。你发给它的请求是 OpenAI 风格的chat.completions格式它内部会把你这个请求翻译成目标厂商真正认识的格式。比如 Anthropic 的消息结构跟 OpenAI 差别很大LiteLLM 会做字段映射、系统提示词拼接、参数换算。这一层做得越扎实用户就越感觉不到后端差异。第二层是路由决策。请求到了以后到底转给哪个厂商这取决于你的配置可以按模型名直接转发也可以配置成一组模型做负载均衡还可以在主模型报错时自动切换备用模型。LiteLLM 会根据你定义的model_list和策略决定这一单“派给”谁。第三层是管控与观测。记录每个请求花多少钱、谁在调、响应速度怎么样、是不是该限流了、预算额度还剩多少。这些信息不是锦上添花而是生产环境里的刚需。没有这一层账单出来的时候你根本不知道钱花哪了。这个“三层结构”的价值在于你的业务代码只需要认识 OpenAI 格式其他所有复杂度都被挡在网关外面。这不是什么高深技术但它对工程效率的提升非常直观。2.2 为什么偏偏是 OpenAI 格式而不是搞一套“万能格式”很多人会问既然要做标准化为什么不能定义一个所有人都认同的“标准格式”让各家模型都来适配它理论上可以但现实中行不通。因为 OpenAI 的接口格式实际上已经成了事实标准——所有主流 SDK、开源工具、Agent 框架、评测系统默认都按 OpenAI 风格调用。你随便打开一个 LangChain 项目或者一个开源 Agent 项目它内部描述 LLM 接口的方式大概率就是base_url加api_key请求体就是messages数组。LiteLLM 选择兼容 OpenAI 格式意味着它不需要发明新生态而是无缝接入现有生态。这个决策非常务实。对我这种用惯了 OpenAI SDK 的人来说接入 LiteLLM 的代理服务只需要改两行配置把base_url指到 LiteLLM 地址把api_key换成虚拟密钥。其余代码一行都不用动。这意味着团队切换模型根本不需要做大规模代码重构风险直线下降。2.3 两种使用姿势库模式还是网关模式LiteLLM 提供了两种集成方式很多人一开始分不清这里我给你捋清楚。第一种是库模式在 Python 代码里直接import litellm调用litellm.completion()或者litellm.embedding()。这时候 LiteLLM 是运行在你进程里的一个函数库你把参数传进去它帮你完成格式转换、调用 API、返回结果。这种方式适合写脚本、做批处理、快速跑实验也适合在单体应用里不想多维护一个服务的场景。第二种是网关模式把 LiteLLM 跑成一个独立的 HTTP 服务默认端口 4000。你用它加载一份配置文件启动后它就对外暴露一个/chat/completions端点。你的应用、你的同事、你的微服务全都把这个端点当成 OpenAI 来调用。密钥、模型路由、预算策略都在服务端统一管理。这种方式适合团队协作、生产部署、多业务复用——网关模式才是 LiteLLM 真正拉开差距的地方。这两种模式不是互斥的很多团队是先库模式验证再切网关模式上生产。我建议你直接按最终形态来规划避免后面返工。3. 动手落地从安装到跑通你的第一个代理接口3.1 最小环境准备开始之前先把环境准备利索。LiteLLM 是 Python 生态Python 3.8 以上基本都能跑但要上生产我建议至少 Python 3.10 以上。安装很简单pip install litellm[proxy]注意这里不是pip install litellm那么简单[proxy]这个 extra 会额外带上代理服务需要的依赖比如 FastAPI、uvicorn 这些。如果你只想用库模式装裸包就行但如果要启动代理一定别漏掉[proxy]。装完以后可以先验证一下版本litellm --version能输出版本号就说明装好了。这里很多人第一步就会踩坑装完litellm敲litellm --help却发现命令找不到。原因通常就是那个[proxy]没带或者环境变量 PATH 出了问题解决方式就是重装一次带 extra 的包。3.2 写第一份 config.yaml网关模式的核心是配置文件。你可以理解为所有路由规则、密钥指向、策略参数都写在 YAML 里启动的时候加载一次。先看一个最简配置model_list: - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: claude-3-5-sonnet litellm_params: model: anthropic/claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY这里面有几种关键写法需要解释。model_list是路由表每一项是一条路由。model_name是对外暴露的名字你的同事写代码时用的是这个名字litellm_params是内部真正要传给后端的参数。model字段的写法是提供商/模型名比如openai/gpt-4o-mini、anthropic/claude-3-5-sonnet。这个前缀不能乱写LiteLLM 靠它识别该走哪套转换逻辑。api_key直接写明文并不推荐更稳妥的是用os.environ/环境变量名这种写法让 LiteLLM 从进程环境变量里读密钥。这样配置文件可以进版本库密钥不会泄露。3.3 启动代理服务的两种路径有了配置启动服务有两种方式。第一种是把配置写到默认位置然后直接启动litellm --config ./config.yaml --port 4000第二种是用config.yaml作为主配置再把模型通过环境变量临时补充进去litellm --model gpt-4o-mini --port 4000第二种适合极简场景你不想写配置文件只想飞快跑一个代理出来。但如果你准备认真用我建议统一走配置文件路线。因为后续加预算、加 fallback、加负载均衡全部都是在config.yaml里扩展命令行参数只是便捷入口不是完整方案。启动之后你会看到服务监听在 4000 端口日志输出模型路由表。看到Uvicorn running on http://0.0.0.0:4000就算成功了。注意默认只监听本机如果要给局域网其他同事用启动参数里记得加上--host 0.0.0.0。3.4 用 curl 验证代理是否真的通了服务起来了先用 curl 打一发试试curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-your-virtual-key \ -d { model: gpt-4o-mini, messages: [{role: user, content: 你好用一句话介绍你自己}] }这里有几个细节要注意路径是/v1/chat/completions不是/chat/completions鉴权头是Authorization: Bearer xxxmodel字段传的是你在model_list里定义的model_name不是真实后端模型名。如果返回的 JSON 里有choices[0].message.content说明整条链路已经通了。3.5 把现有 OpenAI SDK 客户端指到 LiteLLM验证之后更爽的一步来了在你现有的 Python 项目里不用改业务代码只需要改一下客户端配置from openai import OpenAI client OpenAI( api_keysk-your-virtual-key, base_urlhttp://localhost:4000/v1 ) response client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 讲个冷笑话}] ) print(response.choices[0].message.content)这段代码对很多人来说再熟悉不过了唯一变的是base_url和api_key。你现在请求的不是 OpenAI 官方而是 LiteLLM但代码层面的心智负担一点没增加。如果以后想从 GPT 换成 Claude你只需要把model参数改成claude-3-5-sonnet其他都不用动——前提是 LiteLLM 配置文件里已经定义了这个路由。4. 模型路由与密钥管理从单模型过渡到多模型调度4.1 环境变量管理密钥别再往代码里塞 Key密钥管理是很多团队最容易翻车的地方。见过不少人把 API Key 直接写在 Python 文件里或者写进 Docker 镜像的环境变量文件里密钥一泄露账就跑得像流水一样。LiteLLM 的标准做法是用环境变量引用。YAML 里写os.environ/OPENAI_API_KEY然后启动前在 shell 里导出export OPENAI_API_KEYsk-xxxx export ANTHROPIC_API_KEYsk-ant-xxxx如果你用 docker-compose 部署可以在environment字段里传。如果你用 Kubernetes把密钥放到 Secret 里再挂载成环境变量。这样配置文件本身是可以提交到代码仓库的密钥永远留在部署环境里。LiteLLM 还支持从.env文件加载变量它内部会调用 dotenv 的逻辑。你可以在项目目录放一个.env里面写OPENAI_API_KEYsk-xxxx启动时自动加载。但注意.env文件一定不要提交到 Git要在.gitignore里加一条。4.2 model_list 与 model_group路由表才是真正的灵魂很多人把model_list当成一个简单的“模型名映射表”用起来是够的但理解不透会导致后面配置负载均衡一塌糊涂。这里我给你一个更准确的认知model_list里的每一条其实是注册了一个“路由条目”而model_name相当于一个逻辑名字LiteLLM 内部通过这个名字去做查找。举个例子你可以给同一个model_name配置多个真实后端这样可以实现负载均衡和故障转移model_list: - model_name: my-chat-model litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: my-chat-model litellm_params: model: anthropic/claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY表面上看你对外只暴露了一个my-chat-model但请求会在 OpenAI 和 Anthropic 之间轮询分发。这样做有什么好处第一某个厂商出故障时流量可以自动转移到另一家第二你可以按价格或者按性能去调权重让便宜的模型多承接一些请求第三业务方完全感知不到后端换了一家。这就是网关的“总闸”价值——业务方只认一个名字背后的风控、调度、冗余全部由平台层负责。4.3 fallback 策略与重试生产环境不能裸奔只配置路由列表但没有故障转移策略在生产环境就是裸奔。模型厂商接口偶尔 5xx、超时、限流都是家常便饭。尤其 OpenAI 的高峰期429 错误太常见了。在config.yaml里配置 fallback 有两种方式。一种是model_list里的隐式 fallback——把同一个model_name指向多个后端LiteLLM 默认就有重试逻辑当主模型抛错时会尝试列表里的下一个前提是错误类型允许重试。这个隐式行为方便但不好精细控制因为它会对所有模型条目一视同仁地轮询。另一种是显式配置router_settings的 fallback 参数。我常用的是在请求参数里临时指定 fallback 模型response litellm.completion( modelopenai/gpt-4o-mini, messages[{role: user, content: Hello}], fallbacks[anthropic/claude-3-5-sonnet] )生产环境的建议是主备要分清楚。你可以在model_list里只配主模型再通过代码或请求参数指定备选。这样逻辑更清晰不会出现“明明是主备关系结果全混在一起轮询”的问题。另外要留意cooldown参数。LiteLLM 对刚失败的模型有冷却机制在冷却时间内不会把流量打过去。默认的冷却时间可能不适合所有场景如果某个模型故障恢复很快你可以调整cooldown_time比如设成 60 秒。参数太小会频繁触发抖动太大又会让恢复后的模型闲着这个需要观察实际故障频次来调。4.4 虚拟密钥与多租户隔离网关模式下LiteLLM 会生成一个默认的管理密钥你用它通过/key/generate接口给不同业务方生成虚拟密钥。每个虚拟密钥可以绑定不同的模型、不同的预算上限、不同的速率限制。举个例子A 业务线你给一个虚拟密钥模型只允许gpt-4o-mini月度预算 100 美元B 业务线你给另一个虚拟密钥模型可以访问gpt-4o和claude-3-5-sonnet月度预算 500 美元。两个人拿到的 Key 长得很像但权限完全不同。这块功能对于团队协作特别有价值但要注意虚拟密钥是存在 SQLite 或者 Postgres 里的默认 SQLite 适合单机测试多实例部署一定要切到 Postgres否则你启动多个 LiteLLM 实例时虚拟密钥和数据会互相不同步。5. 进阶能力盘点缓存、限速、预算与观测5.1 响应缓存真的能省不少钱大模型调用有个特点很多请求其实是重复或者高度相似的比如同样的系统提示词、同样的知识库问题。如果每次都花真金白银去调用厂商接口成本其实是很浪费的。LiteLLM 提供缓存功能可以基于请求内容计算哈希命中缓存就直接返回结果不再往后端转发。配置很简单litellm_settings: cache: true cache_params: type: redistype可以选redis或者s3本地开发也可以用内存缓存但生产环境几乎必须上 Redis。因为内存缓存在多实例下各存各的命中率低而且进程一重启缓存全丢。设置缓存之后响应里会带有缓存命中标志你可以据此监控命中率。这里有一个坑如果业务对实时性要求很高比如聊天助手要感知用户最新状态那缓存反而会导致回答陈旧。建议只对明显幂等的请求开缓存或者在请求参数里动态加上时间戳等唯一字段来绕过缓存。5.2 速率限制与并发控制别让一个业务把额度烧光团队共用网关的时候最怕的就是某个业务线写了个死循环瞬间把厂商配额打满其他业务全被连带限流。LiteLLM 的速率限制可以在虚拟密钥级别和全局级别分别配置。比如你给某个调用方设一个速率上限litellm.rate_limit (每分钟请求数, 每分钟 token 数)更细的做法是在生成密钥时直接指定max_parallel_requests或者tpm_limit。这样即使某个调用方失控影响也能被限制在它自己的额度里。这里我想强调一个容易忽略的点速率限制不只防别人也防自己。如果你接的模型厂商有严格的 RPM/TPM 配额你可以在网关层把速率限制设得比厂商配额低一点让流量平滑而不是频繁触发厂商侧的 429。这比自己写重试机制优雅得多。5.3 预算控制让每一分钱都有归属预算管理是 LiteLLM 一个非常亮眼的功能。你不只能看总花费还能给每个虚拟密钥、每个业务线、每个用户组设置预算上限。当花销达到预警线或上限时请求会被拒绝或者告警。我建议的做法是预算要设两层。第一层是虚拟密钥级预算防止单个调用方超支第二层是全局预算防止整体失控。比如给密钥设 100 美元硬上限给全局设 1000 美元硬上限双保险。预算数据存在数据库中自带定时任务去聚合统计。配置方式是在config.yaml里启用general_settings: database_url: postgresql://user:passhost:5432/litellm这里再次体现 Postgres 的重要性如果你用 SQLite多实例并发写预算记录时会有锁问题统计还会出现延迟。上生产、上正式团队协作直接上 Postgres省心。5.4 可观测性日志、追踪和告警一个都不能少可观测性的价值只有线上出过问题才会真正懂。LiteLLM 提供了丰富的日志和追踪能力。你可以把每次调用的模型名、耗时、token 消耗、成本、缓存命中情况记录到日志系统里。常用的集成是 Langfuse、Prometheus、自定义 Webhook。我自己的习惯是开 Prometheus 指标配合 Grafana 看板看几个关键指标请求量、错误率、p95 延迟、成本增速、缓存命中率。一旦某个模型错误率超过阈值告警就能拉起来。有一点需要注意默认日志级别是 INFO生产环境如果你存所有请求内容要注意脱敏。如果 messages 里包含用户隐私或者敏感数据日志里必须做字段过滤或者只记录元数据不记录 message 内容。这个细节很多人忽略等出安全问题就来不及了。6. 踩坑实录我在落地 LiteLLM 时遇到的 5 个典型问题6.1 环境变量不生效配置文件里一片报错有一次我启动代理日志疯狂报api_key缺失。检查了.env文件明明写对了。后来才发现LiteLLM 启动时确实会读.env但它读的是当前工作目录下的.env。如果你在别的目录执行litellm --config它就找不到那个文件。解决方式是显式指定环境变量文件路径或者干脆在 shell 里 source 一下.env再启动。这类问题很难排查因为报错信息并不直接说“找不到 .env 文件”而是表现成“key 不存在”。6.2 模型名带前缀不带前缀傻傻分不清这也是一个高频问题。LiteLLM 的模型名有“内部名”和“路由名”之分。配置文件里litellm_params.model要写成openai/gpt-4o-mini带上提供商前缀而请求参数里的model要写model_list.model_name也就是你起的逻辑名gpt-4o-mini。把这两个搞混的结果是要么后端不知道你是哪家厂商要么网关找不到对应的路由条目直接 404。6.3 fallback 没有按预期触发我遇到过配置了 fallback但主模型报错后直接返回错误、没有切换的情况。后来查文档发现fallback 不是对所有异常都生效。比如某些 4xx 错误像是请求参数错误LiteLLM 判定为“重试也没有意义”就不会触发 fallback。只有 429、5xx、超时这类可恢复错误才会切换。这个设计本身合理但一开始确实容易误解。建议你在测试 fallback 时故意用错误 API Key 或者超时请求来验证不要用“故意传错参数”来验证。6.4 OpenAI SDK 传了网关不认识的自定义参数OpenAI SDK 新版本更新很快经常会带一些额外参数比如extra_body或者工具相关的字段。LiteLLM 的兼容层虽然做得不错但不是所有厂商都支持 OpenAI 的全部参数。当 Anthropic 后端收到某些 OpenAI 专属参数时可能直接报错或者静默忽略。这个问题最好在测试环境充分跑一遍“同一套代码不同目标模型”的用例矩阵把不兼容的参数提前找出来。6.5 并发稍微上来请求开始堆积超时某个版本我用默认参数部署压测到 50 并发就出现大量超时。排查发现是 LiteLLM 默认的连接池大小不够而且 SQLite 数据库在统计请求时成了瓶颈。解决方式是连接池参数调大数据库切 Postgres并给代理服务加多实例和负载均衡。LiteLLM 本身是可以水平扩展的但底层的数据库必须跟上。6.6 问题排查速查表整理一个速查表方便你遇到问题时快速对号入座。症状可能原因排查方向启动报 api_key 缺失环境变量未加载检查工作目录、.env路径确认变量名请求返回 404路由名写错核对请求里的 model 是否等于model_name请求返回 401虚拟密钥无效确认密钥生成记录检查是否有黑名单fallback 不触发错误类型不受支持区分 4xx/5xx用 429 或超时测试并发一高就超时连接池小或 DB 锁切 Postgres调大连接池上多实例部分模型返回乱码提供商前缀错误检查litellm_params.model前缀是否匹配7. 要不要上 LiteLLM我的判断与一些实话7.1 什么情况下我很推荐如果你的团队同时接入了两个以上模型提供商或者你希望未来能在不同模型之间低成本切换LiteLLM 能带来的收益是压倒性的。它减少了业务代码里的厂商适配层让密钥管理、预算控制、故障转移有了统一的落点。我见过一个项目原本代码里硬编码了五六个 SDK 的调用逻辑接入 LiteLLM 后整个调用层被压缩成几十行配置后端从三套减成一套。这个收益是实打实的。7.2 什么情况下你要三思LiteLLM 也不是万金油。如果你的业务极其依赖某个模型的独有高级特性比如某些 platform 特有的多模态参数、不明文暴露的推理能力或者流式传输细节被厂商频繁调整那么经过一层网关转换后这些特性有可能会失真。还有一种情况是团队很小、只有一个模型、也没有预算管控需求那直接调官方 SDK 反而更简单。网关是好东西但不要为了用而用。另外如果你对数据隐私要求极高请求内容完全不允许经过任何中间层那么自建网关本身就是合规风险。这种情况下要么不做代理层要么对 LiteLLM 做深度的私有化定制确保日志、缓存、追踪全链路不落盘敏感信息。7.3 最后一个经验之谈我自己的经验是不要把 LiteLLM 当成一个“部署完就不管”的工具。它的配置文件、数据库表、监控指标都是需要持续运营的。模型厂商的接口在变、价格在变、限流策略在变你的路由表和预算参数也一定要跟着变。建议至少每个月审视一次哪些模型的实际成本超出了预期哪些路由该调整权重哪些虚拟密钥已经不再有人使用。还有一个小技巧分享给你在测试环境里可以故意配置一个不存在的模型名让所有请求都失败用它来验证你的告警链路通不通。这种“故障演练”比等着线上出故障再去复盘要舒服得多。LiteLLM 这类工具的出现本质上说明一个趋势大模型技术的使用正在从“会调用 API”走向“规范地管理 API”。先把网关搭好后面再换模型、加模型、调预算你都会感谢当初这个决定。
