Развертывание LiteLLM Proxy в Docker Compose: универсальный AI-шлюз к 100+ нейросетям с кэшированием ответов, балансировкой и контролем бюджета

Внедрение больших языковых моделей (LLM) в проекты быстро приводит к инфраструктурному хаосу: у каждого провайдера (OpenAI GPT-4o / o1, Anthropic Claude 3.5 / 3.7 Sonnet, DeepSeek V3 / R1, локальная Ollama) свой формат API, несовместимые клиентские библиотеки, разрозненные биллинги и риск внезапного исчерпания баланса. Если в компании нейросети используют несколько разработчиков или внутренних сервисов, токены тратятся неконтролируемо, одни и те же запросы оплачиваются повторно, а падение одного провайдера парализует работу приложений. LiteLLM Proxy — это открытый высокопроизводительный AI-шлюз (более 62 000 звёзд на GitHub, лицензия MIT), который объединяет более 100 моделей в единый OpenAI-совместимый интерфейс. LiteLLM кэширует ответы в Redis (сокращая затраты на токены на 30–50%), распределяет нагрузку между аккаунтами, автоматически переключается на резервные модели при ошибках 429 (Rate Limit) и позволяет выпускать виртуальные API-ключи с персональными лимитами бюджета. В этом руководстве мы развернем стабильный релиз LiteLLM Proxy v1.106 в Docker Compose со связкой PostgreSQL 16 и Redis 7, настроим защищенный Nginx с потоковым стримингом (SSE) и подключим мультивендорный пул моделей.

1. Архитектура LiteLLM Proxy: как устроен корпоративный AI-шлюз

Традиционный подход, при котором каждое приложение напрямую общается с серверами OpenAI, Anthropic или DeepSeek, создает жесткую зависимость от конкретного поставщика (Vendor Lock-in) и порождает дыры в безопасности. LiteLLM Proxy выступает централизованным промежуточным звеном (Reverse Proxy & Gateway) между вашими сервисами и внешними нейросетями:

• Единый OpenAI-совместимый эндпоинт. Любой инструмент — будь то веб-интерфейс (Open WebUI, LibreChat), агентная платформа (Dify), среда разработки (Cursor, VS Code) или бэкенд на Python/Node.js — обращается к стандартному адресу /v1/chat/completions или /v1/embeddings. Смена провайдера под капотом не требует переписывания клиентского кода.
• Кэширование ответов и эмбеддингов в Redis. Повторяющиеся системные промпты, популярные запросы пользователей и частые эмбеддинги мгновенно отдаются из оперативной памяти Redis за доли миллисекунды со стоимостью $0.00.
• Отказоустойчивость и цепочки резервирования (Fallbacks). Если upstream-провайдер возвращает ошибку 500, таймаут или исчерпание квоты (HTTP 429 Too Many Requests), шлюз автоматически перенаправляет запрос на запасную модель (например, с Claude Sonnet на GPT-4o или DeepSeek) за миллисекунды, незаметно для клиента.
• Балансировка нагрузки между аккаунтами (Load Balancing). LiteLLM распределяет запросы между несколькими API-ключами одного провайдера по стратегиям simple-shuffle (случайный выбор с весами), least-busy (минимальная очередь) или latency-based-routing (наименьшая задержка отклика).
• Управление виртуальными ключами и бюджетами. Вместо раздачи ценных мастер-ключей провайдеров администратор генерирует временные виртуальные ключи (Virtual Keys) с жесткими ограничениями: лимит бюджета в долларах в месяц, срок действия, максимальное число запросов в минуту (RPM) и список разрешенных моделей.
• Аудит расходов и интеграция с мониторингом. Шлюз протоколирует количество входных и выходных токенов каждого запроса в PostgreSQL и поддерживает экспорт метрик в Prometheus и Langfuse.

2. Системные требования и выбор конфигурации VDS

В отличие от локального инференса весов нейросетей, LiteLLM Proxy выполняет роль легковесного маршрутизатора сетевых пакетов. Ядро сервиса оптимизировано для асинхронной обработки тысяч параллельных HTTP-соединений. Основными потребителями ресурсов на хосте выступают СУБД PostgreSQL (ведение реестра транзакций и ключей) и Redis (буфер кэша и учет лимитов в реальном времени):

3. Подготовка окружения и сетевая безопасность

AI-шлюз оперирует конфиденциальными API-ключами внешних поставщиков и учетными данными разработчиков. Поэтому архитектура развертывания должна следовать принципу наименьших привилегий и полной сетевой изоляции служебных компонентов.

Создайте рабочую директорию проекта /opt/litellm и настройте структуру каталогов:

sudo mkdir -p /opt/litellm/data/postgres /opt/litellm/data/redis
cd /opt/litellm

Для надежной генерации криптографических секретов воспользуйтесь утилитой генератора надежных паролей или сгенерируйте файл /opt/litellm/.env с помощью консольной команды (обратите внимание, что Docker Compose не выполняет подстановку подкоманд $(...) внутри .env-файла, поэтому секреты должны быть сгенерированы командной оболочкой хоста на этапе создания файла):

cat < /opt/litellm/.env
# Мастер-ключ администратора LiteLLM (строго с префиксом sk-)
LITELLM_MASTER_KEY=sk-admin-$(openssl rand -hex 16)

# Секретная соль шифрования ключей провайдеров в БД (нельзя менять после старта!)
LITELLM_SALT_KEY=$(openssl rand -hex 16)

# Параметры подключения к PostgreSQL 16
POSTGRES_DB=litellm
POSTGRES_USER=litellm_user
POSTGRES_PASSWORD=$(openssl rand -hex 20)

# Пароль для сервиса Redis 7
REDIS_PASSWORD=$(openssl rand -hex 20)

# Ключи внешних провайдеров нейросетей
OPENAI_API_KEY=sk-proj-your-openai-key-here
ANTHROPIC_API_KEY=sk-ant-api-your-anthropic-key-here
DEEPSEEK_API_KEY=sk-your-deepseek-key-here
EOF

В результате выполнения команды сформируется готовый файл конфигурации со статическими строковыми значениями:

# Пример содержимого /opt/litellm/.env со сгенерированными ключами:
LITELLM_MASTER_KEY=sk-admin-8f2c3b4e91a05d6e27c81459a0f3b7d1
LITELLM_SALT_KEY=e3b0c44298fc1c149afbf4c8996fb924
POSTGRES_DB=litellm
POSTGRES_USER=litellm_user
POSTGRES_PASSWORD=7d1a2c9f50e48b3a16709fbc8204618e45a2b1c3
REDIS_PASSWORD=4f8e12a9bc70d35e182903746ab19e5c4d0281fa

OPENAI_API_KEY=sk-proj-your-openai-key-here
ANTHROPIC_API_KEY=sk-ant-api-your-anthropic-key-here
DEEPSEEK_API_KEY=sk-your-deepseek-key-here

Установите строгие права доступа, запрещающие чтение секретов посторонними пользователями системы:

chmod 600 /opt/litellm/.env

4. Манифест Docker Compose: запуск связки LiteLLM v1.106, PostgreSQL 16 и Redis 7

В промышленном развертывании СУБД PostgreSQL и кэш Redis не должны публиковать свои порты наружу хоста. Они взаимодействуют со шлюзом исключительно через изолированную внутреннюю сеть Docker. Сам LiteLLM привязывается к интерфейсу обратной петли 127.0.0.1:4000 и закрывается веб-сервером Nginx с TLS-шифрованием.

Создайте файл /opt/litellm/docker-compose.yml:

services:
  # 1. AI-шлюз LiteLLM Proxy
  litellm:
    image: ghcr.io/berriai/litellm:v1.106.4
    container_name: litellm_proxy
    restart: unless-stopped
    ports:
      # Публикация строго на localhost: трафик принимает локальный Nginx с SSL
      - "127.0.0.1:4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    command:
      - "--config=/app/config.yaml"
      - "--port=4000"
      - "--num_workers=4"
    environment:
      DATABASE_URL: "postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}"
      LITELLM_MASTER_KEY: "${LITELLM_MASTER_KEY}"
      LITELLM_SALT_KEY: "${LITELLM_SALT_KEY}"
      STORE_MODEL_IN_DB: "True"
      OPENAI_API_KEY: "${OPENAI_API_KEY}"
      ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY}"
      DEEPSEEK_API_KEY: "${DEEPSEEK_API_KEY}"
      REDIS_HOST: "redis"
      REDIS_PORT: "6379"
      REDIS_PASSWORD: "${REDIS_PASSWORD}"
    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/liveliness')\""]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    mem_limit: 1536m
    cpus: 1.5
    networks:
      - litellm_net

  # 2. Реляционная база данных PostgreSQL 16 (реестр ключей, команд и расходов)
  db:
    image: postgres:16-alpine
    container_name: litellm_db
    restart: unless-stopped
    environment:
      POSTGRES_DB: "${POSTGRES_DB}"
      POSTGRES_USER: "${POSTGRES_USER}"
      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}"
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    # Порт 5432 не пробрасывается на хост — доступ только из внутренней сети контейнеров
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -d ${POSTGRES_DB} -U ${POSTGRES_USER}"]
      interval: 5s
      timeout: 5s
      retries: 10
    mem_limit: 512m
    cpus: 1.0
    networks:
      - litellm_net

  # 3. Быстрый кэш Redis 7 (кэширование ответов, rate-limiting и учет RPM/TPM)
  redis:
    image: redis:7-alpine
    container_name: litellm_redis
    restart: unless-stopped
    command: ["redis-server", "--requirepass", "${REDIS_PASSWORD}", "--save", "60", "1", "--loglevel", "warning"]
    volumes:
      - ./data/redis:/data
    # Порт 6379 изолирован внутри Docker-сети
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD}", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
    mem_limit: 256m
    cpus: 0.5
    networks:
      - litellm_net

networks:
  litellm_net:
    driver: bridge

Если вам требуется собрать специализированную конфигурацию для других веб-сервисов, используйте наш онлайн-генератор Docker Compose.

5. Конфигурация config.yaml: мультивендорный пул моделей и Fallback-цепочки

Файл config.yaml является центральным мозгом маршрутизатора LiteLLM. Здесь определяются доступные виртуальные группы моделей (Model Groups), веса балансировки, приоритеты и правила автоматического переключения при инцидентах.

Создайте файл /opt/litellm/config.yaml:

model_list:
  # 1. Флагман Anthropic Claude 3.5 Sonnet
  - model_name: claude-3-5-sonnet
    litellm_params:
      model: anthropic/claude-3-5-sonnet-20241022
      api_key: os.environ/ANTHROPIC_API_KEY
      rpm: 100
      weight: 1

  # 2. Флагман OpenAI GPT-4o
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
      rpm: 150
      weight: 1

  # 3. Экономичная модель DeepSeek V3 (универсальный чат и код)
  - model_name: deepseek-chat
    litellm_params:
      model: deepseek/deepseek-chat
      api_key: os.environ/DEEPSEEK_API_KEY
      api_base: https://api.deepseek.com
      rpm: 200
      weight: 2

  # 4. Рассуждающая модель DeepSeek R1 (математика, архитектура, глубокий анализ)
  - model_name: deepseek-reasoner
    litellm_params:
      model: deepseek/deepseek-reasoner
      api_key: os.environ/DEEPSEEK_API_KEY
      api_base: https://api.deepseek.com
      rpm: 60

  # 5. Локальная модель Ollama (если развернута на сервере)
  - model_name: local-llama
    litellm_params:
      model: ollama/llama3.1:8b
      api_base: http://host.docker.internal:11434

router_settings:
  # Стратегия балансировки: взвешенный выбор с учетом RPM и весов
  routing_strategy: "simple-shuffle"
  redis_host: os.environ/REDIS_HOST
  redis_port: os.environ/REDIS_PORT
  redis_password: os.environ/REDIS_PASSWORD
  # Проверка лимитов контекстного окна до отправки запроса провайдеру
  enable_pre_call_checks: true
  # Время охлаждения сбойного развертывания (в секундах) при 429 RateLimit
  cooldown_time: 30

  # Каскадные цепочки резервирования (Fallbacks) на уровне маршрутизатора
  fallbacks:
    # При сбое Claude переключаемся на GPT-4o, затем на DeepSeek
    - {"claude-3-5-sonnet": ["gpt-4o", "deepseek-chat"]}
    # При сбое GPT-4o переключаемся на DeepSeek V3
    - {"gpt-4o": ["deepseek-chat"]}

litellm_settings:
  # Глобальное количество повторных попыток при сбоях сети
  num_retries: 2

  # Включение централизованного кэширования в Redis
  cache: true
  cache_params:
    type: "redis"
    host: os.environ/REDIS_HOST
    port: os.environ/REDIS_PORT
    password: os.environ/REDIS_PASSWORD
    supported_call_types: ["completion", "acompletion", "embedding", "aembedding"]
    ttl: 86400 # Время жизни кэша (в секундах, 24 часа)

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL

6. Кэширование ответов в Redis: экономия до 50% затрат на токены

В реальной эксплуатации существенная доля запросов к нейросетям содержит идентичные входные данные: статические системные инструкции ботов поддержки, типовые вопросы пользователей по каталогу товаров, генерация эмбеддингов для статических документов или повторяющиеся тесты разработчиков.

LiteLLM оптимизирует эти вызовы через быстрый точный кэш (Exact Match Cache):

• Точный кэш (Exact Match Cache). Вычисляет криптографический хэш от комбинации системного промпта, сообщений диалога, параметров температуры (temperature) и идентификатора модели. При повторном запросе ответ возвращается из оперативной памяти Redis за 1–3 миллисекунды вместо 1.5–4 секунд ожидания облачного провайдера. Стоимость такого вызова составляет ровно $0.00.
• Кэширование векторных эмбеддингов (Embedding Cache). При построении RAG-систем (поиска по корпоративной базе знаний) векторизация повторяющихся фрагментов текста потребляет существенный бюджет. LiteLLM сохраняет сгенерированные векторы в Redis по хэшу текста, исключая повторные платные вызовы text-embedding-3-small или multilingual-e5.

Работу кэша легко проверить через заголовки HTTP-ответа. При попадании в кэш LiteLLM возвращает заголовок x-litellm-cache-key с хэшем записи в Redis, а время отклика падает до нескольких миллисекунд без расхода токенов у провайдера.

7. Настройка Nginx Reverse Proxy с поддержкой SSE-стриминга и SSL Let's Encrypt

При работе с большими языковыми моделями критически важна посимвольная потоковая передача ответа (Server-Sent Events, SSE). Если на промежуточном прокси-сервере включена стандартная буферизация Nginx, пользователь не увидит постепенного появления текста: Nginx будет накапливать байты в памяти до завершения ответа или переполнения буфера, что создаст ощущение зависшего интерфейса.

Создайте конфигурационный файл виртуального хоста /etc/nginx/sites-available/litellm.conf (замените llm.example.ru на ваш реальный поддомен):

server {
    listen 80;
    server_name llm.example.ru;

    # Отключение буферизации для мгновенного потокового вывода токенов (SSE)
    proxy_buffering off;
    proxy_cache off;

    # Увеличенный таймаут для рассуждающих моделей (DeepSeek R1, OpenAI o1)
    proxy_read_timeout 600s;
    proxy_connect_timeout 60s;
    proxy_send_timeout 600s;

    # Поддержка загрузки изображений и документов в Vision-модели
    client_max_body_size 64M;

    location / {
        proxy_pass http://127.0.0.1:4000;
        proxy_http_version 1.1;

        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_set_header X-Forwarded-Proto $scheme;

        # Поддержка WebSocket для интерактивного дашборда
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Активируйте конфигурацию и проверьте синтаксис:

sudo ln -s /etc/nginx/sites-available/litellm.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Выпустите бесплатный сертификат Let's Encrypt с автоматической перенастройкой редиректа на HTTPS с помощью Certbot:

sudo certbot --nginx -d llm.example.ru --redirect --non-interactive --agree-tos -m admin@example.ru

После применения сертификата проверьте корректность SSL-цепочки через утилиту проверки SSL-сертификатов и убедитесь с помощью онлайн сканера портов, что служебные порты PostgreSQL (5432), Redis (6379) и внутренний порт LiteLLM (4000) закрыты от внешнего мира. Если вам требуется тонкая настройка веб-сервера, воспользуйтесь нашим генератором конфигураций Nginx Reverse Proxy.

8. Виртуальные API-ключи, квоты бюджетов и управление через веб-дашборд

Откройте браузер и перейдите по адресу https://llm.example.ru/ui. Введите значение LITELLM_MASTER_KEY из файла .env для авторизации в панели администратора.

Главное преимущество LiteLLM перед прямой раздачей токенов провайдеров — концепция виртуальных ключей (Virtual Keys). Вместо того чтобы делиться с каждым разработчиком мастер-ключом OpenAI или Anthropic с неограниченным кредитным лимитом, администратор создает изолированные ключи с персональными границами:

curl -X POST "https://llm.example.ru/key/generate" \
  -H "Authorization: Bearer sk-admin-master-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "key_alias": "dev-team-alpha",
    "models": ["gpt-4o", "deepseek-chat"],
    "max_budget": 25.00,
    "budget_duration": "30d",
    "rpm_limit": 60,
    "tpm_limit": 60000
  }'

В ответ шлюз сгенерирует уникальный ключ вида sk-litellm-.... Если приложение исчерпает лимит в $25.00 в течение 30 дней, шлюз мягко отклонит последующие запросы с кодом 400 BudgetExceededError, защитив корпоративный счет от случайных бесконечных циклов в коде или несанкционированного перерасхода.

9. Интеграция с клиентами: подключение Cursor, Open WebUI, Dify и Python SDK

Поскольку LiteLLM на 100% повторяет спецификацию OpenAI API, его можно подключить к любому существующему клиенту за минуту — достаточно переопределить адрес базового URL и передать сгенерированный виртуальный ключ.

1. Вызов через стандартную библиотеку Python (OpenAI SDK)

Вам не нужны сторонние пакеты — используйте официальную библиотеку openai:

from openai import OpenAI

# Подключение к вашему корпоративному AI-шлюзу
client = OpenAI(
    base_url="https://llm.example.ru/v1",
    api_key="sk-litellm-dev-team-alpha"
)

response = client.chat.completions.create(
    model="deepseek-chat", # Автоматически маршрутизируется через шлюз
    messages=[
        {"role": "system", "content": "Вы опытный DevOps-инженер платформы SysKit."},
        {"role": "user", "content": "В чем главное преимущество централизованного AI-шлюза?"}
    ],
    temperature=0.3
)

print(response.choices[0].message.content)

2. Тестовый запрос через cURL

Быстрая проверка доступности и потокового стриминга из консоли сервера:

curl -s -N "https://llm.example.ru/v1/chat/completions" \
  -H "Authorization: Bearer sk-litellm-dev-team-alpha" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "stream": true,
    "messages": [{"role": "user", "content": "Привет! Проверь задержку первого токена."}]
  }'

3. Подключение сред разработки и веб-интерфейсов

• Cursor / VS Code (Continue): В настройках расширения выберите провайдера OpenAI Compatible, укажите Base URL https://llm.example.ru/v1 и вставьте ваш виртуальный ключ. Теперь команда пишет код с автодополнением от Claude Sonnet, GPT-4o или DeepSeek V3 без риска утечки мастер-ключа.
• Веб-интерфейсы: Шлюз бесшовно подключается к Open WebUI или корпоративному чату LibreChat как стандартное подключение OpenAI.
• No-code автоматизация: В платформе создания AI-агентов Dify достаточно настроить одного провайдера OpenAI-API, направив его на шлюз, чтобы все сценарии и чат-боты получили доступ к пулу из сотен моделей с единой квотой расходов.

10. Резервное копирование базы данных и обслуживание шлюза

Вся конфигурация виртуальных ключей, накопленная статистика расходов по проектам и журнал аудита хранятся в реляционной СУБД PostgreSQL.

Создайте скрипт автоматического создания резервной копии /opt/litellm/backup.sh:

#!/usr/bin/env bash
set -euo pipefail

BACKUP_DIR="/opt/litellm/backups"
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
mkdir -p "${BACKUP_DIR}"

# 1. Дамп базы данных PostgreSQL в сжатый архив
docker exec litellm_db pg_dump -U litellm_user litellm | gzip > "${BACKUP_DIR}/litellm_pg_${TIMESTAMP}.sql.gz"

# 2. Сохранение конфигурации и секретов
tar -czf "${BACKUP_DIR}/litellm_configs_${TIMESTAMP}.tar.gz" -C /opt/litellm .env config.yaml docker-compose.yml

# 3. Удаление бэкапов старше 14 дней
find "${BACKUP_DIR}" -type f -mtime +14 -delete

echo "[$(date)] Резервная копия LiteLLM успешно создана: ${BACKUP_DIR}"

Сделайте скрипт исполняемым и добавьте задачу в планировщик crontab -e для ежедневного выполнения в 03:30 ночи:

chmod +x /opt/litellm/backup.sh
# 30 3 * * * /opt/litellm/backup.sh >> /var/log/litellm_backup.log 2>&1

Для обновления версий компонентов без простоя достаточно выполнить:

cd /opt/litellm
docker compose pull
docker compose up -d

11. Чек-лист проверки готовности AI-шлюза к production-эксплуатации