LiteLLM Proxy — 统一 LLM API 网关的生产部署实践

痛点

当团队同时使用 OpenAI、Claude、Gemini、Azure OpenAI 等多家 LLM 服务时，运维面临几个棘手问题：

多密钥管理混乱 — 每个服务独立 API Key，散落在各业务代码的 .env 里，轮转和审计成本高
成本黑洞 — 无法统一追踪各模型的 Token 消耗和费用，月底账单靠猜
无降级容灾 — 某家供应商出故障时，业务直接挂掉，没有自动 Fallback 机制
限流和配额管控缺失 — 开发者随意调用，容易触发供应商 Rate Limit 或产生意外大额账单

LiteLLM Proxy 正是解决这些问题的开源方案 —— 一个统一的 LLM API 网关，对外暴露标准 OpenAI 兼容接口，对内代理 100+ 模型提供商。

方案概述

LiteLLM Proxy（又称 LiteLLM Gateway）是一个 Python 实现的反向代理服务，核心能力：

能力	说明
统一接口	所有模型统一为 OpenAI Chat Completions 格式
负载均衡	同一模型多 Key 轮询，支持权重、延迟感知路由
Fallback	主模型失败自动切换备用模型
限流/配额	按用户、Team、Key 粒度设定 RPM/TPM 上限
费用追踪	实时统计每次调用的 Token 数和美元成本
审计日志	每次请求的元数据可推送到 PostgreSQL、Prometheus、Langfuse

实操步骤

Step 1：Docker Compose 部署

# docker-compose.yml
version: "3.8"
services:
  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    ports:
      - "4000:4000"
    volumes:
      - ./litellm_config.yaml:/app/config.yaml
    environment:
      - DATABASE_URL=postgresql://litellm:secret@db:5432/litellm
      - LITELLM_MASTER_KEY=${LITELLM_MASTER_KEY}
      # 供应商 Key 通过环境变量注入，不写进配置文件
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - GEMINI_API_KEY=${GEMINI_API_KEY}
    command: ["--config", "/app/config.yaml", "--detailed_debug"]
    depends_on:
      - db
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: litellm
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Step 2：配置多模型路由与 Fallback

# litellm_config.yaml
model_list:
  # 主力模型 — 多 Key 负载均衡
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
      rpm: 500   # 单 Key 限速

  # Fallback 模型
  - model_name: gpt-4o
    litellm_params:
      model: anthropic/claude-sonnet-4-20250514
      api_key: os.environ/ANTHROPIC_API_KEY

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

  - model_name: fast-chat
    litellm_params:
      model: gemini/gemini-2.0-flash
      api_key: os.environ/GEMINI_API_KEY

router_settings:
  routing_strategy: latency-based-routing  # 延迟感知路由
  num_retries: 2
  timeout: 30
  fallbacks:
    - gpt-4o: [fast-chat]  # gpt-4o 全部失败时降级到 fast-chat

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL
  # Prometheus 指标
  alerting:
    - prometheus

Step 3：创建 Virtual Key 并分配配额

启动后通过管理 API 创建隔离的虚拟密钥：

# 创建一个给 "data-team" 的 Key，月预算 $200，限 100 RPM
curl -X POST http://localhost:4000/key/generate \
  -H "Authorization: Bearer ${LITELLM_MASTER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "data-team",
    "max_budget": 200,
    "rpm_limit": 100,
    "tpm_limit": 1000000,
    "models": ["gpt-4o", "fast-chat"],
    "duration": "30d"
  }'

返回的 key 值分发给对应团队，他们只需：

from openai import OpenAI

client = OpenAI(
    base_url="http://litellm-proxy:4000/v1",
    api_key="sk-virtual-key-from-above"
)

# 对业务代码完全透明，和直连 OpenAI 一样
resp = client.chat.completions.create(
    model="gpt-4o",  # 逻辑模型名，实际路由由 Proxy 决定
    messages=[{"role": "user", "content": "Hello"}]
)

Step 4：接入 Prometheus + Grafana 监控

LiteLLM 内置 /metrics 端点，暴露关键指标：

# prometheus.yml 追加
scrape_configs:
  - job_name: litellm
    metrics_path: /metrics
    static_configs:
      - targets: ["litellm:4000"]

核心监控指标：

指标	含义
`litellm_requests_total`	总请求数（按模型、状态码分）
`litellm_total_tokens`	Token 消耗（按模型、用户分）
`litellm_request_duration_seconds`	请求延迟分布
`litellm_spend_total`	累计花费（美元）
`litellm_rate_limit_errors`	被限流次数

Grafana Dashboard 推荐关注：各团队日消费趋势、模型延迟 P95、Fallback 触发率。

避坑指南

1. Streaming 响应超时

LiteLLM 默认 stream_timeout=None，但如果前面有 Nginx 反代，Nginx 的 proxy_read_timeout 可能先断。解决：

location /v1/ {
    proxy_pass http://litellm:4000;
    proxy_read_timeout 300s;
    proxy_buffering off;  # SSE 必须关闭缓冲
}

2. PostgreSQL 连接池耗尽

高并发场景下 LiteLLM 到 DB 连接池默认偏小。在 DATABASE_URL 加参数或配置 PgBouncer：

DATABASE_URL=postgresql://litellm:secret@pgbouncer:6432/litellm?connection_limit=50

3. Virtual Key 泄露无法快速止血

建议所有 Key 都设 max_budget 上限。一旦发现泄露，立即调用：

curl -X POST http://localhost:4000/key/delete \
  -H "Authorization: Bearer ${LITELLM_MASTER_KEY}" \
  -d '{"keys": ["sk-leaked-key"]}'

配合告警规则：单 Key 1 分钟内 spend 异常飙升 → 自动告警通知运维。

总结

LiteLLM Proxy 解决的核心问题是 LLM 多供应商管理的运维复杂度：

统一入口 → 业务代码零改造接入任意模型
负载均衡 + Fallback → 提升 LLM 调用可用性到 99.9%+
配额 + 费用追踪 → 成本可控、可审计
Prometheus 指标 → 纳入现有监控体系

适合场景：团队 10+ 人使用 LLM、月 LLM 支出 $500+、或需要满足合规审计要求的组织。部署成本低（单节点 512MB 内存即可启动），后续可水平扩展为多副本 + Redis 共享状态。