# LiteLLM AI 网关

LiteLLM 是一个开源的 AI 网关，为 100+ 个语言模型提供商（包括 OpenAI、Anthropic、Azure、Bedrock、HuggingFace 以及本地托管模型）提供统一的兼容 OpenAI 的 API。在 CLORE.AI 上部署它可以通过单一端点路由、负载均衡并管理所有 LLM API 调用，并内置费用跟踪、速率限制和回退逻辑。

LiteLLM 的真正能力在于大规模场景：运行混合本地+云堆栈的团队可以在不改动应用代码的情况下热插拔模型。将 `gpt-4o` 替换为 `mistral-7b-local` 在配置中，重启 —— 完成。

{% hint style="success" %}
所有示例都可以在通过以下方式租用的 GPU 服务器上运行 [CLORE.AI 市场](https://clore.ai/marketplace).
{% endhint %}

## 服务器要求

| 参数       | 最低要求     | 推荐配置       |
| -------- | -------- | ---------- |
| 内存（RAM）  | 4 GB     | 8 GB+      |
| 显存（VRAM） | 不适用（仅代理） | 不适用        |
| 磁盘       | 10 GB    | 20 GB+     |
| GPU      | 不需要      | 可选（用于本地模型） |

{% hint style="info" %}
LiteLLM 本身是基于 CPU 的代理，不需要 GPU。但是，当您希望在同一台机器上与 LiteLLM 一起运行本地模型（通过 Ollama、TGI、vLLM）时，在 CLORE.AI 的 GPU 服务器上部署是有意义的。
{% endhint %}

## 在 CLORE.AI 上快速部署

**Docker 镜像：** `ghcr.io/berriai/litellm:main-latest`

**端口：** `22/tcp`, `4000/http`

**环境变量：**

| 变量                   | 示例                 | 描述                 |
| -------------------- | ------------------ | ------------------ |
| `OPENAI_API_KEY`     | `sk-xxx...`        | OpenAI API 密钥      |
| `ANTHROPIC_API_KEY`  | `sk-ant-xxx...`    | Anthropic API 密钥   |
| `AZURE_API_KEY`      | `xxx...`           | Azure OpenAI 密钥    |
| `LITELLM_MASTER_KEY` | `sk-my-master-key` | 代理的主认证密钥           |
| `DATABASE_URL`       | `postgresql://...` | 用于费用跟踪的 PostgreSQL |
| `STORE_MODEL_IN_DB`  | `True`             | 将模型配置持久化到数据库       |

## 逐步设置

### 1. 在 CLORE.AI 上租用服务器

LiteLLM 即使在仅 CPU 的服务器上也能很好运行。前往 [CLORE.AI 市场](https://clore.ai/marketplace) 并筛选：

* 用于纯代理设置的最低价 CPU 服务器
* 如果您也想运行本地模型，则选择 GPU 服务器（RTX 3090+）

### 2. SSH 登录到您的服务器

```bash
ssh -p <PORT> root@<SERVER_IP>
```

### 3. 创建配置文件

LiteLLM 使用 YAML 配置文件来定义模型：

```bash
mkdir -p /root/litellm
cat > /root/litellm/config.yaml << 'EOF'
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-3-5-sonnet
    litellm_params:
      model: anthropic/claude-3-5-sonnet-20241022
      api_key: "os.environ/ANTHROPIC_API_KEY"

  # 通过 TGI 的本地模型（在同一服务器上，端口 8080）
  - model_name: mistral-7b-local
    litellm_params:
      model: openai/mistralai/Mistral-7B-Instruct-v0.3
      api_base: "http://localhost:8080/v1"
      api_key: "none"

  # 负载均衡器：路由到多个端点
  - model_name: fast-model
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: "os.environ/OPENAI_API_KEY"
    model_info:
      mode: chat

litellm_settings:
  drop_params: True
  set_verbose: False
  num_retries: 3
  request_timeout: 60

general_settings:
  master_key: "sk-my-secret-master-key"  # 请更改此项！
  alerting: []
EOF
```

### 4. 启动 LiteLLM

**基础启动：**

```bash
docker run -d \
  --name litellm \
  --network host \
  -v /root/litellm/config.yaml:/app/config.yaml \
  -e OPENAI_API_KEY=sk-your-openai-key \
  -e ANTHROPIC_API_KEY=sk-ant-your-anthropic-key \
  -e LITELLM_MASTER_KEY=sk-my-secret-master-key \
  ghcr.io/berriai/litellm:main-latest \
  --config /app/config.yaml \
  --port 4000 \
  --host 0.0.0.0
```

**使用 PostgreSQL 进行费用跟踪：**

首先，启动一个 PostgreSQL 容器：

```bash
docker run -d \
  --name postgres \
  -e POSTGRES_PASSWORD=litellm_pass \
  -e POSTGRES_DB=litellm \
  -p 5432:5432 \
  postgres:15

# 然后用数据库启动 LiteLLM
docker run -d \
  --name litellm \
  -p 4000:4000 \
  -v /root/litellm/config.yaml:/app/config.yaml \
  -e OPENAI_API_KEY=sk-your-openai-key \
  -e ANTHROPIC_API_KEY=sk-ant-your-anthropic-key \
  -e LITELLM_MASTER_KEY=sk-my-secret-master-key \
  -e DATABASE_URL="postgresql://postgres:litellm_pass@localhost:5432/litellm" \
  --network host \
  ghcr.io/berriai/litellm:main-latest \
  --config /app/config.yaml \
  --port 4000 \
  --host 0.0.0.0
```

**使用 Docker Compose（推荐）：**

```bash
cat > /root/litellm/docker-compose.yml << 'EOF'
version: "3.8"
services:
  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    ports:
      - "4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - LITELLM_MASTER_KEY=sk-my-secret-master-key
      - DATABASE_URL=postgresql://postgres:litellm_pass@db:5432/litellm
    command: --config /app/config.yaml --port 4000 --host 0.0.0.0
    depends_on:
      - db

  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: litellm_pass
      POSTGRES_DB: litellm
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:
EOF

cd /root/litellm && docker compose up -d
```

### 5. 验证服务器

```bash
# 检查健康状态
curl http://localhost:4000/health

# 列出可用模型
curl http://localhost:4000/v1/models \
  -H "Authorization: Bearer sk-my-secret-master-key"
```

### 6. 通过 CLORE.AI HTTP 代理访问

您的 CLORE.AI http\_pub（用于端口 4000）URL：

```
https://<order-id>-4000.clore.ai/v1
```

将此用作您的 `api_base` 在任何兼容 OpenAI 的客户端中使用。

***

## 使用示例

### 示例 1：通过代理的直接 API 调用

```bash
curl http://localhost:4000/v1/chat/completions \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-my-secret-master-key" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "德国的首都是什么？"}
    ]
  }'
```

### 示例 2：使用 LiteLLM 代理的 OpenAI Python SDK

```python
from openai import OpenAI

# 只需更改 base_url 和 api_key —— 其余完全相同
client = OpenAI(
    base_url="http://localhost:4000/v1",
    api_key="sk-my-secret-master-key",
)

# 使用配置中的任意模型
response = client.chat.completions.create(
    model="gpt-4o-mini",  # 或 "claude-3-5-sonnet", "mistral-7b-local"
    messages=[{"role": "user", "content": "总结 GPU 计算的好处。"}],
)
print(response.choices[0].message.content)

# 在不改代码的情况下切换模型
response2 = client.chat.completions.create(
    model="claude-3-5-sonnet",
    messages=[{"role": "user", "content": "相同的问题，不同的模型。"}],
)
print(response2.choices[0].message.content)
```

### 示例 3：LiteLLM Python SDK（直接）

```python
import litellm

# 直接使用，不通过代理
response = litellm.completion(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "你好！"}],
    api_key="your-openai-key",
)

# 或通过您的代理路由
response = litellm.completion(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "你好！"}],
    api_base="http://localhost:4000",
    api_key="sk-my-secret-master-key",
)
```

### 示例 4：回退配置

配置模型之间的自动回退：

```yaml
# 在 config.yaml 中
model_list:
  - model_name: smart-fallback
    litellm_params:
      model: gpt-4o
      api_key: "os.environ/OPENAI_API_KEY"

router_settings:
  routing_strategy: least-busy
  model_group_alias:
    "gpt-4-fallback":
      - "gpt-4o"
      - "claude-3-5-sonnet"
      - "mistral-7b-local"
  num_retries: 3
  fallbacks:
    - gpt-4o:
        - claude-3-5-sonnet
        - mistral-7b-local
```

### 示例 5：费用跟踪仪表盘

启用 PostgreSQL 后，访问支出分析：

```bash
# 按用户获取支出
curl http://localhost:4000/global/spend/users \
  -H "Authorization: Bearer sk-my-secret-master-key"

# 按模型获取支出
curl http://localhost:4000/global/spend/models \
  -H "Authorization: Bearer sk-my-secret-master-key"

# 生成支出报告
curl "http://localhost:4000/global/spend?start_date=2024-01-01&end_date=2024-12-31" \
  -H "Authorization: Bearer sk-my-secret-master-key"
```

***

## invokeai.yaml 配置文件

### 虚拟密钥（每用户 API 密钥）

为不同用户创建具有速率限制和预算的独立密钥：

```bash
# 创建带预算的密钥
curl http://localhost:4000/key/generate \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-my-secret-master-key" \
  -d '{
    "models": ["gpt-4o-mini", "claude-3-5-sonnet"],
    "duration": "30d",
    "max_budget": 10.0,
    "metadata": {"user_id": "user_123"}
  }'
```

### 负载均衡

```yaml
model_list:
  # 在多个 OpenAI API 密钥之间轮询
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: sk-key-1
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: sk-key-2

router_settings:
  routing_strategy: least-busy  # 或：simple-shuffle、latency-based-routing
```

### 缓存

```yaml
litellm_settings:
  cache: True
  cache_params:
    type: redis
    host: localhost
    port: 6379
    ttl: 3600  # 1 小时
```

### 速率限制

```yaml
general_settings:
  default_team_settings:
    tpm_limit: 100000   # 每分钟令牌数
    rpm_limit: 1000     # 每分钟请求数
```

***

## 1. 使用 SDXL-Turbo 或 SDXL-Lightning 以实现快速生成

### 1. 为重复提示启用缓存

对于具有常见问题的 RAG 或聊天机器人应用，Redis 缓存可降低 30–70% 的成本，并在缓存命中时将 P50 延迟降至 <5ms：

```yaml
litellm_settings:
  cache: True
  cache_params:
    type: redis
    host: localhost
    port: 6379
```

### 2. 使用异步请求

```python
import asyncio
import litellm

async def batch_complete(prompts):
    tasks = [
        litellm.acompletion(
            model="gpt-4o-mini",
            messages=[{"role": "user", "content": p}],
        )
        for p in prompts
    ]
    return await asyncio.gather(*tasks)

results = asyncio.run(batch_complete(["Hello", "World", "Test"]))
```

### 3. 本地模型路由

将廉价/简单的请求路由到 Clore.ai GPU 上的本地模型，将复杂请求交给 GPT-4：

```yaml
model_list:
  - model_name: smart-router
    litellm_params:
      model: openai/gpt-4o
      api_key: "os.environ/OPENAI_API_KEY"
```

典型设置：在本地运行 Mistral 7B 或 Llama 3 8B（在 Clore.ai 的 RTX 3090 上，$0.10–0.15/小时），在那里处理 80% 的流量，然后将复杂任务升级到 GPT-4o。与仅使用云相比，通常能节省 3–5 倍的成本。

### 4. 设置超时和重试

```yaml
litellm_settings:
  request_timeout: 30
  num_retries: 3
  retry_after: 5
```

***

## Clore.ai 的 GPU 建议

LiteLLM 本身不需要 GPU —— 它是一个代理。只有在您在其旁边共同部署本地推理时，GPU 的选择才重要。

| 本地模型                            | GPU                | 为什么                                   |
| ------------------------------- | ------------------ | ------------------------------------- |
| Mistral 7B / Llama 3 8B（bf16）   | **RTX 3090** 24 GB | 可轻松适配，约 200 tok/s 吞吐量                 |
| Mixtral 8×7B 或 Llama 3 70B（AWQ） | **RTX 4090** 24 GB | 比 3090 更快的内存带宽；可容纳 70B AWQ 的 4-bit 模型 |
| Llama 3 70B（bf16）或多模型服务         | **A100 80 GB**     | 同时运行多个 7–13B 模型；使用 HBM2e 以实现低延迟       |

**单人开发者推荐堆栈：** RTX 3090 + Mistral 7B + LiteLLM 网关。在 Clore.ai 上总成本约 $0.12/小时。可轻松处理约 50 次请求/分钟，并在复杂任务时回退到 GPT-4o。

**团队 / 生产堆栈：** A100 80GB，运行 Llama 3 70B + LiteLLM + PostgreSQL。可服务 20+ 并发用户，完整费用跟踪，对大多数请求实现零云 LLM 支出。

***

## 故障排除

### 问题："找不到模型"

确保请求中的模型名称与 `config.yaml`:

```bash
curl http://localhost:4000/v1/models -H "Authorization: Bearer sk-my-secret-master-key"
```

### 问题："认证失败"

检查您的 `LITELLM_MASTER_KEY` 环境变量并将其用作 Bearer 令牌。

### 问题：配置更改未生效

在更改配置后重启容器：

```bash
docker restart litellm
```

### 问题：首次请求延迟高

LiteLLM 在启动时加载模型配置。前几次请求在建立连接时可能会较慢。

### 问题：数据库连接错误

```bash
# 检查 PostgreSQL 是否在运行
docker logs postgres

# 验证连接字符串格式
DATABASE_URL="postgresql://user:password@host:5432/dbname"
```

### 问题：来自提供商的 429 速率限制错误

配置回退：

```yaml
litellm_settings:
  num_retries: 5
  fallbacks:
    - gpt-4o: [claude-3-5-sonnet]
```

***

## Clore.ai 的 GPU 建议

LiteLLM 是一个 API 网关/代理 —— 它本身不做推理。GPU 的选择取决于您是路由到云 API 还是本地模型。

| 设置         | GPU       | Clore.ai 价格 | 在 Clore.ai 上的预估费用                     |
| ---------- | --------- | ----------- | ------------------------------------- |
| 仅云 API 代理  | 仅 CPU     | ≈$0.02/小时   | 路由到 OpenAI、Anthropic、Gemini —— 无需 GPU |
| 本地 vLLM 后端 | 生产        | \~$0.12/小时  | 自托管的 7B–13B 模型，LiteLLM 作为前端           |
| 本地 vLLM 后端 | 大规模       | \~$0.70/小时  | 更高吞吐量的 7B–34B 本地模型                    |
| 本地 vLLM 后端 | A100 40GB | \~$1.20/小时  | 70B 模型，生产级本地服务                        |

{% hint style="info" %}
**最常见的设置：** 在 Clore.ai 托管的 vLLM/Ollama 实例前运行 LiteLLM 作为统一代理。这为您提供提供商回退、速率限制、费用跟踪和兼容 OpenAI 的路由，同时将所有推理保持在本地以降低成本。

**示例成本：** 在仅 CPU 实例上运行 LiteLLM 代理（~~$0.02/小时）并将其指向在 RTX 3090 上的 vLLM 服务器（~~$0.12/小时）。具有回退、日志记录和速率限制的可用于生产的自托管 LLM API 总成本约 $0.14/小时。
{% endhint %}

***

## 文档

* [GitHub](https://github.com/BerriAI/litellm)
* [文档](https://docs.litellm.ai)
* [Clore.ai GPU 建议](https://github.com/BerriAI/litellm/pkgs/container/litellm)
* [支持的提供商](https://docs.litellm.ai/docs/providers)
* [CLORE.AI 市场](https://clore.ai/marketplace)