Home
Go back

搭建 AI Gateway：从概念到部署（LiteLLM）

最近在学习 AI Gateway 的搭建，在这里给大家分享一下什么是 AI Gateway，以及它的功能、特点等。

AI Gateway 是什么

AI Gateway 是一个位于你的应用和各种 LLM 提供商之间的中间层。它对外暴露一个统一的、与 OpenAI API 兼容的接口，然后将请求路由到后端的各种模型——无论是 OpenAI、Anthropic、Google，还是本地部署的开源模型。

┌──────────┐
│  你的应用 │
└────┬─────┘
     │ POST /v1/chat/completions
     ▼
┌──────────┐
│AI Gateway│  ← 统一入口，OpenAI 兼容
└────┬─────┘
     │ 根据 model 参数路由
     │
     ├──────▶ OpenAI (gpt-4o)
     ├──────▶ Anthropic (claude-sonnet-4-5)
     ├──────▶ Google (gemini-2.5-pro)
     └──────▶ 本地模型 (vLLM / Ollama)

这跟传统的 API Gateway 思路一样：用一层抽象解耦调用方和实现方。

为什么你需要一个 AI Gateway

如果只是偶尔调一下 ChatGPT，直接查看官方文档里如何在代码中调用 LLM 即可。但当你开始认真地把 LLM 集成到产品里，下面这些问题会一个个冒出来：

换句话说，当 LLM 调用从”一次性脚本”变成”基础设施”时，AI Gateway 就是那层必要的基础设施。

为什么选 LiteLLM

市面上有几个 AI Gateway 方案，我选了 LiteLLM。理由很简单：

使用 Docker Compose 部署 LiteLLM

LiteLLM 的部署是一个典型的 docker-compose.yml 加一个配置文件的事情。

1. 准备目录结构

mkdir -p ~/litellm
cd ~/litellm

2. 创建配置文件

LiteLLM 使用 YAML 格式的配置文件来定义可用的模型。创建 litellm_config.yaml：

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

model_list:
  # OpenAI 模型
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY

  - model_name: gpt-4o-mini
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY

  # Anthropic 模型
  - model_name: claude-sonnet-4-5
    litellm_params:
      model: anthropic/claude-sonnet-4-5
      api_key: os.environ/ANTHROPIC_API_KEY

  # Google 模型
  - model_name: gemini-2.5-pro
    litellm_params:
      model: gemini/gemini-2.5-pro
      api_key: os.environ/GEMINI_API_KEY

  # 本地 Ollama 模型
  - model_name: qwen3
    litellm_params:
      model: ollama/qwen3:latest
      api_base: http://host.docker.internal:11434

litellm_settings:
  set_verbose: false
  drop_params: true

router_settings:
  routing_strategy: "usage-based-routing-v2"
  allowed_fails: 3
  num_retries: 2

这里的关键概念：

3. 编写 docker-compose.yml

services:
  litellm:
    image: ghcr.io/berriai/litellm:main-stable
    container_name: litellm
    ports:
      - "4000:4000"
    volumes:
      - ./litellm_config.yaml:/app/config.yaml
    environment:
      LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY}
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
      GEMINI_API_KEY: ${GEMINI_API_KEY}
    command:
      - "--config"
      - "/app/config.yaml"
    restart: unless-stopped

  db:
    image: postgres:17
    container_name: litellm-db
    environment:
      POSTGRES_DB: litellm
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    restart: unless-stopped

这里用 PostgreSQL 来持久化 LiteLLM 的日志和花费数据。如果只是测试，可以不加 PostgreSQL——LiteLLM 默认会把数据存在内存里，但重启后就没了。

4. 配置环境变量

创建 .env 文件：

LITELLM_MASTER_KEY=sk-your-master-key-here
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIza...
POSTGRES_PASSWORD=your-db-password

LITELLM_MASTER_KEY 是网关的管理员密钥，可以创建和删除虚拟密钥、查看所有日志。生产环境中务必使用强随机字符串。

5. 启动

docker compose up -d

启动后访问 http://localhost:4000，你应该能看到 LiteLLM 的 API 在运行。访问 http://localhost:4000/ui 可以进入管理 Dashboard。

使用网关

网关启动后，你的应用只需要把 API 请求指向 LiteLLM：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:4000/v1",
    api_key="sk-your-master-key-here",
)

# 调用 GPT-4o
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "什么是 AI Gateway？"}],
)

# 调用 Claude——只需要改 model 参数
response = client.chat.completions.create(
    model="claude-sonnet-4-5",
    messages=[{"role": "user", "content": "解释一下 Rust 的所有权模型"}],
)

对于不支持 OpenAI SDK 的语言或者 curl 调用，直接发 HTTP 请求：

curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-master-key-here" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "你好"}]
  }'

进阶配置：虚拟密钥与多租户

直接把 master key 分发给所有服务很不安全。LiteLLM 支持创建 虚拟密钥（Virtual Keys），每个密钥可以绑定不同的模型、预算和速率限制。

通过管理 UI 或者 API 创建虚拟密钥：

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-mini", "claude-sonnet-4-5"],
    "max_budget": 50,
    "budget_duration": "1mo",
    "rpm_limit": 100
  }'

这会生成一个新的 API Key，该密钥：

配置负载均衡与 Fallback

这是 AI Gateway 最有价值的特性之一。假设你有两个 OpenAI 的 API Key，或者想在同类型模型之间做故障转移：

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY_PRIMARY

  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY_SECONDARY

router_settings:
  routing_strategy: "usage-based-routing-v2"
  allowed_fails: 3
  num_retries: 2
  fallbacks:
    - gpt-4o: ["claude-sonnet-4-5"]

当 gpt-4o 连续失败 3 次后，LiteLLM 会自动将请求 fallback 到 claude-sonnet-4-5。对调用方来说这完全透明——它们只看到请求最终成功返回。

成本追踪与 Dashboard

LiteLLM 的管理界面 http://localhost:4000/ui 提供了几个关键视图：

所有数据存储在 PostgreSQL 中，重启不会丢失。

接入 Nginx 反向代理

和你的其他自托管服务一样，建议前面加一层 Nginx：

server {
    listen 443 ssl;
    server_name llm.huazaiki.com;

    ssl_certificate     /etc/ssl/certs/llm.huazaiki.com.pem;
    ssl_certificate_key /etc/ssl/private/llm.huazaiki.com.key;

    location / {
        proxy_pass http://127.0.0.1:4000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 300s;
    }
}

注意 proxy_read_timeout 设到 300 秒——LLM 请求有时会非常慢。

总结

AI Gateway 解决的核心问题是一个：当 LLM 调用从”试一试”变成”跑在生产环境里”时，你需要一层统一的控制面。

LiteLLM 提供了一个低门槛的选择——一个 docker compose up -d 就能拥有模型路由、负载均衡、fallback、成本追踪和多租户管理。对于个人项目和小团队来说，这已经足够用了。

如果你在搭建自己的 AI 应用，我强烈建议在早期就把 Gateway 这层加上去。越到后面，模型切换和成本追踪的债务就越难还。

Previous Post
Spring Cloud Gateway：微服务统一入口
Next Post
Spring Cloud Nacos 配置中心：改了配置不必重启