做 AI 应用开发最烦的事情之一就是各个大模型厂商的 API 格式不统一。今天想换个模型试试就得改代码重新对接想让团队里不同的人用不同的模型还得管好各自的 key。这些事情单拎出来都不难但攒在一起足够让人头疼。所以看到 litellm 这个项目的时候我第一反应是终于有人把这个痛点做成正经工具了。这篇文章就聊聊我实际使用 litellm 过程中的理解和一些经验希望能给正在被多模型 API 折腾的朋友一些参考。litellm 本质上是一个 LLM 网关gateway也就是一个统一的代理层。它把市面上主流的几十种大模型服务商的 API 格式全部转换成 OpenAI 的接口格式。这意味着你只需要学会 OpenAI 的调用方式就能访问几乎所有主流的大模型服务。而且它不只是转发请求那么简单还自带 key 管理、预算控制、限流、负载均衡、缓存这些生产环境里必不可少的功能。对个人开发者和团队来说这东西能省下大量重复对接的时间。1. 内容整体设计与思路拆解1.1 解决的核心痛点API 碎片化与重复劳动先说一个很现实的场景。假设你在做一个聊天机器人最开始接的是某家闭源大模型的服务代码里写好了 prompt 模板、流式输出逻辑、错误重试机制。过了一阵子你觉得另一家开源模型的本地化效果更好想切换过去。结果一看文档请求体格式不同、认证方式不同、流式返回的结构也不同得改一个完整的大模型客户端模块。如果之后又想加一个专门做总结的小模型再做一次适配。每接一个新服务商就要重复一遍这个过程而且这些代码往往是复制粘贴后微调维护起来特别容易出错。litellm 的思路很直接把对接服务商这个事从业务代码里抽离出来。你的业务代码只需要面对一套 OpenAI 兼容的接口剩下的事情全交给网关去做。具体来说你请求 litellm 的/v1/chat/completions它根据你配置的模型名称比如gpt-4o-mini、claude-3-5-haiku、ollama_chat/llama3来自动识别该转发到哪个服务商并完成请求格式的转换、认证信息的注入以及返回结果的格式化。这种架构带来的额外好处是你可以随时在网关层面调整路由策略。比如把某个模型的请求按比例分配到两个不同的服务商或者某个 key 的调用量达到上限后自动切换到备用 key。这些操作都无需改动业务代码只需要改一下配置文件。对于多环境开发、测试、生产共存的团队来说这种解耦尤为重要。1.2 为什么选择统一代理层而不是多功能库可能有人会说直接用各家官方 SDK 也不是不行。确实如果你只用一个服务商那直接用官方 SDK 是最省事的。但问题的关键在于大模型领域还处于快速发展期模型和方案随时可能调整。锁定在某一家相当于把项目的灵活性也锁死了。统一代理层在这里相当于一个保险策略它能保证你在将来调整模型方案时业务代码的改动量降到最低。另外litellm 并不仅仅是一个转换库它自己有完整的服务端实现可以独立部署。这意味着团队里多个服务可以共享同一个网关实例而不是在每个服务里都集成一份转换逻辑。这样做还有一个很务实的好处API key 不需要散落在各个服务的环境变量里只需要在网关这一处集中管理可以单独为每个应用、每个用户分配独立的虚拟 key并设置配额和使用上限。对于安全要求较高的项目这个优势是决定性的。1.3 适用场景与使用边界我很建议在这些情况下使用 litellm项目里至少需要接入两个以上的大模型服务商或者你虽然只用一个服务商但有多个人或应用共享 key需要做使用量统计和配额管理又或者你在做模型选型和对比需要频繁切换模型测试效果。这些场景下litellm 能帮你把基础设施的复杂度收敛起来。不太建议的场景也很明确如果只是本地写个脚本练手、调一个模型的 API那直接用官方 SDK 就够用了引入网关反而多了一层部署和维护成本。另外如果对请求延迟有极度苛刻的要求代理层带来的额外一跳确实会增加少量开销通常是几毫秒但绝大多数应用不会感知到这个差异。2. 核心细节解析与实操要点2.1 快速启动pip 安装与第一个转发请求litellm 分为 Python SDK 和独立代理服务两种使用方式。先从最常用的代理服务模式说起。安装很简单用 pip 就能装pip install litellm[proxy]安装完后直接启动服务litellm --model gpt-4o-mini --port 4000启动后litellm 会在4000端口监听提供 OpenAI 兼容的/v1/chat/completions接口。你可以直接把 base_url 指向http://localhost:4000用任意 OpenAI SDK 去调用。这里有个关键点如果你没有设置OPENAI_API_KEY环境变量也没在命令里传--api-keylitellm 会使用一个默认的测试 key通常是sk-1234来完成请求。实际使用时一定要显式配置否则生产环境会暴露一个所有人都知道的 key。2.2 配置文件从单模型到多模型的扩展用命令行启动只适合快速验证真正用到多模型、多服务商的时候配置文件才是核心。litellm 支持 YAML 配置文件启动时指定--config config.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: anthropic/claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY注意model_name和litellm_params.model的区别。model_name是你暴露给消费方的别名调用方可以叫它gpt-4o-mini而litellm_params.model是 litellm 内部用来定位服务商的完整标识。对于第三方服务商需要在模型名前面加上 provider 前缀比如anthropic/、bedrock/、ollama_chat/、openai/。这个前缀很重要litellm 靠它来判断该走哪个适配器不写或写错都会导致转发失败。除model和api_key之外litellm_params里还有一些常用参数值得了解api_base如果你在用一个兼容 OpenAI 格式的自建服务或者某个厂商的专用网关地址就用它来覆盖默认接入点。temperature、max_tokens这些参数可以写在配置里强制覆盖调用方传过来的值适合做统一策略管控。timeout设置请求超时时间避免某个上游服务卡住导致网关线程耗尽。rpm/tpm分别限制模型每分钟的请求数和 token 数。这是 litellm 限流功能的基础配置好之后能防止一个应用把配额耗尽拖垮其他应用。2.3 环境变量与密钥管理别偷懒硬编码配置密钥时强烈建议使用环境变量引用而非直接写入明文。litellm 支持os.environ/VARIABLE_NAME这样的写法在启动进程时从环境变量中读取。我见过有人图省事直接把 key 写在 YAML 里提交到代码仓库结果密钥泄露账单起飞。这不是 litellm 特有的问题但它作为集中管理 key 的地方一旦泄露影响范围更大所以更要谨慎。如果你用的是 Docker 部署可以考虑用 secrets 文件挂载的方式配合容器的环境变量注入。如果是在云服务器上密钥管理服务也是更好的选择。核心心态是代码和配置可以入库但密钥永远只能存在于运行环境中。3. 实操过程与核心环节实现3.1 对接不同服务商同一个接口多种模型先演示一个比较完整的配置。假设业务需要三个模型一个通用聊天模型、一个便宜快速的轻量模型、一个本地部署的开源模型。配置如下model_list: - model_name: chat-model litellm_params: model: anthropic/claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY timeout: 30 - model_name: fast-model litellm_params: model: gpt-4o-mini api_key: os.environ/OPENAI_API_KEY rpm: 100 tpm: 200000 - model_name: local-model litellm_params: model: ollama_chat/llama3.1 api_base: http://localhost:11434配置好后启动代理服务litellm --config config.yaml --port 4000调用的时候不管是哪个模型代码都长一个样子from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000/v1, api_keysk-1234 ) response client.chat.completions.create( modelchat-model, messages[ {role: user, content: 写一个三分熟的牛排煎制步骤} ] ) print(response.choices[0].message.content)这个体验就很舒服了。业务代码只认识chat-model这个名字完全不关心它背后到底是闭源还是开源、是国内还是国外服务商。将来想换一个更便宜的模型顶替fast-model只需要在配置里把litellm_params.model改掉业务代码一行不用动。真实生产环境里这种能力可以避免很多无谓的发布和协作成本。3.2 虚拟 Key 与预算控制给每个调用方立规矩litellm 有个特别实用的功能是虚拟 key 管理。你可以为每个应用、每个团队成员、甚至每个最终用户生成一个独立的 key并在 key 上设定预算上限、速率限制和可访问的模型范围。这样即使某个 key 泄露了影响也是可控的。首先生成一个虚拟 keycurl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-1234 \ -H Content-Type: application/json \ -D { models: [chat-model, fast-model], max_budget: 50, budget_duration: 30d }返回结果里包含一个key字段这个虚拟 key 之后可以作为调用时的api_key。设置max_budget: 50表示这个 key 在 30 天内的总消耗上限为 50 美元结算单位取决于你配置的 provider到了上限后请求会被拒绝并返回 429。这里有个细节值得留意虚拟 key 的模型列表是白名单机制。如果生成 key 时只指定了chat-model那这个 key 就没法调用local-model。这个设计我觉得很贴心相当于在模型层面做了一个访问控制可以防止用户凭一个 key 把你所有的模型都调一遍避免了滥用和费用失控。3.3 负载均衡、重试与多 key 轮转网关的自我修养在生产环境里上游服务商偶尔会抽风限流、超时、5xx这些都是家常便饭。litellm 内置了重试和负载均衡机制可以配置多个服务商作为同一个逻辑模型的多个上游。比如你想同时用两家服务商的同规格模型来做冗余配置可以这样写model_list: - model_name: fallback-model litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY model_info: mode: completion - model_name: fallback-model litellm_params: model: anthropic/claude-3-5-haiku api_key: os.environ/ANTHROPIC_API_KEY同一个model_name配置了两条记录litellm 会默认使用 round-robin 策略将请求分散到这两个上游。如果某个上游返回 5xx 或超时litellm 会触发自动重试切换到另一个。再配合多 key 轮转litellm_params: model: gpt-4o-mini api_key: os.environ/OPENAI_API_KEY api_base: https://one.example.com/v1在上游网关只允许单个 key 时可以在 litellm 的配置里为同一个模型配置多个 key它会在请求时自动轮换使用。这招在应对严格限流的场景下非常实用相当于把多个配额合并成一个更大的池子能显著提升有效吞吐量。3.4 流式输出与函数调用OpenAI 兼容接口的完整度很多人选型 LLM 网关时会担心一件事兼容接口做的是不是只支持基本的 chat复杂功能全部不支持就 litellm 目前的表现来看它对 OpenAI 兼容接口的覆盖已经非常完整流式输出、工具调用function calling、JSON 格式输出response_format这些都是支持的。以流式输出为例在 litellm 代理后面调用 OpenAI SDK 时启用streamTrue就能正常拿到 SSE 格式的分片返回客户端体验和无网关时没有任何区别。工具调用方面配置好 tools 参数后litellm 会在上游返回 tool_calls 时原样透传业务代码处理方式和直连没有任何差别。这份透明代理的功力看着不起眼实际用起来会省很多心因为不需要为网关这一层做额外的适配。3.5 成本跟踪与使用明细管理者的信息刚需另一个容易被人忽视的实用功能是请求日志和成本追踪。litellm 能够记录每一次请求的模型、token 消耗、延迟和估算成本并提供查询接口。这对团队负责人或者独立开发者的吸引力是很大的。你可以随时回答这个月模型调用花了多少钱哪个应用消耗最大这类问题而不是等到月底看到账单才开始复盘。启用方式很简单litellm 默认会通过回调记录日志可以在配置里指定对接数据库或仅内存记录。生产环境建议把日志写到外部存储否则网关实例重启后历史数据就没了。这里提一下升级思路如果不想自建监控面板litellm 的日志数据可以对接一些现成的可观测平台接口是标准化的接入成本不高。4. 常见问题与排查技巧实录我在实际用过一段时间后积攒了一些踩坑经验整理成速查表。这些问题多多少少都和数据格式和配置细节有关。问题现象可能原因排查与解法请求返回 404提示 model not found配置的model_name与实际调用的名称不一致检查请求体里的 model 字段是否与 YAML 配置暴露的别名完全一致转发到某服务商后报格式错误litellm_params.model缺少 provider 前缀根据服务商补全如anthropic/、ollama_chat/请求超时无响应上游服务商接口响应慢或 timeout 设置太短调大litellm_params.timeout或者检查上游服务的负载情况收到 429 限流虚拟 key 速率限制或上游容量被耗尽查看限制配置项确认是否 rpm/tpm 设得太保守后端返回原始错误而不是标准格式上游服务商返回异常状态码litellm 直接透传检查上游服务状态若依赖第三方可用性可配置备用模型做自动切换4.1 排查思路从日志入手层层倒推遇到请求异常时我一般先看 litellm 服务端的日志输出。litellm 在默认配置下会把每个请求的路由结果、目标服务商、耗时和错误信息打印出来。先确认它到底有没有把请求发出去以及发到了哪里。如果日志里显示已经尝试转发但上游返回了错误那问题基本在服务商那边如果日志根本没有记录到请求那就得检查网关前面还有没有别的拦截层比如反向代理、负载均衡的路径规则。如果错误涉及到模型名可以用 litellm 的命令行直接测试一下目标模型是否可用比如litellm --model anthropic/claude-3-5-sonnet --api_key $ANTHROPIC_API_KEY --test--test参数会发一个简单的测试请求并打印完整返回这样能快速判断问题是出在配置还是出在模型本身。用这个命令排除掉服务商的问题后再回到配置里找原因思路就会清晰很多。4.2 部署形态选择本地进程还是容器编排litellm 本身是一个标准的 Python 服务部署方式很灵活。我推荐优先考虑 Docker 部署原因很简单依赖隔离、环境变量注入方便、日志收集统一。官方提供了镜像运行如下docker run -d \ -p 4000:4000 \ -v $(pwd)/config.yaml:/app/config.yaml \ -e OPENAI_API_KEYyour-key \ ghcr.io/berriai/litellm:main-latest \ --config /app/config.yaml启动时把配置文件挂载进去环境变量通过-e传入。如果是配好了虚拟 key 的团队内部使用建议再在前面加一层反向代理做 TLS 终结避免通过明文的 HTTP 传 key。当然如果只是在本地开发环境用用直接进程方式跑也完全足够。4.3 并发与性能网关会成为瓶颈吗从性能角度看litellm 本身是 IO 密集型服务大部分时间都在等待上游响应自身 CPU 开销不大。最乐观的情况是单个实例可以支撑足够大的并发量关键在于它与上游服务之间的连接管理和网络带宽。真正的瓶颈往往在上游的限流上或者配置了过高的rpm导致请求排队时间变长。如果你发现网关成了瓶颈最简单的方法是水平扩展在负载均衡层后面跑多个 litellm 实例。因为 litellm 的路由状态比如 key 的预算计数可以存储在共享数据库中所以多实例共享同一份配置是可行的。不过要注意如果配置了过多的虚拟 key 和预算规则需要保证一致性否则可能会出现预算超限却没被拦截的微小误差。对于大多数规模的项目单实例到多实例的扩展都很平稳。4.4 一些容易忽略的细节有两个小细节很容易踩坑。第一是model_name不要和上游模型重名。比如你把litellm_params.model直接设成gpt-4o-mini同时model_name也叫gpt-4o-mini看起来没问题但当你后面想针对这个model_name配置不同策略时会产生困扰。建议像前面示例那样用一个业务语义的名字chat-model做别名。第二是如果你启用了rpm/tpm限制要注意设置一个合理的初始值。默认情况下 litellm 会试着从上游获取速率限额但如果上游不支持就默认一个比较宽松的值。如果业务需要严格限流最好在配置里显式声明否则实际运行时的限制可能不符合预期。5. 从个人工具到团队底座litellm 的价值延展litellm 的定位决定了它不仅能服务于个人开发者的效率也能在团队项目里扎根。很多团队把 litellm 当作模型接入层的唯一入口下游应用不再与管理各种 key 和权限纠缠只关心业务本身。这种底座思维的性价比很高。因为当你的系统从一个模型进化到多个模型从单环境进化到多环境时底层的复杂度是呈指数级增长的。有了统一网关这种增长被隔离在配置变更这个层面上。换句话说litellm 真正提供的不是转换 API这个动作而是隔离变化这个系统能力。这次分享算是把我自己一个阶段性的理解做了整理。litellm 的功能远比我写的这些更丰富像团队管理、路由策略的进阶配置、对不同数据库的日志对接等还有不少可以深挖的地方。我更倾向于把它当作一个持续演化的工具随着项目需求的变化一点点完善配置和使用方式。如果你正在被多模型接入的重复劳动消耗耐心花一下午部署一个 litellm后续省下的时间绝对值得。