编程 LiteLLM 深度解析:100+ 大模型统一网关的架构设计与生产实战

2026-04-29 05:42:47 +0800 CST views 18

LiteLLM 深度解析:100+ 大模型统一网关的架构设计与生产实战

当你的团队同时调用 OpenAI、Anthropic、Gemini、Bedrock、Azure 以及本地部署的 Qwen 和 DeepSeek 时,你是怎么管理的?每个 SDK 写一套?密钥散落在代码里?换模型就改业务代码?如果你点头了,这篇文章就是写给你的。

一、为什么你需要一个 LLM 网关

1.1 多模型时代的混乱现状

2026 年的大模型生态已经不能用"百花齐放"来形容了——简直是丛林。一个中等规模的技术团队,日常需要打交道的大模型 API 少则五六个,多则十几个:

服务商模型API 格式认证方式
OpenAIGPT-4o, GPT-5.4OpenAI FormatBearer Token
AnthropicClaude Sonnet 4, Claude 4.6Messages APIx-api-key
GoogleGemini 3.1 ProVertex AI FormatService Account
AWSBedrock (多模型)Bedrock FormatAWS SigV4
AzureAzure OpenAIOpenAI Format (部分差异)API Key + Endpoint
DeepSeekDeepSeek-V4OpenAI 兼容Bearer Token
本地部署Qwen, Llama, MistralOpenAI 兼容 (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}")

这段代码的问题一目了然:

  1. 密钥硬编码:API Key 直接写在代码里,即便你用环境变量,分散在十几个地方也不可控
  2. 切换成本高:想从 GPT-4 切到 Claude?改业务代码。想做 A/B 测试?再写一套
  3. 监控缺失:哪个模型花了多少钱?哪个团队用了多少 token?一无所知
  4. 降级困难:GPT-4 挂了怎么办?手工切?半夜三点谁来切?
  5. 代码膨胀:每加一个模型就多一套适配代码,维护成本线性增长

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"]

这意味着:

  1. 请求 gpt-4o → OpenAI 返回 429/500 → 自动重试 2 次
  2. 仍然失败 → 切到 gpt-4o-fallback(Azure)
  3. Azure 也失败 → 切到 claude-sonnet
  4. Claude 也失败 → 最后尝试 deepseek-v4
  5. 全部失败 → 返回错误

对于用户来说,这一切都是透明的——他们只知道请求 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 网关的对比

特性LiteLLMOneAPINew APIOpenRouter
开源✅ MIT
支持模型数100+30+50+100+
Python SDK
Proxy Server
虚拟密钥
成本追踪✅ 精确⚠️ 基础
负载均衡✅ 多策略⚠️ 基础⚠️ 基础
Fallback✅ 链式⚠️ 基础
A2A 支持
MCP 支持
Guardrails
Admin UI
自部署
延迟 (P95)8ms~15ms~12ms~20ms
社区活跃度⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐

LiteLLM 的核心优势在于:

  1. 最完整的 Provider 支持:100+ 模型,覆盖所有主流和长尾
  2. 企业级治理:虚拟密钥 + 预算控制 + 审计日志
  3. 生产级高可用:多策略负载均衡 + 链式 Fallback + 冷却机制
  4. 前沿协议支持:A2A Agent 互操作 + MCP 工具网关
  5. Python-first:SDK + Proxy 双模式,开发体验一流

十五、总结与展望

写在最后

LiteLLM 解决的不是"能不能调模型"的问题——谁都能调 API。它解决的是"怎么管"的问题。

当一个团队从"一个人用一个模型"进化到"多团队、多模型、多场景"时,你必然需要一个网关层来统一管控。这不是过度工程——这是生产环境的基本要求。

适合 LiteLLM 的场景

  • ✅ 团队 5 人以上,使用 3 个以上的模型
  • ✅ 需要 A/B 测试不同模型的效果
  • ✅ 需要成本管控和预算分配
  • ✅ 需要高可用(自动降级、故障转移)
  • ✅ 需要接入本地部署模型 + 云端模型
  • ✅ 需要给不同团队/项目分配不同权限

可能不需要的场景

  • ❌ 个人项目,只用一个模型
  • ❌ 简单的 API 调用,没有治理需求
  • ❌ 对延迟极其敏感(8ms 的网关开销也不能接受)

未来方向

  1. A2A 生态成熟:多 Agent 协作将成为标配,LiteLLM 作为 Agent 网关的定位会越来越重要
  2. MCP 工具生态爆发:MCP Server 数量正在指数级增长,LiteLLM 的 MCP Gateway 能力会成为核心卖点
  3. 成本优化智能化:基于历史用量的自动路由、闲时调度、Spot 实例利用等智能成本优化
  4. 多模态统一网关:图像、音频、视频生成 API 的统一接入
  5. 合规审计增强:随着 AI 监管趋严,审计日志和合规报告会成为必选项

如果你正在管理多个大模型 API,LiteLLM 值得一试。5 分钟部署,10 行配置,你就能拥有一个企业级的 AI 网关。


本文基于 LiteLLM v1.60+ 版本编写,项目地址:https://github.com/BerriAI/litellm

推荐文章

解决 PHP 中的 HTTP 请求超时问题
2024-11-19 09:10:35 +0800 CST
CSS 奇技淫巧
2024-11-19 08:34:21 +0800 CST
Vue3中的事件处理方式有何变化?
2024-11-17 17:10:29 +0800 CST
Vue3中哪些API被废弃了?
2024-11-17 04:17:22 +0800 CST
Go的父子类的简单使用
2024-11-18 14:56:32 +0800 CST
使用Rust进行跨平台GUI开发
2024-11-18 20:51:20 +0800 CST
在 Nginx 中保存并记录 POST 数据
2024-11-19 06:54:06 +0800 CST
nginx反向代理
2024-11-18 20:44:14 +0800 CST
Vue3中如何处理异步操作?
2024-11-19 04:06:07 +0800 CST
ElasticSearch集群搭建指南
2024-11-19 02:31:21 +0800 CST
什么是Vue实例(Vue Instance)?
2024-11-19 06:04:20 +0800 CST
一个简单的打字机效果的实现
2024-11-19 04:47:27 +0800 CST
php机器学习神经网络库
2024-11-19 09:03:47 +0800 CST
php使用文件锁解决少量并发问题
2024-11-17 05:07:57 +0800 CST
一文详解回调地狱
2024-11-19 05:05:31 +0800 CST
程序员茄子在线接单