先问个实际的问题你现在手上是不是同时握着好几家模型厂商的 API Key今天要用这家的大模型明天要换另一家的每次切换都得重新研究接口文档、调整参数格式甚至改代码如果你也在这个状态里那 litellm 这个项目你应该了解一下。litellm 是一个开源的 LLM 网关服务简单说就是把你和各种大模型 API 之间的对接统一收口。你只需要按照一套接口标准去调用它剩下的转发、鉴权、重试、记账这些事它帮你处理。我最早接触这个项目是因为当时一个项目里要用到好几家的模型代码里到处是 if-else 分支光看都快看吐了。后来我把 litellm 接到项目里接口统一了密钥也收拢了整个人轻松了不少。这篇文章我不打算堆官方文档而是按我自己实际落地的过程来拆litellm 的定位、关键机制、部署步骤、以及我在生产环境里踩过的坑。适合正在做 AI 应用开发、想摆脱模型锁定的团队和个人开发者参考。1. 先把这个项目的定位聊透1.1 它不是一个简单的 SDK 封装很多人第一次看 litellm会觉得这玩意儿就是个 Python 库把不同模型的调用封装成统一的 format。你要是只这么理解就太小看它了。它做的其实是一个完整的网关层服务跟 Nginx 作为反向代理的思路很像只是它转发和处理的不是 HTTP 页面而是大模型请求。从这个角度去理解litellm 的价值就非常清晰了所有模型请求统一走一个入口应用端不需要关心背后是哪个厂商。API Key 不会散布到各个业务服务里由 litellm 统一托管和鉴权。请求到达 litellm 后由它做模型选择、负载分发、重试降级。生成的 token 数和成本自动记录预算控制可以前置。所以它解决的不仅仅是一个代码库的问题而是一个架构层面的问题。当你的应用从一个模型扩展成多个模型、从单实例变成多实例时没有这样一层收口你会被各类接口差异折腾得很惨。1.2 什么时候你该用它什么时候别用litellm 不是说放之四海而皆准我用下来觉得它对两类项目特别有用一类是应用本身需要适配多个模型的项目。比如你这周用某家的旗舰模型下周发现另一个开源模型部署到自己的 GPU 服务器上性价比更高想在两者之间随意切换。这种场景下如果业务代码直接对接原厂接口换一次模型就要改一次代码。另一类是团队协作项目。后端给你一把厂商 API Key测试也要用前端也要调密钥散得到处都是。通过 litellm 创建虚拟密钥后每个人拿到的都只是限定额度、限定模型的子 Key权限可控出了问题也好追踪。反过来如果你的项目只需要调用一个固定模型、对延迟要求极其严苛或者你本身就要在嵌入式设备上直接运行推理那中间加一层网关就是多余开销。这种场景不需要引进 litellm直接用原厂 SDK 更省事。2. 核心机制深度拆解2.1 协议转换是怎么做到的litellm 最底层的能力是把各家厂商的请求体统一转换成它自己定义的一套标准格式。你往它那里发请求时请求结构是标准化的它内部再把这份标准格式映射成目标厂商需要的具体格式。这个动作看起来不复杂但细节极其琐碎。比如有的厂商接受的是messages数组有的还需要额外的system字段单独处理有的支持max_tokens这个命名有的叫max_completion_tokens参数名不一样取值范围也不一样。温度的默认值、是否会输出logprobs、是否支持工具调用这些都不同。litellm 内部维护了一张很长的模型能力表记录了不同模型支持的参数集和默认行为这就是它能做到一个标准格式接所有模型的基础。你在配置里指定了某个模型名litellm 就知道这个模型对应的请求限制、上下文长度、默认参数并对请求做相应的校验和调整。这就是它能在极大模型范围内通用而不是只支持某两三家厂商的原因。2.2 虚拟密钥与密钥托管很多团队把 litellm 当成密钥的统一管理入口。你在配置文件里写好自己的真实厂商 API Key然后通过 litellm 的管理接口创建一个虚拟 Key。应用端拿到的都是虚拟 Key而不是你真正的厂商密钥。这个虚拟 Key 的好处是灵活。你可以给同一个模型创建多个虚拟 Key分发到不同业务线每个 Key 设置不同的速率限制、预算额度、可用模型列表。比如 A 业务每天最多调用 100 万 tokenB 业务只能用某个特定模型这些都能在虚拟 Key 上配置。万一某个虚拟 Key 泄露了或者某个业务不再需要了你可以单独吊销这个 Key完全不影响其他业务线真实厂商密钥也不需要轮换。这个思路其实是参考了云计算平台主子账号的模型在团队内部管理上很有价值。2.3 模型路由、优先级与失败重试litellm 内置了一个 Router可以理解成一个智能分发器。它启用了多模型部署策略之后就不再是简单的一对一转发而是会根据你的配置做路由决策。常见的配置场景是这样你希望优先使用某家厂商的旗舰模型它顶不住了或者响应超时就自动切换到备用的另一个模型上。你可以给每个模型设置权重Router 按权重分配请求也可以设置优先级和 cooldown 时间连续失败若干次后自动把流量切换到备用模型。这个机制生产环境里很关键因为单靠一个模型厂商服务稳定性很难保证。有时候厂商那边发版抽风、限流或者某个区域网络抖动如果你没有这层自动降级用户请求就直接失败了。有了 Router至少能给你兜底不至于请求全军覆没。2.4 成本追踪与预算控制大模型调用不像普通 API 那样按次计费它按 token 计费而 token 数是动态的。如果不做成本追踪月底账单出来你根本说不清楚钱去哪了。litellm 把成本追踪内置到了转发链路里。每一次请求结束litellm 会统计请求和响应的 token 数再结合你在配置里填的价格计算成本。你可以在多个维度看这个数据按模型看、按 API Key 看、按用户看、按时间范围看。预算控制也可以设多层整个代理的总预算、单个模型 Key 的预算、单次请求的最大消费上限。超出预算后请求会被拒绝避免失控成本。这些功能对于那些把 AI 能力整合进产品、需要给客户提供使用量报表的开发者来说几乎是刚需。3. 实操部署把 litellm 跑起来3.1 准备工作litellm 可以当 Python 库用但真正要当网关用建议直接用 Docker 部署。我自己的部署环境是一台 Linux 服务器只暴露 litellm 的端口厂商 API Key 都存在环境变量或配置文件里应用端只能访问 litellm。部署前确认好这几件事Docker 环境可用。你有哪些模型厂商的 API Key分别是什么。业务上需要用到大模型的模型名比如打算给客户端暴露成什么名字。如果你暂时没有多个厂商的 Key用一个厂商的 Key 也能先把流程跑通。配置方式是完全一样的后面再扩其他模型只是改配置的事。3.2 编写核心配置文件litellm 的核心配置是一个 YAML 文件通常叫config.yaml。这个文件里定义了模型列表、密钥、路由策略、预算等。先看一个最基础的模型配置model_list: - model_name: zh-model litellm_params: model: openai/zh-chat api_key: os.environ/OPENAI_API_KEY api_base: https://api.xxx.com/v1这里的model_name是给客户端看的客户端调用时填的是这个名字litellm_params.model才是实际发给厂商的那一串标识。你可以把某个厂商的模型暴露成任何名字客户端完全感知不到背后的真实模型名。如果你有多个模型就在model_list下继续加项。下面是一个包含两个模型的例子一个来自某厂商的旗舰模型一个来自某开源模型的托管服务model_list: - model_name: flagship-model litellm_params: model: openai/gpt-flagship api_key: os.environ/FLAGSHIP_API_KEY - model_name: fast-model litellm_params: model: anthropic/fast-model api_key: os.environ/ANTHROPIC_API_KEY注意model字段里的前缀openai/和anthropic/是告诉 litellm 这个请求应该按哪家的协议格式来处理。它根据这个前缀来决定内部的协议转换逻辑。如果你还想配置负载均衡和自动重试可以在配置下面加上 Router 相关的设置这里先不展开后面做基本的验证时用不到。3.3 启动服务并验证一次调用配置文件写好后启动 litellm 服务docker run -d \ --name litellm_proxy \ -p 4000:4000 \ -v $(pwd)/config.yaml:/app/config.yaml \ -e FLAGSHIP_API_KEYsk-xxx \ -e ANTHROPIC_API_KEYsk-xxx \ ghcr.io/berriai/litellm:main-latest \ --config /app/config.yaml --port 4000参数说明一下-p 4000:4000把容器的 4000 端口映射到宿主机-v把当前目录的 config.yaml 挂载进容器环境变量就是你在配置文件里引用的那几把真实 Key。启动之后用 curl 验证一下服务是否正常curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-1234 \ -d { model: flagship-model, messages: [{role: user, content: 你好介绍一下你自己}] }sk-1234是 litellm 默认的本机虚拟密钥你在配置里开启虚拟密钥认证后实际使用时需要创建一个属于自己的虚拟 Key而不是用这个默认值。请求返回后你看响应的结构跟直接调厂商接口格式是一样的里面包含模型返回的文本内容和 token 使用统计。到这里litellm 作为代理服务已经跑通了。你的应用端只需要把 base_url 指向http://localhost:4000模型名填flagship-model就能正常调用。3.4 接入现有 Python 项目litellm 设计得比较舒服的一点是它遵循通用的 OpenAI 兼容接口规范所以市面上大多数主流 SDK 都能直接接入。以 Python 为例你原来写的是直接连接某个厂商的 SDK现在改动很小from openai import OpenAI client OpenAI( api_keysk-虚拟key, base_urlhttp://localhost:4000 ) response client.chat.completions.create( modelflagship-model, messages[{role: user, content: 你好}] ) print(response.choices[0].message.content)你注意到没有应用层代码几乎没怎么改只是换了一个 base_url 和 api_key模型名换成了你自己定义的。今后如果你想把flagship-model背后的真实模型从 A 厂商切换到 B 厂商只需要修改 litellm 的配置并重启服务应用端一行代码都不用动。如果是异步场景用异步客户端指向相同地址即可litellm 本身对异步请求处理没有问题。4. 项目落地时绕不开的坑4.1 响应超时导致的重试抖动大模型接口有一个特点就是响应时间波动大。问一个简单问题可能 1 秒就回问一个需要长思考的问题可能要等 20 秒。如果你在 litellm 上层配置了类似 10 秒超时的策略它到点会主动断掉并触发重试逻辑。这里有一个容易踩的坑如果备用模型本身也有相同的请求但你给两个模型设置的超时时间都是一样的主模型超时之后切到备用模型备用模型也很可能因为同样的问题超时。结果就是用户等了几十秒之后看到的是一个又一个错误。我给的建议是根据模型的实际响应特性分别设置超时和重试参数不要用一套参数套用所有模型。另外Router 的重试次数不宜设得太多我一般设 1 到 2 次多了反而容易造成请求堆积。4.2 流式输出总是断项目里接入聊天机器人普遍都喜欢用流式输出一个字一个字地蹦出来用户体验好。但在 litellm 上刚开始接流式的时候我经常碰到一个问题开头能正常输出输出到一半连接就断了。排查下来原因有两类。一类是网络链路上的超时设置太短尤其是通过公网访问 litellm 的场景路由器、网关等中间设备可能断开了空闲连接。你需要在 litellm 配置里把流式响应的空闲超时调大一些同时客户端那边也别在底层设置了不合理的读超时。另一类是上游模型本身对流式输出的处理方式不同有的厂商对每个 chunk 的格式定义不太一样。litellm 会在内部做格式转换如果某个厂商格式比较特殊它可能没法在这个版本的转换中正确解析。遇到这种情况我建议直接升级 litellm 到最新版本这种兼容性问题一般会在后续版本里修复。4.3 模型名冲突导致路由不正确有一次我给客户端暴露了一个叫chat-model的名字同时配置了两个真实模型都对应到这个名字。我本意是想做负载均衡但实际测试发现流量始终打到一个模型上另一个几乎没收到请求。查了配置和日志后发现litellm 默认的路由策略是按顺序或按权重设置如果权重没写对它可能会一直命中列表里的第一项。你在配置里给多个模型指定同一个model_name时需要明确设置路由策略和权重分配不能指望它自动帮你均衡。排查技巧也分享一个litellm 自带的日志会打印每次请求命中的真实模型名当你觉得路由不对时先去日志里看命中情况通常能很快定位问题。4.4 预算超限但请求还在持续调用预算控制是 litellm 的卖点之一但我第一次配置时也闹过误会。我在配置里给某个 Key 设置了预算上限心想到了上限就该停了结果过了半天去看还在不断调用成功。仔细读文档才知道litellm 的预算控制分多个层级有的层级是按请求维度实时拦截有的层级是按时间段统计事后阻断。如果你的配置只设置了总预算而没有设置最大单次请求预算它不会在最开始就拦截而是在累计超过之后才生效。处理方式是先明确你的核心需求如果是防止单次异常请求消耗过多 token需要配置的是max_budget_per_request或者单次请求的max_tokens上限如果是对某个 Key 做月度总额控制那需要确认统计周期和触发阈值。这两者的机制不一样不要弄混。5. 额外想说的两个配置细节5.1 如何管理多套环境如果你的项目有开发环境、测试环境、生产环境我不建议直接复制三份相同的 litellm 配置。更好的做法是把配置模板化把模型名、预算、密钥这些差异项用环境变量替换然后用 CI/CD 流程为不同环境生成不同的配置。这样做的目的不是减少输入量而是避免环境之间的参数漂移。我见过有团队在测试环境调整了某个模型的超时参数上线时把这个参数带到了生产环境结果生产环境的请求链路表现异常排查很久才发现是参数不一致导致的。litellm 官方也支持把部分配置项用环境变量注入你要做的就是约定好每个环境该填哪些环境变量然后把这份约定固化到部署脚本里。5.2 日志与监控别忽视litellm 默认会打印请求日志但如果你打算长期维护这套代理服务我建议还是把日志接入集中式监控平台并针对几个关键指标配置告警请求失败率突增说明某个上游模型可能不稳定。平均响应延迟升高可能是某条网络链路出了问题。某个虚拟 Key 的调用量激增可能是业务异常或密钥泄露。这里我不展开具体的监控平台怎么搭了重点是想提醒你litellm 这层网关是观测所有模型调用流量最好的位置不要在它上面只做转发浪费了数据价值。6. 后续可以怎么扩展litellm 这个项目本身迭代很快社区也很活跃。我最近关注到的几个方向如果你正好有需求可以研究一下。一个是结合向量数据库做 RAG 场景。litellm 可以配合嵌入模型做统一接入这样不仅大语言模型走统一网关嵌入模型也能走统一网关整个 AI 应用的模型调用面收得更干净。另一个是团队协作时做更细粒度的权限控制。litellm 支持设置每个虚拟 Key 能访问的模型列表、每分钟请求数限制、消费者字段适合做多租户场景下的配额分类。如果你的产品要对不同客户提供不同的 AI 调用额度这一层能力几乎是为这个需求准备的。还有一个方向是把它作为公司内部模型平台上的一层入口。随着各家模型不断出新模型能力在快速迭代接入的模型数量会越来越多。当模型数量达到几十个的规模时如果没有统一的入口管理后续做模型替换、成本对比、灰度放量都会非常困难。我个人在实际项目里体会最深的是litellm 让我终于不用再为了换一个模型而熬夜改代码了模型切换变成配置变更而不是代码变更这带来的心态变化太明显了。你要是也在为多模型接入头疼不妨按这篇文章的步骤搭一套出来试试跑通了之后你大概率会回头把业务代码里那些硬编码的模型调用全清一遍。