From 4f8f2ad6877633abdceae3dbae82d9e534834dce Mon Sep 17 00:00:00 2001 From: Zhirik1337 Date: Tue, 22 Sep 2026 22:26:07 +0300 Subject: [PATCH] =?UTF-8?q?=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB=D0=B5?= =?UTF-8?q?=D0=BD=20fallback=20=D0=B8=20gpu=20=D0=BE=D0=B1=D0=B2=D1=8F?= =?UTF-8?q?=D0=B7=D0=BA=D0=B0=20=D0=B4=D0=BB=D1=8F=20=D1=83=D1=81=D0=BA?= =?UTF-8?q?=D0=BE=D1=80=D0=B5=D0=BD=D0=B8=D1=8F=20=D0=BE=D0=B1=D1=83=D1=87?= =?UTF-8?q?=D0=B5=D0=BD=D0=B8=D1=8F=20=D0=B8=20=D0=BF=D1=80=D0=BE=D0=B8?= =?UTF-8?q?=D0=B7=D0=B2=D0=BE=D0=B4=D0=B8=D1=82=D0=B5=D0=BB=D1=8C=D0=BD?= =?UTF-8?q?=D0=BE=D1=81=D1=82=D0=B8=20=D0=BC=D0=BE=D0=B4=D0=B5=D0=BB=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/DOCKER.md | 143 +++++++++++++++++++++++++++++-------------------- 1 file changed, 84 insertions(+), 59 deletions(-) diff --git a/docs/DOCKER.md b/docs/DOCKER.md index ae96d6d..ba2d481 100644 --- a/docs/DOCKER.md +++ b/docs/DOCKER.md @@ -1,81 +1,106 @@ -# Руководство по запуску FlyGuard в Docker +# Руководство по запуску FlyGuard в Docker (NVIDIA GPU + Graceful CPU Fallback) -## 1. Быстрая сборка образа +FlyGuard поставляется в виде универсального производственного Docker-образа с поддержкой аппаратного ускорения **NVIDIA GPU (CUDA 12.x)** и автоматического гибридного переключения на **CPU (Graceful Fallback)** при отсутствии или сбое графического процессора. -Сборка легковесного образа на базе `python:3.11-slim-bookworm` (включает OpenMP/BLAS и зависимости): +--- +## 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 . ``` +* **База**: `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. ---- - -## 2. Запуск тестов - -Контейнер по умолчанию выполняет самодиагностику и тестовый набор: - +### Облегченный CPU-образ (опционально, ~200 МБ) ```bash -# Прямой запуск через Docker -docker run --rm flyguard:latest - -# Либо через docker compose -docker compose run --rm test +docker build --target cpu -t flyguard:cpu . ``` --- -## 3. Запуск конвейера и бенчмарка с данными лидара +## 3. Запуск через Docker Compose -Датасеты монтируются в контейнер в каталог `/data`: +В [`docker-compose.yml`](file:///home/wpng1337/Brainrot_Muxa/docker-compose.yml) настроены готовые сервисы с автоматической резервацией GPU: ```bash -# Оценка ложных тревог по всем бэгам -docker run --rm \ - -v /path/to/lidar/data:/data:ro \ - -v $(pwd)/artifacts:/app/artifacts \ - --shm-size=2g \ - flyguard:latest evaluate --mbon-dir artifacts/mbon_folds - -# Запуск полигона дальности с новыми аугментациями -docker run --rm \ - -v /path/to/lidar/data:/data:ro \ - -v $(pwd)/artifacts:/app/artifacts \ - --shm-size=2g \ - flyguard:latest benchmark --memory artifacts/mushroom_body.npz --augment - -# Прогон по конкретному бэгу с выводом телеметрии в реальном времени -docker run --rm \ - -v /path/to/lidar/data:/data:ro \ - flyguard:latest pipeline --bag /data/for_hackathon/doubleT_obstacle --verbose -``` - ---- - -## 4. Интерактивная отладка - -Войти внутрь контейнера с настроенным окружением: - -```bash -docker compose run --rm shell +# 1. Главный сервис: сквозная обработка данных лидара +docker compose up # или -docker run -it --rm \ - -v /path/to/lidar/data:/data:ro \ - -v $(pwd)/artifacts:/app/artifacts \ - flyguard:latest bash +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 ``` --- -## 5. Доступные команды шорткатов entrypoint +## 4. Прямой запуск через `docker run` -Точка входа `docker-entrypoint.sh` поддерживает удобные псевдонимы: +### Запуск с аппаратным ускорением 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 +``` -* `test` — запускает автономный набор юнит-тестов (`tests/run_tests.py`) -* `pytest` — запускает `pytest tests` -* `pipeline` — вызывает `tools/run_pipeline.py` -* `benchmark` — вызывает `tools/make_benchmark.py` -* `evaluate` — вызывает `tools/evaluate.py` -* `train-mbon` — вызывает `tools/train_mbon.py` -* `train-track` — вызывает `tools/train_track.py` -* `plot` — вызывает `tools/plot_benchmark.py` -* `bash` / `sh` — открывает командную оболочку +### Запуск на 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 без падения программы.