做 AI 应用开发的大概率遇到过这种场景项目的模型接口刚调通业务方又说要换一家模型服务商或者同一套逻辑今天要跑在 A 平台的模型上明天又要切到 B 平台的模型上每次切换都像重写一遍适配层。我折腾过好几轮这种事儿最直接的感受是接口差异本身不难处理难的是当你同时维护一大撮供应商、模型版本、鉴权方式、计费口径时项目的工程复杂度会肉眼可见地上涨。litellm 就是在这个背景下被我正式引入项目的——它是一个开源的统一 API 网关能把多家模型服务商的接口收敛到一个 endpoint 后面对外只暴露一套标准调用格式工程侧不用再为每个平台各写一套适配代码。下面这篇文章会把我在实际项目里从零到一使用 litellm 的完整过程、配置思路、生产环境落地经验和踩坑记录都翻出来适合正在做模型层统一治理、或者被多模型接口搞到头大的开发同学参考。1. 它到底解决了什么问题用统一接口管理所有模型接入1.1 多供应商接入的真实痛点我先不铺概念直接说从项目里带出来的实际体验。一旦业务同时对接了多家服务商下面这几件事就会反复出现在日常开发里接口协议不一样。有的服务商提供 SDK有的只支持裸 HTTP有的在请求体里还要带专属字段比如某种组织标识或部署名称。鉴权方式差异大。有的是静态密钥有的是临时令牌有的是通过环境变量注入的默认凭证还有的需要在每次请求前先单独换取访问令牌。模型命名不统一。同一个逻辑能力水平的模型在不同平台上的调用名可能完全不同甚至同一家平台的不同区域、不同部署下也要用不同的字符串去指定。返回结构有差异。看似都是“对话补全”有的把内容字段叫 message有的叫 output有的还嵌套在 choices 里解析代码被迫跟着平台走。切换成本极高。业务方想从当前模型平滑迁移到另一家理论上只换一个模型名实际上牵扯到所有调用方的鉴权、超时、错误处理、重试策略全都要跟着改。这些问题单独拎出来都不是大事但叠在一起就变成了一个每天都在消耗开发精力的隐形税。1.2 统一接口带来的直接收益litellm 的做法是把自己放在客户端和各个模型服务商中间你的业务代码永远只跟 litellm 通信litellm 再负责把标准请求翻译成各家能听懂的形式。带来的收益很直接只维护一套调用协议。业务侧写一次请求格式新增供应商时业务代码零改动。模型切换变成配置操作。今天用 A 平台的模型明天换 B 平台的同类模型在配置文件里改几行就行不需要发版。故障转移和负载均衡可以统一做。某家供应商抖动、限流、宕机请求可以自动打到备用供应商上不用自己在每个客户端里写重试逻辑。成本数据集中化。所有请求的 token 用量统一埋在网关这一层统计、预算、账单对账都简单很多。1.3 哪些项目值得上以我的经验下面几类场景引入 litellm 收益最明显项目里同时使用两家以上模型服务商需要频繁做模型对比测试或者业务策略上要支持模型快速切换有多个后端服务都要调模型接口想把鉴权和成本数据收口到一处已经在用本地推理模型又有业务流量要打到云上模型想统一一个入口。如果项目只有一个模型供应商、调用量也小那直接写个函数包一层就够没必要上网关。这个判断很重要工具不是越重越好。1.4 一个关键提醒litellm 解决的是工程层问题不解决业务层问题。它不会让模型输出质量变好也不会替你选择哪家平台更划算它只负责让你的代码不被供应商绑定、让你能把模型接入这件事管理起来。先明确这个定位后面配置时就不会对它产生不切实际的期待。2. 核心概念与基础搭建先跑通第一个请求2.1 安装与运行模式litellm 有两种最常见的用法一种是纯 Python 库直接在现有代码里调用另一种是独立代理服务部署后让所有客户端走 HTTP 接口。我更推荐后一种作为项目主体因为代理模式能让多个服务共享一套接入配置成本统计也天然集中在服务端。安装很简单pip install litellm[proxy]装完之后启动一个最简代理litellm --model gpt-4o-mini如果你的模型服务商是标准 OpenAI 兼容协议这种一行命令模式就能跑。但实际项目里我更推荐用配置文件来管理因为一旦供应商变多命令行的参数会膨胀到没法维护。2.2 环境变量与模型映射先看一个最基础的配置。假设项目里同时接入了 A 平台和 B 平台我把两个平台的密钥放在环境变量里不写进配置文件避免密钥泄露进代码仓库export A_PLATFORM_API_KEYsk-xxx export B_PLATFORM_API_KEYsk-yyy然后写一个基础的 config.yamlmodel_list: - model_name: my-english-model litellm_params: model: platform-a/text-model-x api_key: os.environ/A_PLATFORM_API_KEY - model_name: my-local-model litellm_params: model: local_provider/local-model-name api_base: http://127.0.0.1:11434配置里有一层很关键的设计model_name是对外暴露的名字litellm_params.model是真实的供应商模型标识。业务代码永远只认识my-english-model底层是否换供应商、换模型版本业务无感知。这里我还踩过一个坑yaml 里引用环境变量并不是任意格式都行要严格按照os.environ/变量名这种写法写错了代理启动时不会报错但真正调用时会一直提示缺少密钥。建议配置完先检查环境变量名拼写别在细节上浪费时间。2.3 启动代理服务配置文件就绪后启动代理litellm --config config.yaml --port 4000看到日志里出现“Uvicorn running on http://0.0.0.0:4000”这样的字样说明代理已经正常起来了。默认端口是 4000之所以不是常见的 8000主要是为了避免和业务服务端口冲突这个细节可以记一下。2.4 用 curl 验证代理是否可用代理起来后我习惯先用 curl 做一次最小验证确认链路通不通curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: my-english-model, messages: [{role: user, content: 说一句简短的新年祝福}] }注意请求体里的model字段值就是我自定义的my-english-model而不是真实的供应商模型名。这一点体现的就是统一入口的价值客户端不需要知道自己真的在调用哪家服务商的哪个模型。返回结果里重点看model字段litellm 会在响应里标注实际命中的模型名称方便确认路由是否生效。第一次跑通时我建议把返回体完整打印出来核对choices、usage这些字段的结构跟直接调供应商 SDK 时有些差异别想当然。3. 生产级配置与路由策略从 demo 到可用3.1 model_list 的完整结构一个只包含单个模型的基础配置只能算 demo真正要落地到生产第一个要扩展的是model_list。以我目前正在用的配置为例model_list: - model_name: chat-model litellm_params: model: provider-a/chat-model-2 api_key: os.environ/PROVIDER_A_API_KEY max_tokens: 4096 temperature: 0.7 model_info: cost_per_million_tokens: 0.5 - model_name: embedding-model litellm_params: model: provider-b/embedding-model-1 api_key: os.environ/PROVIDER_B_API_KEYmodel_info是很有用的元数据区可以放自定义标签、成本信息、描述信息。成本信息后面做预算统计时会用到建议从接模型的第一天就顺手写好。3.2 模型路由与负载均衡同一逻辑能力水平的模型如果有多个可用的供应商版本litellm 可以做路由策略。比如我希望所有对话请求在两家供应商之间轮询model_list: - model_name: chat-model litellm_params: model: provider-a/chat-model-2 api_key: os.environ/PROVIDER_A_API_KEY - model_name: chat-model litellm_params: model: provider-b/chat-model-3 api_key: os.environ/PROVIDER_B_API_KEY两个条目共用同一个model_namelitellm 会自动维护一个模型池默认按轮询方式分发。我实际压测下来轮询策略对多实例部署特别友好不会出现某个供应商被集中在同一段时间打满的情况。如果需要更精细的路由比如某个团队固定走 A 平台、其他团队走 B 平台litellm 还支持基于请求元数据的策略路由。这块需要在请求头带上自定义信息然后配置路由规则我会在后面的“进阶技巧”里单独说这里先记住有这种能力即可。3.3 故障转移与重试策略生产环境最怕的就是供应商半夜挂掉业务跟着一起挂。litellm 里做故障转移的逻辑很直观把备用模型当作同一model_name的另一个条目再配合重试配置。router_settings: retry_policy: TimeoutError: retries: 2 RateLimitError: retries: 1 fallbacks: chat-model: - chat-model-backup这段配置的意思是如果主模型请求超时自动重试最多两次如果遇到限流错误重试一次如果主模型彻底不可用就把请求降级到chat-model-backup。我在实际项目中让主模型走云上某平台备用模型指向本地推理服务线上多次验证有效主服务抖动时业务侧几乎无感知。但要注意重试不是越多越好。盲目上调重试次数在供应商已经限流时只会加重对方压力最后变成连锁超时。我建议超时类错误最多重试两次限流类错误最多重试一次然后直接降级。3.4 速率限制与预算控制接入网关后所有请求都过这一层限流和预算自然也能在网关层统一做。litellm 支持配置 RPM每分钟请求数、TPM每分钟 token 数也可以按用户或团队维度设置额度上限。一个参考配置router_settings: rpm_limit: 100 tpm_limit: 100000这个数值要结合你们实际调用来定。我习惯先看各供应商控制台上的配额再取一个保守值比如供应商限额是 1000 RPM我就先在网关设 700留出缓冲。等业务稳定后再逐步上调这种方式比一开始就顶着配额上限跑稳得多。预算控制方面litellm 支持按请求、按天、按月统计成本超过阈值后可以直接拒绝请求。关键是把model_info里的cost_per_million_tokens写准确这个数字写错了后面所有成本统计都会失真。3.5 部署为独立服务代理本身是一个无状态服务部署时我建议单独开进程不要跟业务服务混在一起。原因很简单litellm 内存和 CPU 占用虽然不大但它有独立的路由、日志、重试逻辑跟业务进程混跑会互相干扰。我在项目里用的是最简单的 systemd 管理方式[Unit] DescriptionLiteLLM Proxy Afternetwork.target [Service] Userwww-data WorkingDirectory/opt/litellm EnvironmentFile/etc/litellm/env ExecStart/usr/local/bin/litellm --config /etc/litellm/config.yaml --port 4000 Restartalways RestartSec5 [Install] WantedBymulti-user.target启动后可以用curl http://localhost:4000/health/liveliness来确认健康状态。这里的重点是EnvironmentFile里放密钥配置文件里只写os.environ/xxx引用尽量避免把真实密钥写进 yaml。4. 如何做成本统计与用量追踪4.1 开启内置日志与数据库记录litellm 默认也会在内存里保留一些请求记录但服务一重启就没了。要做成本分析我建议接一个持久化存储最省事的是 SQLitelitellm --config config.yaml --port 4000 --database_url sqlite:///litellm.db请求进来后litellm 会把每次调用的模型、提供方、token 用量、耗时、成本估算都写入这个库。我的习惯是每周跑一条聚合查询把各供应商的调用量拉出来对比能帮助及时调整路由权重。4.2 从返回头里核对现场数据除了查数据库每次响应也可以直接返回用量信息。litellm 会在响应头里追加一组字段比如x-litellm-model-id: chat-model x-litellm-model-name: provider-a/chat-model-2 x-litellm-total-tokens: 128这个功能在排查线上问题时非常有用。我之前遇到过一次模型输出异常就是通过响应头里的 model id 发现请求被路由到了备用模型上而备用模型的能力略弱所以输出质量才下滑。如果只靠逻辑推断这个问题很难定位。4.3 按项目与团队拆分用量多团队共用同一个代理时成本归属是绕不开的话题。litellm 支持在请求头里携带自定义元数据例如curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H x-litellm-metadata: {\team\: \risk-control\, \project\: \anti-fraud\} \ -d { model: chat-model, messages: [{role: user, content: 分析这条交易是否存在异常}] }定义好团队和项目标识后后续查询用量时就可以按这两个维度分组。这在多团队协作场景下几乎是刚需财务对账也轻松很多。5. 进阶技巧自定义路由、本地模型接入与可观测性5.1 按团队路由到不同供应商前面提到可以基于请求元数据做路由这里给出一个我实际用过的简化配置思路router_settings: routing_strategy: simple-shuffle rules: - name: risk-team-route team: risk-control model: chat-model-risk当请求头里携带团队标识为risk-control时请求会被路由到chat-model-risk。这个配置的价值在于不同业务线对模型的要求不同有些业务要求响应快有些业务要求结果稳通过网关统一分流后业务端不用关心具体策略。5.2 本地模型的接入注意点litellm 对接本地推理框架时通常只需要指定api_base。但有几个细节我建议特别注意本地模型服务的并发能力通常远低于云上服务网关层一定要做并发限制否则本地服务会被瞬间打满。本地模型的 token 统计往往偏低甚至不准确成本统计在本地模型上只能作为参考。本地服务进程本身要加守护别让它意外退出。我之前的经验是把本地模型当作全局降级池而不是主路由。这样既能降低成本又不至于因为本地模型不稳定拖垮主链路。5.3 把请求日志送到可观测平台当代理数量不止一个实例时litellm 自带的 SQLite 就不够了。我通常会再加一层日志导出把请求日志送入集中式可观测平台。litellm 支持回调机制可以在请求完成后把日志、token 用量、延迟指标推给外部系统。回调配置示例litellm_settings: success_callback: [langfuse]用集中式平台的核心价值在于多个实例的日志汇聚后可以做全链路搜索。业务侧报“回答慢了”我可以直接看这个请求从进入代理到返回完整结果花了多久再对比供应商侧的平均延迟定位出网络问题还是供应商问题。5.4 多实例部署时的数据一致性如果 litellm 部署多个实例做水平扩展我建议两个配置必须统一一是模型列表配置二是数据库连接地址。配置不统一会出现 A 实例能路由的模型B 实例返回 404数据库不统一则会导致成本数据分散到不同库里统计时对不上账。6. 常见问题与排查技巧实录6.1 代理返回 404先查模型名最常遇到的问题是代理启动后调用某个模型总是返回 404。我的排查顺序是先确认请求体里的model字段是否在model_list中定义过再看实际条目的litellm_params.model写没写对。很多 404 根本不是路由问题而是供应商那边根本没有这个模型标识。特别是同一系列模型在不同区域会有不同的部署名复制粘贴时很容易带错。6.2 一直转圈或超时优先查 api_base请求发出去之后一直不返回最后超时十有八九是litellm_params.api_base写错了。有些时候是少了协议头比如http://没写有些时候是填了 https 但目标服务其实只支持 http。我的建议是先用 curl 单独访问 api_base 确认目标服务可用再来查 litellm 配置。6.3 成本统计少了或多了这个问题的根源基本都在model_info.cost_per_million_tokens。litellm 本身不知道你实际和供应商签的协议价格它只能按配置文件里的单价估算。如果发现统计数字和账单对不上先从单价配置开始核。另外要注意不同供应商计费单位不一样有的按百万 token 计价有的按千 token 计价统一换算后再填进配置。6.4 多个实例下配置不生效修改 config.yaml 后只有部分实例生效大概率是某些实例没有重新读取配置。litellm 支持配置热加载但生产环境我更推荐用带版本管理的配置文件发布流程改配置走一次标准的发布验证流程比在每台机器上手动改安全得多。6.5 一个稳定性的误判陷阱我见过有人把重试次数调得很高然后测试故障转移时发现请求变得特别慢误以为 litellm 有问题。实际上这是所有重试机制的通病重试本身会让用户在错误中停留更久。所以我在配置重试时一定会同时调低超时时间。比如默认 60 秒超时我就改成 20 秒配合 2 次重试即便全部失败最多等 60 秒而不是干等 3 分钟。最后再分享一个小技巧也是我目前一直在用的每次新接入一家供应商时不要急着把它写进主配置先单独建一个测试配置文件手工触发几个不同类型的请求确认返回正常之后再合并进主配置。这样做虽然多花几分钟但能避免把不成熟的配置直接暴露给业务流量。litellm 最让我满意的点就是这种“逐步验证、随时切换”的掌控感——模型接入这件事反复折腾几次之后你会越来越依赖这种统一出口的管理方式。
