最近在帮团队搭一套多模型接入的中转层前前后后对比了好几个方案最后把 litellm 放了进去。之前我们接大模型API的时候每个模型一个SDK、一套鉴权逻辑、一种返回格式每次新增供应商都要改一轮业务代码实在头疼。litellm 提供了一种统一接入的方式把不同模型提供商的接口规范收敛成一套调用风格目前我们团队的新接口已经全部走它来转发。这篇就结合我实际接入踩过的坑把这个工具的思路、部署和常见问题讲清楚。litellm 做的事情很纯粹它对外提供一个标准化的 OpenAI 风格接口对内适配不同的大模型服务商。你不需要关心底层请求签名、错误码、速率限制规则全部由中转层吃掉。这种思路特别适合产品需要快速在多个模型间切换、灰度、容灾的场景也能给非算法团队的同事一个统一的上游入口。对于不熟悉这套东西的人来说理解它有两个关键点。第一个关键点litellm 是一个 Python SDK你可以直接在 Python 代码里import litellm用它来完成单次调用。第二个关键点它还内置了一个高性能的网关服务proxy server跑起来之后你本地会有一个监听端口任何支持 OpenAI 协议的工具都能直接对接比如你写了一套基于普通 HTTP 调用的业务原来访问的是某个模型服务的地址现在改成访问 litellm 的本地地址参数照旧就完成了模型切换。这就是它被很多团队拿来当“大模型API网关”的原因。1. 为什么需要统一的大模型接入层1.1 多模型接入的真实痛点做过具体业务落地的朋友一定懂这种窘境今天接一个文本生成服务用的是 A 厂商的格式明天要接一个对话模型又是 B 平台的协议返回结构里的字段名都不一样。这在代码里就是一片if provider A: ... elif provider B: ...刚开始还能忍等到接入第五六个模型时基本变成一团乱麻。除了格式还有鉴权参数、超时设置、重试策略、限流反馈的差异。A 平台的限流返回 429B 平台返回 400C 平台甚至用一个自定义错误码。如果逻辑全都写在自己的业务代码里那业务代码会被各种供应商细节绑架每次上游接口升级都要跟在后面改联调。更要命的是线上出了问题排查链路很长到底是模型平台问题还是我们自己的请求参数问题很难一眼定位。1.2 litellm 的定位做一个翻译层和交通调度层litellm 本质上是一个翻译层加交通调度层。它把各家 API 的请求参数翻译成内部标准参数然后再把各家返回的数据翻译成标准响应。对外客户端看到的始终是统一的请求和响应结构。它的另一个身份是“交通调度员”。一个请求进来litellm 可以根据配置把流量路由到不同的上游比如按权重分发、按优先级 fallback、按预算控制。这些策略写在配置文件里调整时不用改业务代码。也就是说业务系统只依赖 litellm 这一个出口上游模型供应商随便换客户端无感知。2. 核心功能概览与两种接入方式2.1 核心功能清单我用下来litellm 最值得关注的功能集中在这么几块统一API接口客户端使用 OpenAI 兼容的接口格式/chat/completions、/embeddings、/completions都有对应实现。多模型适配配置里可以声明若干个上游 provider每个 provider 绑定不同的模型名。密钥管理上游 API Key 统一放在配置文件或环境变量里客户端不需要知道上游密钥只用 litellm 自己签发的虚拟 key。负载均衡对同一个模型可以配置多份上游实例实现轮询或权重分发。预算控制与限流支持按虚拟 key、按用户、按 IP 做速率限制和消费配额。重试与降级某个上游失败时自动重试或切换到备用模型。流式输出完整支持 SSE 流式返回也支持非流式。日志与监控内置缓存、审计日志、用量统计能记录 token 消耗和延迟。这些功能有些是开箱即用的有些需要搭配数据库才能持久化。我后面会拆开讲。2.2 两种使用模式怎么选litellm 有 SDK 模式和 Proxy Server 模式选择的关键看你的调用方是谁。SDK 模式适合写 Python 脚本、测试代码或 Python 后端服务。直接在代码里completion litellm.completion(model..., messages[...])简单直接。但这种模式下所有接入逻辑都在进程内如果团队里同时有 Java、Go、Python 多种技术栈SDK 就限制了只有 Python 可以用。Proxy Server 模式适合团队统一接入。启动一个独立服务之后谁都可以通过 HTTP 调用不限定语言。比如我们团队算法组负责维护 litellm 配置后端业务组只需要把原来调用大模型接口的 URL 改成本地网关地址即可。因此我更推荐生产环境用 Proxy Server 模式SDK 适合做快速验证和原型。3. 从零搭建 litellm 代理服务3.1 安装与基础配置安装很简单只要你的 Python 环境在 3.9 以上pip install litellm[proxy]装完之后创建一个配置文件叫config.yaml里面声明模型组和路由规则。这是我最常用的最小化配置示例model_list: - model_name: chat-main litellm_params: model: provider-a/chat-model-1 api_key: os.environ/A_PROVIDER_KEY api_base: https://api.provider-a.com/v1 - model_name: chat-main litellm_params: model: provider-b/chat-model-2 api_key: os.environ/B_PROVIDER_KEY注意这里model_name是对外暴露的名称业务方调用时就写这个模型名。litellm_params.model的格式是供应商标识/真实模型名例如某个供应商就用provider-a/chat-model-1。如果你只有一家上游也可以直接用。配置完成之后用下面的命令启动服务litellm --config config.yaml --port 4000默认端口是 4000启动后服务监听在http://0.0.0.0:4000。你可以先用 curl 验证curl http://localhost:4000/health如果返回服务正常说明最小实例已经跑起来了。3.2 用 OpenAI 兼容接口请求一次正常情况下客户端代码只需要设置base_url为你本地的 litellm 地址。下面这段 Python 代码模拟了 OpenAI 客户端的调用方式from openai import OpenAI client OpenAI( api_keysk-litellm-virtual-key, base_urlhttp://localhost:4000 ) resp client.chat.completions.create( modelchat-main, messages[{role: user, content: 你好}] ) print(resp.choices[0].message.content)这个例子里没有用到真实平台密钥因为虚拟 key 是 litellm 自己签发的它负责去上游解密。这个设计保证了客户端不会接触到你的上游密钥。3.3 多模型和路由策略配置真实项目中通常不只是两个模型。我们会按业务线建多个model_name比如chat-support、chat-code、embedding-general等每个名称映射到一个或多个真实模型。如果同一个model_name下配置了多个真实模型litellm 默认会做轮询切换。比如你的 main 服务有两个供应商请求量会均匀分配。也可以在参数里加routing_strategy来调整负载均衡策略。下面的配置把默认策略改成了基于权重的分发router_settings: routing_strategy: simple-shuffle fallbacks: - chat-main: [chat-main-backup-a, chat-main-backup-b]fallbacks的意思是当主模型全部失败或不可用时自动走备用模型。备用模型不一定要是同一家可以指定另一个供应商的模型。这块对稳定性特别重要后面我会展开讲。4. 关键功能深度拆解4.1 密钥管理与虚拟 Keylitellm 的密钥体系分两层第一层是上游真实 API Key存放在环境变量或者服务端配置中第二层是给业务方使用的虚拟 Key。虚拟 Key 可以绑定到特定的模型列表、限流额度、预算上限。创建虚拟 Key 有两种方式。一种是启动服务后调用管理接口另一种是直接用 CLI 命令我比较常用命令行litellm --config config.yaml --create-key --user alice --models chat-main这个命令会返回一个sk-开头的 key这个 key 只能访问chat-main模型。后续如果要做用户维度审计就能通过这个 key 追溯到是谁调用了什么模型。提示虚拟 key 一旦生成明文只显示一次。一定要立刻存储在安全的地方丢失只能重新生成不能查看历史明文。4.2 负载均衡与重试机制负载均衡是 litellm 最有价值的一块。它并不是简单轮询而是可以根据上游的实时错误率做一些健康检查。如果我们对同一个模型配置了两个上游 API Key例如同样的模型服务有两个不同区域的接入点那么一个 down 掉之后litellm 会在下一个请求自动切换到另一个。在重试方面litellm 默认对 429、5xx 错误进行重试。通过配置可以调整router_settings: retry_policy: timeouts: 3 connect_timeouts: 2 content_policy_errors: 0content_policy_errors表示如果上游因为内容安全策略拒绝请求不重试因为再重试意义不大。这个细节值得注意不是所有错误都适合无脑重试。我们在线业务遇到最多的是超时把超时重试次数控制在 2 到 3 次避免上游已经处理了请求但响应慢了客户端重复提交导致重复扣费。4.3 预算控制与速率限制预算控制对成本敏感型产品特别有用。我们可以给每个虚拟 Key 设置总消费上限、每分钟请求数、每分钟 token 数。以下配置限制了一个虚拟 Key 每分钟最多 10 次请求和 5000 tokenlitellm_settings: max_budget: 100 budget_duration: 30d max_parallel_requests: 10 rpm_limit: 10 tpm_limit: 5000max_budget是周期内最大消费金额这里的单位是美元。在公司内部按项目组隔离成本时这种配额机制能让各组之间互不挤兑。litellm 在计算 token 时会根据模型返回的 usage 信息做累计超过阈值后直接拒绝新请求直到下一个周期恢复。4.4 流式输出与工具调用支持现在的对话产品基本都要求打字机效果流式是刚需。litellm 对 OpenAI 兼容的流式请求支持很完整你启动它之后直接把streamTrue传给客户端就行。底层 SSE 流会被 litellm 转换为统一格式再返回给调用方。工具调用function calling也是很多项目的痛点不同模型实现的工具调用格式有细微差异。litellm 把这些差异做了标准化处理只要上游模型支持工具参数litellm 的 proxy 接口就按标准格式透传。我们实际测试过在统一接口模式下同一套工具定义能在不同模型上稳定跑通减少了大量适配代码。5. 实际项目里的落地经验5.1 把 litellm 当作“替身”嵌入现有系统我们团队原来有一套老业务代码里直接请求某个模型平台的 API请求路径、请求体都是死的。要切换到 litellm 时我没有去动业务代码只是在服务配置里改了上游地址指向 litellm 的 4000 端口业务方甚至没有感知。因为 litellm 的 proxy 接口和 OpenAI 兼容接口长得一样老代码里用过的Authorization: Bearer xxx也依然有效虚拟 key 替换了真实 key。这种方式非常适合做灰度实验。比如新接入一个模型先让 5% 的流量走新模型观察反馈再逐步调高权重。litellm 的路由配置改完直接 reload 即可不需要重新发版。5.2 日志与用量监控litellm 支持将请求日志写入数据库默认是 SQLite生产建议迁移到 PostgreSQL。它会记录每次请求的模型名、虚拟 key、token 消耗、延迟、状态码、错误信息这些数据单独拉出来就能做成本报表。这里的坑点是默认 SQLite 在高并发下容易锁库。我们刚开始直接用了默认配置跑到每秒几十并发时偶尔报database is locked。后来把数据库切到 PostgreSQL并且在 litellm 设置里开启database_connection_pool问题就消失了。如果你的请求量不大SQLite 也能凑合但生产环境还是老老实实上 PostgreSQL。5.3 高可用部署注意事项litellm 本身支持多实例部署但由于它的预算统计和虚拟 Key 管理依赖数据库多实例之间需要共享同一个数据库。否则一个实例上创建的 key另一个实例不认识。部署时我通常会做两层前端挂一个负载均衡器后面跑两个 litellm 实例实例都连同一个 PostgreSQL。然后启动时加上--num_workers参数控制单实例内部的并发 worker 数。需要注意的是litellm 的配置更新机制是多实例共用的改了配置文件后需要通过 Admin API 刷新不能每个实例单独 reload否则策略不一致。另外一个容易被忽视的问题是日志清理。数据库里的日志会持续膨胀要写定期清理任务比如 90 天前的请求日志直接删除否则后续查询和统计会越来越慢。6. 常见问题与排查方法6.1 配置不生效或模型 404最常见的问题是改了配置文件但服务没重启。其次要确认配置里的model_name和客户端请求时用的model是否完全一致。litellm 对模型名的匹配是精确匹配大小写敏感。如果客户端传入的 model 在配置中不存在它会返回 404 的兼容格式错误。排查方法很简单启动时加上--detailed_debug参数日志里会打印出实际匹配到的路由项。我一般先用这条命令看链路litellm --config config.yaml --detailed_debug6.2 请求超时重试导致重复扣费litellm 默认会在超时后重试但如果上游实际已经生成结果只是响应慢了重试就会产生两次费用。针对这一点我建议把超时时间设置得比业务可接受时间稍长并且把重试次数控制在 2 次以内。同时在设计业务逻辑时尽量让客户端请求带上一个唯一请求号在网关层做幂等处理避免重复提交。6.3 流式响应不稳定流式问题很多出在代理环境。如果 litellm 和上游之间有负载均衡设备或代理它们可能会拦截或缓冲 SSE 流导致客户端看到断断续续的效果。我遇到过一次明明直连测试正常经过一层代理后就经常中断。后来检查发现是代理服务器对长连接的 idle timeout 设得太短调整后就恢复了。排查流式问题时可以先绕开 litellm直接用上游原始接口测试。如果上游流式正常再对比 litellm 的中间层日志基本能定位。6.4 虚拟 Key 权限不足创建虚拟 Key 时如果不指定模型它默认可以访问所有模型。如果指定了模型列表那这个 key 访问其他模型会被拒绝。很多团队把 key 下发给不同业务线后发现某个业务线调不了新上线的模型其实就是因为权限列表没加。要修改虚拟 Key 权限可以通过 Admin API 的/key/update接口或者在管理后台直接操作。6.5 预算告警不触发预算扣减依赖 token 计费数据如果上游 API 返回的 usage 字段格式特殊litellm 可能解析不到准确的 token 数导致预算计算失真。遇到这种情况可以先用一条真实请求打印完整的返回体确认 usage 字段是否齐全。如果上游确实不返回 usage可以配置一个模型级别max_output_tokens作为兜底估算。关于后续扩展的小建议litellm 现在不光是 OpenAI 风格的聊天补全接口像 embedding、rerank 这些也有对应实现。如果你的产品不只是做对话还需要做向量检索、语义排序建议把 embedding 接口也统一收到 litellm 里这样不管是切换向量模型还是统计 token 成本都能享受到统一管理的好处。我个人在实际操作中的体会是litellm 最适合的场景不是单纯“调用某个模型”而是“管理和路由多个模型”。它的学习曲线不算陡但配置文件的灵活度很高建议先从小流量跑起把路由、预算、日志三件套摸清楚再逐步开放给团队其他成员。最后再提醒一遍用这种网关工具时上游密钥的保管比什么都重要千万不要为了图省事明文写在业务环境变量里虚拟 Key 该启用就启用该设限就设限。