★ FEATURED ARTICLE 直接可发布的 Markdown 正文如下1. 为什么我会盯上 litellm一个LLM网关的真实需求先说实话我第一次接触 litellm 的时候心里想的是“这年头怎么什么都要搞个网关”Redis 有网关数据库有网关现在连大模型接口也要套一层代理。但等我真正在一个多模型项目里被 API 格式折腾到崩溃之后我才理解 litellm 解决的问题有多实际——它不是一个“为了架构而架构”的中间层而是一个把大模型调用这件事真正工程化的底座。先说背景。现在的 LLM 生态早就不是“一家独大”了OpenAI 系的、Anthropic 系的、Google 系的还有各种开源模型私有化部署。每家模型服务商都有自己的请求格式、鉴权方式、计费口径和限流策略。你在 A 厂商那里写好的 prompt 模板换到 B 厂商就要重写请求体今天用的模型涨价了你想换一个更便宜的又得改代码团队里五个人各自申请了五把 API key月底对账的时候根本不知道谁花了多少钱。这些痛点我全踩过而且踩得很疼。litellm 的核心思路其实特别朴素把“各家模型的差异”全部收敛到一个统一入口后面对外只暴露一套 OpenAI 兼容的 API。你只需要记一种格式、用一个 key、走一个地址剩下的模型调度、密钥管理、预算控制、日志审计全都交给网关处理。更重要的是它是开源的能自托管这意味着你的模型调用流量不用经过任何第三方中转数据链路完全可控。这篇文章我会从实际使用者的角度把 litellm 怎么装、怎么配、怎么用以及我在生产环境里踩过的坑和做过的取舍一次性讲清楚。适合谁看呢如果你正在做多模型接入、需要给团队统一管理 API key、想把模型调用成本管起来或者准备做一套包含多家模型的中台服务这篇内容基本就是为你准备的。就算你只是自己写点小工具不想每次换模型都改代码litellm 也能帮你省掉大量重复劳动。2. litellm 核心能力拆解它到底替你扛了多少事litellm 这个项目表面上看是个“API 转换层”但实际能力远不止转换格式那么简单。我把它拆成四层来讲这四层基本覆盖了我在实际项目里用到和测试过的全部核心功能。2.1 统一 API 格式用 OpenAI 语法调所有模型这是 litellm 最基础也最核心的能力。它内部维护了一个映射层把各家模型服务商的请求格式、响应格式、错误码、流式协议统一转换成 OpenAI 兼容格式。你在代码里只需要用 OpenAI SDK把 base_url 指向 litellm 服务就能用同一套代码调 GPT、Claude、Gemini以及各种开源模型的托管服务。这个能力的价值在于“降低切换成本”。我做过一个内容生成服务一开始用的 A 厂商模型后来因为成本问题想换 B 厂商模型最初的做法是要把请求构造、流式解析、错误重试、token 统计全部改一遍。接入 litellm 之后切换模型只是改一行配置的事情代码一行都不用动。2.2 多模型路由与负载均衡一个入口多路分发litellm 支持把同一个“逻辑模型名”绑定到多个实际的模型端点然后按策略分发请求。它有几种路由策略简单的轮询round-robin把请求均摊到所有后端基于权重的随机分发适用于后端性能差异大的场景基于优先级的方式在可用序列中选择最合适的端点结合健康检查与失败重试的自动故障转移这一点对于做高可用非常关键。比如你有两个模型服务商都提供同类能力平时负载均衡分摊流量其中一家挂了litellm 会自动把流量切到另一家。对上层应用来说它感知不到后端故障只会在极端情况下看到个别请求变慢或超时。2.3 Key 管理、预算控制与安全边界这个部分是我认为 litellm 最被低估的价值之一。它提供了一套完整的虚拟 key 管理机制你可以创建多个“子 key”每个 key 绑定不同的模型访问范围、速率限制、预算上限。团队里每个人、每个项目、甚至每类任务都可以使用独立的 key月底看报表就知道谁消耗了多少 token哪个项目成本异常。预算控制上litellm 同时支持请求级限流和金额级预算。你可以给某个 key 设置“每秒钟最多 10 次请求”也可以设置“这个月累计消费不能超过 1000 元”。一旦达到上限网关直接拒绝后续请求不会出现那种“月底看到账单直接血压拉满”的情况。安全方面litellm 还支持给后端模型 key 做加密存储避免真实密钥直接暴露给业务方——所有人拿到的都是虚拟 key真实的模型服务商密钥只保存在网关服务端。2.4 日志、审计与可观测性一次模型调用涉及的链路不算短请求进来、做格式转换、转发给后端、流式接收、token 统计、成本计算、返给上游。litellm 天然就能把这一整条链路的日志沉淀下来。它支持把调用日志写进 Postgres、MySQL 等数据库也可以对接 Prometheus 做指标监控。我实际最常用的一个功能是“按用户/按 key 查看调用历史”。出了线上问题比如某个用户反馈响应很慢我可以直接查这个用户对应的虚拟 key 有哪些调用、走了哪个模型、耗时多少、token 花了多少问题定位效率比从前高了一个量级。3. 实操从零装好 litellm跑通第一个代理前面讲了一堆概念下面进入真正动手的部分。这一节我会带着你从安装开始一步一步把 litellm 跑起来并用 OpenAI SDK 完成一次实际调用。所有步骤都是我在真实环境里验证过的。3.1 环境准备与安装litellm 本身是 Python 项目安装方式很简单但有一个细节需要留意安装选项决定你拿到的是“客户端库”还是“代理服务”。# 只安装客户端库用来在代码里直接调用 litellm 的 Python API pip install litellm # 安装完整的代理服务包含 FastAPI 网关、管理端、数据库支持 pip install litellm[proxy]如果你只是想在自己脚本里用 Python 调各家模型装第一个就够了。但如果你想要网关能力——统一 API 入口、虚拟 key、预算管理、日志——必须装带 proxy 选项的版本。我的建议是直接用虚拟环境装避免污染全局 Python 环境。实测下来 Python 3.10-3.12 版本都没问题Python 3.8 相关依赖可能会有兼容问题建议至少用 3.10 起步。提示安装阶段最常遇到的坑是依赖冲突尤其是 pydantic 版本冲突。litellm 代理服务对 pydantic v2 支持得比较好如果有旧项目占用了环境建议用独立虚拟环境隔离。3.2 写第一个 config.yamllitellm 代理服务的配置集中在 YAML 文件里。下面是一份最基础的配置作用是把两类不同厂商的模型统一暴露出来。model_list: - model_name: gpt-4o-mini-proxy litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: claude-proxy litellm_params: model: anthropic/claude-sonnet-4 api_key: os.environ/ANTHROPIC_API_KEY先解释一下这个配置里的两个关键字段model_name你对外暴露的逻辑模型名业务代码里请求这个名字就行model实际的后端模型标识格式是“厂商前缀/模型名”这里的厂商前缀很重要。litellm 内部通过前缀识别走哪套 SDK 和协议openai/开头的走 OpenAI 兼容协议anthropic/开头的走 Anthropic 协议gemini/开头走 Google 协议。还有一种情况如果你的模型走的是 OpenAI 兼容的第三方端点比如某些国产模型可以用openai/模型名加api_base参数指定端点地址。model_list: - model_name: custom-via-openai-format litellm_params: model: openai/custom-chat-model api_base: https://custom-endpoint.example.com/v1 api_key: os.environ/CUSTOM_API_KEY环境变量在配置里用os.environ/变量名引用这样密钥不会写死在配置文件里。第一次启动前记得先设置好环境变量。export OPENAI_API_KEY你真实的密钥 export ANTHROPIC_API_KEY你真实的密钥3.3 启动代理并完成第一次调用配置文件准备好之后一条命令就能启动litellm --config config.yaml --port 4000启动成功后litellm 会在 4000 端口监听打印出一串管理路由比如/health健康检查、/model/info模型列表、/key/generate生成虚拟 key 等。接下来用一个最简单的 Python 脚本验证链路是否通。注意这里用的就是标准的 OpenAI SDK唯一变化是把 base_url 指向本地 litellm 服务。from openai import OpenAI client OpenAI( api_keysk-any-string, base_urlhttp://localhost:4000/v1 ) resp client.chat.completions.create( modelgpt-4o-mini-proxy, messages[{role: user, content: 你好请用一句话介绍你自己}] ) print(resp.choices[0].message.content)这里有个容易让人困惑的点为什么api_key随便填一个字符串也能通过因为 litellm 启动时如果没开启虚拟 key 校验网关不会严格验证客户端传来的 key。但当你开启 master key 或虚拟 key 功能之后这里的 key 就必须换成真实的虚拟 key 了。这个后面会讲到。跑通这一步你就已经拥有一个最简 LLM 网关能力了。任何支持 OpenAI 协议的工具——包括各类框架、IDE 插件、自动化脚本——都能通过这个网关统一访问多个模型。4. 深入实战预算控制、模型路由与团队管理怎么落地基础链路通了之后litellm 真正的价值开始浮现。这一节我会讲三个我实际使用频率最高的能力并且给出可以直接抄作业的配置。4.1 给虚拟 key 设置预算和限流先说说虚拟 key 这个机制。litellm 的 master key 相当于管理员的“总钥匙”虚拟 key 是从 master key 派生出来的子 key。创建虚拟 key 的时候可以绑定一堆限制条件。生成方式有两种一种是通过管理 API另一种是直接调用管理接口。我习惯用 curl 快速创建curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer 你的master_key \ -H Content-Type: application/json \ -d { models: [gpt-4o-mini-proxy], max_budget: 50, budget_duration: 30d, max_parallel_requests: 5, tpm_limit: 100000, rpm_limit: 60 }这里每个参数的含义和为什么要这么设置max_budget: 50这个 key 在 30 天内最多消费 50 元防止团队里某个成员一次性把预算烧光budget_duration: “30d”是预算周期配合上面的字段相当于一个月的额度max_parallel_requests: 5限制同一时刻最多 5 个并发请求tpm_limit: 100000每分钟最多消耗 10 万 token保护后端模型不被突发流量打爆rpm_limit: 60每分钟最多 60 次请求返回结果里会有一个新的 key 字符串把这个 key 分发给对应的同学或服务使用即可。实际跑业务时litellm 会实时统计这个 key 的消耗不管是 token 数还是估算金额接近上限时就会在日志里给出告警达到上限后直接返回 429 拒绝请求。这个能力在“多项目共享网关”的场景下非常香。我手上有三个业务线共用一个 litellm 网关每条业务线一个虚拟 key各自限额互相隔离。以前那种“一到月底每个项目都说是别人把预算用完了”的扯皮事再也没有发生过。4.2 模型路由故障转移与自定义权重litellm 的模型路由配置集中在router_settings里。下面这个配置是我实际用过的方案目标是把流量尽量分发到成本低的模型上同时保证高可用。model_list: - model_name: chat-main litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY weight: 7 - model_name: chat-main litellm_params: model: anthropic/claude-sonnet-4 api_key: os.environ/ANTHROPIC_API_KEY weight: 3 - model_name: chat-main litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY weight: 1 router_settings: routing_strategy: usage-based-routing model_group_alias: chat-main: chat-main这个配置里有几个点值得展开同名的model_name表示这些模型属于同一个模型组。请求进来时litellm 会从这三条后端里选择一条转发。weight是权重字段在简单策略下表示分发比例在usage-based-routing策略下litellm 会结合当前各后端的负载情况优先选便宜且可用的模型。我之所以保留一个昂贵的gpt-4o但只给权重 1是为了让它在前面两个模型都故障时兜底。实际测试过模拟故障场景关闭 OpenAl key 对应的服务后litellm 会把流量全切到 Anthropic 系模型业务方无感知只有监控上能看到后端的切换。路由策略的选择直接决定网关的表现。如果后端模型能力差异不大且价格相近最简单的轮询就够如果有明确的成本偏好建议用基于用量的策略让网关自动偏向便宜模型。注意故障转移不是零延迟的。当后端服务异常时litellm 需要一次失败探测才能感知故障因此个别请求会出现短暂超时。我实测在超时重试配置合理的情况下对用户体验的影响可以控制在可接受范围内。4.3 管理多用户防止互相越权团队人数一多虚拟 key 的管理就不能靠手动发 key 了。litellm 支持为每个用户或每个业务方创建独立 key 并绑定模型范围。curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer 你的master_key \ -H Content-Type: application/json \ -d { user: team-a, models: [chat-main], max_budget: 200, budget_duration: 30d }我比较推荐的一个做法是“按团队建 key、按服务建子 key”。比如 A 团队一个总 key月预算 200 元关键服务单独建 key限额更高方便追踪每一条服务的真实消耗。配置完成后通过/key/info接口可以查看任意 key 的实时消耗curl http://localhost:4000/key/info \ -H Authorization: Bearer 你的master_key返回结果里包含这个 key 的已用 token 数、预算剩余、最近请求时间、历史调用次数。这个接口对于排查成本异常特别有用。5. 企业部署把 litellm 放到生产环境要处理的事单机跑通 litellm 只是第一步。真正放到生产环境需要考虑数据持久化、性能、安全、部署形态这些实际工程问题。这节内容全部来自我的实际部署经验。5.1 数据库选型和数据持久化litellm 默认把日志和 key 信息存在内存里服务一重启数据就没了。生产环境必须配置数据库。官方支持 Postgres 和 MySQL我强烈建议直接用 Postgres原因有三事务和并发性能更好litellm 的 key 更新操作比较频繁原生支持 JSON 类型方便存复杂配置生态工具丰富后续对接分析系统更顺配置方式是在启动命令里指定数据库连接串litellm --config config.yaml --port 4000 \ --database_url postgresql://user:passwordlocalhost:5432/litellm_db配好数据库之后虚拟 key、预算记录、调用日志都会落盘持久化。注意一点一旦启用数据库所有历史 key 的策略会自动从库中恢复迁移环境时只需要把数据库迁走不需要重新创建 key。5.2 生产环境的部署形态容器化与反向代理我目前的标准部署方式是 Docker 容器 反向代理。litellm 官方提供了镜像但依赖版本更新频繁我更推荐自己基于官方源码构建容器锁定依赖版本。FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir litellm[proxy]具体版本号 COPY config.yaml . COPY entrypoint.sh . EXPOSE 4000 CMD [litellm, --config, config.yaml, --port, 4000]反向代理这层可以直接用你熟悉的工具只需把/v1前缀的请求转发到 litellm 的 4000 端口。我选择在前面加反向代理的原因主要有两个一个是复用已有的 TLS 证书体系另一个是可以统一做 IP 白名单。一个看似细节但实际很重要的点litellm 的健康检查路径是/health反向代理一定要把这个路径放行并且建议配置成定时探测。这样网关挂掉时负载均衡器能及时把流量摘除。5.3 并发与性能调优参数怎么设litellm 默认配置在低并发下够用但生产流量上来之后需要调几个关键参数。我在压测环境中发现最重要的参数是线程池大小。litellm 底层是同步请求转发高并发场景下默认线程池容易被阻塞。启动时可以加这个参数litellm --config config.yaml --port 4000 \ --num_workers 4 \ --database_url postgresql://...num_workers控制进程数。每个 worker 是独立的进程能利用多核 CPU。我实测 8 核机器配置 4 个 worker吞吐量比单进程提升了差不多 3 倍。与此同时虚拟 key 的rpm_limit和tpm_limit不只是限制客户端也是保护网关本身的手段。假设网关后端模型每秒只能处理 10 个请求某个业务方把并发拉到 100后端可能直接崩溃。通过对 key 设置并发上限可以把风险前置挡住。性能调优需要结合实际请求大小来定没有一个万能参数。我的经验法是先按默认配置上线然后逐步压测观察 CPU、内存、数据库连接数三个指标再决定要不要加 worker、要不要调大连接池。5.4 高可用设计我踩过的一个真实教训第一次做高可用部署时我以为启动两个 litellm 实例指向同一个数据库就完事了。后来发现过于理想化litellm 的一些内部状态比如限流计数、预算扣减依赖内存态多实例部署时会出现统计偏差。真实的解决方案是给 litellm 加一层 Redis 做分布式状态同步。配置方式是在启动参数里加入 Redis 连接信息让多个 litellm 实例共享限流计数和预算扣减状态。litellm --config config.yaml --port 4000 \ --database_url postgresql://... \ --redis_host localhost \ --redis_port 6379配置完 Redis 后我的生产部署变成了“两台 litellm 实例 同一套 Postgres 同一套 Redis”前面再用负载均衡分发流量。实测故障切换时客户端只感受到极短暂的连接重置重试即可恢复。6. 常见问题与排查实录litellm 用久了一些典型问题基本都会遇到。我整理了一份排查速查表附带我在实际排障中积累的心得。现象可能原因排查思路与解法启动时提示依赖冲突pydantic 或 FastAPI 版本不兼容独立虚拟环境安装锁定版本号调用时报模型不存在请求的模型名跟 config 里的model_name不一致查看/model/info接口核对逻辑模型名虚拟 key 突然返回 429预算超限、并发超限或速率超限查/key/info看哪个字段触顶按需调大同一模型组流量不均权重配置或路由策略导致检查weight字段和routing_strategy设置流式请求中途断开后端模型流式响应超时调大网关的 timeout 配置检查客户端是否设置了过短的读超时请求偶尔变慢故障转移探测机制触发检查后端模型健康状态确认路由策略中的重试次数预算统计和实际消耗对不上多实例部署但没配 Redis给所有实例统一配置同一个 Redis6.1 我在实际踩坑中总结的三个提醒先说第一个坑配置文件里的model_name和实际模型标识model一定要分清。我在一次上线前把两者写反了结果业务请求全部打到默认模型上走了两天的流量才发现。建议上线前先跑一次/model/info确认映射关系。第二个坑是流式输出的超时设置。litellm 默认超时时间是 600 秒但流式场景下有“首包延迟”这个隐藏逻辑。有些客户端在等待第一个 token 时设置了很短的超时比如 10 秒后端模型响应稍慢就直接断连。我在生产环境把客户端的读超时设置成 60 秒以上同时又限制了tpm_limit才稳定下来。第三个坑是日志量。没做日志采样时生产环境的调用日志增长速度远超想象Postgres 单表很快就有几百万行。我现在按天分区清理只保留 30 天热数据和 90 天归档数据。如果你有合规要求提前设计好日志分层存储方案别等出问题再补。6.2 从日志里快速定位问题litellm 的日志字段非常详细建议重点关注这几个model实际使用的后端模型requested_model客户端请求的逻辑模型名user虚拟 key 对应的用户标识spend单次调用的估算成本response_time后端响应耗时status调用成功或失败的状态码我遇到线上反馈“某个用户响应特别慢”时直接按 user 字段过滤出该用户最近 30 分钟的请求一眼就能看出是网关转发慢还是后端模型慢。这个定位速度在没有网关之前是不可想象的。7. 一点个人体会litellm 在我这边已经稳定跑了接近一年从最初的单机试用到现在支撑多条业务线、日均几万次模型调用它可以说是把大模型接入这件事彻底从“写代码适配”变成了“配置化运维”。它不复杂核心思路足够朴素但正是这种朴素让它成为 LLM 工程化里很难绕开的一块基石。如果你正准备接多个模型或者已经在被各家 API 差异折磨我的建议很简单别急着写抽象层先用 litellm 跑通一条链路把虚拟 key、预算、日志这三个能力用起来。等流量大了、团队人多了再一步步往上加路由策略和高可用配置。这条路我替你试过走得很顺。
阅读完成 · 觉得有帮助？
