LiteLLM 实战：统一代理管理多家大模型

2026年10月3日 AI 应用 suzhe

当你的生产系统同时调用 OpenAI、Anthropic、智谱 GLM 和本地 Ollama 时，每家 SDK 的鉴权、超时与返回格式都不一样。LiteLLM 用一层统一代理把多家大模型 API 收口为 OpenAI 兼容协议，既能一行切换模型，又能自动兜底、限流与统计成本，是接入多模型时最省心的那块拼图。

一、为什么需要一个统一 LLM 代理

很多团队在原型阶段只接一家厂商，上线后却被现实教育：某家突发限流、某家价格上调、某家某个能力更强。于是代码里开始出现一堆 if provider == "openai" 的分支，密钥散落在各个服务，成本也成了一笔糊涂账。

LiteLLM 的定位就是这层”适配器”：它把 100+ 家模型（OpenAI、Azure、Anthropic、Google、智谱 GLM、DeepSeek、Ollama 等）统一成 OpenAI 格式，你只需改一个 model 字段就能切换后端。更关键的是，它在代理层提供了兜底（fallback）、重试（retry）、限流（rate limit）和预算（budget）等企业级能力，而这些能力在裸调各家 SDK 时要自己手写。

场景	裸接多家 SDK	用 LiteLLM 代理
切换模型	改代码 + 重编译	改一个 model 字符串
某家限流	业务自己写兜底	代理自动 fallback 到下家
成本统计	各平台后台手动汇总	统一回调记录 token 与花费
密钥管理	散落各服务	集中在代理配置

二、用 Docker 快速拉起代理

最稳妥的部署方式是把 LiteLLM 跑成一个独立代理服务，业务侧只跟它打交道。下面这份 docker-compose.yml 挂载一份 config.yaml 作为模型与密钥清单：

version: "3.9"
services:
  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    command: ["--config", "/app/config.yaml", "--port", "4000", "--detailed_debug"]
    ports:
      - "4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml
    environment:
      - LITELLM_MASTER_KEY=sk-master-3f9a2c7e          # 代理自身的访问密钥
      - LITELLM_LOG=INFO
    restart: unless-stopped

config.yaml 里声明可用模型与对应的厂商密钥。注意密钥只在代理侧存在，业务代码只持有一个 sk-master-* 代理密钥，安全边界清晰：

model_list:
  - model_name: gpt-prod
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY

  - model_name: glm-prod
    litellm_params:
      model: openai/zhipuai/glm-4-flash
      api_base: https://open.bigmodel.cn/api/paas/v4
      api_key: os.environ/ZHIPU_API_KEY

  - model_name: local-llm
    litellm_params:
      model: ollama/qwen2.5:7b
      api_base: http://host.docker.internal:11434

litellm_settings:
  drop_params: true          # 忽略厂商不支持的字段，避免 400
  request_timeout: 60

三、业务侧一行切换模型

代理跑起来后，业务代码用标准 OpenAI SDK 指向 http://localhost:4000，把 model 换成你在配置里定义的名字即可。要换厂商，只改这一个字符串，其余逻辑不动：

from openai import OpenAI

client = OpenAI(
    api_key="sk-master-3f9a2c7e",        # 代理密钥，不是厂商密钥
    base_url="http://localhost:4000",
)

resp = client.chat.completions.create(
    model="glm-prod",                    # 换成 gpt-prod / local-llm 即可切换后端
    messages=[{"role": "user", "content": "用一句话解释什么是向量数据库"}],
)
print(resp.choices[0].message.content)

这正是把多模型收口的价值：上层应用完全感知不到底层是云厂商还是本地推理。如果你已经在用 Dify + Ollama 搭建私有知识库，也可以把 Dify 的模型供应商直接指向 LiteLLM 代理，实现”一处配置、全局切换”。

四、自动兜底与重试

生产环境最怕某家厂商临时 429 或超时。LiteLLM 支持在配置里声明 fallback 链和重试策略，某家失败会自动切到下家，对调用方透明：

model_list:
  - model_name: chat
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY
  - model_name: chat
    litellm_params:
      model: openai/zhipuai/glm-4-flash
      api_base: https://open.bigmodel.cn/api/paas/v4
      api_key: os.environ/ZHIPU_API_KEY

router_settings:
  fallbacks:
    - chat:               # 同名模型组成兜底组，按列表顺序切换
        - openai/gpt-4o-mini
        - openai/zhipuai/glm-4-flash
  num_retries: 3
  timeout: 30

策略	配置项	作用
兜底	`router_settings.fallbacks`	主模型失败时切到备用模型
重试	`num_retries`	对 429/5xx 自动指数退避重试
超时	`timeout`	单请求上限，避免长尾拖垮线程
降级	`mock_response`	全部失败时返回兜底话术而非报错

兜底逻辑和重试边界，与我们在大模型工具调用可靠性实战里强调的”超时、重试与降级”是一致的——代理层负责横向兜底，业务层负责纵向降级，两层配合才稳。

五、成本控制与用量统计

多模型最头疼的是算不清账。LiteLLM 在每次响应里都返回 x-litellm-response-cost 头，并支持通过回调把每次调用的模型、token、花费写进数据库或日志，便于做部门分摊与异常告警：

litellm_settings:
  callbacks: ["langfuse"]          # 也可接 prometheus / datadog / 自定义 webhook
  success_callback: ["langfuse"]

# 预算上限：超过后该虚拟密钥被拒绝，防止跑飞
general_settings:
  # 在代理启动时校验预算
  budget_duration: "30d"
  max_budget: 200.0

更细的粒度是按”虚拟密钥”限预算。给每个业务线发一把 sk-... 子密钥，配 max_budget 与 budget_duration，谁超支谁被拦，互不拖累：

# 生成带预算的子密钥
curl -X POST "http://localhost:4000/key/generate" \
  -H "Authorization: Bearer sk-master-3f9a2c7e" \
  -H "Content-Type: application/json" \
  -d '{
    "models": ["glm-prod", "gpt-prod"],
    "max_budget": 50.0,
    "budget_duration": "7d",
    "aliases": {"cheap": "glm-prod"}
  }'

如果你关心底层推理开销，可把贵模型换成本地量化部署的 GGUF 模型跑在 Ollama 上，由 LiteLLM 统一代理——高频简单请求走本地、复杂请求走云端，成本直接下一截。

六、与 Spring AI 集成

Java 后端也能无痛接入。在 Spring AI 实战的基础上，把 base-url 指向 LiteLLM 代理，api-key 填代理密钥，model 填代理里的逻辑名即可复用全部 Spring AI 能力（流式、Function Calling、RAG）：

# application.yml
spring:
  ai:
    openai:
      base-url: http://litellm:4000
      api-key: sk-master-3f9a2c7e
      chat:
        options:
          model: glm-prod

七、生产部署检查清单

项	要点
密钥	厂商密钥只在 config.yaml，靠环境变量注入；代理只暴露 master key
兜底	每个核心 model 至少配 1 个 fallback，避免单点
预算	按业务线发子密钥并设置 max_budget，防跑飞
可观测	接 prometheus/langfuse 回调，盯住成本与失败率
超时	设置 request_timeout 与客户端超时，长尾要截断
健康	用 `/health/liveliness` 做探针，代理本身也要高可用

最后提醒一句：LiteLLM 只解决”接入与治理”，模型本身的推理质量仍是底座。若要做高吞吐在线服务，建议先参考推理引擎选型与部署把底层算力规划清楚，再让代理层做统一收口，整条链路才既稳又省。

八、负载均衡与多副本路由

当同一个模型部署了多个副本——比如本地多卡 Ollama、或者你手握多家同模型账号想做负载分摊——可以在 model_list 里用同一个 model_name 列出多份部署。LiteLLM 会按权重轮询，并支持 rpm/tpm 限速，避免单个账号触发厂商限频：

model_list:
  - model_name: gpt-prod
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_KEY_A
      rpm: 50
  - model_name: gpt-prod
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_KEY_B
      rpm: 50

router_settings:
  model_group_retry_policy:
    gpt-prod:
      Timeout: 30
      RetryCount: 2

这样业务侧仍只写 model="gpt-prod"，流量却会被均匀打到两个账号上。配合上一节的 fallback，你就同时拥有了”横向扩容”与”纵向兜底”两道防线。

九、常见误区与排障

现象	根因	处理
401 Unauthorized	代理 master key 错，或厂商 key 缺失/失效	核对 config 里 api_key 与代理 Authorization 头
400 Bad Request	请求字段不被该厂商支持	开 `drop_params: true` 丢弃多余字段
429 Too Many Requests	触发厂商限频	配 fallback + rpm 限速 + num_retries
成本对不上	没接回调，用量未记录	开启 `success_callback` 接 prometheus/langfuse
切换模型无反应	model 名与 config 不一致	确认业务侧 model 等于 config 里 model_name