LiteLLM 详解：Agent 的开源模型网关

TL;DR — LiteLLM 是一个开源 Python 代理，给你一个 OpenAI 兼容端点就能对接 100+ 模型供应商。你调一个 API，它路由到 OpenAI、Anthropic、Google、Bedrock、本地 vLLM 或任何你配好的后端——自带自动故障转移、成本追踪、限速和预算上限。如果你的 Agent 需要调多个模型（应该的），LiteLLM 就是让你不用写供应商特定代码的那一层。

LiteLLM 解决什么问题

你在建 Agent。它需要强模型做规划（Claude）、快模型做简单工具调用（GPT-4o-mini）、便宜模型做摘要（本地 vLLM 跑的 Llama）。这就是三套不同的 API、三种认证方式、三种响应格式、三种错误码、三个计费面板。

再乘以每次模型更新改价格、凌晨两点打到 rate limit、某个供应商宕机而你的 Agent 崩了而不是优雅降级。

LiteLLM 把这一切收成一个端点。你的 Agent 代码调 POST /chat/completions 加模型名。下面的事 LiteLLM 全管。

LiteLLM 是什么

LiteLLM 有两面：

1. Python SDK — 一个 completion() 函数，把 100+ 供应商包成 OpenAI 兼容接口。直接 import 用。
2. Proxy Server（AI 网关） — 独立部署的服务。暴露 OpenAI 兼容端点，按你定义的规则把请求路由到配好的供应商。

对生产级 Agent 技术栈来说，Proxy 是真正的价值所在。它是所有模型访问的集中控制面。

关键数据：

指标	数值
GitHub stars	20K+
OpenRank（2026年5月）	156.06
活跃贡献者	249
Docker 拉取数	2.4 亿+
支持供应商	100+
生产请求处理量	10 亿+
许可证	MIT

架构：网关的位置

┌──────────────────────────────────────────────────┐
│  Agent 运行时                                      │
│  (调 POST /v1/chat/completions)                   │
├──────────────────────────────────────────────────┤
│  LiteLLM Proxy  ←── 网关                          │
│  ┌────────────────────────────────────────────┐  │
│  │ 路由器: model → provider 映射              │  │
│  │ 负载均衡: round-robin / least-busy         │  │
│  │ 降级: provider A 挂了 → 试 B              │  │
│  │ 成本追踪: 按 token、按 key、按团队         │  │
│  │ 限速: TPM / RPM 上限                      │  │
│  │ 预算: 每个虚拟 key 的硬性花费上限          │  │
│  │ 缓存: 语义或精确匹配                       │  │
│  │ 护栏: 内容过滤                             │  │
│  └────────────────────────────────────────────┘  │
├──────────────────────────────────────────────────┤
│  供应商                                           │
│  OpenAI | Anthropic | Bedrock | vLLM | SGLang    │
│  Google | Mistral | Cohere | Ollama | ...        │
└──────────────────────────────────────────────────┘

你的 Agent 代码不知道（也不需要知道）哪个供应商在跑哪个模型。那是网关的事。

对 Agent 技术栈最重要的功能

统一 API — 一个端点，一种格式。从 Claude 切到 GPT-4o 只改模型名字符串，不用重写工具调用逻辑。

自动故障转移 — Anthropic 返回 529，LiteLLM 重试备用部署或降级到其他供应商。你的 Agent 会话不会因为某个 API 打嗝就挂。

成本追踪 — 每个请求记录 input/output token 和费用。可以看按 Agent、按团队、按模型的细分。当你的 coding agent 在调试循环里烧了 $40，你能知道是哪个会话干的。

预算上限 — 每个虚拟 API key 设硬限制。给每个 Agent 实例 $5/天预算。用完请求被拒绝，不会刷爆信用卡。

负载均衡 — 同一供应商多个 API key？多个 vLLM 实例？LiteLLM 分发请求。某个 key 到 rate limit 了，流量自动转移。

虚拟 key — 为团队或 Agent 创建 API key，不用暴露你的真实供应商 key。每个虚拟 key 有独立的预算、限速和模型访问权限。

缓存 — 精确匹配或语义缓存。两个 Agent 会话用相同上下文问同样的问题，直接返回缓存。省 token 省延迟。

成本路由的故事

LiteLLM 和 Agent 基础设施的一个新兴趋势交汇在这里。ICLR 2025 的 RouteLLM 和 EMNLP 2025 的 IPR 研究表明，按难度把请求路由到不同级别的模型可以在保持质量的同时砍掉 40-50% 成本。

实践中 LiteLLM 的 GitHub issues 讲的也是同一个故事：cost based routing 23 条、lowest cost 18 条、budget routing 37 条、spend tracking 76 条。团队在问：在满足质量要求的前提下，怎么路由到最便宜的够用模型？

一个基础的成本路由配置：

model_list:
  - model_name: agent-planner
    litellm_params:
      model: anthropic/claude-sonnet-4
      api_key: sk-ant-...
    model_info:
      cost_per_token: 0.000003

  - model_name: agent-executor
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: sk-...
    model_info:
      cost_per_token: 0.00000015

  - model_name: agent-summarizer
    litellm_params:
      model: openai/hosted_vllm/llama-3.3-70b
      api_base: http://vllm-internal:8000/v1

Agent 代码对不同任务调不同模型名。网关把每个请求路由到对应后端。Agent 代码里没有任何供应商 SDK import。

快速启动

# Docker（最快）
docker run -d \
  -p 4000:4000 \
  -v ./litellm_config.yaml:/app/config.yaml \
  -e DATABASE_URL=postgresql://... \
  ghcr.io/berriai/litellm:main-latest \
  --config /app/config.yaml

# 测试
curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-your-virtual-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent-planner",
    "messages": [{"role": "user", "content": "Plan the refactor"}],
    "max_tokens": 500
  }'

这个请求到 LiteLLM，解析 agent-planner 为 Claude Sonnet 4，加认证，转发请求，记录成本，返回 OpenAI 格式响应。

真正管用的故障转移

LiteLLM 对生产 Agent 最有价值的功能就是故障转移——也是大家最容易配错的。天真的配置长这样：

model_list:
  - model_name: agent-planner
    litellm_params:
      model: anthropic/claude-sonnet-4
      api_key: os.environ/ANTHROPIC_KEY_1
  - model_name: agent-planner          # 同名 = 一个 fallback 组
    litellm_params:
      model: anthropic/claude-sonnet-4
      api_key: os.environ/ANTHROPIC_KEY_2  # 不同 key

router_settings:
  num_retries: 2
  retry_after: 5
  allowed_fails: 3
  cooldown_time: 30
  fallbacks: [{"agent-planner": ["agent-planner-backup"]}]

大多数人忽略的微妙之处：**当供应商本身宕机时，同供应商内部的重试帮不上忙。**如果 Anthropic 返回 529（过载），2 秒后重试同一个 Anthropic 端点通常还是 529。真正的韧性需要跨供应商 fallback：

  - model_name: agent-planner-backup
    litellm_params:
      model: openai/gpt-4o           # 不同供应商
      api_key: os.environ/OPENAI_KEY

现在 Anthropic 过载时，请求落到 GPT-4o。你的 Agent 拿到稍微不同的模型但活着。对一个规划步骤，这个 trade-off 几乎总是值得的。

另一个坑：allowed_fails 和 cooldown_time。当一个部署失败 allowed_fails 次，LiteLLM 把它冷却 cooldown_time 秒——把流量路由到别处。cooldown_time 设太低（如 5s）你会一直锤一个挣扎中的供应商。太高（如 300s）你会因为一次瞬时抖动丢 5 分钟容量。30-60s 是大多数 Agent 工作负载的甜点。

Streaming + Fallback 陷阱

一个专门坑 Agent 开发者的 bug。当你流式返回响应（为了体验你应该这么做）而主供应商在流中途失败——发了 50 个 token 然后报错——会怎样？

LiteLLM 可以 fallback 到备用供应商，但客户端已经收到那 50 个 token 了。Fallback 响应从头开始，用户看到 50 个 token，然后流用不同内容重启。对聊天 UI 这很突兀；对解析结构化输出的 Agent，这是解析失败。

缓解办法：对输出完整性比延迟更重要的 Agent 工具调用请求，关掉 streaming，用非流式路径配 fallback。把 streaming 留给可以容忍重启的面向用户的聊天。LiteLLM 不替你解决这个——你得按端点决定 streaming 还是可靠 fallback 更重要。

LiteLLM vs 其他选择

功能	LiteLLM	OpenRouter	SandBase	自建代理
自托管	✅	❌（SaaS）	✅	✅
开源	✅ MIT	❌	部分	看情况
供应商数	100+	200+	精选	你建多少
成本追踪	内置	内置	内置	自己做
预算上限	✅	❌	✅	自己做
限速	✅	平台级	✅	自己做
故障转移	✅	平台级	✅	自己做
部署成本	低	零	低	高

LiteLLM 是你自托管的开源选项。OpenRouter 是托管市场。SandBase 提供带沙箱/执行能力的托管网关。它们解决重叠但不同的问题——你甚至可以把 LiteLLM 当更上层平台下面的路由层来用。

什么时候需要网关

需要网关：

• Agent 用了不止一个模型供应商
• 需要成本可见性和预算控制
• 想在供应商宕机时自动降级
• 多团队或多 Agent 共享 API key 需要隔离
• 在自托管模型和云 API 之间路由

可能不需要：

• 单模型、单供应商、低量
• 在原型阶段还不关心成本
• 供应商原生 SDK 已经够用

对大多数生产级 Agent 系统，在有多于一个模型或多于一个团队时网关就变得必要。不装的成本是隐性的——直到你收到意外的 $2,000 账单，或者因为硬编码了单一供应商端点而宕机 3 小时。

FAQ

LiteLLM 能按内容/难度路由吗？

原生没有内置分类器，但你可以实现。在 Agent 代码里为不同复杂度设不同模型名，LiteLLM 路由到对应供应商。有些团队在前面放一个轻量分类器选模型名。

LiteLLM 增加延迟吗？

很小——通常 5-15ms 每请求。它是薄代理，不做重计算。相比模型生成时间可以忽略。

支持 streaming 吗？

支持。完整 SSE streaming 支持，包括故障转移时（如果主流在响应中间断了，可以在备用上重试）。

怎么处理不同响应格式？

LiteLLM 把所有格式统一成 OpenAI 格式。Anthropic 的 Messages API、Google 的 Gemini 格式、Bedrock 的结构——全部以标准 OpenAI chat completions 返回给你的 Agent 代码。

必须要 PostgreSQL 吗？

只有持久化成本追踪和预算管理需要。没有数据库也能用路由和故障转移，只是花费数据重启后丢失。

核心要点

• LiteLLM 给 Agent 一个 OpenAI 兼容端点对接 100+ 供应商，自带故障转移、成本追踪和预算上限。
• 网关模式在 Agent 使用多模型时必不可少——为了成本优化应该这么做（强模型做规划，便宜模型做简单任务）。
• 成本路由是新兴趋势：路由到满足质量要求的最便宜模型。LiteLLM 提供管道；路由逻辑你来定。
• Docker 部署一个代理放在 Agent 和模型供应商之间。Agent 代码再也不用 import 供应商 SDK。