最近在折腾多模型项目的时候发现一个高频问题代码里写死了某个模型厂商的接口想换模型就得改代码重新发布。尤其现在主流模型供应商那么多每家接口风格都有差异一个应用里同时对接多家 API 更是头疼。litellm 是我想重点推荐给大家的一个突破口——一个开源的 LLM 网关能把所有模型后端统一成一个 OpenAI 兼容接口无论底层是哪个厂商面向业务代码的调用方式都一模一样。我是一个经常在各种内部工具里接大模型的人之前最烦的就是“换一次模型改一次代码”。后来把 litellm 部署成一个独立的网关服务业务方只管发请求路由、重试、限流、成本核算全部丢给它整个接入流程清爽了很多。这篇东西我会从它是什么、怎么装、怎么配、怎么用一个完整链路讲清楚也会把我实际踩过的一些坑放出来适合正在做多模型接入、统一管理平台、AI 应用网关的开发者参考。1. litellm 解决的问题为什么值得搞1.1 多模型接入的混乱现状做 AI 应用的人都懂各家模型厂商的 SDK 和 API 风格完全不一样。OpenAI 有自己的一套参数结构Anthropic 的消息格式是另一种Google Gemini 又是另一套。想在应用里同时支持多个模型最直接的办法是给每个厂商写一版适配代码再做一堆 if-else 分发。前期模型少还行模型一多维护成本直接爆炸。我见过不少团队踩过这种坑某个功能想要兼容三个厂商的模型代码里到处都是厂商判断每个模型返回的字段结构还有差异解析逻辑写得很痛苦。更麻烦的是你没法用一个统一的配置去管理每个模型的 API Key、超时时间、上下文长度、并发数。这些都是散落在代码里的隐藏配置改一次模型就要动一次发布。litellm 做的一件核心事情就是把“厂商差异”这一层从业务代码里剥离出去。它对外暴露一个 OpenAI 格式的接口你往它发标准的 chat/completions 请求它内部再去调用对应的上游模型。这样业务代码只需要认识一种接口风格模型切换变成了改一条配置项的事。1.2 litellm 的两种使用形态litellm 有两种最常见的用法。第一种是作为 Python SDK 直接嵌入你的代码里适合不需要独立网关、项目规模不大的场景。你在代码里调用litellm.completion()传入模型名和消息它自动帮你路由到某个厂商的后端返回统一格式的结果。第二种是作为独立服务部署启动一个网关进程所有业务服务都通过 HTTP 请求这个网关网关再转发给上游模型。第二种形态我更喜欢它其实就是一个 LLM API Gateway 的思路。网关替你扛住了上游模型的地址、密钥、限流策略业务侧只需要关心请求和响应。因为接口是 OpenAI 兼容的所以连 ChatGPT 的一些开源平替前端都可以直接把 baseURL 指向 litellm 网关原来的代码一行不用改就能切到别的模型上。1.3 适合谁用解决什么痛点litellm 适合的场景非常明确你想在多个模型之间做统一接入或者希望有一套集中的模型管理、成本控制、密钥管理方案。比如企业内部有一个 AI 平台多个产品和项目共用一组模型 API那你确实需要一个网关来做请求转发和配额管控。再比如个人开发者想快速对比不同模型的输出效果用 litellm 把各家 API Key 配好一行代码就能换来换去。这不是一个 AI 模型本身也不是某种框架而是一个“中间层”。它解决的问题不是“模型效果”而是“工程效率”。如果你只是简单调用一两个接口可能用不上它但一旦你的系统里模型的种类多了、调用方多了、成本开始不受控了litellm 的帮助就非常明显。2. 安装部署从 pip 到 Docker2.1 最简单的方式pip 安装litellm 是一个 Python 包官方推荐直接用 pip 或者 poetry 这类工具安装。我本机测试时用的是普通虚拟环境执行pip install litellm装完后你可以先用 SDK 模式跑一个最快的小样例确认环境没问题。litellm 本身依赖了 httpx 等库来做异步请求所以首次安装时下载的东西会多一些属于正常现象。如果是在已有项目里引入建议把它单独放进一个 service 里而不是和业务代码深度混在一起。安装之后SDK 模式的第一行代码大概长这样import litellm response litellm.completion( modelgpt-3.5-turbo, messages[{role: user, content: 你好介绍一下你自己}], api_key你的密钥 ) print(response.choices[0].message.content)你没猜错它把调用方式抹平了。不管后面接的是 OpenAI、Anthropic 还是其他家对上面这段业务代码来说参数格式不变。不同厂商的差异被 litellm 拦在了代码外面。2.2 用网关模式部署命令行启动SDK 模式适合你的程序里直接做调用但如果你希望多个服务共享一套模型配置那就得把 litellm 跑成独立进程。最直接的启动方式是用命令行指定配置文件litellm --config config.yaml --port 4000这个命令会启动一个本地 HTTP 服务监听 4000 端口对外提供 OpenAI 兼容的接口。你往这个服务发请求它根据配置向上游模型发起调用并返回结果。这里有个很关键的点网关模式的好处不只是“统一接口”它还把密钥集中到了服务端。业务服务不需要保存各个厂商的 API Key它们只认证网关的 Key。这样一来厂商 Key 的泄露面就小了很多也不需要每台机器都配一遍环境变量。如果你有大量的上游模型要管理config.yaml 会变成核心角色。一个简单的配置示意model_list: - model_name: gpt-4 litellm_params: model: openai/gpt-4 api_key: os.environ/OPENAI_API_KEY - model_name: claude-sonnet litellm_params: model: anthropic/claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEYmodel_name是暴露给外部调用方的名字litellm_params是真正映射到上游模型的实际参数。外部业务代码只认gpt-4、claude-sonnet这些别名具体上游是哪个厂商由配置决定。2.3 Docker 部署生产环境更省心到了生产环境我一般不直接跑裸进程而是用 Docker 或者 Docker Compose 来管。litellm 官方维护了镜像直接拉下来就行docker pull ghcr.io/berriai/litellm:main-latest docker run -d -p 4000:4000 -v $(pwd)/config.yaml:/app/config.yaml ghcr.io/berriai/litellm:main-latest --config /app/config.yaml用 Docker 的好处是可以把网关和业务服务放在同一套编排体系里环境变量、日志、重启策略都能统一管理。尤其是当你的网关上还接了数据库做成本统计时Docker Compose 把 litellm 和数据库一起拉起会更顺手。2.4 部署时的一个小经验如果你是第一次部署网关模式先别急着配一堆模型。我建议先把一个模型配好启动后用 curl 调一次确认整个链路通了你再往 model_list 里加其他模型。这样做的好处是一旦出问题你排查的范围会小很多。我见过有人第一次就配了十几个模型结果某个上游的 Key 写错了日志里全是认证报错找半天都不知道是哪个模型引起的。3. 核心配置详解模型路由与负载均衡3.1 model_list 的映射机制litellm 的模型路由靠的就是 model_list 里的映射关系。这里的细节我觉得值得展开一下因为很多人第一次用会搞混。外部的model_name可以是你自己起的任意别名不一定要和上游模型名一致。实际使用时litellm_params 里的model字段要带上厂商前缀格式是厂商名/模型名。比如openai/gpt-4oanthropic/claude-3-5-sonnetgemini/gemini-1.5-proazure/gpt-4oAzure OpenAI这个前缀很重要。model_name只负责对外litellm 内部根据litellm_params里的前缀判断去请求哪一家的接口。如果你只写了gpt-4o而没写openai/litellm 默认会往 OpenAI 官方接口发请求同理如果你要接的是 Azure 部署的 GPT 模型前缀就得写azure/然后额外配api_base等参数。我用过一个安在一个内部网关上的例子映射大概是这样的model_list: - model_name: fast-model litellm_params: model: openai/gpt-4o-mini api_key: os.environ[OPENAI_API_KEY] - model_name: high-quality-model litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ[ANTHROPIC_API_KEY]对外业务方看到的就是fast-model和high-quality-model两个名字完全不知道后端到底是哪家厂商。换模型时只需要改配置业务代码继续用原来的名字或者改一下调用名不会再因为厂商 SDK 升级而头痛。3.2 负载均衡与重试litellm 的负载均衡机制也藏在这个配置里。比如同一个model_name映射了多个上游模型litellm 会在这些上游之间做轮询或者按权重分发。这种设计很实用比如你有多个厂商或者多个应用层的 API Key希望分散请求压力就可以配置多个 litellm_params 指向同一个 model_name。还有一种常见用法是为同一个模型配置多个 Key。比如openai/gpt-4o你有两个 API Key想把请求均衡到两个 Key 上配置可以这样写model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_keys: [key1, key2]当某个上游返回限流错误或者超时litellm 会根据配置的重试策略自动尝试下一个实例。我自己实际操作中会把重试次数设成 2 次因为大多数模型接口的偶发失败都是临时的重试一次成功率就很高了。重试次数设太多反而拖慢请求响应时间尤其在一些对延迟敏感的场景里重试策略要收敛一点。3.3 模型参数与上下文长度控制很多人刚用 litellm 时会忽略一个配置项max_input_tokens。不同模型对于上下文的限制不一样如果网关不做限制业务方一股脑把几万 token 的文本塞进来上游大概率直接报错。litellm 支持在配置里给模型设置输入长度上限超过上限就提前拦截并返回错误这样上下游能更早发现问题。model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ[OPENAI_API_KEY] max_input_tokens: 8000除了max_input_tokenslitellm 也支持配置temperature、max_tokens之类的默认值。不过这些参数业务方一般会在请求里覆盖网关层面的默认配置只是兜底。我的习惯是网关只控制“路由和配额”具体的生成参数尽量留给调用方传这样不同业务场景才能灵活定制。3.4 密钥管理与 virtual keys网关模式下litellm 并不要求业务方直接使用厂商的 API Key它可以生成一套虚拟 Key。业务方用虚拟 Key 请求 litellmlitellm 内部再去映射厂商 Key。这样即使某个业务方的 Key 泄漏了也不会直接暴露厂商 Key更不会影响其他业务方使用同一个厂商账户。生成虚拟 Key 的操作一条 curl 就完成了curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-your-master-key \ -H Content-Type: application/json \ -d {duration: 30d}返回里会包含一个key字段这个就是业务方要用的 Key。我实际管理时习惯给不同项目发不同虚拟 Key并在 Key 上绑定预算上限这样能有效防止某一个项目把整个厂商的配额耗光。后面讲到成本控制时还会提到这个。4. 实操笔记用 Python SDK 和网关做一次完整调用4.1 从零开始的 Python 调用流程先走一遍 SDK 模式的最基础链路方便你建立感觉。装好 litellm 后直接看例子import litellm messages [ {role: system, content: 你是一个简短助手}, {role: user, content: 用一句话介绍 litellm} ] response litellm.completion( modelopenai/gpt-4o-mini, messagesmessages, api_key你的OpenAI Key ) print(response)如果你接的不是 OpenAI而是 Anthropic代码几乎不用变只是 model 参数改成anthropic/claude-3-5-sonnet同样需要传对应的 api_key。对上层业务来说返回的对象都是 litellm 统一的 Response 对象访问response.choices[0].message.content就能拿到文本。如果你用的是网关模式从业务代码的角度来看更像是在操作一个自定义的 OpenAI 服务。你可以直接用 OpenAI 的 Python SDK把 base_url 指向 litellm 的地址from openai import OpenAI client OpenAI( api_keylitellm虚拟Key, base_urlhttp://localhost:4000 ) response client.chat.completions.create( modelfast-model, messages[{role: user, content: 你好}] ) print(response.choices[0].message.content)这里你会发现 litellm 的强兼容性它不只是自己提供 SDK而是能直接兼容 OpenAI 官方 SDK。很多改成 OpenAI 接口格式的工具都可以直接把 baseURL 切到 litellm 上来这是它适配场景广的重要原因。4.2 流式输出的处理流式输出在真实业务里非常常见打字机效果总比一等十秒再看到完整结果体验好。litellm 对流式响应也有处理SDK 模式下加一个streamTrue就可以response litellm.completion( modelopenai/gpt-4o-mini, messagesmessages, streamTrue, api_key你的Key ) for chunk in response: if chunk.get(choices) is not None: delta chunk[choices][0].get(delta, {}) content delta.get(content) if content: print(content, end)注意这里是按 litellm 的流式返回格式来解析的每个 chunk 里choices[0].delta.content是增量文本。如果你是在网关模式下直接用 OpenAI SDK 的 stream 参数也是一样的逻辑。流式的核心价值是首字延迟低litellm 内部本身是异步转发上游流式响应所以延迟控制得还可以。4.3 把 litellm 接到真实业务里的完整流程拿一个实际模拟场景来说我的内部工具需要支持两个模型一个用于快速分类一个用于深度分析。按照 litellm 的玩法我会先写一份 config.yamlmodel_list: - model_name: classify-model litellm_params: model: openai/gpt-4o-mini api_key: os.environ[OPENAI_API_KEY] - model_name: deep-analyze-model litellm_params: model: anthropic/claude-3-5-sonnet api_key: os.environ[ANTHROPIC_API_KEY]启动网关litellm --config config.yaml --port 4000业务侧通过标准 HTTP 请求调用curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的虚拟Key \ -d { model: classify-model, messages: [ {role: user, content: 这段文本属于哪个分类} ] }我实测下来这个流程从配置到调通顺利的话十几分钟就能搞定。如果算上环境初始化和密钥配置第一次一小时以内完成也是正常的。关键是这个流程里业务方根本没有直接接触厂商密钥厂商能力被高度抽象成了一个“模型名字”。4.4 响应格式的统一问题很多第一次接触 litellm 的人会担心不同模型返回的格式能不能完全一样。实际来看litellm 会尽力把上游的响应转换成 OpenAI 格式。文本内容、角色的组织结构基本一致但部分模型的特殊字段比如某些厂商返回的 reasoning trace可能会被映射到扩展字段里。所以我的建议是如果你的业务逻辑非常依赖响应里的某个字段先去网关实测一次真实返回不要想当然。大部分情况下choices、usage这些核心字段是稳定的但一些非标准字段需要做一点兼容处理。这个点其实任何网关类项目都躲不掉litellm 已经算是做得很规范的了。5. 成本控制与用量追踪5.1 给每个虚拟 Key 设置预算多模型项目里成本失控是特别容易被忽视的问题。没有预算管控的模型网关就像没有一个额度限制的车险卡随便谁都能刷月底账单出来就得傻眼。litellm 很早就支持给虚拟 Key 绑定预算你可以精确到一个 Key 能用多少额度按天还是按总量。创建带预算的 Keycurl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-master-key \ -H Content-Type: application/json \ -d { duration: 30d, max_budget: 100 }这个例子表示该 Key 在 30 天内最多消费 100 美元额度。当这个 Key 的消费累计超过这个数litellm 会自动拒绝对应的请求。这种管控方式在内部平台场景里非常好用给每个项目一个独立 Key再设好预算上限月底对账只需要看各 Key 的消费报表就行。5.2 数据库持久化消费记录默认情况下 litellm 的用量数据是存在内存里的服务重启数据就丢了。想要积累一段时间的消费记录就得给它配一个数据库。litellm 支持多种数据库我实际使用中比较常用 PostgreSQL。对应配置可以放到 config.yamlgeneral_settings: database_url: postgresql://user:passwordlocalhost:5432/litellm master_key: sk-your-master-key配上数据库之后litellm 会在 PostgreSQL 里记录每次请求的 token 用量、成本、模型、虚拟 Key 等信息。通过这些数据你可以知道每个模型每天的调用量和费用也可以统计哪些业务方消耗最多配额。5.3 成本计算的原理litellm 的成本计算依赖各家模型的 token 单价表它会把你每次请求的 prompt token 和 completion token 数量乘以对应的单价汇总出一次调用的成本。这个计算内置了主流模型的价目表所以不需要你自己配价格。不过有一点要提醒模型价格是经常调整的。当你发现 litellm 统计的成本和你实际账单差异较大时先去看看是不是模型价格更新滞后了。这种情况不算 bug更多是价格同步的时效问题。好在 litellm 社区更新比较勤快主流模型的价格通常能比较快地跟进。5.4 预算告警的经验我给内部项目配预算时习惯设两个阈值一个是软阈值比如 80%到了就发告警但继续运行一个是硬阈值比如 100%到了直接熔断。实际效果是告警能让你提前知道哪个项目快超支了硬限制能兜底防止彻底失控。虽然 litellm 本身不负责发送告警通知但你可以通过数据库里的消费记录做监控也可以在请求日志里埋点触发条件后由外部监控系统去通知。6. 常见问题与排坑心得6.1 认证错误频发在我接触过的使用场景里最常碰到的问题是AuthenticationError。这个错误一般分两种一种是厂商 Key 写错了比如从某个环境变量里读出来的是空字符串另一种是网关下发的虚拟 Key 权限不足或者虚拟 Key 过期。排查思路我建议按顺序来先确认 litellm 所在环境有没有正确加载厂商 Key 的环境变量然后测试直连厂商 API 是否正常接着再测一次网关转发。直连 OK 但网关不行问题大概率出在网关配置或者虚拟 Key 上。6.2 模型名称找不到报错ModelNotFoundError时十有八九是 model_list 配置里没有这个别名或者别名和实际模型名映射不完整。记住一个原则对外用的别名可以随便起但 litellm_params 里的 model 字段必须带厂商前缀否则 litellm 会猜一个默认厂商猜错就报错。还有一种情况是你想用的模型没在 litellm 内置支持的模型列表里。这类定制化模型需要额外引入对应的 provider 模块配置会稍微复杂一点普通场景基本用不到。6.3 超时和并发限制大模型接口处理时间长加上网络波动超时问题很难完全避免。litellm 支持在配置里设置请求超时时间我通常设置为 30 秒到 60 秒。如果你有很复杂的生成任务超时时间可以适当放宽但不要设置成无限超时否则并发一起来请求全部挂住后面就全都堵死了。并发限制方面litellm 也有相关配置可以限制同一个模型或同一个 Key 的并发请求数。很多模型厂商对并发有严格限制超过会返回 429。与其等 429 出现再处理不如在网关层直接把并发数控制在安全范围内更省心。6.4 费用统计不准怎么办如果你发现 cost 字段算出来的数字和你信用卡扣款对不上先检查是不是同一个价格模型但 API 类型不同导致的。比如有的模型支持长上下文输入价格和普通版本不一样litellm 算的时候可能还没更新到最新的价格档位。这种误差通常会在官方同步价格后消失但在大规模高频率调用时短期误差还是要注意。6.5 排坑速查表常见报错可能原因快速排查方向AuthenticationErrorAPI Key 错误、环境变量未加载直连厂商 API 测试ModelNotFoundError模型别名未配置、缺厂商前缀检查 config.yaml 中 model_listContextLengthExceeded请求超过模型上下文限制配置 max_input_tokensTimeoutError上游模型响应太慢调整请求 timeout 参数RateLimitError厂商限流配置网关并发限制、重试策略6.6 几条避坑心得别把厂商 Key 硬编码在 config.yaml 里用环境变量引用不然文件一泄漏所有密钥就全露了。网关的 master key 要设一个强密码这个 Key 是管理后台和生成虚拟 Key 的入口重要性不同寻常。配置文件的改动要采用“重启验证”的思路改一点、重启一次、验证一次避免一次性改太多导致问题不好定位。如果你的业务方数量很多建议每个项目单独用一套虚拟 Key别图省事全部共用一个。出了问题隔离性很重要。数据库的消费记录要定期备份特别是你用来做成本核算的话这类数据丢了很难追溯。7. 扩展玩法与其它系统的集成7.1 做一个模型侧入口litellm 最常见的扩展用法是作为多个开源应用的模型后端。现在很多 AI 应用都支持自定义 OpenAI 兼容接口你只要把 baseURL 指向 litellm 的地址填上虚拟 Key就可以把原本只能用 OpenAI 的应用接到 Anthropic 或者其他模型上。这种玩法不需要改一行前端代码直接在配置里切过去就行。我身边已经有人这么玩了公司内部部署了某个开源问答面板原来只支持 OpenAI 接口后来通过 litellm 把底层换成了其他模型。用户感知不到变化但成本预算和模型效果都控制得更好了。7.2 配合监控系统使用litellm 本身有请求日志你可以把这些日志接入现有的日志平台统一做监控和分析。这样你能直观看到每个模型响应时间的变化趋势、错误率、token 消费量。出现上游不稳定时也可以在监控图表上反应出来。生产环境里我把 litellm 的日志格式稍微规整了一下配合可观测性系统做告警。当某个模型的错误率超过阈值时自动触发告警值班同学可以去排查是否上游故障或者配置失效。这个思路不复杂但确实能把多模型的稳定性隐性问题尽早暴露出来。7.3 多区域部署时的注意事项如果你需要跨区域部署多个 litellm 网关建议配置中心统一管理 config.yaml而不是每台机器维护一份。配置文件一旦多了漂移问题会很严重。轻量方案可以用 Git 管理配置配合 CI 流程做配置校验复杂一点的可以引入配置中心服务。只要保证每个网关读到的配置一致后面的模型路由才不会出现偏差。8. 我对 litellm 的整体评价和实际使用体会litellm 给我最深的感觉是“务实”两个字。它没有堆一大堆花哨功能而是把多模型接入这个真问题拆解得非常细每一个模块都对应实际使用中的痛点。模型路由、密钥管理、预算控制、负载均衡这些点单独拎出来都有对应的替代工具但能融合到一个服务里并且保持稳定的litellm 确实做得很不错。我一开始也犹豫要不要引入一个中间层担心它会成为性能瓶颈。实际用了之后发现它带来的额外开销远远小于它解决的问题。业务代码变得更干净了模型切换变得很轻成本心里也有数了。尤其是当团队里同时有多个项目需要用不同模型的时候统一网关节省下来的沟通和开发成本非常可观。最后再分享一个小技巧如果你只是自己做点小项目可以先从 SDK 模式用起等规模大了再切到网关模式。litellm 的迁移成本很低也不用推翻重来。但如果你一开始就打算给团队提供一个统一平台直接上网关模式虚拟 Key 和预算控制这两个功能越早用上越好。
最近在折腾多模型项目的时候发现一个高频问题代码里写死了某个模型厂商的接口想换模型就得改代码重新发布。尤其现在主流模型供应商那么多每家接口风格都有差异一个应用里同时对接多家 API 更是头疼。litellm 是我想重点推荐给大家的一个突破口——一个开源的 LLM 网关能把所有模型后端统一成一个 OpenAI 兼容接口无论底层是哪个厂商面向业务代码的调用方式都一模一样。我是一个经常在各种内部工具里接大模型的人之前最烦的就是“换一次模型改一次代码”。后来把 litellm 部署成一个独立的网关服务业务方只管发请求路由、重试、限流、成本核算全部丢给它整个接入流程清爽了很多。这篇东西我会从它是什么、怎么装、怎么配、怎么用一个完整链路讲清楚也会把我实际踩过的一些坑放出来适合正在做多模型接入、统一管理平台、AI 应用网关的开发者参考。1. litellm 解决的问题为什么值得搞1.1 多模型接入的混乱现状做 AI 应用的人都懂各家模型厂商的 SDK 和 API 风格完全不一样。OpenAI 有自己的一套参数结构Anthropic 的消息格式是另一种Google Gemini 又是另一套。想在应用里同时支持多个模型最直接的办法是给每个厂商写一版适配代码再做一堆 if-else 分发。前期模型少还行模型一多维护成本直接爆炸。我见过不少团队踩过这种坑某个功能想要兼容三个厂商的模型代码里到处都是厂商判断每个模型返回的字段结构还有差异解析逻辑写得很痛苦。更麻烦的是你没法用一个统一的配置去管理每个模型的 API Key、超时时间、上下文长度、并发数。这些都是散落在代码里的隐藏配置改一次模型就要动一次发布。litellm 做的一件核心事情就是把“厂商差异”这一层从业务代码里剥离出去。它对外暴露一个 OpenAI 格式的接口你往它发标准的 chat/completions 请求它内部再去调用对应的上游模型。这样业务代码只需要认识一种接口风格模型切换变成了改一条配置项的事。1.2 litellm 的两种使用形态litellm 有两种最常见的用法。第一种是作为 Python SDK 直接嵌入你的代码里适合不需要独立网关、项目规模不大的场景。你在代码里调用litellm.completion()传入模型名和消息它自动帮你路由到某个厂商的后端返回统一格式的结果。第二种是作为独立服务部署启动一个网关进程所有业务服务都通过 HTTP 请求这个网关网关再转发给上游模型。第二种形态我更喜欢它其实就是一个 LLM API Gateway 的思路。网关替你扛住了上游模型的地址、密钥、限流策略业务侧只需要关心请求和响应。因为接口是 OpenAI 兼容的所以连 ChatGPT 的一些开源平替前端都可以直接把 baseURL 指向 litellm 网关原来的代码一行不用改就能切到别的模型上。1.3 适合谁用解决什么痛点litellm 适合的场景非常明确你想在多个模型之间做统一接入或者希望有一套集中的模型管理、成本控制、密钥管理方案。比如企业内部有一个 AI 平台多个产品和项目共用一组模型 API那你确实需要一个网关来做请求转发和配额管控。再比如个人开发者想快速对比不同模型的输出效果用 litellm 把各家 API Key 配好一行代码就能换来换去。这不是一个 AI 模型本身也不是某种框架而是一个“中间层”。它解决的问题不是“模型效果”而是“工程效率”。如果你只是简单调用一两个接口可能用不上它但一旦你的系统里模型的种类多了、调用方多了、成本开始不受控了litellm 的帮助就非常明显。2. 安装部署从 pip 到 Docker2.1 最简单的方式pip 安装litellm 是一个 Python 包官方推荐直接用 pip 或者 poetry 这类工具安装。我本机测试时用的是普通虚拟环境执行pip install litellm装完后你可以先用 SDK 模式跑一个最快的小样例确认环境没问题。litellm 本身依赖了 httpx 等库来做异步请求所以首次安装时下载的东西会多一些属于正常现象。如果是在已有项目里引入建议把它单独放进一个 service 里而不是和业务代码深度混在一起。安装之后SDK 模式的第一行代码大概长这样import litellm response litellm.completion( modelgpt-3.5-turbo, messages[{role: user, content: 你好介绍一下你自己}], api_key你的密钥 ) print(response.choices[0].message.content)你没猜错它把调用方式抹平了。不管后面接的是 OpenAI、Anthropic 还是其他家对上面这段业务代码来说参数格式不变。不同厂商的差异被 litellm 拦在了代码外面。2.2 用网关模式部署命令行启动SDK 模式适合你的程序里直接做调用但如果你希望多个服务共享一套模型配置那就得把 litellm 跑成独立进程。最直接的启动方式是用命令行指定配置文件litellm --config config.yaml --port 4000这个命令会启动一个本地 HTTP 服务监听 4000 端口对外提供 OpenAI 兼容的接口。你往这个服务发请求它根据配置向上游模型发起调用并返回结果。这里有个很关键的点网关模式的好处不只是“统一接口”它还把密钥集中到了服务端。业务服务不需要保存各个厂商的 API Key它们只认证网关的 Key。这样一来厂商 Key 的泄露面就小了很多也不需要每台机器都配一遍环境变量。如果你有大量的上游模型要管理config.yaml 会变成核心角色。一个简单的配置示意model_list: - model_name: gpt-4 litellm_params: model: openai/gpt-4 api_key: os.environ/OPENAI_API_KEY - model_name: claude-sonnet litellm_params: model: anthropic/claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEYmodel_name是暴露给外部调用方的名字litellm_params是真正映射到上游模型的实际参数。外部业务代码只认gpt-4、claude-sonnet这些别名具体上游是哪个厂商由配置决定。2.3 Docker 部署生产环境更省心到了生产环境我一般不直接跑裸进程而是用 Docker 或者 Docker Compose 来管。litellm 官方维护了镜像直接拉下来就行docker pull ghcr.io/berriai/litellm:main-latest docker run -d -p 4000:4000 -v $(pwd)/config.yaml:/app/config.yaml ghcr.io/berriai/litellm:main-latest --config /app/config.yaml用 Docker 的好处是可以把网关和业务服务放在同一套编排体系里环境变量、日志、重启策略都能统一管理。尤其是当你的网关上还接了数据库做成本统计时Docker Compose 把 litellm 和数据库一起拉起会更顺手。2.4 部署时的一个小经验如果你是第一次部署网关模式先别急着配一堆模型。我建议先把一个模型配好启动后用 curl 调一次确认整个链路通了你再往 model_list 里加其他模型。这样做的好处是一旦出问题你排查的范围会小很多。我见过有人第一次就配了十几个模型结果某个上游的 Key 写错了日志里全是认证报错找半天都不知道是哪个模型引起的。3. 核心配置详解模型路由与负载均衡3.1 model_list 的映射机制litellm 的模型路由靠的就是 model_list 里的映射关系。这里的细节我觉得值得展开一下因为很多人第一次用会搞混。外部的model_name可以是你自己起的任意别名不一定要和上游模型名一致。实际使用时litellm_params 里的model字段要带上厂商前缀格式是厂商名/模型名。比如openai/gpt-4oanthropic/claude-3-5-sonnetgemini/gemini-1.5-proazure/gpt-4oAzure OpenAI这个前缀很重要。model_name只负责对外litellm 内部根据litellm_params里的前缀判断去请求哪一家的接口。如果你只写了gpt-4o而没写openai/litellm 默认会往 OpenAI 官方接口发请求同理如果你要接的是 Azure 部署的 GPT 模型前缀就得写azure/然后额外配api_base等参数。我用过一个安在一个内部网关上的例子映射大概是这样的model_list: - model_name: fast-model litellm_params: model: openai/gpt-4o-mini api_key: os.environ[OPENAI_API_KEY] - model_name: high-quality-model litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ[ANTHROPIC_API_KEY]对外业务方看到的就是fast-model和high-quality-model两个名字完全不知道后端到底是哪家厂商。换模型时只需要改配置业务代码继续用原来的名字或者改一下调用名不会再因为厂商 SDK 升级而头痛。3.2 负载均衡与重试litellm 的负载均衡机制也藏在这个配置里。比如同一个model_name映射了多个上游模型litellm 会在这些上游之间做轮询或者按权重分发。这种设计很实用比如你有多个厂商或者多个应用层的 API Key希望分散请求压力就可以配置多个 litellm_params 指向同一个 model_name。还有一种常见用法是为同一个模型配置多个 Key。比如openai/gpt-4o你有两个 API Key想把请求均衡到两个 Key 上配置可以这样写model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_keys: [key1, key2]当某个上游返回限流错误或者超时litellm 会根据配置的重试策略自动尝试下一个实例。我自己实际操作中会把重试次数设成 2 次因为大多数模型接口的偶发失败都是临时的重试一次成功率就很高了。重试次数设太多反而拖慢请求响应时间尤其在一些对延迟敏感的场景里重试策略要收敛一点。3.3 模型参数与上下文长度控制很多人刚用 litellm 时会忽略一个配置项max_input_tokens。不同模型对于上下文的限制不一样如果网关不做限制业务方一股脑把几万 token 的文本塞进来上游大概率直接报错。litellm 支持在配置里给模型设置输入长度上限超过上限就提前拦截并返回错误这样上下游能更早发现问题。model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ[OPENAI_API_KEY] max_input_tokens: 8000除了max_input_tokenslitellm 也支持配置temperature、max_tokens之类的默认值。不过这些参数业务方一般会在请求里覆盖网关层面的默认配置只是兜底。我的习惯是网关只控制“路由和配额”具体的生成参数尽量留给调用方传这样不同业务场景才能灵活定制。3.4 密钥管理与 virtual keys网关模式下litellm 并不要求业务方直接使用厂商的 API Key它可以生成一套虚拟 Key。业务方用虚拟 Key 请求 litellmlitellm 内部再去映射厂商 Key。这样即使某个业务方的 Key 泄漏了也不会直接暴露厂商 Key更不会影响其他业务方使用同一个厂商账户。生成虚拟 Key 的操作一条 curl 就完成了curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-your-master-key \ -H Content-Type: application/json \ -d {duration: 30d}返回里会包含一个key字段这个就是业务方要用的 Key。我实际管理时习惯给不同项目发不同虚拟 Key并在 Key 上绑定预算上限这样能有效防止某一个项目把整个厂商的配额耗光。后面讲到成本控制时还会提到这个。4. 实操笔记用 Python SDK 和网关做一次完整调用4.1 从零开始的 Python 调用流程先走一遍 SDK 模式的最基础链路方便你建立感觉。装好 litellm 后直接看例子import litellm messages [ {role: system, content: 你是一个简短助手}, {role: user, content: 用一句话介绍 litellm} ] response litellm.completion( modelopenai/gpt-4o-mini, messagesmessages, api_key你的OpenAI Key ) print(response)如果你接的不是 OpenAI而是 Anthropic代码几乎不用变只是 model 参数改成anthropic/claude-3-5-sonnet同样需要传对应的 api_key。对上层业务来说返回的对象都是 litellm 统一的 Response 对象访问response.choices[0].message.content就能拿到文本。如果你用的是网关模式从业务代码的角度来看更像是在操作一个自定义的 OpenAI 服务。你可以直接用 OpenAI 的 Python SDK把 base_url 指向 litellm 的地址from openai import OpenAI client OpenAI( api_keylitellm虚拟Key, base_urlhttp://localhost:4000 ) response client.chat.completions.create( modelfast-model, messages[{role: user, content: 你好}] ) print(response.choices[0].message.content)这里你会发现 litellm 的强兼容性它不只是自己提供 SDK而是能直接兼容 OpenAI 官方 SDK。很多改成 OpenAI 接口格式的工具都可以直接把 baseURL 切到 litellm 上来这是它适配场景广的重要原因。4.2 流式输出的处理流式输出在真实业务里非常常见打字机效果总比一等十秒再看到完整结果体验好。litellm 对流式响应也有处理SDK 模式下加一个streamTrue就可以response litellm.completion( modelopenai/gpt-4o-mini, messagesmessages, streamTrue, api_key你的Key ) for chunk in response: if chunk.get(choices) is not None: delta chunk[choices][0].get(delta, {}) content delta.get(content) if content: print(content, end)注意这里是按 litellm 的流式返回格式来解析的每个 chunk 里choices[0].delta.content是增量文本。如果你是在网关模式下直接用 OpenAI SDK 的 stream 参数也是一样的逻辑。流式的核心价值是首字延迟低litellm 内部本身是异步转发上游流式响应所以延迟控制得还可以。4.3 把 litellm 接到真实业务里的完整流程拿一个实际模拟场景来说我的内部工具需要支持两个模型一个用于快速分类一个用于深度分析。按照 litellm 的玩法我会先写一份 config.yamlmodel_list: - model_name: classify-model litellm_params: model: openai/gpt-4o-mini api_key: os.environ[OPENAI_API_KEY] - model_name: deep-analyze-model litellm_params: model: anthropic/claude-3-5-sonnet api_key: os.environ[ANTHROPIC_API_KEY]启动网关litellm --config config.yaml --port 4000业务侧通过标准 HTTP 请求调用curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的虚拟Key \ -d { model: classify-model, messages: [ {role: user, content: 这段文本属于哪个分类} ] }我实测下来这个流程从配置到调通顺利的话十几分钟就能搞定。如果算上环境初始化和密钥配置第一次一小时以内完成也是正常的。关键是这个流程里业务方根本没有直接接触厂商密钥厂商能力被高度抽象成了一个“模型名字”。4.4 响应格式的统一问题很多第一次接触 litellm 的人会担心不同模型返回的格式能不能完全一样。实际来看litellm 会尽力把上游的响应转换成 OpenAI 格式。文本内容、角色的组织结构基本一致但部分模型的特殊字段比如某些厂商返回的 reasoning trace可能会被映射到扩展字段里。所以我的建议是如果你的业务逻辑非常依赖响应里的某个字段先去网关实测一次真实返回不要想当然。大部分情况下choices、usage这些核心字段是稳定的但一些非标准字段需要做一点兼容处理。这个点其实任何网关类项目都躲不掉litellm 已经算是做得很规范的了。5. 成本控制与用量追踪5.1 给每个虚拟 Key 设置预算多模型项目里成本失控是特别容易被忽视的问题。没有预算管控的模型网关就像没有一个额度限制的车险卡随便谁都能刷月底账单出来就得傻眼。litellm 很早就支持给虚拟 Key 绑定预算你可以精确到一个 Key 能用多少额度按天还是按总量。创建带预算的 Keycurl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-master-key \ -H Content-Type: application/json \ -d { duration: 30d, max_budget: 100 }这个例子表示该 Key 在 30 天内最多消费 100 美元额度。当这个 Key 的消费累计超过这个数litellm 会自动拒绝对应的请求。这种管控方式在内部平台场景里非常好用给每个项目一个独立 Key再设好预算上限月底对账只需要看各 Key 的消费报表就行。5.2 数据库持久化消费记录默认情况下 litellm 的用量数据是存在内存里的服务重启数据就丢了。想要积累一段时间的消费记录就得给它配一个数据库。litellm 支持多种数据库我实际使用中比较常用 PostgreSQL。对应配置可以放到 config.yamlgeneral_settings: database_url: postgresql://user:passwordlocalhost:5432/litellm master_key: sk-your-master-key配上数据库之后litellm 会在 PostgreSQL 里记录每次请求的 token 用量、成本、模型、虚拟 Key 等信息。通过这些数据你可以知道每个模型每天的调用量和费用也可以统计哪些业务方消耗最多配额。5.3 成本计算的原理litellm 的成本计算依赖各家模型的 token 单价表它会把你每次请求的 prompt token 和 completion token 数量乘以对应的单价汇总出一次调用的成本。这个计算内置了主流模型的价目表所以不需要你自己配价格。不过有一点要提醒模型价格是经常调整的。当你发现 litellm 统计的成本和你实际账单差异较大时先去看看是不是模型价格更新滞后了。这种情况不算 bug更多是价格同步的时效问题。好在 litellm 社区更新比较勤快主流模型的价格通常能比较快地跟进。5.4 预算告警的经验我给内部项目配预算时习惯设两个阈值一个是软阈值比如 80%到了就发告警但继续运行一个是硬阈值比如 100%到了直接熔断。实际效果是告警能让你提前知道哪个项目快超支了硬限制能兜底防止彻底失控。虽然 litellm 本身不负责发送告警通知但你可以通过数据库里的消费记录做监控也可以在请求日志里埋点触发条件后由外部监控系统去通知。6. 常见问题与排坑心得6.1 认证错误频发在我接触过的使用场景里最常碰到的问题是AuthenticationError。这个错误一般分两种一种是厂商 Key 写错了比如从某个环境变量里读出来的是空字符串另一种是网关下发的虚拟 Key 权限不足或者虚拟 Key 过期。排查思路我建议按顺序来先确认 litellm 所在环境有没有正确加载厂商 Key 的环境变量然后测试直连厂商 API 是否正常接着再测一次网关转发。直连 OK 但网关不行问题大概率出在网关配置或者虚拟 Key 上。6.2 模型名称找不到报错ModelNotFoundError时十有八九是 model_list 配置里没有这个别名或者别名和实际模型名映射不完整。记住一个原则对外用的别名可以随便起但 litellm_params 里的 model 字段必须带厂商前缀否则 litellm 会猜一个默认厂商猜错就报错。还有一种情况是你想用的模型没在 litellm 内置支持的模型列表里。这类定制化模型需要额外引入对应的 provider 模块配置会稍微复杂一点普通场景基本用不到。6.3 超时和并发限制大模型接口处理时间长加上网络波动超时问题很难完全避免。litellm 支持在配置里设置请求超时时间我通常设置为 30 秒到 60 秒。如果你有很复杂的生成任务超时时间可以适当放宽但不要设置成无限超时否则并发一起来请求全部挂住后面就全都堵死了。并发限制方面litellm 也有相关配置可以限制同一个模型或同一个 Key 的并发请求数。很多模型厂商对并发有严格限制超过会返回 429。与其等 429 出现再处理不如在网关层直接把并发数控制在安全范围内更省心。6.4 费用统计不准怎么办如果你发现 cost 字段算出来的数字和你信用卡扣款对不上先检查是不是同一个价格模型但 API 类型不同导致的。比如有的模型支持长上下文输入价格和普通版本不一样litellm 算的时候可能还没更新到最新的价格档位。这种误差通常会在官方同步价格后消失但在大规模高频率调用时短期误差还是要注意。6.5 排坑速查表常见报错可能原因快速排查方向AuthenticationErrorAPI Key 错误、环境变量未加载直连厂商 API 测试ModelNotFoundError模型别名未配置、缺厂商前缀检查 config.yaml 中 model_listContextLengthExceeded请求超过模型上下文限制配置 max_input_tokensTimeoutError上游模型响应太慢调整请求 timeout 参数RateLimitError厂商限流配置网关并发限制、重试策略6.6 几条避坑心得别把厂商 Key 硬编码在 config.yaml 里用环境变量引用不然文件一泄漏所有密钥就全露了。网关的 master key 要设一个强密码这个 Key 是管理后台和生成虚拟 Key 的入口重要性不同寻常。配置文件的改动要采用“重启验证”的思路改一点、重启一次、验证一次避免一次性改太多导致问题不好定位。如果你的业务方数量很多建议每个项目单独用一套虚拟 Key别图省事全部共用一个。出了问题隔离性很重要。数据库的消费记录要定期备份特别是你用来做成本核算的话这类数据丢了很难追溯。7. 扩展玩法与其它系统的集成7.1 做一个模型侧入口litellm 最常见的扩展用法是作为多个开源应用的模型后端。现在很多 AI 应用都支持自定义 OpenAI 兼容接口你只要把 baseURL 指向 litellm 的地址填上虚拟 Key就可以把原本只能用 OpenAI 的应用接到 Anthropic 或者其他模型上。这种玩法不需要改一行前端代码直接在配置里切过去就行。我身边已经有人这么玩了公司内部部署了某个开源问答面板原来只支持 OpenAI 接口后来通过 litellm 把底层换成了其他模型。用户感知不到变化但成本预算和模型效果都控制得更好了。7.2 配合监控系统使用litellm 本身有请求日志你可以把这些日志接入现有的日志平台统一做监控和分析。这样你能直观看到每个模型响应时间的变化趋势、错误率、token 消费量。出现上游不稳定时也可以在监控图表上反应出来。生产环境里我把 litellm 的日志格式稍微规整了一下配合可观测性系统做告警。当某个模型的错误率超过阈值时自动触发告警值班同学可以去排查是否上游故障或者配置失效。这个思路不复杂但确实能把多模型的稳定性隐性问题尽早暴露出来。7.3 多区域部署时的注意事项如果你需要跨区域部署多个 litellm 网关建议配置中心统一管理 config.yaml而不是每台机器维护一份。配置文件一旦多了漂移问题会很严重。轻量方案可以用 Git 管理配置配合 CI 流程做配置校验复杂一点的可以引入配置中心服务。只要保证每个网关读到的配置一致后面的模型路由才不会出现偏差。8. 我对 litellm 的整体评价和实际使用体会litellm 给我最深的感觉是“务实”两个字。它没有堆一大堆花哨功能而是把多模型接入这个真问题拆解得非常细每一个模块都对应实际使用中的痛点。模型路由、密钥管理、预算控制、负载均衡这些点单独拎出来都有对应的替代工具但能融合到一个服务里并且保持稳定的litellm 确实做得很不错。我一开始也犹豫要不要引入一个中间层担心它会成为性能瓶颈。实际用了之后发现它带来的额外开销远远小于它解决的问题。业务代码变得更干净了模型切换变得很轻成本心里也有数了。尤其是当团队里同时有多个项目需要用不同模型的时候统一网关节省下来的沟通和开发成本非常可观。最后再分享一个小技巧如果你只是自己做点小项目可以先从 SDK 模式用起等规模大了再切到网关模式。litellm 的迁移成本很低也不用推翻重来。但如果你一开始就打算给团队提供一个统一平台直接上网关模式虚拟 Key 和预算控制这两个功能越早用上越好。
