Skip to content

DEPLOYMENT.md

Latest commit

 

History

History
524 lines (396 loc) · 16.1 KB

DEPLOYMENT.md

File metadata and controls

524 lines (396 loc) · 16.1 KB
Raw

📦 VLLM Proxy Service - Подробное руководство по развертыванию

🎯 Обзор

VLLM Proxy Service - это прокси-сервис для модели OSS120B, обеспечивающий совместимость с OpenAI API и корректную обработку tool calls для интеграции с n8n workflows.

📋 Системные требования

Минимальные требования

  • GPU: 2x GPU с минимум 24GB VRAM каждая (рекомендуется NVIDIA A100, V100, RTX 4090)
  • RAM: 64GB системной памяти
  • CPU: 16 ядер
  • Диск: 500GB свободного места (для модели и кэшей)
  • ОС: Ubuntu 20.04+ с установленным NVIDIA Driver 535+

Программные зависимости

  • Docker: 24.0+
  • Docker Compose: 2.20+
  • NVIDIA Container Toolkit: Последняя версия
  • CUDA: 12.0+

🚀 Быстрый запуск (Production)

Шаг 1: Подготовка сервера

# Подключение к серверу
ssh root@YOUR_SERVER_IP

# Обновление системы
apt update && apt upgrade -y

# Установка Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

# Установка Docker Compose
curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

# Установка NVIDIA Container Toolkit
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

apt update && apt install -y nvidia-container-toolkit
nvidia-ctk runtime configure --runtime=docker
systemctl restart docker

# Проверка GPU
nvidia-smi
docker run --rm --gpus all nvidia/cuda:12.0-base-ubuntu20.04 nvidia-smi

Шаг 2: Клонирование и подготовка проекта

# Создание рабочей директории
mkdir -p /opt/vllm-proxy
cd /opt/vllm-proxy

# Получение проекта (если у вас есть архив)
# Скопируйте архив на сервер и распакуйте
scp vllm-proxy-service.tar.gz root@YOUR_SERVER_IP:/opt/vllm-proxy/
tar -xzf vllm-proxy-service.tar.gz

# Или клонируйте из git репозитория
# git clone <your-repo-url> .

# Создание необходимых директорий
mkdir -p logs/{proxy,vllm} data config/grafana/{provisioning,dashboards}
chmod -R 755 logs data config

Шаг 3: Настройка переменных окружения

# Копирование и настройка .env файла
cp .env.example .env

# Редактирование конфигурации
nano .env

Основные переменные для production:

# VLLM Configuration
VLLM_BASE_URL=http://vllm:8000
VLLM_API_KEY=your-secure-production-api-key-here
VLLM_TIMEOUT=300

# Redis Configuration
REDIS_URL=redis://redis:6379
REDIS_TTL=3600
REDIS_MAX_CONNECTIONS=50

# Proxy Configuration
LOG_LEVEL=INFO
ENABLE_DOCS=false
ENABLE_METRICS=true
ENABLE_CORS=true
CORS_ORIGINS=https://your-n8n-domain.com,https://your-api-domain.com

# Security
PROXY_API_KEY=your-super-secure-proxy-api-key-here
ENABLE_RATE_LIMITING=true
RATE_LIMIT_REQUESTS=1000
RATE_LIMIT_WINDOW=60

# Monitoring
GRAFANA_PASSWORD=your-secure-grafana-password

Шаг 4: Подготовка модели

# Проверка наличия модели в Hugging Face кэше
ls -la ~/.cache/huggingface/

# Если модель не скачана, используйте следующий скрипт:
python3 -c "
from huggingface_hub import snapshot_download
snapshot_download('openai/gpt-oss-120b', cache_dir='/root/.cache/huggingface')
"

# Убедитесь, что модель доступна
ls -la ~/.cache/huggingface/models--openai--gpt-oss-120b/

Шаг 5: Запуск сервисов

# Запуск полного стека
docker-compose -f docker/docker-compose.yml up -d

# Проверка статуса сервисов
docker-compose -f docker/docker-compose.yml ps

# Просмотр логов
docker-compose -f docker/docker-compose.yml logs -f

# Проверка отдельных сервисов
docker-compose -f docker/docker-compose.yml logs vllm      # Логи VLLM
docker-compose -f docker/docker-compose.yml logs proxy    # Логи прокси
docker-compose -f docker/docker-compose.yml logs redis    # Логи Redis

Шаг 6: Проверка работоспособности

# Health checks
curl http://localhost:5000/health/live    # Прокси
curl http://localhost:8000/health         # VLLM
curl http://localhost:6379                # Redis (должен ответить)

# Проверка API endpoints
curl -H "Authorization: Bearer your-proxy-api-key" \
     http://localhost:5000/v1/models

# Тест tool calls
curl -X POST http://localhost:5000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-proxy-api-key" \
  -d '{
    "model": "openai/gpt-oss-120b",
    "messages": [{"role": "user", "content": "What is the weather like?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string"}
          }
        }
      }
    }]
  }'

🔧 Конфигурация для различных сценариев

Scenario 1: Development/Testing

# Использование dev конфигурации
cp .env.example .env.dev

# Настройка для разработки
echo "LOG_LEVEL=DEBUG" >> .env.dev
echo "ENABLE_DOCS=true" >> .env.dev
echo "CORS_ORIGINS=*" >> .env.dev

# Запуск с dev конфигурацией
docker-compose -f docker/docker-compose.yml --env-file .env.dev up -d

Scenario 2: High Load Production

# Настройка для высокой нагрузки
cat >> .env << EOF
# High Load Configuration
PROXY_WORKERS=8
RATE_LIMIT_REQUESTS=5000
RATE_LIMIT_WINDOW=60
REDIS_MAX_CONNECTIONS=200
VLLM_TIMEOUT=600
EOF

# Увеличение лимитов Redis
docker-compose -f docker/docker-compose.yml exec redis redis-cli CONFIG SET maxmemory 2gb
docker-compose -f docker/docker-compose.yml exec redis redis-cli CONFIG SET maxmemory-policy allkeys-lru

Scenario 3: SSL/HTTPS Setup

# Создание SSL сертификатов
mkdir -p /opt/vllm-proxy/ssl
cd /opt/vllm-proxy/ssl

# Самоподписанный сертификат (для тестирования)
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes \
  -subj "/C=US/ST=State/L=City/O=Organization/CN=your-domain.com"

# Или используйте Let's Encrypt
# certbot --nginx -d your-domain.com

# Настройка nginx reverse proxy
cat > nginx.conf << 'EOF'
events {
    worker_connections 1024;
}

http {
    upstream vllm_proxy {
        server localhost:5000;
    }

    server {
        listen 443 ssl;
        server_name your-domain.com;

        ssl_certificate /etc/ssl/cert.pem;
        ssl_certificate_key /etc/ssl/key.pem;

        location / {
            proxy_pass http://vllm_proxy;
            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;
        }
    }
}
EOF

# Запуск nginx контейнера
docker run -d --name nginx-proxy \
  -p 443:443 \
  -v /opt/vllm-proxy/ssl:/etc/ssl:ro \
  -v /opt/vllm-proxy/nginx.conf:/etc/nginx/nginx.conf:ro \
  --network vllm-proxy_vllm-network \
  nginx:alpine

🔍 Мониторинг и диагностика

Доступ к мониторингу

# Grafana Dashboard
# URL: http://localhost:3000
# Логин: admin
# Пароль: значение GRAFANA_PASSWORD из .env

# Prometheus Metrics
# URL: http://localhost:9090

# Основные метрики для мониторинга:
# - proxy_requests_total
# - proxy_request_duration_seconds
# - proxy_tool_calls_total
# - proxy_vllm_errors_total

Полезные команды диагностики

# Проверка ресурсов
docker stats

# Логи в реальном времени
docker-compose -f docker/docker-compose.yml logs -f --tail=100

# Проверка подключения между сервисами
docker-compose -f docker/docker-compose.yml exec proxy curl http://vllm:8000/health
docker-compose -f docker/docker-compose.yml exec proxy redis-cli -h redis ping

# Проверка использования GPU
nvidia-smi -l 1

# Анализ производительности
curl -w "@curl-format.txt" -o /dev/null -s http://localhost:5000/v1/models

Создайте файл curl-format.txt:

     time_namelookup:  %{time_namelookup}\n
        time_connect:  %{time_connect}\n
     time_appconnect:  %{time_appconnect}\n
    time_pretransfer:  %{time_pretransfer}\n
       time_redirect:  %{time_redirect}\n
  time_starttransfer:  %{time_starttransfer}\n
                     ----------\n
          time_total:  %{time_total}\n

🛠️ Управление сервисами

Основные команды

# Остановка всех сервисов
docker-compose -f docker/docker-compose.yml down

# Перезапуск отдельного сервиса
docker-compose -f docker/docker-compose.yml restart proxy

# Обновление конфигурации
docker-compose -f docker/docker-compose.yml up -d --force-recreate

# Очистка volumes (ВНИМАНИЕ: удалит все данные)
docker-compose -f docker/docker-compose.yml down -v

# Резервное копирование Redis
docker-compose -f docker/docker-compose.yml exec redis redis-cli --rdb /data/backup.rdb

# Восстановление Redis
docker-compose -f docker/docker-compose.yml exec redis redis-cli --rdb /data/backup.rdb

Обновление кода

# Остановка прокси сервиса
docker-compose -f docker/docker-compose.yml stop proxy

# Пересборка образа с новым кодом
docker-compose -f docker/docker-compose.yml build proxy

# Запуск обновленного сервиса
docker-compose -f docker/docker-compose.yml up -d proxy

# Zero-downtime deployment (если у вас несколько инстансов)
docker-compose -f docker/docker-compose.yml up -d --scale proxy=2 --no-recreate
# Подождать запуска
docker-compose -f docker/docker-compose.yml up -d --scale proxy=1

📊 Бэкап и восстановление

Автоматический бэкап

# Создание скрипта бэкапа
cat > /opt/vllm-proxy/backup.sh << 'EOF'
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/opt/vllm-proxy/backups/$DATE"

mkdir -p $BACKUP_DIR

# Бэкап конфигурации
cp -r /opt/vllm-proxy/.env $BACKUP_DIR/
cp -r /opt/vllm-proxy/config $BACKUP_DIR/

# Бэкап Redis данных
docker-compose -f /opt/vllm-proxy/docker/docker-compose.yml exec -T redis \
  redis-cli --rdb /data/backup_$DATE.rdb

# Копирование из контейнера
docker cp vllm-redis:/data/backup_$DATE.rdb $BACKUP_DIR/

# Архивирование
tar -czf $BACKUP_DIR.tar.gz -C $BACKUP_DIR .
rm -rf $BACKUP_DIR

# Удаление старых бэкапов (оставляем 7 дней)
find /opt/vllm-proxy/backups -name "*.tar.gz" -mtime +7 -delete

echo "Backup completed: $BACKUP_DIR.tar.gz"
EOF

chmod +x /opt/vllm-proxy/backup.sh

# Настройка cron для автоматического бэкапа
echo "0 2 * * * /opt/vllm-proxy/backup.sh" | crontab -

🔒 Безопасность

Настройка firewall

# Настройка ufw
ufw allow 22/tcp      # SSH
ufw allow 5000/tcp    # Proxy API
ufw allow 443/tcp     # HTTPS (если используется)
ufw allow 3000/tcp    # Grafana (только для администраторов)
ufw --force enable

# Ограничение доступа к внутренним портам
ufw deny 8000/tcp     # VLLM (только внутренний доступ)
ufw deny 6379/tcp     # Redis (только внутренний доступ)
ufw deny 9090/tcp     # Prometheus (только внутренний доступ)

Настройка API ключей

# Генерация безопасных API ключей
VLLM_KEY=$(openssl rand -base64 32)
PROXY_KEY=$(openssl rand -base64 32)
GRAFANA_PASS=$(openssl rand -base64 16)

# Обновление .env файла
sed -i "s/your-production-api-key-here/$VLLM_KEY/" .env
sed -i "s/your-super-secure-proxy-api-key-here/$PROXY_KEY/" .env
sed -i "s/your-secure-grafana-password/$GRAFANA_PASS/" .env

echo "API Keys updated. Save these keys securely:"
echo "VLLM_API_KEY: $VLLM_KEY"
echo "PROXY_API_KEY: $PROXY_KEY"
echo "GRAFANA_PASSWORD: $GRAFANA_PASS"

🚨 Решение проблем

Часто встречающиеся проблемы

1. VLLM не запускается

# Проверка GPU
nvidia-smi

# Проверка NVIDIA Container Runtime
docker run --rm --gpus all nvidia/cuda:12.0-base-ubuntu20.04 nvidia-smi

# Проверка логов VLLM
docker-compose -f docker/docker-compose.yml logs vllm

# Возможные решения:
# - Увеличить timeout в docker-compose.yml
# - Проверить доступность модели
# - Освободить GPU память

2. Proxy возвращает 502 ошибки

# Проверка подключения к VLLM
docker-compose -f docker/docker-compose.yml exec proxy curl http://vllm:8000/health

# Проверка переменных окружения
docker-compose -f docker/docker-compose.yml exec proxy env | grep VLLM

# Перезапуск прокси
docker-compose -f docker/docker-compose.yml restart proxy

3. Redis подключение не работает

# Проверка Redis
docker-compose -f docker/docker-compose.yml exec redis redis-cli ping

# Проверка сетевого подключения
docker-compose -f docker/docker-compose.yml exec proxy redis-cli -h redis ping

# Очистка Redis (если нужно)
docker-compose -f docker/docker-compose.yml exec redis redis-cli flushall

Логи и диагностика

# Детальные логи прокси в режиме отладки
docker-compose -f docker/docker-compose.yml exec proxy \
  uvicorn src.main:app --log-level debug --reload

# Анализ производительности
docker-compose -f docker/docker-compose.yml exec proxy \
  python -m cProfile -o profile.stats src/main.py

# Проверка состояния процессов
docker-compose -f docker/docker-compose.yml exec proxy ps aux

📞 Поддержка и контакты

В случае проблем:

  1. Проверьте логи: docker-compose logs -f
  2. Убедитесь в корректности .env конфигурации
  3. Проверьте системные ресурсы: htop, nvidia-smi
  4. Обратитесь к разработчикам с полным описанием проблемы

Полезные ресурсы:

Статус документа: ✅ Готов к использованию Версия: 1.0 Последнее обновление: $(date)