做 AI 应用开发这两年我最大的体会是模型能力很重要但把各家模型接入工程化才是真正拉开开发效率差距的地方。LiteLLM 这个开源项目解决的就是“怎么用一套接口同时接 OpenAI、Anthropic、Gemini 等主流模型”的问题。它既是一个 Python SDK也能以代理网关的方式运行让团队里所有业务服务像调一个本地服务一样调用不同大模型。这篇文章不吹概念直接讲 LiteLLM 怎么用、配置怎么写、生产环境怎么落地以及我踩过的坑。1. 为什么需要 LiteLLM多模型接入带来的真实痛点1.1 多个模型服务商多套 SDK调用逻辑东拼西凑先还原一个非常常见的场景项目最开始只接了一家模型服务代码里就是简单地调一下官方 SDK比如 OpenAI 的接口。后来发现某些任务换成别的模型效果更好或者为了成本考虑想把部分流量切给更便宜的模型。这时候问题就来了——第二家模型的 SDK 有自己的请求格式、超时配置、错误码设计第三家的鉴权方式又不一样。没有一个统一的东西兜底业务代码里就会出现一堆if provider anthropic之类的分支判断。而且每家的细节差异非常磨人。比如消息格式上A 家用systemmessagesB 家也差不多但参数名不同流式输出的数据样式不同用量统计的字段名也不同。只要接的模型超过两家光维护这套“翻译层”就要耗费大量精力。LiteLLM 的核心思路就是把这部分差异收敛到它的 SDK 内部对外统一暴露 OpenAI 风格的接口。也就是说你的业务代码永远只需要跟一种格式打交道后面换模型、加模型都发生在 LiteLLM 这一层。1.2 团队协作与企业级需求Key 管理、预算、日志谁来管个人开发阶段模型密钥写在环境变量里脚本里直接调用问题不大。但一旦进入团队协作痛点会立刻暴露几个人共用一个模型密钥根本不知道谁调了多少某个功能模块把上下文设得很大月底账单超支了一截却说不清是哪条链路烧的。这些不是模型能力本身的问题而是接入工程化没做好。LiteLLM 的代理模式就是冲着这个来的。它可以作为一层网关跑在服务端对外暴露标准的/chat/completions端点对内管理模型密钥、虚拟 Key、预算额度、请求日志。团队里的同事不需要接触上游模型密钥只需要拿一个前端伪造的虚拟 Key 来调用网关。谁消耗了多少、哪个模型花了多少钱都可以从日志和统计里查出来。对团队来说这比每人各存一把模型密钥安全得多也规范得多。1.3 方案选型对比自己封装 SDK 还是用网关我自己刚接触到这类工具时也犹豫过这层封装看起来不复杂自己写一个模块不行吗后来算了一下账还是决定用现成的。自己封装意味着要持续跟进各家模型的接口变化还要处理鉴权、错误映射、重试策略、成本统计这些工作量加起来非常可观。而且个人封装往往只覆盖自己正在用的那两三个模型等新业务要上一个新模型时又要改代码。如果你团队里有一套非常固定的模型调用方式并且产品形态很轻自己封装确实可行。但如果你需要灵活切换多个模型、有成本管控需求、还要有统一的日志和监控入口用 LiteLLM 这类网关工具会更合适。它本质上就是把你本来要手写的那层“多模型适配器”“流量治理设施”提前做好了而且还在持续迭代。对比维度自己封装调用层使用 LiteLLM新增模型成本需要写新适配代码配置一行 model 映射多 Key 负载均衡自己实现轮询和熔断内置路由和冷却逻辑预算管控一般没有支持预算上限和限额日志统计需要额外开发网关层自动记录维护成本持续跟进各模型变化跟随开源版本更新2. 30 分钟快速上手从安装到发出第一个请求2.1 安装与环境准备先说明一下依赖环境。LiteLLM 是 Python 项目建议 Python 版本在 3.9 以上。安装命令很简单pip install litellm[proxy]这里的[proxy]是带代理网关支持的安装方式如果你只打算在项目里当 SDK 用直接pip install litellm也行。我建议即使当前只需要 SDK也直接把 proxy 装上因为你很可能过两天就想上一套网关看看效果省得再折腾一次依赖。环境变量方面LiteLLM 沿用各家模型服务商的常用变量名。比如调用 OpenAI 系列模型就设置OPENAI_API_KEY调用 Anthropic 模型就设置ANTHROPIC_API_KEY。严格说不设置也可以在代码里直接传api_key参数但环境变量方式更安全也方便代理模式统一读取。export OPENAI_API_KEY你的密钥 export ANTHROPIC_API_KEY你的另一个密钥2.2 用 Python 直连完成首次调用安装好后先跑一个最简单的例子验证链路。LiteLLM 的 SDK 用法非常直接核心函数就是completionfrom litellm import completion messages [ {role: system, content: 你是一个简洁的助手}, {role: user, content: 用一句话介绍 LiteLLM} ] response completion( modelopenai/gpt-4o, messagesmessages, temperature0.7 ) print(response.choices[0].message.content)注意这里的model参数是带前缀的openai/gpt-4o表示调用 OpenAI 渠道的gpt-4o模型。同理anthropic/claude-3-5-sonnet表示调用 Anthropic 渠道的 Claude 模型gemini/gemini-1.5-pro表示调用 Gemini 渠道的模型。这个前缀规则是整个 LiteLLM 识别提供方的方式配置和调用时都靠它一定要理解。跑通这一步后你会发现后续换成别的模型代码结构基本不变只需要改model参数。业务代码里不再需要关心某个消息格式在别的服务商那里是不是叫prompt。2.3 用代理模式跑通 OpenAI SDKSDK 直连适合在计算脚本里用但如果你希望其他语言写的服务也能接入或者希望多团队共享一套接入层那就要启动代理模式。LiteLLM 启动后会默认在本地开一个 HTTP 服务端口通常用 4000对外提供与 OpenAI 兼容的接口。先用一份最简单的配置启动# config.yaml model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude-sonnet litellm_params: model: anthropic/claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY然后在终端启动litellm --config config.yaml --port 4000看到日志里出现Uvicorn running on http://0.0.0.0:4000代理就起来了。这时用 OpenAI 的 SDK 也能访问这个网关from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000, api_keyany-string ) response client.chat.completions.create( modelgpt-4o, messages[{role: user, content: 你好}] ) print(response.choices[0].message.content)注意我随便传了一个api_key字符串因为默认配置下网关没有开启 Key 校验。生产环境一定要开启 Key 管理后面会细说。用curl验证也是一样的curl http://localhost:4000/chat/completions \ -H Content-Type: application/json \ -d {model: gpt-4o, messages: [{role: user, content: 你好}]}3. 核心功能拆解路由、重试、负载均衡、预算一个不少3.1 模型路由与智能选择LiteLLM 真正的价值不在简单的转发而是内置了一个 Router 机制。你可以把多个模型提供商的后端配置好Router 会根据你的规则选择实际调用哪一个。用一个很实用的例子假设你同时有 OpenAI 和 Anthropic 两个渠道且都配置了同一个对外模型名gpt-4o客户端请求时只需要指定modelgpt-4oRouter 会按照model_list里配置的权重把流量分配到不同后端。这个能力在生产环境中非常有用比如想灰度测试某个新模型给新模型一个较小的权重让部分流量自然流过去观察效果不用改任何业务代码。权重分配在配置里的写法也很直白同一个model_name下配置两个litellm_params条目然后分别指定权重model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY weight: 0.7 - model_name: gpt-4o litellm_params: model: anthropic/claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY weight: 0.3这样一个model_name背后就走两个渠道六成流量给 OpenAI四成给 Anthropic。对调用方来说完全透明。我更看重的是这个机制在“容灾演练”时的价值——上游某家不稳定时直接把权重调向另一家或者把某个后端摘除整个过程不需要改代码。3.2 Fallback 与重试策略任何一个模型服务商都不可能永远稳定。限流、超时、5xx 错误总会有。LiteLLM 对这类问题提供了两层机制重试和 fallback。先说重试。Router 对象可以配置num_retries例如让请求在遇到 429、连接错误等情况时自动重试from litellm import Router router Router( model_list[...], num_retries3, timeout30 ) response router.completion( modelgpt-4o, messages[{role: user, content: 你好}] )这里有个我在实际使用中很在意的点重试次数不是越大越好。有些模型按调用计费网络传输阶段的重试可能产生重复请求而模型已经生成内容但响应断开时的重试容易造成重复扣费。所以我在大多数项目中会把num_retries设为 2 到 3同时把timeout设得合理一些比如 30 秒左右避免慢响应占用太多资源。Fallback 则更稳健。它允许你在主模型失败时自动切换到另一个可用模型。配置方式是在 Router 参数里指定 fallbacksrouter Router( model_list[...], fallbacks[ {gpt-4o: [claude-sonnet]} ] )意思是当gpt-4o这个模型的请求失败达到阈值时自动改用claude-sonnet处理同一个 prompt。这在关键业务上是保底手段宁可换一家模型应答也不要直接给用户返回报错。3.3 负载均衡同一模型挂多个 Key 的玩法如果你在某一家模型服务商那里有多把访问密钥可以把它们配置在同一模型下LiteLLM 会按顺序轮询。这个方案非常适合面对上游限流时扩容单把 Key 有每分钟请求数限制那就多挂几把 Key 分散压力。model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY_BACKUP从业务方视角看它们请求的都是同一个gpt-4o不存在感知差异。LiteLLM 在某个 Key 返回限流错误时会主动把这个 Key 冷却一段时间然后优先用其他 Key 继续服务。这个“自动冷却”非常省心我早期手动管理多把 Key 时最头疼的就是一把 Key 被限流后其他 Key 不知道去顶上导致业务间歇性不可用。3.4 预算管理与费率限制预算管控是我觉得 LiteLLM 最值得上生产环境的原因之一。Leader 最怕的不是模型贵而是失控的调用。LiteLLM 支持给每个 Key 或每个用户设置消费上限litellm_settings: max_budget: 1000 budget_duration: 30d在配置里设置了预算周期后网关会追踪这段时间内的累计消费超过上限就拒绝新请求并返回一个明确的错误提示。这比在业务代码里自己写次数统计要可靠得多因为网关在转发层就能把超预算的请求拦住。更细的用法是给每个虚拟 Key 单独设置额度。比如给某个测试用户分配一个 10 美元额度的 Key他调完了就不会再成功也不会影响其他人的正常使用。这在实际团队协作里尤其好用——实习生调试代码不小心写了个死循环反复调用大模型如果没有 Key 级别的额度限制这笔开销就得自己背了。4. 生产环境配置一份可落地的 config.yaml 与部署策略4.1 配置结构拆解生产环境不能用命令行随手传参应该把所有模型路由、预算、缓存策略写进一份 config.yaml纳入版本管理。配置的核心结构是model_list每一个条目代表一个对外可被调用的模型入口。条目的model_name是对外暴露的名字客户端请求时必须用它litellm_params里的model才是真正渠道上的模型标识通常带 provider 前缀并且最好不包含密钥明文而是通过os.environ/变量名指向环境变量。我见过不少新手在model_name和内部实际模型之间产生混淆最后以为网关配置错了其实是请求里用的名字和配置里不一致。比如配置里对外叫gpt-4o-mini实际litellm_params.model是openai/gpt-4o-mini客户端如果直接请求openai/gpt-4o-mini反而匹配不到因为网关是按model_name做路由匹配的。4.2 后端存储与数据持久化默认情况下LiteLLM 的 Key 和日志数据会存本地 SQLite。单机调试没问题但生产环境多实例部署时必须换成统一的存储否则每个实例各查各的数据虚拟 Key 在不同实例之间的校验都不一致。我通常会配置 Postgres 作为主存储litellm --config config.yaml \ --database_url postgresql://user:passwordhost:5432/litellmPostgres 主要存虚拟 Key、预算历史、请求日志。只要数据库连接稳定多个网关实例就能共享同一份数据。缓存方面如果启用了cache: true又希望多个实例共享缓存结果最常用的方案是 Redislitellm_settings: cache: true cache_params: type: redis host: localhost port: 6379这个缓存机制对语义缓存场景特别有用比如一些固定问题重复命中时可以直接返回缓存的响应既能减少延迟又能省成本。但要注意如果业务对实时性要求很高或者模型输出必须保持更新这种缓存反而可能误导调用方需要设置合理的 TTL。4.3 部署形态单节点、Docker、K8s 里怎么跑单节点部署最简单后台跑一个进程即可。Docker 部署也很直接官方镜像可以直接拉取使用挂载配置文件、映射端口就能启动docker run -d --name litellm-proxy \ -p 4000:4000 \ -v $(pwd)/config.yaml:/app/config.yaml \ -e OPENAI_API_KEY你的密钥 \ ghcr.io/berriai/litellm:main-latest \ --config /app/config.yaml需要注意容器里读取环境变量的方式和宿主机一样只是这些变量需要显式传到docker run环境或 compose 文件里。K8s 里部署时我习惯把这个服务做成一个普通的 Deployment用 ConfigMap 挂载 config.yaml并用 Service 暴露 4000 端口。网关本身是无状态的只要 Postgres 和 Redis 在外面统一管理副本数随便扩。健康检查可以直接使用/health/liveliness这个端点K8s 的 readiness probe 和 liveness probe 都能挂它。这个细节很实用我早期没配健康检查有一回实例内存被打满流量还是继续打进来用户侧各种超时。配了探针之后K8s 能自动摘除异常副本故障恢复时间大幅缩短。4.4 成本与用量追踪抛开预算管控单纯想回答“这个月模型花了多少钱、花在哪了”LiteLLM 也提供了支撑。它内置了一个模型价格表会按月更新各家模型的价格数据。请求日志里会记录模型名、输入 token 数、输出 token 数、总耗时、对应 Key 和用户信息。我更推荐直接查 Postgres 里那张请求日志表按model和user分组做汇总SELECT model, user_id, SUM(prompt_tokens) AS total_prompt_tokens, SUM(completion_tokens) AS total_completion_tokens, SUM(spend) AS total_spend FROM litellm_proxy_request_log WHERE request_ts NOW() - INTERVAL 30 days GROUP BY model, user_id ORDER BY total_spend DESC;这张表几乎记录了生产环境排查问题所需的全部信息。哪个模型最烧钱、哪个调用方在刷接口都能直接定位。不少团队看完数据后马上就把一些降本需求提上日程能直观地看到效果。5. 常见问题与排查实录5.1 总是报 401 Authentication Error这个是接代理模式最常见的问题之一。排查时先看网关端日志确认请求是否成功到达了代理。如果代理日志正常说明问题出在代理到上游模型那一环。常见原因有三个环境变量没有设置成功litellm_params里没有引用到环境变量或者上游密钥本身已经失效。我遇到过最隐蔽的一个情况是配置文件里写了api_key: os.environ/OPENAI_API_KEY但表格没转成环境变量Windows 下直接在系统设置里配好了启动服务后是新的进程环境变量读到了可如果在 IDE 里点运行读取的环境变量来自 IDE 的启动环境跟系统环境不一致就容易出现 “本地好好的一跑就 401”。这时候在启动处打印一下os.environ.get(OPENAI_API_KEY)就能快速定位。5.2 上下文长度超出报错大模型任务很容易撞上Context Window Exceeded这类报错。上游模型侧有最大输入 token 限制请求太长就会被拒。LiteLLM 本身不改变模型的能力边界但它可以做一层保护在转发前自动截断或拒绝超长请求。一个实践做法是给模型条目设置max_input_tokens让代理在请求体过大时直接返回明确错误而不是让业务端等超时。这块还有个小技巧就是对用户输入做 token 估算预算一下 messages 里所有内容的长度在进入网关前就先拦截一大部分无效请求。毕竟把一个大 prompt 转发到模型再被拒收既浪费时间又浪费流量自己提前拦截最省。5.3 超时与限流429 和 timeouts429 是上游限流信号LiteLLM 默认会对这类错误进行重试但如果上游确实被打满重试只会加重负担。生产环境的建议是配好冷却和 fallback。代理内部有冷却机制某个后端持续 429 时会自动把流量切给其他后端直到恢复。超时问题则要分开看连接超时通常说明网络到上游不通读超时则说明模型生成时间太长可能要调整timeout参数。大模型流式输出时如果你设置了过短的 timeout即使模型还在正常生成也可能被误杀成超时。我在流式接口上会把 timeout 设置得比非流式更长涉及到具体业务至少留出 60 秒以上。5.4 模型名映射混乱为什么 gpt-4o 请求到了别的模型这个几乎是配置理解问题。客户端请求里填的model参数必需命中model_list里某个model_name然后网关根据该条目的litellm_params.model去调用真正的模型。所以同一个model_name名下配置了多个后端请求分流就是正常行为。如果希望调试时精准走某一个渠道可以临时给那个渠道单独定义一个model_name比如gpt-4o-openai和gpt-4o-anthropic客户端显式指定。这在灰度阶段特别实用。等验证完再把流量收敛到同一个对外名称。这个方法我屡试不爽排查问题时能快速定位到底是渠道问题还是模型能力问题而不是在路由器里猜。最后再分享一个小技巧如果你准备在项目里引入 LiteLLM我的建议是先不要把预算、虚拟 Key、多后端全铺开。第一步只用它做标准 SDK把调用代码全部切换成completion风格第二步跑一个简单代理让其他语言的服务也走同一入口第三步再逐步加上 fallback、负载均衡和预算管控。这样每一步的影响面都可控出了问题也能快速回滚。我在实际项目里踩过最不值当的坑就是一上来就配了一堆路由和预算策略结果模型本身的效果还没验证好光排查配置就花了一晚上。先把链路跑通再慢慢加治理能力这个顺序几乎不会错。