LiteLLM

这是什么？适合谁？

LiteLLM（BerriAI/litellm，56.9k Stars，2026-08-21 仍活跃推送）是一个开源 AI Gateway（LLM 网关）：用统一的 OpenAI 格式调用 100+ LLM 提供商——OpenAI、Anthropic、Gemini、Bedrock、Azure 等，一个接口替换掉各家 SDK。它有两种形态：Python SDK（库级集成）和 Proxy Server（AI Gateway）（集中式网关服务），官方口径 Rust 核心 + Python SDK，P95 延迟 8ms@1k RPS（官方基准）。

它解决的问题：多提供商 LLM 调用的碎片化——每家 SDK、鉴权方式、请求格式、错误类型都不一样。LiteLLM 给出生产级答案：虚拟密钥（virtual keys）、支出追踪（spend tracking）、护栏（guardrails）、负载均衡、fallback、管理后台开箱即用。README 列出的采用方包括 Stripe 等头部公司，Y Combinator W23 项目。

适合人群：

• 接多家 LLM 的应用团队：换模型不改代码，一个统一接口
• 平台/基础设施工程师：给业务方发虚拟密钥、按团队限额、追踪每密钥支出
• 需要高可用 LLM 调用的服务：多提供商负载均衡 + 自动 fallback，单家故障不炸
• 成本敏感团队：跨提供商比价路由，预算超限自动熔断

不适合：只调单一模型的个人小项目（直接用官方 SDK 更简单）；需要极端定制推理参数的算法研究场景（网关标准化是双刃剑）。

使用前提：Python 3.9+（SDK）；网关部署需要 Docker 或云主机；至少一家 LLM 提供商的 API Key。

准备工作

• 账号：无需 LiteLLM 账号（开源自部署）；需要至少一家 LLM 提供商（OpenAI/Anthropic/Gemini/Bedrock 等）的 API Key
• 时间预算：SDK 起步 5 分钟；Proxy Server 起步 15-30 分钟（Docker 一条命令）
• 成本：MIT 系开源协议免费（GitHub license 字段为 NOASSERTION，仓库内含多种协议组件，商用前自行核对）；托管企业版另有定价（litellm.ai/enterprise）
• 环境：Python 3.9+；Docker（部署网关时）
• 网络：需能访问 LLM 提供商 API

快速上手（3 步）

第一步：安装 SDK 并发起第一次调用

pip install litellm

import litellm
# 用 OpenAI Key 调 Anthropic 模型（统一 OpenAI 格式）
response = litellm.completion(
    model="anthropic/claude-sonnet-4-5",
    messages=[{"role": "user", "content": "Hello, LiteLLM!"}],
    api_key="sk-your-anthropic-key",
)
print(response.choices[0].message.content)

第二步：部署 Proxy Server（AI Gateway）

docker run -d \
  -p 4000:4000 \
  -e LITELLM_MASTER_KEY="sk-master-1234" \
  -v $(pwd)/litellm_config.yaml:/app/config.yaml \
  ghcr.io/berriai/litellm:main-latest \
  --config /app/config.yaml --port 4000

最小配置文件 litellm_config.yaml：

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
  - model_name: claude
    litellm_params:
      model: anthropic/claude-sonnet-4-5
      api_key: os.environ/ANTHROPIC_API_KEY

第三步：把团队流量切到网关

业务代码只需把 base_url 指向网关，用虚拟密钥替代真实 Key：

from openai import OpenAI
client = OpenAI(base_url="http://localhost:4000", api_key="sk-team-member-key")
resp = client.chat.completions.create(model="gpt-4o", messages=[{"role": "user", "content": "hi"}])

成功判定：curl http://localhost:4000/health/liveliness 返回 healthy；用虚拟密钥调用成功；管理后台（/ui，默认 master key 登录）能看到该密钥的支出与请求记录。

初级用法

• 统一接口调多家：litellm.completion() 一套代码切换 OpenAI/Anthropic/Gemini/Bedrock
• OpenAI 兼容兜底：存量 OpenAI 代码只改 base_url，零改造接入网关
• 成本看板：管理后台按虚拟密钥/模型/团队维度看支出
• 简单 fallback：配置里列出同一路由的多个 provider，主家 429/5xx 自动切换

高级玩法

1. 负载均衡 + 权重路由：model_list 里同名 model 配多个部署，按权重分流；配合 rpm/tpm 限额做速率感知调度
2. 虚拟密钥治理：给每个团队/用户发 virtual key，各自预算上限（max_budget）、模型白名单（models[]），超限自动熔断——内部”LLM 计费系统”不用自研
3. 护栏（Guardrails）：请求/响应两侧挂钩审核（PII 脱敏、关键词拦截、自定义 hook），在网关层统一执行
4. 缓存与降级：响应缓存 + cooldown 策略（某部署连续失败自动摘除冷却），配合跨区部署做高可用
5. 观测三件套：Langfuse/Langsmith 回调、Prometheus 指标、结构化日志，把 LLM 调用纳入现有可观测体系

常见踩坑（5 条）

踩坑 1：模型名前缀写错

• 现象：调用报 “model not found” 或走了意料外的提供商
• 原因：LiteLLM 用 provider/model 前缀路由（如 anthropic/claude-sonnet-4-5），前缀决定鉴权与请求格式
• 解决：对照官方 provider 文档核对前缀；网关配置里 model_name（对外名）与 litellm_params.model（真实路由）分开配，别混淆

踩坑 2：环境变量没有注入容器

• 现象：Docker 网关起不来，报 key 缺失
• 原因：配置里 os.environ/OPENAI_API_KEY 依赖容器内环境变量，docker run 没传 -e
• 解决：-e OPENAI_API_KEY=... 显式传入，或用 .env 文件 + --env-file

踩坑 3：fallback 只配了一层以为万事大吉

• 现象：高峰期仍然大面积报错
• 原因：fallback 只覆盖”提供商不可用”，不覆盖”配额耗尽后切换目标也同时限额”
• 解决：路由层配多提供商 + 每部署独立限额 + cooldown；对关键业务做预算告警而不是等熔断

踩坑 4：虚拟密钥权限理解错

• 现象：团队成员说”我的 key 调不了某模型”
• 原因：virtual key 的 models 白名单没包含该模型，或团队预算已耗尽
• 解决：管理后台检查 key 的 model 权限与 budget；给团队预留告警阈值

踩坑 5：把网关当推理引擎用

• 现象：自己部署后延迟反而变高
• 原因：LiteLLM 是”调用网关”，不做模型推理；模型仍在提供商侧
• 解决：延迟敏感场景确认官方 8ms P95 基准是网关开销而非端到端；就近部署网关减少一跳

小技巧（5 条）

1. 先 SDK 后网关：小项目直接 litellm.completion()；团队规模上来再上 Proxy，迁移成本极低
2. litellm --model 快速试：CLI 里一条命令试任意模型连通性，排错第一步
3. 预算写进配置：max_budget/budget_duration 在虚拟密钥层硬限制，别靠事后看账单
4. 健康检查探活：/health/liveliness 与 /health/readiness 接入你的监控，网关自身也要被监控
5. 官方 cookbook 走一遍：仓库 docs 与示例覆盖了路由、缓存、护栏、观测的完整配置，比拼凑博客快

常见问题 FAQ

Q1：LiteLLM 免费吗？

A：开源自部署免费（56.9k Stars，2026-08-21 采集）；企业版（托管 Proxy、SSO、高级支持）另收费，见 litellm.ai/enterprise。自部署只有基础设施成本。

Q2：和 One API / OpenRouter 有何区别？

A：OpenRouter 是托管服务，你依赖它的可用性与加价；One API 偏”账号池聚合”，治理能力浅；LiteLLM 是完整网关（虚拟密钥/支出/护栏/负载均衡），深度与采用方体量（Stripe 等）更适合团队生产环境。

Q3：支持多少提供商？

A：官方口径 100+ LLM 提供商，覆盖 OpenAI/Anthropic/Gemini/Bedrock/Azure/Vertex 及国内主流模型，见 docs.litellm.ai/docs/providers。

Q4：网关会拖慢请求吗？

A：官方基准 8ms P95 @1k RPS（docs.litellm.ai/docs/benchmarks，2026-08-21 读取），Rust 核心；实际端到端延迟主要由提供商侧决定。

Q5：能做内容安全审查吗？

A：能。Guardrails 支持请求/响应钩子（PII、关键词、自定义回调），在网关层统一执行，业务代码零侵入。

进阶学习建议

• 精读官方路由文档的”负载均衡/加权分流/cooldown”三节，理解多部署调度的完整语义，这是网关的核心价值
• 把 virtual key -> team -> budget -> alert 的治理链路在测试环境搭一遍，这是 LiteLLM 区别于”简单转发器”的分水岭
• 对照 vLLM（推理引擎）与本条目（调用网关）的定位差异，搞清”推理层 vs 网关层”的架构分层
• 用 Langfuse 回调把一次真实业务的全部 LLM 调用可视化，建立成本/延迟/错误率的基线
• 关注官方 benchmark 方法学（8ms P95 的测试条件），学会自己复测而不是照抄宣传数字

参考链接

• LiteLLM GitHub 仓库
• 官方文档（Proxy Server）
• 支持的提供商列表
• 官方基准测试

本文基于公开资料于 2026-08-21 整理，社区指标来自 GitHub API 公开数据。独立实测未进行，延迟与功能表现以实际部署为准，配置可能随版本更新变化。