152 lines
8.6 KiB
Markdown
Executable file
152 lines
8.6 KiB
Markdown
Executable file
# 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`, а MLflow — по
|
||
`http://127.0.0.1:5000`. Compose намеренно публикует оба порта только на loopback и
|
||
хранит состояние MLflow в `./mlflow`. Не заменяйте адреса на `0.0.0.0` без
|
||
аутентифицирующего reverse proxy: API позволяет запускать и останавливать
|
||
ресурсоёмкие задачи.
|
||
|
||
Для NVIDIA GPU раскомментируйте секцию `deploy.resources.reservations.devices` в
|
||
`docker-compose.yml`. Web/MLflow-зависимости устанавливаются в версиях из
|
||
`uv.lock`, а PyTorch, Ultralytics и GPU runtime предоставляет базовый образ
|
||
Ultralytics. Для полностью воспроизводимой production-сборки дополнительно
|
||
зафиксируйте базовый образ по digest.
|
||
|
||
## Разрешённые пути
|
||
|
||
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`-упаковки.
|
||
|
||
WebUI дополняет штатные метрики стабильным namespace `monitor/*`. Значения
|
||
собираются после validation текущей эпохи, поэтому не запаздывают на одну эпоху:
|
||
|
||
| Задача | Основные дополнительные ряды |
|
||
|---|---|
|
||
| `detect` | box F1 при оптимальном confidence, mAP@0.75, метрики худшего класса |
|
||
| `segment` | F1 при оптимальном confidence и mAP@0.75 отдельно для box и mask |
|
||
| `classify` | top-1/top-5 error, macro precision/recall/F1, weighted F1, balanced accuracy |
|
||
| `pose` | F1 при оптимальном confidence и mAP@0.75 отдельно для box и keypoints (OKS) |
|
||
| `obb` | F1 при оптимальном confidence, mAP@0.75 и метрики худшего класса для oriented boxes |
|
||
|
||
Для всех задач также записываются исходный Ultralytics fitness и нормализованный
|
||
`task_score` (для `segment`/`pose` сумма box+mask/keypoints приводится к диапазону
|
||
0–1), суммарные train/validation loss, gap/ratio между ними, средний learning rate,
|
||
время эпохи и скорость validation по стадиям. Теги `yolo.task` и
|
||
`monitoring.schema_version` позволяют фильтровать совместимые запуски. Финальные
|
||
per-class precision/recall/F1/AP и support сохраняются в артефакте
|
||
`monitoring/task_metrics.csv`, чтобы не создавать сотни поэпоховых рядов для
|
||
датасетов с большим числом классов. Monitor подключается внутри task-specific
|
||
trainer и сохраняется при запуске Ultralytics DDP на нескольких GPU.
|
||
|
||
Шаги MLflow остаются совместимыми с Ultralytics: первая эпоха имеет `step=0`, а
|
||
финальная проверка лучшего checkpoint добавляется отдельной точкой после последней
|
||
эпохи. В WebUI эпохи отображаются привычно, начиная с 1.
|
||
|
||
Проверка интеграции на минимальных датасетах для всех пяти задач:
|
||
|
||
```bash
|
||
uv run scripts/create_yolo26_smoke_datasets.py
|
||
uv run scripts/run_yolo26_smoke_training.py --mlflow
|
||
uv run scripts/verify_mlflow_smoke.py
|
||
```
|
||
|
||
Smoke-runner присваивает всей пятёрке запусков уникальный тег `yolo.run_group`;
|
||
проверка берёт только самый свежий batch и не смешивает его со старыми успешными
|
||
run-ами.
|
||
|
||
Второй скрипт завершается с ошибкой, если отсутствует experiment/run, параметры,
|
||
task-specific метрики, их история, теги, `monitoring/task_metrics.csv`,
|
||
`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.
|