# Руководство по запуску FlyGuard в Docker (NVIDIA GPU + Graceful CPU Fallback)

FlyGuard поставляется в виде универсального производственного Docker-образа с поддержкой аппаратного ускорения **NVIDIA GPU (CUDA 12.x)** и автоматического гибридного переключения на **CPU (Graceful Fallback)** при отсутствии или сбое графического процессора.

---

## 1. Быстрый запуск через helper-скрипт `docker-run.sh`

Скрипт [`docker-run.sh`](file:///home/wpng1337/Brainrot_Muxa/docker-run.sh) автоматически проверяет наличие `nvidia-smi` и подключает флаги `--gpus all`:

```bash
# Сборка универсального образа (flyguard:latest)
./docker-run.sh build

# Общий запуск конвейера (по всем бэгам в data/)
./docker-run.sh run

# Проверка видимости GPU и драйвера внутри контейнера
./docker-run.sh info

# Прогон всех 41 верификационных unit-тестов
./docker-run.sh test

# Обучение клеток Кеньона (50 000 KC) на GPU
./docker-run.sh train-mbon --device cuda --n-kc 50000

# Генерация бенчмарка дальности с аугментациями
./docker-run.sh benchmark
```

---

## 2. Сборка образов напрямую через `docker build`

### Универсальный образ с GPU-ускорением (по умолчанию)
```bash
docker build -t flyguard:latest -f Dockerfile.offline .
```
* **База**: `nvidia/cuda:12.4.1-runtime-ubuntu22.04`
* **Python**: 3.11, PyTorch CUDA 12.1+, cuDNN, OpenMP `libgomp1`
* **Поддерживаемые архитектуры**: Ada Lovelace (RTX 4070 Ti Super 16GB), Ampere, Hopper, Turing.
* **Отказоустойчивость**: если запущен без `--gpus all`, прозрачно работает на CPU.

### Облегченный CPU-образ (опционально, ~200 МБ)
```bash
docker build --target cpu -t flyguard:cpu -f Dockerfile.offline .
```

---

## 3. Запуск через Docker Compose

В [`docker-compose.yml`](file:///home/wpng1337/Brainrot_Muxa/docker-compose.yml) настроены готовые сервисы с автоматической резервацией GPU:

```bash
# 1. Главный сервис: сквозная обработка данных лидара
docker compose up
# или
docker compose run --rm pipeline

# 2. Проверка оборудования
docker compose run --rm info

# 3. Полный набор unit-тестов
docker compose run --rm test

# 4. Высокопроизводительное обучение MBON на 50k клеток
docker compose run --rm train-mbon

# 5. Оценка метрик детекции и ложных тревог
docker compose run --rm evaluate

# 6. Интерактивная отладка в bash
docker compose run --rm shell
```

---

## 4. Прямой запуск через `docker run`

### Запуск с аппаратным ускорением NVIDIA GPU:
```bash
docker run --rm -it \
  --gpus all \
  -v /path/to/lidar/data:/data:ro \
  -v $(pwd)/artifacts:/app/artifacts \
  --shm-size=8g \
  flyguard:latest pipeline --all --verbose
```

### Запуск на CPU (стенд жюри без GPU / fallback):
```bash
docker run --rm -it \
  -v /path/to/lidar/data:/data:ro \
  -v $(pwd)/artifacts:/app/artifacts \
  --shm-size=4g \
  flyguard:latest pipeline --all --verbose
```

---

## 5. Архитектура Graceful Fallback на CPU

Конвейер использует гибридную схему вычислений:
1. **Статический выбор**: при инициализации `device = "cuda" if is_cuda_available() else "cpu"`.
2. **Динамический рантайм-откат**: если в процессе работы видеокарта возвращает ошибку (CUDA OOM, отвал драйвера), модуль [`flyguard/device.py`](file:///home/wpng1337/Brainrot_Muxa/flyguard/device.py) фиксирует сбой через `notify_cuda_error(exc)`, текущий кадр мгновенно досчитывается на CPU через NumPy/SciPy, а конвейер переходит в режим CPU без падения программы.