别再直连 SDK 了！用 LiteLLM 10 分钟搭好生产级模型网关

前言很多团队在 AI 应用早期都是「哪个模型好用就 import 哪个 SDK」OpenAI 用openaiClaude 用anthropic本地模型再接一个requests。等模型一多、供应商一挂、老板问「这个月花了多少 token」代码已经改不动了。本文用 LiteLLM 带你在 10 分钟内搭起一个生产级模型网关统一 OpenAI 兼容接口、按成本/质量路由、自动 Fallback、限流与成本观测全部可复制运行。它和《从 Prompt Demo 到生产级架构》里讲的「模型网关模块」是同一件事的两面——那篇讲职责划分这篇讲动手落地。背景或问题直连 SDK 的三种典型痛供应商锁定每个模型一套 client、一套参数、一套异常处理。要换模型等于重写一整片调用层。没有 Fallback某个供应商 429 / 503整条链路直接崩没有自动降级。成本不可观测token 花在哪、哪个用户/业务线烧钱最多全靠月末对账根本不知道。模型网关就是把这些能力从「业务代码里东一块西一块」收拢成一个独立、可治理的「模型接入层」。核心思路LiteLLM 做两件事统一接口用一套completion()调用 100 模型模型名前缀区分后端openai/、anthropic/、azure/、openai/localhost/...。网关模式跑一个litellm代理进程对外暴露标准 OpenAI 兼容的/v1接口内部负责路由、Fallback、限流、记成本。业务侧只认一个 base_url彻底和具体供应商解耦。整体结构如下核心链路业务代码 → 网关(统一接口) → 路由策略选模型 → 失败则 Fallback 链 → 记成本/限流。实现步骤1. 安装pipinstalllitellm[proxy]proxy额外包含网关进程所需依赖。2. 最小可用同一接口调不同模型不需要网关单文件就能体验统一调用fromlitellmimportcompletion# OpenAIr1completion(modelgpt-4o,messages[{role:user,content:用一句话解释什么是模型网关}],)print(r1.choices[0].message.content)# Anthropic只换 model 前缀r2completion(modelanthropic/claude-opus-4,messages[{role:user,content:用一句话解释什么是模型网关}],)print(r2.choices[0].message.content)# 本地 vLLMopenai 兼容指向本地 base_urlr3completion(modelopenai/Qwen2.5-72B-Instruct,api_basehttp://localhost:8000/v1,api_keyfake,messages[{role:user,content:用一句话解释什么是模型网关}],)print(r3.choices[0].message.content)注意模型名写法provider/model本地模型用openai/自定义名并配api_base。3. 起一个生产级网关配置文件新建config.yamlmodel_list:-model_name:gpt-4olitellm_params:model:openai/gpt-4oapi_key:os.environ/OPENAI_API_KEY-model_name:claude-opuslitellm_params:model:anthropic/claude-opus-4api_key:os.environ/ANTHROPIC_API_KEY-model_name:local-llamalitellm_params:model:openai/Qwen2.5-72B-Instructapi_base:http://localhost:8000/v1api_key:fakerouter_settings:routing_strategy:least-busy# 合法值: simple-shuffle(默认) / least-busy / latency-based-routing / usage-based-routing注意没有 cost-basedfallbacks:-{gpt-4o:[claude-opus]}# gpt-4o 失败自动回落到 claude-opus注意是 {源模型: [目标模型]} 格式timeout:30num_retries:2general_settings:master_key:os.environ/LITELLM_MASTER_KEY# 生产必设值必须以 sk- 开头telemetry:false启动litellm--configconfig.yaml--port4000网关主密钥配置在general_settings.master_key也可用环境变量LITELLM_MASTER_KEY值必须以sk-开头。生产环境务必设置否则任何人都能免密钥调用你的额度。4. 业务侧只认一个 base_urlfromopenaiimportOpenAI clientOpenAI(api_keysk-任意字符串,# 走虚拟 key 时换成下发的 keybase_urlhttp://localhost:4000,# 全部请求打到网关)respclient.chat.completions.create(modelgpt-4o,# 想换模型只改这里messages[{role:user,content:你好}],)print(resp.choices[0].message.content)业务代码从此不感知后端是谁换供应商零改动。5. 限流与虚拟 key给不同业务线/用户发带限额的 keycurl-XPOSThttp://localhost:4000/key/generate\-HAuthorization: Bearer master-key\-HContent-Type: application/json\-d{ models: [gpt-4o, claude-opus], max_budget: 10, rpm_limit: 60, tpm_limit: 100000 }返回token即虚拟 key可独立限流、独立计费注销也只吊销这一把。6. 成本观测默认网关会把每次调用的 token 用量写进 Spend Logs。要持久化虚拟 key、预算与成本账单需要接一个 Postgres也可用 Supabase / Neon 托管在general_settings.database_url配置general_settings:master_key:os.environ/LITELLM_MASTER_KEYdatabase_url:postgresql://user:passhost:5432/litellm# 启用后才有虚拟 key / 预算 / Spend Tracking / UI 面板注意database_url才是启用「虚拟 key 成本追踪 管理 UI」的总开关不接库这些能力都不生效。连接串用标准postgresql://不要写成postgresqlasyncpg://那是 SQLAlchemy 异步驱动写法LiteLLM 不用。之后可用GET /key/info?key虚拟key查询每个 key、每个模型的累计花费或在http://localhost:4000/ui用 master key 登录看成本面板。代码示例上面 1–6 步已覆盖最小可用到生产级的关键代码。完整配置与启动命令可直接复制运行前提已配置好各供应商API_KEY环境变量本地模型可选。运行结果或效果说明搭好之后你会得到一处接入业务代码只用base_url网关地址后端随便换。自动兜底主模型超时/限流时网关按fallbacks切到备用模型业务无感。可控成本每个 key 有预算与速率上限月底不再「不知道钱花哪了」。可观测每次调用的模型、token、耗时都有记录能做成本归因。常见问题与避坑没有 master_key 就公网上线网关会允许免密调用等于把你的额度敞开。务必设LITELLM_MASTER_KEY并用反向代理加鉴权。Fallback 不是万能Fallback 只在「调用失败」时触发模型「返回了但答非所问」不会回落。语义层面的兜底要靠评测 重试策略网关管不到。routing_strategy 选错usage-based-routing按用量/成本会优先便宜模型可能牺牲质量latency-based-routing优先快模型可能用贵模型顶峰值。按业务选别默认。本地模型别名要唯一openai/名字里的名字要在model_list中先声明否则网关找不到路由。配置版本差异本文基于 LiteLLM 较新版本router_settings/general_settings字段名随版本演进跑不通先litellm --version对照官方文档。另外模型名如anthropic/claude-opus-4会随供应商迭代而变化以litellm --models或官方 model registry 为准别照抄报model not found。总结模型网关不是「又加一层复杂度」而是把散落在各业务里的供应商适配、降级、限流、成本核算收拢成一个可治理的接入层。LiteLLM 用「统一接口 配置化网关」让这件事 10 分钟就能落地业务只认一个base_url剩下的路由、Fallback、限流、记账交给网关。