> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# LiteLLM

> 使用 Docker Compose 部署 LiteLLM，并通过 MixRoute 转发模型请求

## 概览

LiteLLM 可以作为内部代理部署在 MixRoute 前面。业务应用调用 LiteLLM，LiteLLM 再将请求转发到 MixRoute，同时提供统一鉴权、模型发现、Dashboard 管理、virtual keys 和用量记录。

LiteLLM 官方 Docker Compose 安装教程：[https://docs.litellm.ai/docs/proxy/deploy](https://docs.litellm.ai/docs/proxy/deploy)

## Docker Compose 部署

准备三个文件：

```text theme={null}
.
├── .env
├── config.yaml
└── docker-compose.yml
```

`.env`：

```env theme={null}
MIXROUTE_API_KEY=<mixroute-api-key>
LITELLM_MASTER_KEY=<litellm-master-key>
LITELLM_SALT_KEY=<stable-random-salt-key>
POSTGRES_PASSWORD=<postgres-password>
```

| 变量                   | 说明                                          |
| -------------------- | ------------------------------------------- |
| `MIXROUTE_API_KEY`   | MixRoute API key。LiteLLM 转发请求到 MixRoute 时使用 |
| `LITELLM_MASTER_KEY` | LiteLLM 管理员 key，可用于调用 API 和登录 Dashboard     |
| `LITELLM_SALT_KEY`   | LiteLLM 用于加密数据库中 key 的稳定随机值                 |
| `POSTGRES_PASSWORD`  | Docker Compose 内部 PostgreSQL 的数据库密码         |

`docker-compose.yml`：

```yaml theme={null}
services:
  postgres:
    image: postgres:17
    container_name: litellm-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: litellm
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm -d litellm"]
      interval: 5s
      timeout: 5s
      retries: 20
    volumes:
      - litellm-postgres-data:/var/lib/postgresql/data

  litellm:
    image: ghcr.io/berriai/litellm-database:main-stable
    container_name: litellm
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    env_file:
      - .env
    environment:
      DATABASE_URL: postgresql://litellm:${POSTGRES_PASSWORD}@postgres:5432/litellm
      USE_PRISMA_MIGRATE: "True"
      STORE_MODEL_IN_DB: "True"
    command: ["--config", "/app/config.yaml", "--host", "0.0.0.0", "--port", "4000"]
    ports:
      - "4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml:ro

volumes:
  litellm-postgres-data:
```

| 变量                   | 说明                                                                |
| -------------------- | ----------------------------------------------------------------- |
| `DATABASE_URL`       | LiteLLM 连接 PostgreSQL 的连接串，用于 Dashboard、virtual keys、用量记录和模型配置持久化 |
| `USE_PRISMA_MIGRATE` | 设为 `True` 时，LiteLLM 启动时会执行数据库 migration                           |
| `STORE_MODEL_IN_DB`  | 设为 `True` 时，Dashboard/API 中新增或修改的模型配置会写入 PostgreSQL               |

启动 LiteLLM：

```bash theme={null}
docker compose pull
docker compose up -d
```

## 接入 MixRoute

MixRoute Base URL：

```text theme={null}
https://api.mixroute.ai/v1
```

在 `config.yaml` 中配置 LiteLLM 路由：

```yaml theme={null}
model_list:
  - model_name: o3-mini
    litellm_params:
      model: openai/o3-mini-2025-01-31
      api_base: https://api.mixroute.ai/v1
      api_key: os.environ/MIXROUTE_API_KEY
    model_info:
      mode: chat

  - model_name: openai/*
    litellm_params:
      model: openai/*
      api_base: https://api.mixroute.ai/v1
      api_key: os.environ/MIXROUTE_API_KEY

  - model_name: anthropic/*
    litellm_params:
      model: anthropic/*
      api_base: https://api.mixroute.ai
      api_key: os.environ/MIXROUTE_API_KEY

  - model_name: gemini/*
    litellm_params:
      model: gemini/*
      api_base: https://api.mixroute.ai/v1
      api_key: os.environ/MIXROUTE_API_KEY

litellm_settings:
  drop_params: true
  request_timeout: 600
  telemetry: false
  check_provider_endpoint: true

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL
  store_model_in_db: true
```

| 配置                              | 作用                                                                 |
| ------------------------------- | ------------------------------------------------------------------ |
| `openai/*`                      | 接入 MixRoute OpenAI-compatible `/v1`，用于文本、embedding、图片、视频等接口        |
| `anthropic/*`                   | 接入 MixRoute Anthropic-compatible API，LiteLLM 会处理 `/v1/messages` 路径 |
| `gemini/*`                      | 接入 MixRoute Gemini-compatible API                                  |
| `check_provider_endpoint: true` | 让 LiteLLM 通过 MixRoute `/v1/models` 自动发现模型                          |
| `drop_params: true`             | 自动丢弃上游不支持的参数，减少跨厂商兼容问题                                             |
| `store_model_in_db: true`       | Dashboard/API 中新增或修改的模型会保存到 PostgreSQL                             |
| `o3-mini`                       | 示例 alias，将短模型名映射到 MixRoute 实际模型名                                   |

`openai/` 是 LiteLLM 的 OpenAI-compatible provider 前缀，不代表模型来源一定是 OpenAI。

## 客户端调用方式

OpenAI-compatible Base URL：

```text theme={null}
<LITELLM_OPENAI_BASE_URL>
```

请求头：

```http theme={null}
Authorization: Bearer <LITELLM_API_KEY>
```

获取模型列表：

```bash theme={null}
curl -sS <LITELLM_OPENAI_BASE_URL>/models \
  -H "Authorization: Bearer <LITELLM_API_KEY>"
```

调用时使用返回的模型 ID，例如 `openai/gpt-5.5`、`anthropic/claude-sonnet-5`、`gemini/gemini-2.5-flash`，或显式配置的 alias `o3-mini`。

## 验证

```bash theme={null}
curl -sS <LITELLM_BASE_URL>/health/liveliness
```

```bash theme={null}
curl -sS <LITELLM_OPENAI_BASE_URL>/chat/completions \
  -H "Authorization: Bearer <LITELLM_API_KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "openai/gpt-5.5",
    "messages": [{"role": "user", "content": "Return exactly OK"}],
    "max_tokens": 8
  }'
```

```bash theme={null}
curl -sS <LITELLM_BASE_URL>/v1beta/models/gemini/gemini-2.5-flash:generateContent \
  -H "Authorization: Bearer <LITELLM_API_KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "contents": [{"role": "user", "parts": [{"text": "Return exactly OK"}]}],
    "generationConfig": {"maxOutputTokens": 8}
  }'
```

Gemini `generateContent` 使用 LiteLLM 前端路径 `/v1beta/models/gemini/<model-id>:generateContent`；转发到 MixRoute 时，上游 Base URL 仍为 `https://api.mixroute.ai/v1`。