📦 资源信息

⭐ GitHub 星标52,876

🔧 最后维护2026/5/19

简介 #

你用 Claude 做推理，GPT-4o 写代码，Gemini Flash 做便宜的分类任务。每个服务商都有自己的 SDK、自己的重试逻辑、自己的速率限制响应头、自己的账单面板。凌晨两点 Anthropic 的 API 抽风时，会有人被叫醒处理。OpenAI 账单周环比暴涨 40% 时，没人知道是哪个团队搞的。

这就是多 LLM 运维税——而且每加一个新模型都会复利式增长。LiteLLM 消除了这个税。它是一个开源 AI 网关，暴露一个统一的 OpenAI 兼容 API 端点，把请求代理到 100+ LLM 服务商，内置自动故障转移、负载均衡、虚拟 key 和成本追踪。

凭借 22,500+ GitHub Star 和 1,500+ 贡献者，LiteLLM 已经成为想要网关级控制力、又不想被单一厂商锁死的团队的默认选择。这篇 LiteLLM 教程会带你在 30 分钟内走完一套完整的 LLM 网关搭建——从 LiteLLM Docker 部署到虚拟 key 管理，再到 LiteLLM 生产环境监控。

LiteLLM 是什么？ #

LiteLLM 是一个开源的 LLM 代理网关和 Python SDK，用单一 OpenAI 兼容的 API 格式，提供调用 100+ LLM API 的统一接口——OpenAI、Anthropic、Azure、Google Vertex AI、AWS Bedrock、Cohere、Ollama 等等。

它有两种模式：

Python SDK —— 在代码里 import litellm; completion(...)，与服务商无关
代理服务器 —— 一个自托管的 HTTP 网关，跑在 :4000 端口，任何 OpenAI SDK 客户端都能指向它

大多数生产团队用的是代理模式。它追加了虚拟 key、团队管理、预算控制、限速、缓存和可观测性——全部通过单一的 config.yaml 文件配置。

LiteLLM 是怎么工作的 #

请求流程：

你的应用向 http://litellm-proxy:4000/v1/chat/completions 发送一个 OpenAI 格式的请求
LiteLLM 验证虚拟 key，检查团队的预算和速率限制
路由器根据配置的策略（基于延迟、基于成本，或简单负载均衡）选择最佳的模型部署
如果主力服务商返回 429/5xx，会在几毫秒内触发自动故障转移
无论最终是哪个服务商处理的，响应都以 OpenAI 格式流式返回
花费、延迟和 token 数会被记录到 PostgreSQL；同时发出 Prometheus 指标

核心组件：

组件	用途	外部依赖
代理服务器	HTTP API、路由、认证	无（Python/FastAPI）
PostgreSQL	虚拟 key、花费日志、团队数据	生产环境必需
Redis	限速协调、缓存	推荐使用
管理后台	key/模型的网页仪表盘	内置

安装与配置 #

前置条件 #

Docker 24+ 和 Docker Compose v2
PostgreSQL 14+（本地容器，或用托管服务比如 DigitalOcean Managed Postgres）
代理容器最低 2 vCPU / 4GB 内存

第一步：下载 Docker Compose 模板 #

# 创建项目目录
mkdir -p litellm-gateway && cd litellm-gateway

# 下载官方 docker-compose.yml
curl -O https://raw.githubusercontent.com/BerriAI/litellm/main/docker-compose.yml

# 创建环境变量文件
cat > .env << 'EOF'
LITELLM_MASTER_KEY="sk-litellm-admin-$(openssl rand -hex 16)"
LITELLM_SALT_KEY="sk-salt-$(openssl rand -hex 32)"
OPENAI_API_KEY="sk-your-openai-key"
ANTHROPIC_API_KEY="sk-your-anthropic-key"
DATABASE_URL="postgresql://llmproxy:dbpassword9090@db:5432/litellm"
EOF

第二步：创建 config.yaml #

# litellm_config.yaml
model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
      rpm: 500
      tpm: 150000

  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-20250514
      api_key: os.environ/ANTHROPIC_API_KEY
      rpm: 200
      tpm: 40000

  - model_name: gemini-flash
    litellm_params:
      model: gemini/gemini-2.0-flash
      api_key: os.environ/GEMINI_API_KEY
      rpm: 1000

  - model_name: ollama-llama
    litellm_params:
      model: ollama/llama3.3
      api_base: http://ollama:11434
    model_info:
      mode: chat

  # 嵌入模型
  - model_name: text-embedding
    litellm_params:
      model: openai/text-embedding-3-small
      api_key: os.environ/OPENAI_API_KEY

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL
  max_budget: 10000.00
  budget_duration: 30d
  alerting:
    - slack
  alerting_threshold: 300
  global_max_parallel_requests: 200

litellm_settings:
  drop_params: true
  num_retries: 3
  request_timeout: 120

  # 自动故障转移
  fallbacks:
    - gpt-4o:
      - claude-sonnet
      - gemini-flash
    - claude-sonnet:
      - gpt-4o
      - gemini-flash

  # Redis 缓存
  cache: true
  cache_params:
    type: redis
    host: redis
    port: 6379
    ttl: 3600

  # 可观测性回调
  success_callback: ["prometheus"]
  failure_callback: ["prometheus"]

第三步：启动并测试 #

# 拉取并启动所有服务
docker compose up -d

# 验证服务健康状态
docker compose ps

# 查看代理日志
docker compose logs -f litellm

# 测试对话补全
curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "What is LiteLLM?"}]
  }'

# 测试嵌入
curl http://localhost:4000/v1/embeddings \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding",
    "input": ["LiteLLM is an AI gateway"]
  }'

与主流工具集成 #

OpenAI SDK (Python) #

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:4000",
    api_key="sk-your-litellm-virtual-key"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Explain load balancing"}]
)
print(response.choices[0].message.content)

LangChain #

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="claude-sonnet",
    openai_api_key="sk-your-virtual-key",
    openai_api_base="http://localhost:4000"
)

result = llm.invoke("What are the types of LLM gateways?")
print(result.content)

Anthropic SDK（原生兼容） #

from anthropic import Anthropic

client = Anthropic(
    base_url="http://localhost:4000/anthropic",
    api_key="sk-your-virtual-key"
)

response = client.messages.create(
    model="claude-sonnet",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Compare LiteLLM vs OpenRouter"}]
)
print(response.content[0].text)

Ollama（本地模型） #

# 加进 litellm_config.yaml
model_list:
  - model_name: local-llama
    litellm_params:
      model: ollama/llama3.3
      api_base: http://localhost:11434
    model_info:
      mode: chat

# 拉取并启动所有服务
docker compose up -d

# 验证服务健康状态
docker compose ps

# 查看代理日志
docker compose logs -f litellm

# 通过 LiteLLM 测试本地模型
curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local-llama",
    "messages": [{"role": "user", "content": "Hello local model"}]
  }'

Cohere #

model_list:
  - model_name: cohere-command
    litellm_params:
      model: cohere/command-r-plus
      api_key: os.environ/COHERE_API_KEY

from openai import OpenAI
client = OpenAI(base_url="http://localhost:4000", api_key="sk-virtual-key")
response = client.chat.completions.create(
    model="cohere-command",
    messages=[{"role": "user", "content": "Summarize this"}]
)

性能测试 / 真实使用场景 #

一个团队把内部聊天产品和对外 API 客户服务背后的四个服务商 SDK 统一整合到 LiteLLM 之后，前后对比如下：

指标	用 LiteLLM 之前	用 LiteLLM 之后
维护的服务商 SDK 数量	4 个（OpenAI、Anthropic、Gemini、Ollama）	1 个（OpenAI 兼容）
API key 管理	环境变量里的共享 key	按团队/客户分配虚拟 key
成本归因	手动导出 CSV	实时 UI 里按 key 显示花费
故障响应	人工呼叫，平均修复时间 15 分钟	自动故障转移，<500ms
每月 LLM 花费	8500 美元（未优化）	6200 美元（路由优化后降 27%）

网关开销 #

在一台 4 vCPU / 8GB 内存的自托管实例上，LiteLLM 代理本身每次请求只增加几毫秒的路由开销——相比 LLM 服务商自身的响应延迟（占总请求时间的大头），这个开销很小且可预测。

注：网关开销不含 LLM API 的响应时间。LiteLLM 增加的延迟很小、也很可预测。对于每一毫秒都很关键的场景，把代理部署在和你的应用同一个 VPC 里。

进阶用法 / 生产环境加固 #

虚拟 Key 与团队管理 #

虚拟 key 是 LiteLLM 强制执行按团队预算、模型访问权限和速率限制的方式，全程不需要把你真正的服务商 API key 分发出去：

# 为"frontend-team"创建一个虚拟 key
curl -X POST http://localhost:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key_alias": "frontend-team-key",
    "team_id": "frontend-team",
    "models": ["gpt-4o", "gemini-flash"],
    "max_budget": 500.00,
    "budget_duration": "30d",
    "rpm_limit": 100,
    "tpm_limit": 50000,
    "metadata": {
      "service": "customer-chat-widget",
      "env": "production"
    }
  }'

# 响应：
# {
#   "key": "sk-litellm-abc123...",
#   "expires": null,
#   "max_budget": 500.00,
#   "models": ["gpt-4o", "gemini-flash"]
# }

你也可以按上游服务商而不是按 key 设置花费上限，这在多个团队共用同一个 OpenAI 或 Anthropic 账号时很有用：

general_settings:
  provider_budget_config:
    openai:
      monthly_budget: 5000.00
    anthropic:
      monthly_budget: 3000.00
    gemini:
      monthly_budget: 1000.00

基于延迟的路由 #

router_settings:
  routing_strategy: latency-based-routing
  routing_strategy_args:
    ttl: 60
  allowed_fails: 3
  cooldown_time: 60
  num_retries: 2
  timeout: 90
  retry_after: 5

生产环境安全加固 #

# 安全加固版 config.yaml
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL

  # 生产环境强制 HTTPS
  # 部署在 Nginx 或 AWS ALB 之后做 TLS 终止

  # 关闭详细日志
  litellm_settings:
    set_verbose: false

  # 静态加密 key
  litellm_settings:
    key_generation_algorithm: "rsa"
    allow_user_auth: false

Kubernetes / Helm 部署 #

对于超出单台 Docker Compose 主机承载能力的流量，用官方 Helm chart 部署，让 HorizontalPodAutoscaler 在 Kubernetes 下处理扩缩容：

# 添加 LiteLLM Helm 仓库
helm pull oci://docker.litellm.ai/berriai/litellm-helm

# 用自定义值安装
helm install litellm-gateway ./litellm-helm \
  --namespace litellm \
  --create-namespace \
  --set replicaCount=3 \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=litellm.yourdomain.com \
  --set env.LITELLM_MASTER_KEY="sk-$(openssl rand -hex 16)" \
  --set env.DATABASE_URL="postgresql://user:pass@neon-host/litellm"

用 Prometheus + Grafana 监控 #

# 加进 config.yaml
litellm_settings:
  success_callback: ["prometheus"]
  failure_callback: ["prometheus"]

用 Prometheus 抓取暴露出来的 /metrics 端点：

# 按模型统计请求速率
rate(litellm_request_total_requests[5m])

# 错误率
rate(litellm_requests_total_failed[5m])

# 每个 key 剩余预算
litellm_remaining_requests

# 网关开销直方图
histogram_quantile(0.95, litellm_overhead_latency_ms_bucket)

导入 LiteLLM 官方的 Grafana 仪表盘 JSON，能直接用上展示每秒请求数、token 用量、每团队成本和延迟百分位的预制面板。

与其他方案对比 #

特性	LiteLLM	Portkey	OpenRouter	Helicone
协议	MIT（开源）	闭源核心 + 开源 SDK	闭源（托管）	闭源（托管+自托管）
部署方式	自托管 / Docker / K8s	云端 + 混合	仅托管	云端 + 自托管
支持的模型	100+ 服务商	200+	300+	视服务商而定
自托管成本	每月 200-800 美元基础设施	不适用（托管）	不适用（托管）	每月 0-100 美元（自托管）
虚拟 key / 预算	按 key + 按团队	按 key + 按用户	基础按 key	按组织
自动故障转移	可配置的链路	断路器	服务商路由	有限
语义缓存	Redis + Qdrant	内置	无	无
可观测性	Prometheus + 外部工具	内置深度追踪	基础用量统计	主打功能
合规	自行搭建（靠基础设施实现 SOC2）	SOC 2, ISO 27001, HIPAA	部分支持	SOC 2
最适合	完全掌控，零锁定	企业治理	快速接入模型	可观测性优先

该怎么选：

LiteLLM —— 你有 DevOps 能力，想要零厂商锁定，需要对路由、缓存和数据归属地有完全控制权。
Portkey —— 你需要企业级治理（SOC 2、审计日志）、提示词管理界面，也愿意付 SaaS 价格。
OpenRouter —— 你想零基础设施工作量、即时访问 300+ 模型，能接受 5.5% 的充值手续费。
Helicone —— 可观测性是你的首要关切；你需要跨 LLM 调用的详细追踪和成本归因。

局限性 / 真实评估 #

LiteLLM 并不适合所有团队。生产环境中有两点局限尤其突出：

没有内置的多区域故障转移 —— LiteLLM 默认是单区域代理。如果你需要自动跨区域故障转移，得自己在多个 LiteLLM 部署前面用 DNS 或全局负载均衡器搭建。
企业级 SSO 要花钱 —— SAML/SSO、审计日志和高级护栏功能属于 LiteLLM Enterprise，不在开源版本里。开源版只处理虚拟 key 和基础预算管理。

常见问题 #

问：LiteLLM 和 OpenRouter 比怎么样？ LiteLLM 是自托管的开源网关；OpenRouter 是托管的多模型 API。LiteLLM 不加价，对你的数据有完全控制权。OpenRouter 对充值收取 5.5% 手续费，但不需要任何基础设施工作量。对于每月 LLM 花费超过 5000 美元、又有 DevOps 能力的团队，长期看 LiteLLM 更省钱；对于想完全不折腾基础设施的团队，OpenRouter 更简单。

问：怎么把现有的 OpenAI SDK 代码迁移到 LiteLLM？ 把你现有 OpenAI SDK 客户端的 base_url 指向你的 LiteLLM 代理，把 api_key 换成一个虚拟 key。其他一切——模型名、消息格式、流式传输——都不用变。这正是团队采用 LiteLLM 的主要原因：除了配置之外零代码改动。

问：LiteLLM 需要什么数据库？ 生产部署需要 PostgreSQL 14+；它存储虚拟 key、花费日志和团队数据。推荐（非必需）用 Redis 做限速协调和缓存。两者都用于预算管理、团队管理和管理后台。

问：故障转移机制是怎么工作的？ 你在 config.yaml 里定义故障转移链路。如果一个模型返回 429、500 或超时，LiteLLM 会自动对配置好的故障转移链路里的下一个模型重试请求，调用方完全无感知。

问：怎么为高流量扩展 LiteLLM？ 先用上面的 Docker Compose 配置起步，加上 Redis 缓存，随着流量增长再迁移到 Kubernetes 上的官方 Helm chart——给代理设置 replicaCount，并配置 HorizontalPodAutoscaler (HPA) 在 Kubernetes 下自动扩缩容。

问：怎么在生产环境监控 LiteLLM？ 在 config.yaml 里开启 Prometheus 回调，抓取 /metrics 端点，导入官方 Grafana 仪表盘。给 litellm_requests_total_failed（错误率）和 litellm_remaining_requests（预算耗尽）设置告警。把 success_callback 接到 Langfuse 做逐请求追踪。

结语 #

LiteLLM 解决的是针对多个 LLM 服务商跑生产软件这件事本身的混乱现实：一个 OpenAI 兼容端点、自动故障转移、带预算的虚拟 key，以及内置可观测性，全部通过单一的 config.yaml 配置。先用上面的 Docker Compose 配置起步，加上 Redis 缓存，随着流量增长再用 Helm 扩展到 Kubernetes。

行动清单：

克隆 LiteLLM GitHub 仓库，跑一遍 Docker Compose 快速开始
为每个团队创建虚拟 key，设置按 key 的预算
开启 Redis 缓存和 Prometheus 监控
加入 LiteLLM Discord 社区获取支持并参与功能讨论

本文部分链接为联盟链接。如果你通过这些链接购买主机服务，我们可能获得佣金——这不会影响价格或我们的推荐。

来源与延伸阅读 #

LiteLLM GitHub 仓库 — 官方源码，22,500+ Star
LiteLLM 文档 — 完整的代理和 SDK 参考
LiteLLM Docker 快速开始 — 官方 Docker 配置指南
LiteLLM 配置参考 — 全部 config.yaml 选项
LiteLLM Helm 部署 — Kubernetes 和 Helm chart
LiteLLM 管理后台文档 — 虚拟 key 和团队管理
LiteLLM 缓存指南 — Redis、语义缓存和磁盘缓存
Portkey vs LiteLLM 对比 — 厂商对比页面
OpenRouter 文档 — 替代网关参考
Helicone 文档 — 以可观测性为主打的替代方案

LiteLLM — 统一的 OpenAI 兼容 API，接入 100+ LLM 服务商

📦 资源信息

简介 #

LiteLLM 是什么？ #

LiteLLM 是怎么工作的 #

安装与配置 #

前置条件 #

第一步：下载 Docker Compose 模板 #

第二步：创建 config.yaml #

第三步：启动并测试 #

与主流工具集成 #

OpenAI SDK (Python) #

LangChain #

Anthropic SDK（原生兼容） #

Ollama（本地模型） #

Cohere #

性能测试 / 真实使用场景 #

网关开销 #

进阶用法 / 生产环境加固 #

虚拟 Key 与团队管理 #

基于延迟的路由 #

生产环境安全加固 #

Kubernetes / Helm 部署 #

用 Prometheus + Grafana 监控 #

与其他方案对比 #

局限性 / 真实评估 #

常见问题 #

结语 #

推荐的托管与基础设施 #

来源与延伸阅读 #

💬 留言讨论

📦 资源信息

简介 #

LiteLLM 是什么？ #

LiteLLM 是怎么工作的 #

安装与配置 #

前置条件 #

第一步：下载 Docker Compose 模板 #

第二步：创建 config.yaml #

第三步：启动并测试 #

与主流工具集成 #

OpenAI SDK (Python) #

LangChain #

Anthropic SDK（原生兼容） #

Ollama（本地模型） #

Cohere #

性能测试 / 真实使用场景 #

网关开销 #

进阶用法 / 生产环境加固 #

虚拟 Key 与团队管理 #

基于延迟的路由 #

生产环境安全加固 #

Kubernetes / Helm 部署 #

用 Prometheus + Grafana 监控 #

与其他方案对比 #

局限性 / 真实评估 #

常见问题 #

结语 #

推荐的托管与基础设施 #

来源与延伸阅读 #

🔗 相关资源推荐

💬 留言讨论