# Шлюз LiteLLM AI

LiteLLM — это открытый шлюз ИИ, предоставляющий унифицированный API, совместимый с OpenAI, для более чем 100 поставщиков языковых моделей — включая OpenAI, Anthropic, Azure, Bedrock, HuggingFace и локально размещённые модели. Разверните его на CLORE.AI, чтобы маршрутизировать, балансировать нагрузку и управлять всеми вашими вызовами LLM API через единый эндпоинт с встроенным отслеживанием затрат, ограничением скорости и логикой резервного перехода.

Настоящая мощь LiteLLM проявляется в масштабе: команды, использующие смешанные локальные+облачные стеки, могут «горячо» менять модели без изменения кода приложения. `gpt-4o` на `mistral-7b-local` в конфигурации, перезапустите — готово.

{% hint style="success" %}
Все примеры можно запускать на GPU-серверах, арендуемых через [CLORE.AI Маркетплейс](https://clore.ai/marketplace).
{% endhint %}

## Требования к серверу

| Параметр | Минимум             | Рекомендуется                         |
| -------- | ------------------- | ------------------------------------- |
| ОЗУ      | 4 ГБ                | 8 ГБ+                                 |
| VRAM     | N/A (только прокси) | N/A                                   |
| Диск     | 10 ГБ               | 20 ГБ+                                |
| GPU      | Не требуется        | Необязательно (для локальных моделей) |

{% hint style="info" %}
Сам LiteLLM является прокси на базе CPU и не требует GPU. Тем не менее имеет смысл развернуть его на GPU‑сервере CLORE.AI, если вы планируете запускать локальные модели (через Ollama, TGI, vLLM) рядом с LiteLLM в качестве единого шлюза на той же машине.
{% 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. Доступ через HTTP‑прокси CLORE.AI

Ваш URL http\_pub CLORE.AI для порта 4000:

```
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: OpenAI Python SDK с LiteLLM прокси

```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: Конфигурация резервирования (fallback)

Настройте автоматические резервные варианты между моделями:

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

***

## Конфигурация

### Виртуальные ключи (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 час
```

### Ограничение частоты (Rate Limiting)

```yaml
general_settings:
  default_team_settings:
    tpm_limit: 100000   # токенов в минуту
    rpm_limit: 1000     # запросов в минуту
```

***

## Советы по производительности

### 1. Включите кеширование для повторяющихся подсказок

Для RAG или чатботов с часто задаваемыми вопросами кеширование в Redis сокращает расходы на 30–70% и снижает P50 задержку до <5 мс при попадании в кэш:

```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. Маршрутизация к локальным моделям

Направляйте дешёвые/простые запросы к локальным моделям на GPU Clore.ai, сложные — к 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 важен только если вы развертываете локальный inference рядом с ним.

| Локальная модель                             | GPU                | Почему                                                                     |
| -------------------------------------------- | ------------------ | -------------------------------------------------------------------------- |
| Mistral 7B / Llama 3 8B (bf16)               | **RTX 3090** 24 ГБ | Вмещается с запасом, \~200 ток/с пропускная способность                    |
| Mixtral 8×7B или Llama 3 70B (AWQ)           | **RTX 4090** 24 ГБ | Быстрее пропускная способность памяти, чем у 3090; вмещает 70B AWQ 4‑бит   |
| Llama 3 70B (bf16) или многомодельный сервер | **A100 80 ГБ**     | Запускайте одновременно несколько моделей 7–13B; HBM2e для низкой задержки |

**Рекомендуемый стек для одиночного разработчика:** RTX 3090 + Mistral 7B + шлюз LiteLLM. Общая стоимость на Clore.ai: \~0.12$/час. Лёгко обрабатывает \~50 запросов/мин, с резервным переходом на GPT‑4o для сложных задач.

**Командный / продакшен стек:** A100 80GB, запуск Llama 3 70B + LiteLLM + PostgreSQL. Обслуживает 20+ одновременных пользователей, полнота отслеживания затрат, ноль расходов на облачные LLM для большинства запросов.

***

## Устранение неполадок

### Проблема: «model not found»

Убедитесь, что имя модели в вашем запросе точно соответствует тому, что в `config.yaml`:

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

### Проблема: «authentication failed»

Проверьте ваш `LITELLM_MASTER_KEY` переменную окружения и используйте её как токен Bearer.

### Проблема: изменения конфигурации не применяются

Перезапустите контейнер после изменения конфигурации:

```bash
docker restart litellm
```

### Проблема: высокая задержка при первом запросе

LiteLLM загружает конфигурации моделей при запуске. Первые несколько запросов могут быть медленнее, пока устанавливаются соединения.

### Проблема: ошибки соединения с базой данных

```bash
# Проверьте, что PostgreSQL запущен
docker logs postgres

# Проверьте формат строки подключения
DATABASE_URL="postgresql://user:password@host:5432/dbname"
```

### Проблема: ошибки 429 (rate limit) от провайдеров

Настройте резервные варианты:

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

***

## Рекомендации Clore.ai по GPU

LiteLLM — это шлюз/прокси API — он сам не выполняет вывод. Выбор GPU зависит от того, маршрутизируете ли вы к облачным API или к локальным моделям.

| Установка                      | GPU             | Цена Clore.ai | Сценарий использования                                        |
| ------------------------------ | --------------- | ------------- | ------------------------------------------------------------- |
| Только прокси для облачных API | Только CPU      | \~$0.02/ч     | Маршрутизация к OpenAI, Anthropic, Gemini — GPU не нужен      |
| Локальный бэкенд vLLM          | RTX 3090 (24GB) | \~$0.12/ч     | Самохостинг моделей 7B–13B с LiteLLM в качестве фронтенда     |
| Локальный бэкенд vLLM          | RTX 4090 (24GB) | \~$0.70/ч     | Более высокая пропускная способность локальных моделей 7B–34B |
| Локальный бэкенд vLLM          | A100 40GB       | \~$1.20/ч     | 70B модели, продакшен‑локальное обслуживание                  |

{% hint style="info" %}
**Наиболее распространённая конфигурация:** Запускайте LiteLLM как единый прокси перед вашими размещёнными на Clore.ai vLLM/Ollama инстансами. Это даёт вам резервные провайдеры, ограничение скорости, отслеживание затрат и маршрутизацию, совместимую с OpenAI, при сохранении всего вывода локальным и дешёвым.

**Пример стоимости:** Запустите прокси LiteLLM на экземпляре только с CPU (\~\~0.02$/час) и укажите его на vLLM сервер на RTX 3090 (\~\~0.12$/час). Общая стоимость \~0.14$/час для готового к продакшену, саморазмещённого LLM API с резервными вариантами, логированием и ограничением скорости.
{% endhint %}

***

## Ссылки

* [GitHub](https://github.com/BerriAI/litellm)
* [Документация](https://docs.litellm.ai)
* [Docker Hub / GHCR](https://github.com/BerriAI/litellm/pkgs/container/litellm)
* [Поддерживаемые провайдеры](https://docs.litellm.ai/docs/providers)
* [CLORE.AI Маркетплейс](https://clore.ai/marketplace)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-ru/yazykovye-modeli/litellm.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.