为什么需要 LiteLLM Proxy

独立开发者刚做 AI 应用时通常先用一家 SDK——OpenAI SDK 调 OpenAI 官方 / OneAPI / 中转。慢慢就遇到三个真实问题:

  1. 多家比价:Claude 在 coding 任务上更强,但客服场景 Gemini 长上下文便宜,想都用又不想代码里写三套 SDK
  2. 官方 + 中转双线:海外卡能办的项目走 Anthropic 官方,办不了或国内同事访问的走中转,但应用层不该感知这种切换
  3. 团队预算:几个项目共享一份中转账户,需要给每个项目独立用量隔离与封顶预算

LiteLLM(访问于 2026-05-19)就是为解决这三件事生的。一个 OpenAI 风格的统一 Proxy,后端挂多厂商,前端给应用一个 endpoint + 一个 key。

步骤一:装 LiteLLM Proxy

pip install 'litellm[proxy]'

或 Docker:

docker run -p 4000:4000 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  ghcr.io/berriai/litellm:main-stable \
  --config /app/config.yaml --port 4000

config.yaml 最小模板:

model_list:
  - model_name: opus-4-7
    litellm_params:
      model: anthropic/claude-opus-4-7
      api_base: https://你的 Claude 中转域名
      api_key: os.environ/CLAUDE_RELAY_KEY
  
  - model_name: gpt-5-5
    litellm_params:
      model: openai/gpt-5.5
      api_base: https://你的 OpenAI 中转域名/v1
      api_key: os.environ/OPENAI_RELAY_KEY
  
  - model_name: gemini-3-1-pro
    litellm_params:
      model: vertex_ai/gemini-3.1-pro
      vertex_project: my-project
      vertex_location: asia-southeast1

litellm_settings:
  master_key: sk-master-不要外泄
  database_url: postgresql://litellm:pwd@db/litellm

router_settings:
  fallbacks:
    - opus-4-7: ["gpt-5-5"]
    - gpt-5-5: ["opus-4-7"]
  num_retries: 2
  timeout: 30

步骤二:挂三家后端

LiteLLM 支持 100+ 家 LLM 提供商(访问于 2026-05-19)。常见三家挂法:

提供商model 前缀关键参数
Claude(中转或官方)anthropic/claude-opus-4-7api_base + api_key
GPT(中转或官方)openai/gpt-5.5api_base(带 /v1)+ api_key
Gemini(Vertex 或 AI Studio)vertex_ai/gemini-3.1-pro 或 gemini/gemini-3.1-provertex_project / api_key

国内开发同事访问 Claude 官方 / OpenAI 官方控制台稳定性差,在 LiteLLM 后端挂一条独立开发者用得起的 Claude 4.7 / GPT-5.5 中转,既解决调用可达性又拿到价差红利,Vertex 用 GCP 海外项目直连。

步骤三:虚拟 key 与团队预算

应用层不能拿 master_key,要用虚拟 key:

curl -X POST http://litellm:4000/key/generate \
  -H "Authorization: Bearer sk-master-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "models": ["opus-4-7", "gemini-3-1-pro"],
    "max_budget": 50.0,
    "budget_duration": "30d",
    "metadata": {"team": "growth", "project": "copywriter"}
  }'

返回 sk-app-yyy,发给应用用。

每个虚拟 key 三层约束:

维度字段用途
模型白名单models限定能调哪几个 model alias
预算max_budget + budget_duration30 天 50 美金封顶
速率rpm_limit / tpm_limit防一个项目把别人挤死

步骤四:应用端切 OpenAI SDK

应用代码原本可能写:

# Before
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
resp = client.messages.create(model="claude-opus-4-7", messages=[...])

改成:

# After
from openai import OpenAI
client = OpenAI(
    base_url="http://litellm:4000/v1",
    api_key=os.environ["LITELLM_APP_KEY"],  # sk-app-yyy
)
resp = client.chat.completions.create(
    model="opus-4-7",  # LiteLLM 里配的别名
    messages=[...],
)

所有厂商的请求统一走 OpenAI 风格 /chat/completions,LiteLLM 在后台做协议翻译。

步骤五:跨厂商 Fallback

router_settings.fallbacks 配主备链:

router_settings:
  fallbacks:
    - opus-4-7: ["gpt-5-5", "gemini-3-1-pro"]
    - gpt-5-5: ["opus-4-7"]
  
  context_window_fallbacks:
    - opus-4-7: ["gemini-3-1-pro"]  # 超长上下文降级 Gemini
  
  retry_after: 5
  num_retries: 2

Claude 中转 429 → 自动重试 GPT 中转 → 再失败试 Gemini。应用端零代码改动。

同一别名挂多份 key 做轮询:

model_list:
  - model_name: opus-4-7
    litellm_params:
      model: anthropic/claude-opus-4-7
      api_key: os.environ/RELAY_KEY_1
  - model_name: opus-4-7
    litellm_params:
      model: anthropic/claude-opus-4-7
      api_key: os.environ/RELAY_KEY_2

两份 key 自动 round-robin,等效双倍 RPM。

改造前后对比

改造前改造后
应用代码三套 SDK一份 OpenAI SDK
切厂商改一片代码改 config.yaml 一行
多人共用中转 key 看不清谁花了钱每虚拟 key 独立账单
厂商 429 应用全挂自动 fallback 跨厂商重试
切官方账号要改环境变量后端切换应用无感

2026 年公开问卷(访问于 2026-05-19)显示,生产环境用 LiteLLM 的团队中位数挂 3.2 家后端,平均 fallback 命中率 4-8%——意味着每 20 次请求里有 1 次靠 fallback 救活。

与中转方协作

应用 → LiteLLM Proxy ─┬─→ Claude 中转 A (主路)
                      ├─→ Claude 中转 B (兜底)
                      ├─→ OpenAI 中转 C (跨厂商兜底)
                      └─→ Vertex AI 官方 (长上下文专用)

中转方负责「拿到通道」,LiteLLM 负责「在内网伪装成同一个端点」。两层职责清晰,问题排查也分得清。

常见坑

坑原因处理
502 Bad Gatewayapi_base 路径漏 /v1OpenAI 风格必须带 /v1,Anthropic 不带
Model not foundmodel alias 拼错LiteLLM 是 case-sensitive
401 Unauthorized虚拟 key 模型白名单不包含检查 /key/info 看 models 数组
tool_use 返回不对schema 严格度差异关键工具调用走原生 endpoint

相关阅读