# YOLO Train WebUI

Локальный веб-интерфейс для обучения моделей Ultralytics YOLO с журналом,
графиками метрик, мягкой остановкой и интеграцией MLflow.

## Возможности

- задачи `detect`, `segment`, `classify`, `pose` и `obb`;
- локальные датасеты и официальные имена моделей Ultralytics;
- настройка эпох, размера изображения, batch, устройства, workers и patience;
- цветовые и геометрические аугментации, Mosaic, MixUp, CutMix, copy-paste,
  erasing и AutoAugment;
- live-прогресс, журнал, графики метрик и восстановление состояния после
  переподключения браузера;
- сохранение профилей запуска и кооперативная остановка обучения;
- локальное MLflow-хранилище или внешний tracking server.

## Локальная установка и запуск

Нужны Python 3.11+ и [uv](https://docs.astral.sh/uv/).

```bash
uv sync --locked
uv run yolo-train-webui
```

Альтернативный запуск как Python-модуля:

```bash
uv run -m yolo_webui
```

Откройте `http://127.0.0.1:8000`. Сервер по умолчанию слушает только loopback.

При первом использовании официального имени модели, например `yolo11n.pt`,
Ultralytics скачает веса. Пользовательские модели размещайте в `./models` или в
`./runs`, а датасеты — в `./datasets`. Результаты записываются в `./runs`.

## Docker Compose

```bash
docker compose up --build
```

WebUI будет доступен по `http://127.0.0.1:8000`. Compose намеренно публикует порт
только на loopback. Не заменяйте адрес на `0.0.0.0` без аутентифицирующего reverse
proxy: API позволяет запускать и останавливать ресурсоёмкие задачи.

Для NVIDIA GPU раскомментируйте секцию `deploy.resources.reservations.devices` в
`docker-compose.yml`. Образ устанавливает зафиксированные в `uv.lock` зависимости;
для другого варианта PyTorch используйте отдельно сгенерированный и проверенный
lock-файл.

## Разрешённые пути

API отклоняет URL и не разрешает обучению читать или записывать произвольные пути:

- датасеты и файлы классов — `./datasets`;
- модели — `./models` и `./runs`;
- результаты — `./runs`.

Дополнительные доверенные корни можно перечислить через системный разделитель путей
в `YOLO_WEBUI_DATA_ROOTS`, `YOLO_WEBUI_MODEL_ROOTS` и
`YOLO_WEBUI_RUN_ROOTS`. Например, в Linux/macOS:

```bash
YOLO_WEBUI_DATA_ROOTS=/mnt/datasets:/data/shared uv run yolo-train-webui
```

PyTorch checkpoints загружаются с включённым restricted-режимом Ultralytics
(`ULTRALYTICS_SAFE_LOAD=1`). Используйте только модели из доверенных источников.

## Датасеты

Для `detect`, `segment`, `pose` и `obb` укажите YAML-файл либо каталог со структурой
`images/` + `labels/`. WebUI может детерминированно разделить такой каталог на
train/val. Для `classify` нужен готовый каталог с `train` и `val`/`test`, внутри
которых изображения разложены по классам; автоматическое detection-style разбиение
для этой задачи отключено.

## MLflow

По умолчанию метаданные записываются в `./mlflow.db`. Открыть интерфейс просмотра:

```bash
uv run mlflow ui --backend-store-uri sqlite:///mlflow.db
```

Затем откройте `http://127.0.0.1:5000`. Для внешнего tracking server укажите его URI
в настройках WebUI.

Для каждого завершённого запуска Ultralytics записывает в MLflow параметры,
поэпоховые метрики, графики, `results.csv` и checkpoints
`weights/best.pt`/`weights/last.pt`. SQLite-файл хранит tracking metadata, а сами
файлы находятся в MLflow Artifact Repository (локально — в `./mlruns`). Это
артефакты запуска, а не версии MLflow Model Registry: raw YOLO checkpoint не имеет
стандартной MLflow `MLmodel`-упаковки.

Проверка интеграции на минимальных датасетах для всех пяти задач:

```bash
uv run scripts/run_yolo26_smoke_training.py --mlflow
uv run scripts/verify_mlflow_smoke.py
```

Второй скрипт завершается с ошибкой, если отсутствует experiment/run, параметры,
метрики, `results.csv`, `best.pt` или `last.pt` хотя бы для одной задачи.

## Проверка

```bash
uv run pytest -q
node --check src/yolo_webui/static/app.js
docker compose config
```

Ultralytics распространяется по лицензии AGPL-3.0; для закрытых коммерческих
продуктов проверьте условия Enterprise-лицензии Ultralytics.