最近这段时间我一直在处理多个大模型 API 的接入问题。手上有三四家模型服务商每家给的 SDK、鉴权方式、限流规则、计费口径都不一样早期还能靠复制粘贴胶水代码应付等模型一换、服务商一调整维护成本就彻底失控了。后来我把所有请求统一转发到一个本地代理服务上这个代理就是 litellm。简单说litellm 是一个开源的大模型 API 网关它把不同服务商的接口包装成一个标准聊天补全接口业务方只需要记住一个 base_url、一个 api_key按月、按项目、按模型查账单这件事它也一并管了。如果你正在做多模型接入、模型频繁切换、又需要成本分摊这篇文章应该能给你一个比较完整的落地参考。1. 从胶水代码到统一网关litellm 到底解决了什么问题1.1 没有代理时接多模型到底有多痛先说一个很典型的场景你的业务里需要支持文本生成、摘要抽取、情感分析可能还要在几个模型之间做 A/B 测试。没有统一网关的时候代码会变成什么样子通常是要么在代码里直接调用不同服务商的 SDK要么自己写一堆适配层。每个 SDK 的请求参数名不一样有的用messages有的叫prompt有的需要单独传temperature有的还分 system 和 user 角色返回结构更是五花八门有的返回choices[0].message.content有的返回content[0].text。一套业务逻辑要想兼容两个服务商就得写两套解析函数再加一个判断分支。服务商模型更新、接口字段不兼容你还要追着改。更麻烦的是密钥管理。多个服务商的 API Key 存在不同环境变量里如果前端直接调用等于把 Key 的暴露面扩大了好几倍。团队成员各自去官网开账号、充钱月底对账的时候根本不知道哪一笔消耗是哪个项目产生的。我在实际项目里就经历过一次某个内部工具默默跑了一个星期账单出来吓了一跳最后翻日志才发现是一个同事把测试 Key 写到了公共配置文件里。1.2 代理模式统一的是什么litellm 的存在就是把这些琐碎问题集中到一个代理层处理。它本身运行成一个本地 HTTP 服务对外暴露的是一套标准的 Chat Completions 风格接口。你可以把它理解成一个“中转站”业务端把请求发给 litellmlitellm 根据请求里的模型名找到对应的服务商配置完成真实调用再把结果按统一格式返回给业务端。这个“统一”不是只统一了协议格式。它至少统一了四件事协议统一业务端永远使用同一个/chat/completions端点不需要关心背后的服务商是谁。模型名统一你在请求里写的模型名可以和实际的服务商模型名不一样。比如内部约定叫fast-chat实际映射到某个便宜的模型哪天想换成另一个模型只改代理配置业务代码一行不动。密钥统一业务端只需要认 litellm 的 Key真实的供应商 Key 全部存在 litellm 的配置或环境变量里大大降低了 Key 泄露面。成本记录统一所有请求都经过代理litellm 能把每一次请求的 token 用量、费用、模型、用户标识落到日志里方便后续做账单拆分。这套思路非常适合做团队内的“模型服务层”。业务方不直接接触任何一家服务商 SDK只需要写一套对 litellm 的调用代码。后面无论增加供应商、调整模型、开通新能力都是运维层面的事开发不用跟着受累。2. 十分钟跑起来最小配置与验证流程2.1 安装与启动litellm 的安装非常简单我是用pip直接装的。因为要用代理功能需要安装带proxy扩展的版本pip install litellm[proxy]安装完成后终端里直接执行litellm就是启动代理服务默认监听0.0.0.0:4000。不过一般我不会直接裸启动而是准备一个config.yaml把模型列表和维护项都写进去。最小可用的配置文件大概是这个样子model_list: - model_name: fast-chat litellm_params: model: provider-a/chat-v1 api_key: os.environ/PROVIDER_A_KEY这里面有一个很容易搞混的点model_name是暴露给业务端用的名字你可以随便起叫fast-chat、qa-bot都可以litellm_params.model才是真正请求服务商时使用的完整模型标识前面前缀要按 litellm 支持的供应商前缀规则写。业务端请求时拿model: fast-chat发给代理litellm 看到这个映射关系后会转成provider-a/chat-v1再去调真实的模型服务。启动命令litellm --config config.yaml --port 4000 --detailed_logging--detailed_logging会在终端打印每次请求的耗时、token 用量和具体报错调试阶段强烈建议打开。2.2 用 curl 验证代理已经生效配置文件写好后先在本地起一个最小验证。由于 litellm 默认没有强制鉴权我可以直接用一个假 Key 测试curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-local-test \ -d { model: fast-chat, messages: [ {role: system, content: You are a helpful assistant.}, {role: user, content: Hello, say hi in one sentence.} ], temperature: 0.7 }请求体用的就是常见的聊天补全数据结构。返回结果里同样有choices、usage这些字段。如果能看到返回内容和usage里的 token 统计说明代理链路已经通了。这里有个容易被忽略的细节如果你配置的模型服务商对网络访问有额外要求比如某些模型需要部署在特定区域在litellm_params里还有api_base字段可以指定自定义端点。遇到模型报连接错误时优先检查这个字段是否被正确设置。2.3 不同服务商的 Key 配置方式配置里不直接写明文 Key 是比较稳妥的做法。litellm 支持从环境变量读取密钥例如export PROVIDER_A_KEYsk-xxxxxx配置文件中写成api_key: os.environ/PROVIDER_A_KEY这样即便别人拿到配置文件也看不到真实密钥。启动进程时环境变量已经在内存里litellm 运行时会自动解析。我习惯把所有的模型服务商 Key 集中到一个.env文件里管理然后通过类似set -a; source .env; set a的方式加载到环境变量中。这样配置和密钥分离后面交接也方便。3. 路由、密钥、账单litellm 核心能力拆解3.1 模型路由和别名机制litellm 最基础的能力是“按模型名路由”。它的路由逻辑很像一个查表过程收到请求后先解析出model字段再到model_list里找到对应的litellm_params然后按参数发起上游调用。除了简单的一对一映射litellm 还支持多个真实模型共用一个模型名也就是模型组。比如我把fast-chat指向两个不同服务商的模型并配置了轮询策略litellm 会自动在它们之间分发请求。这里贴一段平时会用到的配置model_list: - model_name: fast-chat litellm_params: model: provider-a/chat-v1 api_key: os.environ/PROVIDER_A_KEY model_group: chat-group - model_name: fast-chat litellm_params: model: provider-b/general-chat api_key: os.environ/PROVIDER_B_KEY model_group: chat-group router_settings: routing_strategy: simple-shufflemodel_group相同的条目会进入同一个路由池routing_strategy控制分发策略。默认的simple-shuffle是简单轮询还有基于延迟和错误率的策略。这样做的价值在于当某个模型服务不稳定时你可以把流量切到另一个模型上而业务端的模型名可以一直保持不变。3.2 多 Key 轮询与负载均衡如果同一个模型服务商你申请了好几个 Key并且担心单 Key 被限流litellm 也支持多 Key 轮询。只需要在litellm_params里把api_key写成一个列表- model_name: fast-chat litellm_params: model: provider-a/chat-v1 api_key: - os.environ/PROVIDER_A_KEY_1 - os.environ/PROVIDER_A_KEY_2 - os.environ/PROVIDER_A_KEY_3litellm 会在请求之间自动切换 Key某个 Key 返回鉴权失败时会暂时把它标记为不健康过一段时间再尝试恢复。这个机制我实际用下来很有效尤其是高频调用场景下单 Key 的每分钟请求限制很容易被触顶多 Key 轮询可以明显减少 429 限流报错。3.3 用量与费用统计是怎么记录的成本追踪是我最终愿意在团队内部推 litellm 的重要原因。所有请求通过代理转发后litellm 会记录每次请求的输入 token、输出 token、模型单价和总费用并写入内置的数据库。它还会把请求来源的用户信息、自定义标签一起记录下来这样月底对账时就能按项目、按调用方拆分成本。在实际配置里需要关注general_settings下的预算设置general_settings: master_key: sk-master-for-admin max_budget: 100 budget_duration: 1d这里的max_budget是总预算上限budget_duration是预算周期。超过预算后代理会拒绝新的请求起到硬性熔断的作用。如果对整个团队的总预算没有概念建议先从较大的额度开始跑一段时间拿到真实基线后再收紧。费用统计还有一个额外好处你在做模型选型对比时不再需要自己写计费逻辑直接查询 litellm 的 spending 日志就够了。4. 上生产前必须处理的四个细节4.1 身份认证别把代理裸奔在公网本地开发时代理可能只监听在127.0.0.1问题不大。但一旦部署到服务器上尤其是有公网 IP 时必须给代理加上身份认证。litellm 的master_key在很多版本里默认不开启需要你在配置里显式配置。开启后客户端请求头里的Authorization: Bearer必须带上这个 Key否则请求会被拒绝。更严谨的做法是在代理前面再套一层网络访问控制比如只允许内网网段访问。litellm 本身解决的是模型调用层的问题网络层的防火墙还是要自己做好。内部系统如果有统一鉴权平台也可以先用平台鉴权再把用户信息通过自定义请求头传给 litellm这样日志里的用户维度也会更完整。4.2 超时、重试与限流模型服务商接口偶尔会慢甚至超时。上游一个慢请求会长时间占用代理的连接资源如果并发一高整个代理可能被拖垮。我建议在每个模型参数里显式配置超时时间- model_name: fast-chat litellm_params: model: provider-a/chat-v1 api_key: os.environ/PROVIDER_A_KEY timeout: 30这里timeout的单位是秒指等待上游返回的最长时间。超过后 litellm 会返回超时错误。重试机制可以交给调用方控制也可以使用 litellm 的全局重试配置但要注意重试不能太激进。如果上游服务本来就因为过载而超时重试只会加重它的负担。我的经验是超时时间设 20-30 秒重试次数不超过 2 次且第一次重试前至少间隔 1 秒。限流方面litellm 允许按 Key、按用户设置请求频率上限。比如某个内部机器人每秒最多调用 5 次直接在配置里加上限流规则超过后直接返回限流错误避免业务方把代理当成无限资源。4.3 与常见开发框架的集成方式如果你已经在业务代码里使用某种聊天补全风格的官方 SDK接入 litellm 通常只需要改两个参数base_url指向 litellm 的地址api_key换成 litellm 的 Key。以 Python 环境为例基本是这样from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000/v1, api_keysk-local-test, ) resp client.chat.completions.create( modelfast-chat, messages[{role: user, content: 你好}], ) print(resp.choices[0].message.content)这里的openai指的是兼容该接口风格的第三方客户端库不是特定公司。只要你的框架支持自定义base_url几乎都能这样接。如果你不想用 HTTP 方式litellm 也提供了 Python SDK 形式的调用import litellm response litellm.completion( modelprovider-a/chat-v1, messages[{role: user, content: 你好}], )这种方式适合在脚本、定时任务里直接用少起一个服务。不过既然用了 litellm我还是更推荐走代理模式这样日志、限流和账单才能统一收口。4.4 日志落盘与监控生产环境里litellm 终端打印的日志是不能作为唯一依据的。必须把日志落盘或者把关键指标推到监控系统。litellm 支持配置回调比如把每次请求的 token 用量、响应时间和状态码发送到自定义 Webhook也可以对接 Prometheus 采集指标。我个人的做法是配置了一个简洁的 Webhook让 litellm 在每次请求统计完成后把模型名、耗时、是否成功、token 用量、用户标识推送出去自己写一个小服务负责聚合和告警。这样当某个模型的失败率突然升高或者每天成本超过阈值时我能第一时间收到通知而不是等问题反馈到用户那边。5. 我在真实业务里踩过的三个坑5.1 成本统计对不上的问题有一次我发现 litellm 记录的某模型费用和模型服务商后台账单差距很大差了差不多三倍。排查后发现是 litellm 对那个模型的默认计费单价和我实际被收取的价格不一样。很多新模型的定价经常调整litellm 内置的价格表不一定总是跟得上。解决办法是手动覆盖单价- model_name: fast-chat litellm_params: model: provider-a/chat-v1 api_key: os.environ/PROVIDER_A_KEY model_info: custom_pricing: true input_cost_per_token: 0.000001 output_cost_per_token: 0.000002input_cost_per_token和output_cost_per_token的单位是单 token 的价格实际填的时候记得先搞清楚计费是按 1K token 还是 1M token 计费单位搞错的话费用统计会差几千倍。建议每次接入新模型都先拿一个短文本请求做对照看 litellm 的统计成本和真实账单是否在合理误差范围内。5.2 模型名和实际模型搞混有次业务方反馈说请求报“model not found”但配置文件里明明有这个模型名。我在 litellm 日志里看到业务端传过来的模型名是provider-a/chat-v1而不是我在model_name里定义的别名fast-chat。原因是业务端代码里直接写死了旧模型名代理收到请求后去model_list里查查不到就报错。这个问题本质上是团队没有约定好“外部只能使用别名”的规则。后来我做了两层约束第一配置里不要出现容易被业务方猜到的真实模型名第二给业务方只提供一份文档明确告诉它们哪些模型名可用所有真实模型名都不对外暴露。5.3 代理进程内存持续上涨litellm 默认会保存一定的历史记录和统计数据长时间运行后内存占用会缓慢上涨。有一回我们的代理跑了快一个月内存一直居高不下最后发现是日志记录保留周期太长积累了大量请求详情。解决办法是在配置里调整日志保存策略定期清理旧数据或者把详细的请求体日志关闭只保留统计摘要。如果你的请求量非常大建议把 litellm 的数据库存储和业务数据库分离并且给代理进程设置合理的内存限制防止内存被打满后影响到其他服务。5.4 上游限流导致连锁失败还有一次比较典型某个模型服务商因为账号欠费突然开始大量返回鉴权错误。litellm 的负载均衡策略会把该 Key 暂时标记为不健康但当时我们一部分请求已经被路由到了这个不健康 Key 上导致整体成功率下降。后来我加了一个简单的健康检查机制定期用一个最小请求探测不健康 Key 是否恢复恢复后再重新加入轮询。如果你的服务商数量比较多建议也配置一下健康检查不要完全依赖被动标记。6. 选型边界什么情况下不该用 litellmlitellm 的优势非常明显但它不是银弹。我先说清楚的适用场景多模型、多团队、多项目并且有成本分摊需求的环境用 litellm 非常合适。它能让你对模型调用集中掌控也能减少 SDK 碎片化带来的维护成本。但如果你只是个人开发一个简单的 Demo只调用一家模型服务商那完全没有必要引入代理层。直接使用服务商 SDK 更轻快少一跳网络请求也少一些排查成本。如果团队没有专门的运维同学只是在一台服务器上临时跑几个脚本也不建议一开始就上代理因为代理本身需要维护、升级、监控它也是个服务。另一种需要谨慎的情况是如果企业对数据有严格的合规要求禁止把内部数据转发给某些外部模型服务商那把所有流量都引流到代理上时不一定会自动满足合规。litellm 只是统一了调用的技术路径数据要去哪里、能去哪里仍然需要架构层面明确。这种情况下适合使用 litellm 的本地模型或私有化部署模型接入能力把流量控制在合规边界内。在替代方案上如果觉得 litellm 偏重也可以自己写一个几十行的适配层但你要自己承担负载均衡、Key 管理、账单统计这些功能的开发成本。这类功能看起来简单实际打磨起来非常费时。如果只需要一个基础的统一入口可以先用轻量方案跑一段时间后如果发现确实需要路由、限流、计费再迁移到 litellm 也不迟。7. 我个人在项目收尾时的一些习惯每次把 litellm 部署到一个新环境我都会顺手做几件小事第一确认master_key已经配置并测试不带 Key 的请求是否会被拒绝第二用不同的模型名各跑一次真实请求并对比 litellm 的统计成本和账单后台第三设置一个偏保守的预算上限宁可因为误触发熔断暂时不可用也不要等月底收到超额账单再后悔。真正跑了几天之后再把预算放宽到一个合理值。另外在更新 litellm 版本时也要谨慎。这个项目迭代速度很快配置字段有能力变动。我会先在一个测试环境升级并验证核心功能确认没破坏现有模型路由和成本统计后再灰度替换生产环境。别小看这个习惯我遇到过两次小版本升级后日志字段格式变化导致监控断掉的情况提前在测试环境跑一遍能省下不少排查时间。litellm 这类工具最好的用法是先把它当成一个“统一出网口”用起来再根据实际痛点逐步解锁限流、预算、健康检查这些高级能力。一开始就堆太多配置反而容易让整个链路变得难以排查。从最小配置起步让业务方先看到模型调用变简单后续再补齐治理能力这个节奏我个人觉得最舒服。