★ FEATURED ARTICLE 1. 先聊聊 litellm 到底解决了什么问题做 AI 应用集成做久了最烦的其实不是模型效果不够好而是每次接一个新模型都要重新读一遍文档、改一遍请求格式、调一遍 SDK 参数。我手头一个项目从单一模型扩展到多个模型时这种痛苦被放大了好几倍业务代码里塞满了各种 if-else 分支每家一个调用方式认证逻辑还不一样。后来我把 litellm 引入进来才算是把这摊子理顺了。简单说litellm 是一个开源的大模型 API 统一网关它对外提供一套 OpenAI 兼容的接口内部帮你把各家模型服务商的 API 差异全部消化掉。你的业务代码只需要认识一套接口格式剩下的事情交给它去翻译和路由。这个项目适合三类人第一类是自己写 AI 应用以后可能要多模型切换的开发者第二类是团队里多个人共用 API key需要统一管理和控制预算的技术负责人第三类是需要做高可用设计希望自动降级、失败重试、负载均衡的人。对于只打算调一家模型、做个一次性 demo 的场景直接上 litellm 反而有点重后面我会专门讲哪些情况不建议用它。1.1 API 碎片化每家一个格式接到怀疑人生你打开几家主流模型服务商的文档就会发现请求体结构大同小异但细看全是对不上的有的用messages有的用prompt有的返回内容在choices[0].message.content有的在generated_text超参数名字也不统一温度、top_p、max_tokens 在不同平台叫法略有差异。更别提认证方式有的是 Bearer Token有的是自定义请求头有的还要走特定的签名流程。这还不是最难受的。SDK 也各搞一套Python 环境里装了一堆不同家的 SDK版本互相影响升级一个可能搞挂另一个。业务要想同时支持几家就得为每一家写一层适配代码模型越多适配层越臃肿。litellm 的核心思路就是把这些差异从你的业务代码里抽离出来你只管 OpenAI 格式的请求它负责翻译给真正的目标模型。业务代码里那些if provider xxx的分支全部可以删掉了。1.2 key 管理和成本控制不集中管控就是一笔糊涂账另一个容易被忽视的痛点是 API key 的管理。小团队里通常是一把钥匙大家共用谁用了多少、调用了哪些模型、烧了多少钱全都黑盒。你要是直接把 key 写在代码里或者发给同事一旦泄露或者被超出预算地调用账单出来的时候基本已经晚了。litellm 相当于在业务代码和模型的原始 key 之间加了一道隔离层。你不再需要把原始 key 暴露给业务侧而是在网关里创建虚拟 key每个虚拟 key 可以单独设置预算上限、每分钟请求数限制还可以在后台看到每个 key 的真实调用记录和费用估算。这种能力对成本敏感的项目来说是刚需尤其是接入了多个模型、多人共用的场景。1.3 从“能用”到“可用”网关带出来的可用性优势只用单一模型供应商的时候接口一抖动整个业务就跟着抖。你可能会在业务代码里做重试、做故障切换但这部分逻辑跟业务耦合在一起写起来啰嗦还容易出错。litellm 把这类稳定性能力下沉到了网关层上游某个模型返回限流了网关可以自动重试主模型挂了可以自动切换到备用模型同一个模型配置了多个 key可以轮询分散压力。业务方不会感知这些变化它们拿到的还是一个 OpenAI 兼容接口的响应。2. litellm 的核心设计是怎么做到“一把梭”的前面说的是它解决什么问题接下来拆一下它是怎么解决的。理解了设计思路你在配置和使用的时候就不会抓瞎出了问题也知道往哪个方向排查。2.1 OpenAI 兼容接口成了整个生态的“通用语言”在众多模型服务商里OpenAI 的接口格式事实上已经成了行业标准很多其他平台也直接提供 OpenAI 兼容端点。litellm 干脆把 OpenAI 这种格式作为对外的统一接口也作为内部的中间表示。请求进来的时候是 OpenAI 格式翻译层把它转成目标模型原生格式目标模型返回之后再统一转回 OpenAI 格式。这个选择的聪明之处在于生态复用。你的业务代码只需要会调 OpenAI SDK或者会发一个标准 HTTP 请求就能访问 litellm 背后的所有模型。这意味着你现有的监控、测试、日志工具几乎不用改接入成本极低。对团队来说新人上手也快只需要理解一套接口约定。2.2 翻译层一个请求从进入到返回中间发生了什么你向 litellm 发送一个请求它的处理流程大致是这样的先根据配置里面定义的模型列表找到你请求的那个模型名确认它对应哪家服务商取到该服务商配置的 key 和模型标识然后调用对应的翻译器把 OpenAI 格式的请求转成目标服务商的原生格式发送出去。拿到响应后再做一次反向翻译把返回内容、token 用量、报错信息统一成 OpenAI 结构的字段。不同服务商的差异点主要集中在几处请求 URL 的组装方式、认证请求头、超参数映射、输出文本字段的提取、错误码到标准错误响应的转换。litellm 内部维护了大量这类映射规则这也是它最核心的资产。你不需要知道每条规则长什么样但要知道凡是主流模型服务商它基本都有现成适配社区更新也比较活跃新出的模型通常隔一阵就能被支持。2.3 路由、预算和策略都在配置层解决litellm 不是把各家 API 简单包装一下就完事它还把不少策略能力内置了进来通过一份 YAML 配置文件就能启用。模型列表、密钥、预算上限、并发限制、重试次数、负载均衡策略、fallback 顺序这些都是配置而不是代码。改策略不用发版改配置文件、重启进程或者直接通过管理接口热更新。举个例子你在配置里可以给某个虚拟 key 设置max_budget: 100当这个 key 的累计调用费用超过 100 的时候网关会直接拒绝后续请求。这个能力如果自己写你得记录每次调用的 token 数再按模型单价算费用工程量不小。litellm 内置了费用估算表按模型单价计算省了很多事。2.4 网关由哪些部分组成litellm 本身是 Python 写的核心是一个类 FastAPI 的服务会暴露一组 REST 接口。同时它带了一个可选的 Web 控制台界面用来管理 key、查看日志、调整模型配置。默认情况下它也可以把日志写进 SQLite方便查询和统计。部署形态很简单本地跑一个进程或者起一个容器开发环境、生产环境都能用。3. 实操半小时跑通你的第一个统一网关理论说再多不如自己跑一遍。下面我按实际操作的顺序把从安装到发起第一个请求的完整过程走一遍。这些步骤我在多个环境里都验证过照着做基本不会有问题。3.1 环境准备与安装前提是你的机器有 Python 3.8 以上版本建议用虚拟环境来装避免污染全局环境。安装命令很简单pip install litellm[proxy][proxy]这个扩展会装上服务端相关的依赖包括 FastAPI、数据库驱动这些。如果你只是想简单调用一下不跑服务装pip install litellm就够了。我个人建议从最开始就装完整版省得后面用到代理功能才发现缺依赖。装完之后验证一下litellm --version能输出版本号就说明装好了。如果在公司内网可能需要配 pip 镜像源具体的按你团队既有习惯来就行。3.2 写第一份 config.yamllitellm 的核心配置是一个 YAML 文件。下面给一个最小可用的示例我把改动点都做了注释说明model_list: - model_name: gpt-4o-mini litellm_params: model: gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: claude-3-5-sonnet litellm_params: model: claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY这里有几个关键点model_name是你在业务代码里实际要用的名字可以自己起不一定跟上游模型原名一致litellm_params里面定义的是真正的上游模型标识和对应的 key。os.environ/OPENAI_API_KEY表示从环境变量里读取 key而不是明文写在配置文件里这个习惯一定要养成别把密钥提交到代码仓库。3.3 启动服务配置文件写好后启动litellm --config config.yaml --port 4000看到类似 “Uvicorn running on http://0.0.0.0:4000” 的日志就说明起来了。默认端口是 4000你也可以换成别的。注意如果你要对外提供服务需要自行保证网络安全不要把没有任何鉴权的服务直接暴露到公网。启动后可以在浏览器打开http://localhost:4000会看到一个简易控制台里面可以查看请求日志、创建虚拟 key。初次登录可能需要设置一个管理员账号和密码按提示操作即可。3.4 用 OpenAI SDK 打第一个请求litellm 对外提供的接口是 OpenAI 兼容的所以直接用 OpenAI 的 Python SDK 来调是最省事的方式只需要改一下base_url和api_keyfrom openai import OpenAI client OpenAI( base_urlhttp://localhost:4000, api_keysk-anything, ) resp client.chat.completions.create( modelgpt-4o-mini, messages[ {role: user, content: 你好用一句话介绍一下你自己} ], ) print(resp.choices[0].message.content)这里的api_key你随便填一个占位符就行因为 litellm 在本地没有强制校验。用 curl 也是一样curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 你好}] }能拿到正常响应说明整个链路已经通了。这时候你再把配置里的model_name换成claude-3-5-sonnet业务代码一行都不用改请求就被转发到了另一个服务商的模型上。这就是 litellm 最直观的价值。3.5 创建虚拟 key 并绑定预算直接裸用网关虽然能转发请求但体现不出管理能力。接下来去控制台创建一个虚拟 key给它设置每月预算上限。在 UI 里找到创建 key 的入口填一个名字选预算金额和速率限制生成后会给你一串以sk-开头的字符串这就是业务代码里实际要用的 key。把前面的 Python 示例里的api_key换成这个虚拟 key再调用一次。然后回头看控制台的日志页面能看到这次请求的模型名、token 数、估算费用。这套机制保证了每一个调用方都有自己的独立凭证出了问题能追到具体是谁成本也能分摊清楚。3.6 零配置文件快速开始如果你只是想快速实验一下不想写配置文件litellm 也支持命令行直接起服务litellm --model gpt-4o-mini --port 4000这种方式会在内存里自动生成一个最简配置适合临时测试。不过它不持久化一重启就没了正经项目还是从配置文件开始比较好。4. 进阶用法把网关当基础设施来用跑通基础链路之后你会慢慢发现网关能做的事情比想象中多。下面这几个用法是我在实际项目里切实受益的按推荐程度排序。4.1 多模型自动降级如果主模型偶尔抽风或者被限流你希望自动切换到备用模型可以在配置里给同一个model_name配多个模型并指定优先级model_list: - model_name: my-chat-model litellm_params: model: gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: my-chat-model litellm_params: model: claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY业务代码里请求modelmy-chat-model时litellm 会默认优先使用第一个如果第一个报错或者超时会自动尝试第二个。这个 fallback 是发生在网关层的调用方没有感知。我自己把这种机制当成了高可用设计的一部分比起在业务里写一堆容错逻辑干净得多。需要注意的是fallback 触发条件默认是连接错误、超时、5xx 这类服务端异常。业务层面的错误比如被模型内容审核拦截不会触发 fallback这是合理的别指望网关能替你过滤所有问题。4.2 同一个模型配置多个 key 做负载均衡当你在一个模型上消耗很大单把 key 触发了速率限制可以配置多个 key 让网关轮询使用model_list: - model_name: my-chat-model litellm_params: model: gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: my-chat-model litellm_params: model: gpt-4o-mini api_key: os.environ/OPENAI_API_KEY_2注意两个条目的model_name一样但上游 key 不同。网关在转发时会自动在多个可用条目之间做负载均衡。这么做有一个隐藏的好处单把 key 因为超预算被服务商临时封禁时另一把 key 还能顶上。4.3 预算、配额和用量追踪litellm 的用量统计逻辑是每次请求响应后会拿到返回里的 token 使用量再根据单价表估算这次请求的费用。你可以在虚拟 key 里设置按请求的速率限制比如每分钟最多 100 次也可以设置总预算比如 100 美元达到上限之后 key 自动失效。如果想把用量数据导入自己的监控系统litellm 支持把日志同步到数据库或者通过管理接口拉取用量明细。我通常每个月底导出一次用量按虚拟 key 维度做成成本报表谁用了多少一目了然。这对多部门分摊成本非常有帮助。4.4 接入本地模型和内网推理服务litellm 不止对接云端服务商也能把本地跑的推理服务统一纳管进来。比如你在内网用开源模型架了一个推理服务地址是http://10.x.x.x:8080配置方式是这样model_list: - model_name: llama-local litellm_params: model: openai/llama-local api_key: local api_base: http://10.x.x.x:8080/v1这个场景的价值在于业务代码不需要区分模型是云端还是本地。本地服务没负载的时候走本地需要扩展的时候切云端切换逻辑只发生在配置层。对于有数据隔离要求的项目你可以把敏感数据的推理全部走本地模型通用场景走云端业务代码却不需要感知这两种模式的存在。4.5 流式响应和超时控制流式输出对用户体验很重要litellm 完全支持 OpenAI 风格的流式响应。业务代码里用 OpenAI SDK 的方式开启streamTrue拿到的是流式对象用法和直连官方 API 一致。服务端接收到流式请求后会把上游模型的流式输出逐段转发给调用方中间的翻译也是按增量处理的。超时参数可以在配置里控制比如litellm_settings: request_timeout: 30建议根据你的业务场景设定合理的超时时间太短容易误杀长耗时模型太长会让用户体验变差。我一般设 30 到 60 秒之间长文本生成场景会放宽到 120 秒。5. 实战中踩过的坑与排查方法这部分把我实际遇到过的典型问题整理成速查按现象分类方便你遇到问题时快速定位。5.1 请求返回 404提示模型不存在这个问题的常见原因有三个一是请求里的model参数跟配置文件里的model_name不一致哪怕是大小写不同也不行配置里写了gpt-4o-mini请求里传了gpt-4o那就找不到二是配置改了之后没重启服务进程还在用旧的模型列表三是服务跑在多个实例上你改的是其中一个实例的配置但请求发到了另一个实例。优先检查请求参数和当前进程的配置加载情况基本能解决七八成的 404。5.2 虚拟 key 认证失败如果你配置了 Master Key 或者启用了 key 管理业务请求必须带上有效虚拟 key。常见错误是用环境变量里原始服务商的 key 直接请求 litellm这时候 litellm 不认识它会返回认证错误。记住业务侧使用的始终是 litellm 创建的虚拟 key而不是上游服务商的 key。虚拟 key 失效还有一种情况是你设置了预算或过期时间它到了上限之后会被自动禁用控制台日志里会记录原因。5.3 超时和限流的误区上游模型偶尔限流是常态。litellm 本身会做重试但重试策略默认不一定适合所有场景。如果你发现某个上游服务经常超时可以像这样调整litellm_settings: request_timeout: 60 retry_max_attempts: 3 retry_policy: Timeout: true RateLimitError: trueretry_policy可以按错误类型精细控制哪些情况需要重试。注意重试次数别设太多否则上游模型持续抖动时网关会积压大量请求反而把自己的服务拖垮。我一般设 2 到 3 次。5.4 日志与调试开关排查问题时打开调试日志很有帮助。启动命令加一个参数litellm --config config.yaml --port 4000 --detailed_debug这样请求进来后litellm 会输出内部转发过程的详细日志包括它调用了哪个上游地址、拿到了什么响应、转换后的结果如何。对于自己写适配器或者排查翻译异常的人来说这个开关就是救命的。5.5 排查速查表现象可能原因快速排查方法模型不存在model 参数与配置不一致检查请求里的 model 与配置的 model_name认证失败用了原始 key或虚拟 key 失效换用 virtual key检查 key 的预算状态请求超时上游模型响应慢配置超时太短调大 request_timeout检查上游状态频繁被限流单 key 触发速率上限配置多个 key 做负载均衡返回乱码上游模型输出编码问题不经过 litellm 直连上游确认排除网关问题费用异常key 没有限额给虚拟 key 设置预算上限6. 有没有不适合用 litellm 的情况客观说litellm 不是银弹有些场景上了它反而更费劲。第一个场景只用一个模型服务商而且团队规模很小。这时候直接用官方 SDK 最简单没有中间层没有额外维护成本出问题还能直接看官方文档。网关适合在有多元化需求的时候引入提前引入属于过度设计。第二个场景业务对数据出口有严格限制所有请求都不允许出内网也不允许经过额外的第三方组件。litellm 本身是开源可自部署的但它默认还是在你的内网里充当一个转发节点如果你连这种转发都不允许那就只能直连模型服务商或者用别的安全方案。第三个场景团队已经有成熟的 API 网关和鉴权体系又不想再引入一套带 UI 和 key 管理的服务。这种情况下重复建设多了一层维护成本收益却不明显。除此以外大多有多个模型接入需求的场景litellm 都是值得考虑的。它最大的优势就是能把模型接入这个相对繁琐、重复度高的工作标准化让你把时间花在业务逻辑本身。最后再分享一个我个人的习惯我把 litellm 的用量统计和团队内部的周报绑定每周看一眼费用曲线对着异常峰值去找调用来源。这么做看起来只是顺手的事但长期下来帮我避免了好几次成本失控。如果你准备引入这个工具我建议也从第一周就养成看用量的习惯别等到月底账单出来再头疼。
阅读完成 · 觉得有帮助？
