LiteLLM 深度解析:100+ 大模型统一网关的架构设计与生产实战
当你的团队同时调用 OpenAI、Anthropic、Gemini、Bedrock、Azure 以及本地部署的 Qwen 和 DeepSeek 时,你是怎么管理的?每个 SDK 写一套?密钥散落在代码里?换模型就改业务代码?如果你点头了,这篇文章就是写给你的。
一、为什么你需要一个 LLM 网关
1.1 多模型时代的混乱现状
2026 年的大模型生态已经不能用"百花齐放"来形容了——简直是丛林。一个中等规模的技术团队,日常需要打交道的大模型 API 少则五六个,多则十几个:
| 服务商 | 模型 | API 格式 | 认证方式 |
|---|---|---|---|
| OpenAI | GPT-4o, GPT-5.4 | OpenAI Format | Bearer Token |
| Anthropic | Claude Sonnet 4, Claude 4.6 | Messages API | x-api-key |
| Gemini 3.1 Pro | Vertex AI Format | Service Account | |
| AWS | Bedrock (多模型) | Bedrock Format | AWS SigV4 |
| Azure | Azure OpenAI | OpenAI Format (部分差异) | API Key + Endpoint |
| DeepSeek | DeepSeek-V4 | OpenAI 兼容 | Bearer Token |
| 本地部署 | Qwen, Llama, Mistral | OpenAI 兼容 (vLLM) | 可选认证 |
看到了吗?六种不同的调用方式、至少四种认证模式、三种不同的消息格式。如果你在代码里直接集成了这些 SDK,你的项目大概是这个样子的:
# 典型的多模型混乱代码
from openai import OpenAI
from anthropic import Anthropic
import google.cloud.aiplatform as aiplatform
import boto3
# 每个模型一套客户端,每套一套初始化逻辑
openai_client = OpenAI(api_key="sk-xxx")
anthropic_client = Anthropic(api_key="sk-ant-xxx")
bedrock_client = boto3.client("bedrock-runtime", region_name="us-east-1")
def call_gpt4(prompt: str) -> str:
response = openai_client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": prompt}]
)
return response.choices[0].message.content
def call_claude(prompt: str) -> str:
response = anthropic_client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=4096,
messages=[{"role": "user", "content": prompt}]
)
return response.content[0].text
def call_bedrock(prompt: str) -> str:
# Bedrock 的调用方式完全不同...
import json
response = bedrock_client.invoke_model(
modelId="anthropic.claude-3-sonnet-20240229-v1:0",
body=json.dumps({
"anthropic_version": "bedrock-2023-05-31",
"messages": [{"role": "user", "content": prompt}],
"max_tokens": 4096
})
)
return json.loads(response["body"].read())["content"][0]["text"]
# 业务代码里到处都是 if-else
def get_answer(prompt: str, model: str = "gpt4") -> str:
if model == "gpt4":
return call_gpt4(prompt)
elif model == "claude":
return call_claude(prompt)
elif model == "bedrock":
return call_bedrock(prompt)
else:
raise ValueError(f"Unknown model: {model}")
这段代码的问题一目了然:
- 密钥硬编码:API Key 直接写在代码里,即便你用环境变量,分散在十几个地方也不可控
- 切换成本高:想从 GPT-4 切到 Claude?改业务代码。想做 A/B 测试?再写一套
- 监控缺失:哪个模型花了多少钱?哪个团队用了多少 token?一无所知
- 降级困难:GPT-4 挂了怎么办?手工切?半夜三点谁来切?
- 代码膨胀:每加一个模型就多一套适配代码,维护成本线性增长
1.2 LLM 网关的核心价值
类比一下微服务架构中的 API Gateway——你不会让每个前端服务直接连后端的每个微服务吧?LLM 网关就是 AI 应用架构中的 API Gateway:
┌─────────────────────────────────────────────────┐
│ 你的应用层 │
│ (ChatBot / Coding Assistant / RAG Pipeline) │
└──────────────────┬──────────────────────────────┘
│ 统一 OpenAI 格式
▼
┌──────────────────────────────────────────────────┐
│ LiteLLM AI Gateway │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ 认证鉴权 │ │ 路由负载 │ │ 成本追踪 │ │
│ └──────────┘ └──────────┘ └──────────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ 限流熔断 │ │ 降级兜底 │ │ 审计日志 │ │
│ └──────────┘ └──────────┘ └──────────────┘ │
└───┬──────┬──────┬──────┬──────┬──────┬──────────┘
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
OpenAI Anthropic Gemini Bedrock Azure 本地模型
核心价值就四个字:统一管控。
- 统一接口:一套 OpenAI 格式调用所有模型
- 统一认证:虚拟密钥体系,不暴露真实 API Key
- 统一监控:调用次数、Token 用量、费用支出,全链路可观测
- 统一治理:限流、降级、负载均衡,生产级高可用
二、LiteLLM 核心概念与双模式架构
2.1 两种使用模式
LiteLLM 提供了两种互补的使用方式:
Python SDK 模式——适合个人开发者、脚本工具、原型验证:
from litellm import completion
import os
# 设置密钥(实际项目用环境变量)
os.environ["OPENAI_API_KEY"] = "sk-xxx"
os.environ["ANTHROPIC_API_KEY"] = "sk-ant-xxx"
# 调用 OpenAI——和原生 SDK 几乎一样
response = completion(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "解释量子计算"}]
)
print(response.choices[0].message.content)
# 切到 Claude——只改 model 参数,其他代码不动
response = completion(
model="anthropic/claude-sonnet-4-20250514",
messages=[{"role": "user", "content": "解释量子计算"}]
)
print(response.choices[0].message.content)
# 调用本地 vLLM 部署的 Qwen——加个前缀就行
response = completion(
model="openai/Qwen3-Coder-30B-A3B-Instruct",
api_base="http://localhost:8100/v1",
api_key="local-no-key",
messages=[{"role": "user", "content": "解释量子计算"}]
)
看到区别了吗?model 参数用 provider/model-name 格式,LiteLLM 自动识别并路由到正确的 API。返回值统一为 OpenAI 的响应格式——不管底层是哪个模型。
Proxy Server 模式——适合团队协作、生产环境、企业级部署:
# 安装
uv tool install 'litellm[proxy]'
# 启动——最简模式,单模型
litellm --model gpt-4o --port 4000
启动后,任何支持 OpenAI 格式的客户端都可以直接连:
import openai
# 只需要改 base_url,其他代码完全不变
client = openai.OpenAI(
api_key="anything", # 网关自己的虚拟密钥
base_url="http://0.0.0.0:4000"
)
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Hello!"}]
)
这意味着你已有的 OpenAI SDK 代码——LangChain、LlamaIndex、CrewAI、AutoGen——全部零改动接入。
2.2 内部架构:从请求到响应的完整链路
当你通过 Proxy Server 发起一个请求时,LiteLLM 内部经历了以下流程:
客户端请求 (OpenAI 格式)
│
▼
┌─────────────────┐
│ 认证中间件 │ ← 验证 Virtual Key / Master Key
└────────┬────────┘
│
▼
┌─────────────────┐
│ 请求预处理 │ ← 参数映射、模型名解析、路由选择
└────────┬────────┘
│
▼
┌─────────────────┐
│ 限流检查 │ ← RPM / TPM / 并发数 / 预算
└────────┬────────┘
│
▼
┌─────────────────┐
│ Pre-call Hook │ ← 自定义 Guardrails / 内容审核
└────────┬────────┘
│
▼
┌─────────────────┐
│ Provider 适配 │ ← 转换为目标 Provider 的格式
└────────┬────────┘
│
▼
┌─────────────────┐
│ 实际 API 调用 │ ← HTTP 请求 + 重试 + 超时控制
└────────┬────────┘
│
▼
┌─────────────────┐
│ 响应后处理 │ ← 格式统一 + 成本计算 + 日志记录
└────────┬────────┘
│
▼
┌─────────────────┐
│ Post-call Hook │ ← 自定义后处理 / 审计
└────────┬────────┘
│
▼
统一 OpenAI 格式响应
这个中间件链是 LiteLLM 最核心的设计。每一个环节都可以自定义、可插拔、可扩展。
2.3 模型名路由机制
LiteLLM 用 provider/model-name 的命名约定来路由请求,这比维护一个路由表要简洁得多:
# config.yaml 中的模型配置
model_list:
- model_name: gpt-4o # 对外暴露的逻辑名
litellm_params:
model: openai/gpt-4o # 实际路由目标
api_key: os.environ/OPENAI_API_KEY
- model_name: gpt-4o # 同一个逻辑名,多个后端 → 负载均衡
litellm_params:
model: azure/gpt-4o-eastus
api_base: https://my-azure.openai.azure.com
api_key: os.environ/AZURE_API_KEY
- model_name: claude-sonnet
litellm_params:
model: anthropic/claude-sonnet-4-20250514
api_key: os.environ/ANTHROPIC_API_KEY
- model_name: local-qwen
litellm_params:
model: openai/Qwen3-Coder-30B-A3B-Instruct
api_base: http://192.168.1.100:8100/v1
api_key: local-key
drop_params: true # 丢弃不支持的参数,避免报错
关键点:当 model_name 相同时,LiteLLM 会在这些部署之间做负载均衡和故障转移——后面会详细讲。
三、Python SDK 深度实战
3.1 基础调用:覆盖所有主流 Provider
import litellm
import os
# ========== OpenAI ==========
os.environ["OPENAI_API_KEY"] = "sk-xxx"
resp = litellm.completion(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "写一个快排"}],
temperature=0.7,
max_tokens=2048
)
# ========== Anthropic ==========
os.environ["ANTHROPIC_API_KEY"] = "sk-ant-xxx"
resp = litellm.completion(
model="anthropic/claude-sonnet-4-20250514",
messages=[{"role": "user", "content": "写一个快排"}],
max_tokens=2048
)
# ========== Google Gemini (Vertex AI) ==========
# 需要配置 Google Cloud 认证
resp = litellm.completion(
model="vertex_ai/gemini-3.1-pro",
messages=[{"role": "user", "content": "写一个快排"}]
)
# ========== AWS Bedrock ==========
# 需要 AWS 凭证配置
resp = litellm.completion(
model="bedrock/anthropic.claude-3-sonnet-20240229-v1:0",
messages=[{"role": "user", "content": "写一个快排"}]
)
# ========== Azure OpenAI ==========
resp = litellm.completion(
model="azure/my-gpt4-deployment",
api_base="https://my-resource.openai.azure.com",
api_key=os.environ["AZURE_API_KEY"],
api_version="2024-12-01-preview",
messages=[{"role": "user", "content": "写一个快排"}]
)
# ========== DeepSeek (OpenAI 兼容) ==========
resp = litellm.completion(
model="openai/deepseek-v4",
api_base="https://api.deepseek.com/v1",
api_key=os.environ["DEEPSEEK_API_KEY"],
messages=[{"role": "user", "content": "写一个快排"}]
)
# ========== 本地 vLLM/Ollama ==========
resp = litellm.completion(
model="openai/Qwen3-235B-A22B",
api_base="http://localhost:8000/v1",
api_key="fake-key",
messages=[{"role": "user", "content": "写一个快排"}]
)
3.2 流式输出
# 流式调用——和 OpenAI SDK 完全一致
response = litellm.completion(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "写一篇关于 Rust 的技术博客"}],
stream=True
)
for chunk in response:
content = chunk.choices[0].delta.content or ""
print(content, end="", flush=True)
3.3 异步调用
import litellm
import asyncio
async def multi_model_query(prompt: str):
"""同时向多个模型发请求,取最快返回的结果"""
tasks = [
litellm.acompletion(
model="openai/gpt-4o",
messages=[{"role": "user", "content": prompt}]
),
litellm.acompletion(
model="anthropic/claude-sonnet-4-20250514",
messages=[{"role": "user", "content": prompt}]
),
]
# 谁先回来用谁
done, pending = await asyncio.wait(
tasks, return_when=asyncio.FIRST_COMPLETED
)
for task in pending:
task.cancel()
result = done.pop().result()
return result.choices[0].message.content
# 运行
result = asyncio.run(multi_model_query("解释 Transformer 架构"))
print(result)
3.4 Embedding 调用
# 文本嵌入——同样统一格式
response = litellm.embedding(
model="openai/text-embedding-3-large",
input=["这是一段中文文本", "这是另一段文本"]
)
print(response.data[0]["embedding"][:5]) # 嵌入向量的前5维
# 用 Azure 的嵌入模型
response = litellm.embedding(
model="azure/my-embedding-deployment",
input=["这是测试文本"],
api_base="https://my-resource.openai.azure.com",
api_key=os.environ["AZURE_API_KEY"]
)
3.5 Function Calling / Tool Use
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "获取指定城市的天气信息",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "城市名称"
}
},
"required": ["city"]
}
}
}
]
# 不管底层模型是什么,Tool Use 格式统一
response = litellm.completion(
model="anthropic/claude-sonnet-4-20250514",
messages=[{"role": "user", "content": "北京今天天气怎么样"}],
tools=tools,
tool_choice="auto"
)
# 解析工具调用
if response.choices[0].finish_reason == "tool_calls":
tool_calls = response.choices[0].message.tool_calls
for call in tool_calls:
print(f"调用函数: {call.function.name}")
print(f"参数: {call.function.arguments}")
四、Proxy Server 生产级部署
4.1 Docker Compose 完整配置
这是我在生产环境中使用的完整配置,包含了数据库、缓存和监控:
# docker-compose.yml
services:
litellm:
image: ghcr.io/berriai/litellm:main-stable
ports:
- "4000:4000"
volumes:
- ./config.yaml:/app/config.yaml
environment:
- DATABASE_URL=postgresql://llmproxy:${DB_PASSWORD}@db:5432/litellm
- STORE_MODEL_IN_DB=True
- REDIS_HOST=redis
- REDIS_PORT=6379
- REDIS_PASSWORD=${REDIS_PASSWORD}
- LITELLM_MASTER_KEY=${MASTER_KEY}
- SET_DB_ORDER=1 # 确保数据库初始化顺序
env_file:
- .env # 各模型的 API Key
depends_on:
db:
condition: service_healthy
redis:
condition: service_healthy
healthcheck:
test: ["CMD-SHELL", "python3 -c \"import urllib.request; urllib.request.urlopen('http://localhost:4000/health')\""]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
restart: unless-stopped
deploy:
resources:
limits:
cpus: "2.0"
memory: 4G
db:
image: postgres:16-alpine
environment:
- POSTGRES_USER=llmproxy
- POSTGRES_PASSWORD=${DB_PASSWORD}
- POSTGRES_DB=litellm
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U llmproxy"]
interval: 10s
timeout: 5s
retries: 5
restart: unless-stopped
redis:
image: redis:7-alpine
command: redis-server --requirepass ${REDIS_PASSWORD} --maxmemory 256mb --maxmemory-policy allkeys-lru
healthcheck:
test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD}", "ping"]
interval: 10s
timeout: 5s
retries: 5
restart: unless-stopped
prometheus:
image: prom/prometheus:latest
ports:
- "9090:9090"
volumes:
- ./prometheus.yml:/etc/prometheus/prometheus.yml
restart: unless-stopped
volumes:
pgdata:
4.2 config.yaml 配置详解
这是 LiteLLM 的核心配置文件,决定了网关的行为:
# config.yaml —— 生产级配置
model_list:
# ===== GPT-4o 双区域负载均衡 =====
- model_name: gpt-4o
litellm_params:
model: azure/gpt-4o-eastus
api_base: https://my-eastus.openai.azure.com
api_key: os.environ/AZURE_EASTUS_API_KEY
api_version: "2024-12-01-preview"
- model_name: gpt-4o
litellm_params:
model: azure/gpt-4o-westus
api_base: https://my-westus.openai.azure.com
api_key: os.environ/AZURE_WESTUS_API_KEY
api_version: "2024-12-01-preview"
# ===== Claude Sonnet 4 =====
- model_name: claude-sonnet
litellm_params:
model: anthropic/claude-sonnet-4-20250514
api_key: os.environ/ANTHROPIC_API_KEY
# ===== DeepSeek V4 (低成本备选) =====
- model_name: deepseek-v4
litellm_params:
model: openai/deepseek-v4
api_base: https://api.deepseek.com/v1
api_key: os.environ/DEEPSEEK_API_KEY
# ===== 本地 Qwen (代码场景) =====
- model_name: local-qwen-coder
litellm_params:
model: openai/Qwen3-Coder-30B-A3B-Instruct
api_base: http://192.168.1.100:8100/v1
api_key: local-no-key
drop_params: true # 自动丢弃不支持的参数
# ===== 嵌入模型 =====
- model_name: text-embedding
litellm_params:
model: openai/text-embedding-3-large
api_key: os.environ/OPENAI_API_KEY
# ===== 路由策略 =====
router_settings:
routing_strategy: usage-based-routing-v2 # 基于用量的智能路由
num_retries: 3 # 重试次数
timeout: 60 # 超时秒数
retry_after: 0 # 重试间隔
allowed_fails: 3 # 允许失败次数(超过则冷却)
cooldown_time: 60 # 冷却时间(秒)
# ===== 通用设置 =====
litellm_settings:
drop_params: true # 全局:丢弃不支持的参数
set_verbose: false # 关闭详细日志(生产环境)
json_logs: true # JSON 格式日志
cache: true # 启用缓存
cache_params:
type: redis # 使用 Redis 缓存
namespace: litellm_cache
# ===== 限流配置 =====
rate_limit_settings:
default_rate_limit:
rpm: 100 # 默认每分钟请求数
tpm: 100000 # 默认每分钟 Token 数
4.3 环境变量管理
# .env 文件(不要提交到 Git!)
AZURE_EASTUS_API_KEY=xxx
AZURE_WESTUS_API_KEY=xxx
ANTHROPIC_API_KEY=sk-ant-xxx
DEEPSEEK_API_KEY=sk-xxx
OPENAI_API_KEY=sk-xxx
# 数据库和缓存
DB_PASSWORD=your-strong-db-password
REDIS_PASSWORD=your-strong-redis-password
MASTER_KEY=sk-your-master-key-here
安全最佳实践:
# 1. .env 文件权限
chmod 600 .env
# 2. .gitignore 确保
echo ".env" >> .gitignore
# 3. 生产环境建议用密钥管理服务
# AWS Secrets Manager / Azure Key Vault / HashiCorp Vault
# LiteLLM 支持从环境变量读取,可以结合这些服务注入
4.4 启动与验证
# 启动所有服务
docker compose up -d
# 检查健康状态
curl http://localhost:4000/health
# 创建虚拟密钥(首次使用)
curl -X POST 'http://localhost:4000/key/generate' \
-H 'Authorization: Bearer sk-your-master-key-here' \
-H 'Content-Type: application/json' \
-d '{
"models": ["gpt-4o", "claude-sonnet", "deepseek-v4"],
"max_budget": 100.0,
"budget_duration": "30d",
"metadata": {"team": "backend"}
}'
# 返回的 key 就是给团队成员用的虚拟密钥
# 示例响应:{"key": "sk-projects-abc123..."}
# 测试调用
curl -X POST 'http://localhost:4000/v1/chat/completions' \
-H 'Authorization: Bearer sk-projects-abc123...' \
-H 'Content-Type: application/json' \
-d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "Hello!"}]
}'
五、虚拟密钥体系:企业级安全管控
5.1 为什么需要虚拟密钥
想象一个场景:你的团队有 20 个人在用大模型 API。如果每个人手里都有真实的 API Key:
- 有人离职了,Key 泄露风险
- 没法控制每个人的用量和预算
- 无法追踪是谁、在什么时候、调用了什么模型
- 无法按项目/团队分账
LiteLLM 的虚拟密钥体系完美解决了这些问题:
┌──────────────────────────────────────┐
│ 真实 API Key │
│ (只存在 LiteLLM 服务端) │
│ sk-openai-xxx │
│ sk-ant-xxx │
│ azure-key-xxx │
└──────────────────────────────────────┘
▲
│ 内部路由
│
┌──────────────────────────────────────┐
│ LiteLLM Proxy Server │
│ │
│ ┌─────────┐ ┌─────────┐ │
│ │ Key A │ │ Key B │ │
│ │Team A │ │Team B │ │
│ │$50/day │ │$100/day │ │
│ │GPT4+Claude│ │全模型 │ │
│ └─────────┘ └─────────┘ │
│ ┌─────────┐ ┌─────────┐ │
│ │ Key C │ │ Key D │ │
│ │Dev-zhang│ │Dev-li │ │
│ │$10/day │ │$20/day │ │
│ │GPT4 only│ │Claude │ │
│ └─────────┘ └─────────┘ │
└──────────────────────────────────────┘
▲
│ 虚拟密钥认证
│
┌──────────────────────────────────────┐
│ 团队成员 │
│ 只知道自己的虚拟密钥 │
│ 从不接触真实 API Key │
└──────────────────────────────────────┘
5.2 密钥管理的完整操作
# 创建团队级密钥(按预算限制)
curl -X POST 'http://localhost:4000/key/generate' \
-H 'Authorization: Bearer sk-master-key' \
-H 'Content-Type: application/json' \
-d '{
"key_alias": "backend-team",
"models": ["gpt-4o", "claude-sonnet", "deepseek-v4"],
"max_budget": 500.0,
"budget_duration": "30d",
"max_parallel_requests": 10,
"tpm_limit": 50000,
"rpm_limit": 100,
"metadata": {
"team": "backend",
"owner": "zhangsan"
}
}'
# 创建个人开发密钥(更严格限制)
curl -X POST 'http://localhost:4000/key/generate' \
-H 'Authorization: Bearer sk-master-key' \
-H 'Content-Type: application/json' \
-d '{
"key_alias": "dev-lisi",
"models": ["deepseek-v4", "local-qwen-coder"],
"max_budget": 20.0,
"budget_duration": "7d",
"max_parallel_requests": 3,
"metadata": {
"team": "frontend",
"developer": "lisi"
}
}'
# 查看密钥信息
curl -X GET 'http://localhost:4000/key/info?key=sk-projects-abc123' \
-H 'Authorization: Bearer sk-master-key'
# 更新密钥(调整预算、权限)
curl -X POST 'http://localhost:4000/key/update' \
-H 'Authorization: Bearer sk-master-key' \
-H 'Content-Type: application/json' \
-d '{
"key": "sk-projects-abc123",
"max_budget": 800.0,
"models": ["gpt-4o", "claude-sonnet", "deepseek-v4", "local-qwen-coder"]
}'
# 删除/吊销密钥
curl -X POST 'http://localhost:4000/key/delete' \
-H 'Authorization: Bearer sk-master-key' \
-H 'Content-Type: application/json' \
-d '{"keys": ["sk-projects-abc123"]}'
5.3 成本追踪与预算告警
# 查看全局支出
curl -X GET 'http://localhost:4000/spend/tags' \
-H 'Authorization: Bearer sk-master-key'
# 查看特定密钥的支出
curl -X GET 'http://localhost:4000/key/info?key=sk-projects-abc123' \
-H 'Authorization: Bearer sk-master-key'
# 响应中包含 spend、max_budget、budget_duration 等信息
# 按模型查支出
curl -X GET 'http://localhost:4000/global/spend/models?startDate=2026-04-01&endDate=2026-04-30' \
-H 'Authorization: Bearer sk-master-key'
LiteLLM 内置了精确的成本计算,基于各模型的官方定价表自动核算每次调用的花费。你不需要自己维护定价数据——LiteLLM 会随着官方价格变动更新。
六、负载均衡与故障降级
6.1 多部署负载均衡
当你在多个区域部署了同一个模型时,LiteLLM 可以自动做负载均衡:
# 同一逻辑名配置多个后端 → 自动负载均衡
model_list:
- model_name: gpt-4o
litellm_params:
model: azure/gpt-4o-eastus
api_base: https://eastus.openai.azure.com
api_key: os.environ/AZURE_EASTUS_KEY
- model_name: gpt-4o
litellm_params:
model: azure/gpt-4o-westus
api_base: https://westus.openai.azure.com
api_key: os.environ/AZURE_WESTUS_KEY
- model_name: gpt-4o
litellm_params:
model: openai/gpt-4o
api_key: os.environ/OPENAI_API_KEY
router_settings:
routing_strategy: usage-based-routing-v2
# 基于使用量的路由:优先选择剩余配额最多的部署
# 如果一个部署的 TPM 限额快满了,自动切换到下一个
路由策略选项:
| 策略 | 说明 | 适用场景 |
|---|---|---|
simple-shuffle | 随机选择 | 同质部署,无状态偏好 |
least-busy | 选最空闲的 | 请求量波动大 |
usage-based-routing-v2 | 基于剩余配额 | 有 TPM/RPM 限额 |
latency-based-routing | 选延迟最低的 | 对响应时间敏感 |
cost-based-routing | 选成本最低的 | 预算敏感场景 |
6.2 自动降级与 Fallback
# Fallback 配置:主模型挂了自动切到备选
model_list:
- model_name: gpt-4o
litellm_params:
model: openai/gpt-4o
api_key: os.environ/OPENAI_API_KEY
- model_name: gpt-4o-fallback
litellm_params:
model: azure/gpt-4o-eastus
api_base: https://eastus.openai.azure.com
api_key: os.environ/AZURE_KEY
- model_name: claude-sonnet
litellm_params:
model: anthropic/claude-sonnet-4-20250514
api_key: os.environ/ANTHROPIC_API_KEY
- model_name: deepseek-v4
litellm_params:
model: openai/deepseek-v4
api_base: https://api.deepseek.com/v1
api_key: os.environ/DEEPSEEK_API_KEY
# 关键:fallback 链配置
router_settings:
num_retries: 2
allowed_fails: 3
cooldown_time: 120
fallbacks:
- gpt-4o: ["gpt-4o-fallback", "claude-sonnet", "deepseek-v4"]
- claude-sonnet: ["gpt-4o", "deepseek-v4"]
这意味着:
- 请求
gpt-4o→ OpenAI 返回 429/500 → 自动重试 2 次 - 仍然失败 → 切到
gpt-4o-fallback(Azure) - Azure 也失败 → 切到
claude-sonnet - Claude 也失败 → 最后尝试
deepseek-v4 - 全部失败 → 返回错误
对于用户来说,这一切都是透明的——他们只知道请求 gpt-4o,得到了结果。
6.3 冷却机制
router_settings:
allowed_fails: 3 # 连续失败 3 次后,该部署进入冷却
cooldown_time: 120 # 冷却 120 秒,期间不再路由到该部署
冷却机制防止了"雪崩效应":当一个后端服务出现问题时,不会持续把请求打向一个不可用的服务,而是自动绕过它,给它恢复的时间。
七、Guardrails 与内容安全
7.1 内置内容审核
# config.yaml
litellm_settings:
guardrails:
- guardrail_name: "content-moderation"
litellm_params:
guardrail: aim # 使用 AIM Guardrail
mode: "during_call" # 调用中检查
default_on: true # 默认开启
7.2 自定义 Pre-call/Post-call Hooks
# custom_hooks.py
from litellm.integrations.custom_logger import CustomLogger
from litellm.proxy._types import UserAPIKeyAuth
class MyCustomGuardrail(CustomLogger):
"""自定义 Guardrail:检查请求内容,拦截敏感信息"""
async def async_pre_call_hook(
self,
user_api_key_dict: UserAPIKeyAuth,
cache: dict,
data: dict,
call_type: str,
) -> Exception | str | None:
"""请求前的拦截逻辑"""
messages = data.get("messages", [])
for msg in messages:
content = msg.get("content", "")
# 检查是否包含敏感信息
if any(keyword in content.lower() for keyword in
["密码", "password", "secret", "api_key"]):
return Exception(
"🚫 请求被拦截:检测到可能包含敏感信息的内容。"
"请不要在对话中传递密码或密钥。"
)
# 检查模型权限
model = data.get("model", "")
allowed_models = user_api_key_dict.models
if allowed_models and model not in allowed_models:
return Exception(
f"🚫 权限不足:你的密钥无权访问模型 {model}"
)
return None # 放行
async def async_post_call_hook(
self,
user_api_key_dict: UserAPIKeyAuth,
cache: dict,
data: dict,
response: dict,
) -> None:
"""响应后的处理逻辑"""
# 记录审计日志
model = data.get("model", "")
usage = response.get("usage", {})
print(f"[审计] 模型: {model}, "
f"Token: {usage.get('total_tokens', 0)}, "
f"用户: {user_api_key_dict.key_alias}")
# 注册
custom_guardrail = MyCustomGuardrail()
在 config.yaml 中引用:
litellm_settings:
callbacks: custom_hooks
八、与开发工具链的集成
8.1 接入 Claude Code
Claude Code 已经和 OpenAI 分道扬镳,它使用 Anthropic 原生接口。通过 LiteLLM 可以让它接入任何模型:
# 步骤 1: 配置 LiteLLM
# litellm_config.yaml
model_list:
- model_name: claude-sonnet-4-20250514
litellm_params:
model: openai/Qwen3-Coder-30B-A3B-Instruct
api_base: http://192.168.1.100:8100/v1
api_key: local-key
drop_params: true
max_tokens: 66912
# 步骤 2: 启动 LiteLLM
litellm --config litellm_config.yaml --port 4000
# 步骤 3: 配置 Claude Code 使用 LiteLLM
export ANTHROPIC_BASE_URL=http://localhost:4000
export ANTHROPIC_API_KEY=sk-your-litellm-key
8.2 接入 VS Code Continue 插件
// ~/.continue/config.json
{
"models": [
{
"title": "GPT-4o (via LiteLLM)",
"provider": "openai",
"model": "gpt-4o",
"apiBase": "http://localhost:4000/v1",
"apiKey": "sk-your-litellm-key"
},
{
"title": "Claude Sonnet (via LiteLLM)",
"provider": "openai",
"model": "claude-sonnet",
"apiBase": "http://localhost:4000/v1",
"apiKey": "sk-your-litellm-key"
}
]
}
8.3 接入 LangChain
from langchain_openai import ChatOpenAI
# 代码完全不变,只改 base_url
llm = ChatOpenAI(
model="gpt-4o",
base_url="http://localhost:4000/v1",
api_key="sk-your-litellm-key",
temperature=0.7
)
response = llm.invoke("解释 Rust 的所有权机制")
print(response.content)
8.4 接入 NVIDIA NIM
# NVIDIA NIM 提供 1 年免费额度,接入方式
model_list:
- model_name: glm5
litellm_params:
model: openai/glm5.1
api_base: https://integrate.api.nvidia.com/v1
api_key: os.environ/NVIDIA_API_KEY
drop_params: true
- model_name: deepseek-nim
litellm_params:
model: openai/deepseek-v3.2
api_base: https://integrate.api.nvidia.com/v1
api_key: os.environ/NVIDIA_API_KEY
drop_params: true
- model_name: kimi-nim
litellm_params:
model: openai/kimi-k2.5
api_base: https://integrate.api.nvidia.com/v1
api_key: os.environ/NVIDIA_API_KEY
drop_params: true
九、2026 年新特性:A2A Agent 与 MCP Gateway
9.1 A2A (Agent-to-Agent) 网关
LiteLLM 在 2026 年新增了 A2A 协议支持,让多个 AI Agent 之间可以通过标准协议互相调用:
# Python SDK 中使用 A2A
from litellm.a2a_protocol import A2AClient
from a2a.types import SendMessageRequest, MessageSendParams
from uuid import uuid4
# 连接到一个 Agent
client = A2AClient(base_url="http://localhost:10001")
request = SendMessageRequest(
id=str(uuid4()),
params=MessageSendParams(
message={
"role": "user",
"parts": [{"kind": "text", "text": "分析这段代码的性能瓶颈"}],
"messageId": uuid4().hex,
}
)
)
response = await client.send_message(request)
通过 Proxy Server 管理 A2A Agent:
# 在 LiteLLM Proxy 中注册 Agent
# 然后通过统一的 API 端点调用
model_list:
- model_name: code-review-agent
litellm_params:
model: a2a/code-reviewer # A2A 类型
api_base: http://agent-host:10001
9.2 MCP (Model Context Protocol) Gateway
MCP 是 2025-2026 年最热门的 AI 工具协议之一。LiteLLM 现在支持将 MCP Server 作为工具接入:
# Python SDK 中使用 MCP 工具
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from litellm import experimental_mcp_client
import litellm
server_params = StdioServerParameters(
command="python",
args=["mcp_server.py"]
)
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
# 加载 MCP 工具,转换为 OpenAI Function Calling 格式
tools = await experimental_mcp_client.load_mcp_tools(
session=session,
format="openai"
)
# 用任何模型调用 MCP 工具
response = await litellm.acompletion(
model="gpt-4o",
messages=[{"role": "user", "content": "查看最近的 PR"}],
tools=tools
)
通过 Proxy 调用 MCP:
curl -X POST 'http://0.0.0.0:4000/v1/chat/completions' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "总结最近的 PR"}],
"tools": [{
"type": "mcp",
"server_url": "litellm_proxy/mcp/github",
"server_label": "github_mcp",
"require_approval": "never"
}]
}'
还可以将 LiteLLM 本身作为 MCP Server 暴露给 Claude Code 等工具:
{
"mcpServers": {
"LiteLLM": {
"url": "http://localhost:4000/mcp/",
"headers": {
"x-litellm-api-key": "Bearer sk-1234"
}
}
}
}
十、性能优化实战
10.1 延迟优化
LiteLLM 官方基准:8ms P95 延迟(1k RPS)。在默认配置下已经很快了,但还可以进一步优化:
# 性能优化配置
litellm_settings:
# 启用响应缓存——相同请求直接返回缓存结果
cache: true
cache_params:
type: redis
namespace: litellm_cache
ttl: 3600 # 缓存 1 小时
# 连接池优化
num_workers: 4 # Worker 数量
request_timeout: 30 # 请求超时
router_settings:
# 延迟优先路由——选最快的后端
routing_strategy: latency-based-routing
# 预热:启动时探测各后端延迟
model_group_alias:
gpt-4o-fast: gpt-4o # 别名映射
10.2 缓存策略
# 通过请求参数控制缓存
response = litellm.completion(
model="gpt-4o",
messages=[{"role": "user", "content": "什么是 Docker?"}],
cache={"use-cache": True} # 明确启用缓存
)
# 跳过缓存(实时性要求高的场景)
response = litellm.completion(
model="gpt-4o",
messages=[{"role": "user", "content": "今天天气怎么样"}],
cache={"use-cache": False}
)
10.3 数据库连接池
# docker-compose.yml 中的 PostgreSQL 优化
db:
image: postgres:16-alpine
command: >
postgres
-c max_connections=200
-c shared_buffers=256MB
-c effective_cache_size=768MB
-c work_mem=4MB
-c maintenance_work_mem=64MB
environment:
- POSTGRES_USER=llmproxy
- POSTGRES_PASSWORD=${DB_PASSWORD}
- POSTGRES_DB=litellm
10.4 高并发部署
对于 1k+ RPS 的高并发场景,需要水平扩展:
# docker-compose.yml —— 多实例 + Nginx 负载均衡
services:
litellm-1:
image: ghcr.io/berriai/litellm:main-stable
# ... 同上的配置
environment:
- DATABASE_URL=postgresql://llmproxy:${DB_PASSWORD}@db:5432/litellm
- REDIS_HOST=redis
ports:
- "4001:4000"
litellm-2:
image: ghcr.io/berriai/litellm:main-stable
# ... 同上的配置
environment:
- DATABASE_URL=postgresql://llmproxy:${DB_PASSWORD}@db:5432/litellm
- REDIS_HOST=redis
ports:
- "4002:4000"
nginx:
image: nginx:alpine
ports:
- "4000:80"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf
depends_on:
- litellm-1
- litellm-2
# nginx.conf
upstream litellm_backend {
least_conn;
server litellm-1:4000;
server litellm-2:4000;
}
server {
listen 80;
location / {
proxy_pass http://litellm_backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# SSE 支持(流式响应)
proxy_buffering off;
proxy_cache off;
chunked_transfer_encoding on;
}
}
十一、Admin UI 与可观测性
11.1 内置管理面板
LiteLLM 自带一个 Web 管理界面,启动 Proxy 后访问 http://localhost:4000/ui 即可:
- 模型管理:查看/添加/删除模型配置
- 密钥管理:创建/编辑/吊销虚拟密钥
- 用量看板:按团队/模型/时间的支出统计
- 请求日志:每次调用的完整记录
- 团队管理:按团队分配预算和权限
11.2 Prometheus 监控集成
# prometheus.yml
global:
scrape_interval: 15s
scrape_configs:
- job_name: 'litellm'
static_configs:
- targets: ['litellm:4000']
metrics_path: /metrics
authorization:
credentials: 'sk-master-key'
关键指标:
# 每秒请求数
rate(litellm_requests_total[5m])
# P95 延迟
histogram_quantile(0.95, rate(litellm_request_duration_bucket[5m]))
# 模型调用量分布
sum by (model) (litellm_requests_total)
# 错误率
rate(litellm_requests_failed_total[5m]) / rate(litellm_requests_total[5m])
# Token 消耗速率
rate(litellm_tokens_total[1h])
11.3 日志集成
# 将日志推送到 Datadog / Langfuse / Helicone 等
litellm_settings:
success_callback: ["langfuse", "datadog"]
failure_callback: ["langfuse", "datadog"]
# Langfuse 配置
langfuse_public_key: os.environ/LANGFUSE_PUBLIC_KEY
langfuse_secret_key: os.environ/LANGFUSE_SECRET_KEY
langfuse_host: https://cloud.langfuse.com
十二、安全最佳实践
12.1 网络层防护
# 只允许内网访问
services:
litellm:
ports:
- "127.0.0.1:4000:4000" # 只监听本地
# 或者用 Docker 网络隔离
networks:
- internal
networks:
internal:
internal: true # 不暴露到外网
如果需要外网访问,加 Nginx 反向代理 + TLS:
server {
listen 443 ssl http2;
server_name llm-gateway.yourcompany.com;
ssl_certificate /etc/letsencrypt/live/llm-gateway.yourcompany.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/llm-gateway.yourcompany.com/privkey.pem;
# 限流
limit_req_zone $binary_remote_addr zone=llm:10m rate=30r/m;
location / {
limit_req zone=llm burst=10 nodelay;
proxy_pass http://litellm:4000;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
12.2 密钥轮换策略
# 定期轮换 Master Key
# 1. 生成新 Key
NEW_KEY=$(openssl rand -hex 32)
# 2. 更新环境变量
sed -i "s/LITELLM_MASTER_KEY=.*/LITELLM_MASTER_KEY=sk-${NEW_KEY}/" .env
# 3. 重启服务
docker compose restart litellm
# 4. 旧 Key 失效,新 Key 生效
12.3 审计日志
# 自定义审计 Hook
class AuditLogger(CustomLogger):
async def async_post_call_hook(
self, user_api_key_dict, cache, data, response
):
audit_record = {
"timestamp": datetime.utcnow().isoformat(),
"user": user_api_key_dict.key_alias,
"team": user_api_key_dict.metadata.get("team"),
"model": data.get("model"),
"tokens": response.get("usage", {}).get("total_tokens", 0),
"cost": response.get("_hidden_params", {}).get("response_cost", 0),
"success": True
}
# 写入审计数据库或发送到 SIEM
await save_audit_record(audit_record)
十三、常见问题与排障
13.1 模型参数不兼容
不同模型支持的参数不一样,比如 Claude 不支持 temperature=0(需要用 temperature=0.01),本地模型可能不支持 logprobs。
解决方案:
# 全局 drop_params
litellm_settings:
drop_params: true # 自动丢弃不支持的参数
# 单模型级别
model_list:
- model_name: local-qwen
litellm_params:
model: openai/Qwen3-Coder-30B-A3B-Instruct
api_base: http://localhost:8100/v1
drop_params: true # 只对这个模型生效
13.2 超时与重试
router_settings:
timeout: 60 # 全局超时 60 秒
num_retries: 3 # 重试 3 次
retry_after: 0 # 无间隔重试(429 时自动遵守 Retry-After)
# 单模型超时
model_list:
- model_name: slow-model
litellm_params:
model: openai/gpt-4o
timeout: 120 # 这个模型允许 120 秒超时
num_retries: 5
13.3 数据库连接问题
# 检查数据库连接
docker compose exec litellm python3 -c "
from litellm.proxy.utils import PrismaClient
import asyncio
async def check():
db = PrismaClient(database_url='postgresql://llmproxy:password@db:5432/litellm')
await db.connect()
print('Database connected!')
await db.disconnect()
asyncio.run(check())
"
13.4 OOM 问题
LiteLLM 默认内存占用不高,但高并发场景下可能 OOM:
# 限制 Worker 数量和内存
services:
litellm:
deploy:
resources:
limits:
cpus: "2.0"
memory: 4G
environment:
- LITELLM_MODE=PRODUCTION # 生产模式,减少内存占用
- WORKERS=2 # Worker 数量
十四、与其他 AI 网关的对比
| 特性 | LiteLLM | OneAPI | New API | OpenRouter |
|---|---|---|---|---|
| 开源 | ✅ MIT | ✅ | ✅ | ❌ |
| 支持模型数 | 100+ | 30+ | 50+ | 100+ |
| Python SDK | ✅ | ❌ | ❌ | ✅ |
| Proxy Server | ✅ | ✅ | ✅ | ✅ |
| 虚拟密钥 | ✅ | ✅ | ✅ | ✅ |
| 成本追踪 | ✅ 精确 | ⚠️ 基础 | ✅ | ✅ |
| 负载均衡 | ✅ 多策略 | ⚠️ 基础 | ⚠️ 基础 | ❌ |
| Fallback | ✅ 链式 | ❌ | ⚠️ 基础 | ❌ |
| A2A 支持 | ✅ | ❌ | ❌ | ❌ |
| MCP 支持 | ✅ | ❌ | ❌ | ❌ |
| Guardrails | ✅ | ❌ | ❌ | ❌ |
| Admin UI | ✅ | ✅ | ✅ | ✅ |
| 自部署 | ✅ | ✅ | ✅ | ❌ |
| 延迟 (P95) | 8ms | ~15ms | ~12ms | ~20ms |
| 社区活跃度 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ |
LiteLLM 的核心优势在于:
- 最完整的 Provider 支持:100+ 模型,覆盖所有主流和长尾
- 企业级治理:虚拟密钥 + 预算控制 + 审计日志
- 生产级高可用:多策略负载均衡 + 链式 Fallback + 冷却机制
- 前沿协议支持:A2A Agent 互操作 + MCP 工具网关
- Python-first:SDK + Proxy 双模式,开发体验一流
十五、总结与展望
写在最后
LiteLLM 解决的不是"能不能调模型"的问题——谁都能调 API。它解决的是"怎么管"的问题。
当一个团队从"一个人用一个模型"进化到"多团队、多模型、多场景"时,你必然需要一个网关层来统一管控。这不是过度工程——这是生产环境的基本要求。
适合 LiteLLM 的场景:
- ✅ 团队 5 人以上,使用 3 个以上的模型
- ✅ 需要 A/B 测试不同模型的效果
- ✅ 需要成本管控和预算分配
- ✅ 需要高可用(自动降级、故障转移)
- ✅ 需要接入本地部署模型 + 云端模型
- ✅ 需要给不同团队/项目分配不同权限
可能不需要的场景:
- ❌ 个人项目,只用一个模型
- ❌ 简单的 API 调用,没有治理需求
- ❌ 对延迟极其敏感(8ms 的网关开销也不能接受)
未来方向:
- A2A 生态成熟:多 Agent 协作将成为标配,LiteLLM 作为 Agent 网关的定位会越来越重要
- MCP 工具生态爆发:MCP Server 数量正在指数级增长,LiteLLM 的 MCP Gateway 能力会成为核心卖点
- 成本优化智能化:基于历史用量的自动路由、闲时调度、Spot 实例利用等智能成本优化
- 多模态统一网关:图像、音频、视频生成 API 的统一接入
- 合规审计增强:随着 AI 监管趋严,审计日志和合规报告会成为必选项
如果你正在管理多个大模型 API,LiteLLM 值得一试。5 分钟部署,10 行配置,你就能拥有一个企业级的 AI 网关。
本文基于 LiteLLM v1.60+ 版本编写,项目地址:https://github.com/BerriAI/litellm