用 LiteLLM 给 Agent 做统一模型网关与故障回退（一处配置接百家模型）

当 Agent 同时接多家模型，你会遇到三类问题：Key 散落难管理、某家限流/宕机时无处可退、成本难统一核算。网关把这三类问题收口到一处。

典型场景：
· 主力用 gpt-4o，成本太高时回退到 claude 或本地模型
· 某模型 429 限流，希望自动换一家重试
· 多家 Key 想集中托管，业务代码不碰明文密钥

用 pip 安装，然后直接以命令行方式调用一个模型，确认链路通：

pip install litellm

# 临时用环境变量放 Key，验证能通
export OPENAI_API_KEY=sk-xxx
litellm --model gpt-4o
# 进入交互后直接对话，能回就说明 SDK 装好

核心是一个 model_list，每个模型给一个「网关别名」+ 真实模型路径 + Key 来源（建议走环境变量，不写死）。

model_list:
  - model_name: gpt-4o            # 网关别名，业务代码用这个
    litellm_params:
      model: openai/gpt-4o       # 真实模型，前缀标厂商
      api_key: os.environ/OPENAI_API_KEY
  - model_name: claude-opus
    litellm_params:
      model: anthropic/claude-opus-4
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: local-qwen
    litellm_params:
      model: openai/qwen3-32b
      api_base: http://localhost:8000/v1
      api_key: not-needed

用配置启动代理，默认监听 4000 端口；之后你的代码把 base_url 指向它就行。

litellm proxy --config config.yaml --port 4000

# 业务侧环境变量（让 OpenAI SDK 走本地网关）
export OPENAI_API_BASE_URL=http://localhost:4000/v1
export OPENAI_API_KEY=anything   # 网关侧再决定真实 Key

在 router_settings 里声明超时、重试次数、以及「主模型挂了回退到谁」：

router_settings:
  timeout: 60
  retry_after: 5
  num_retries: 3
  fallbacks:
    - { "gpt-4o": ["claude-opus", "local-qwen"] }
  # 可选：按 rpm/tpm 做限流
  # rpm: 1000
  # tpm: 1000000

业务代码用标准 OpenAI SDK，只把 base_url 指向网关，模型名用网关别名：

from openai import OpenAI
client = OpenAI(
    base_url="http://localhost:4000/v1",
    api_key="anything",
)
# 想换模型？只改下面这一行
resp = client.chat.completions.create(
    model="gpt-4o",          # 改 "claude-opus" 即切换，无需改其它代码
    messages=[{"role": "user", "content": "帮我总结这段日志"}],
)
print(resp.choices[0].message.content)

· Key 全部走环境变量 / 密钥管理，绝不进配置与镜像
· 开启 LiteLLM 的花费与请求日志，做统一看板
· 用虚拟密钥（virtual key）给不同业务发额度，而非共享主 Key
· 配置 rpm/tpm 限流，防单业务把额度打爆
· 网关本身做健康检查与多副本，避免成为单点