Формат датасета

Общие требования

Датасет загружается в API как один ZIP-архив через POST /datasets/create. Архив должен содержать изображения и файлы аннотаций. Валидация в API проверяет только базовые свойства архива, а training-воркер уже ожидает конкретную структуру, совместимую с YOLO-style dataset.

Требования API-валидации:

• файл не должен быть пустым;
• имя файла не должно быть пустым;
• максимальная длина имени файла - 255 символов;
• имя файла может содержать латиницу, цифры, _, -, ., пробелы;
• расширение архива - только .zip;
• максимальный размер архива - 5 GB;
• внутри ZIP не допускаются абсолютные пути;
• внутри ZIP не допускаются path traversal-компоненты ..;
• в первых 100 файлах архива должен быть хотя бы один файл изображения;
• в первых 100 файлах архива должен быть хотя бы один текстовый или YAML-файл аннотаций.

Поддерживаемые расширения изображений при первичной валидации:

• jpg
• jpeg
• png
• bmp
• tiff

Поддерживаемые расширения текстовых файлов при первичной валидации:

• csv
• txt
• yml
• yaml

Практически ожидаемый формат

Training-воркер ищет внутри распакованного ZIP первый файл с расширением .yaml или .yml. Без YAML-файла обучение завершится ошибкой:

Dataset yaml file not found

Фактически датасет должен быть совместим с YOLO-форматом:

dataset.zip
└── dataset/
    ├── data.yaml
    ├── images/
    │   ├── train/
    │   │   ├── image_001.jpg
    │   │   └── image_002.jpg
    │   └── val/
    │       ├── image_101.jpg
    │       └── image_102.jpg
    └── labels/
        ├── train/
        │   ├── image_001.txt
        │   └── image_002.txt
        └── val/
            ├── image_101.txt
            └── image_102.txt

Рекомендуемый data.yaml:

path: .
train: images/train
val: images/val
test: images/test
names:
  0: class_a
  1: class_b

Допустим также список классов:

path: .
train: images/train
val: images/val
names:
  - class_a
  - class_b

Поле test необязательно. Поля train и val обязательны для Faster R-CNN trainer и практически обязательны для корректного обучения.

Нормализация YAML при загрузке воркером

DatasetLoader распаковывает архив во временную директорию и изменяет YAML перед обучением:

• пытается прочитать YAML в кодировках utf-8-sig, utf-8, cp1251, latin-1;
• если path указывает на директорию, существующую рядом с YAML, заменяет path на реальный локальный путь;
• если значения train, val или test абсолютные, заменяет их на basename;
• сохраняет YAML обратно в UTF-8.

Это сделано для того, чтобы датасеты, созданные в разных окружениях, могли быть распакованы и обучены внутри контейнера.

Формат YOLO-аннотаций

Для каждого изображения ожидается .txt-файл с тем же basename:

images/train/image_001.jpg
labels/train/image_001.txt

Каждая строка label-файла описывает один объект:

<class_id> <x_center> <y_center> <width> <height>

Где:

• class_id - целочисленный индекс класса, начиная с 0;
• x_center - нормированная координата центра bounding box по X;
• y_center - нормированная координата центра bounding box по Y;
• width - нормированная ширина bounding box;
• height - нормированная высота bounding box.

Все координаты должны быть нормированы относительно размера изображения и обычно лежать в диапазоне [0, 1].

Пример:

0 0.5123 0.4381 0.1200 0.0850
1 0.2310 0.7720 0.0440 0.0900

Особенности для YOLO training

YOLO trainer использует ultralytics.YOLO и передает в model.train:

• data - абсолютный путь к YAML;
• epochs - значение из задачи или 10 по умолчанию;
• imgsz - значение из задачи или 640 по умолчанию;
• batch=4;
• workers=4;
• device="cuda";
• deterministic=True;
• exist_ok=True;
• name - имя training run из задачи или yolo_custom.

Следовательно, для YOLO желательно сохранять структуру датасета максимально близкой к стандартной структуре Ultralytics.

Особенности для Faster R-CNN training

Faster R-CNN trainer читает YAML самостоятельно и ожидает:

• train - путь к директории изображений train;
• val - путь к директории изображений validation;
• names - список или словарь классов.

Пути label-файлов выводятся из путей изображений заменой компонента images на labels. Поэтому структура должна содержать сегмент директории images; иначе обучение завершится ошибкой:

'images' not found in path: ...

Для Faster R-CNN labels читаются из YOLO .txt-файлов и преобразуются из normalized center-format в absolute xyxy.

Рекомендации к качеству датасета

• Каждый label-файл должен соответствовать изображению по имени.
• Неиспользуемые изображения без label-файла допустимы технически, но будут интерпретированы как изображения без объектов.
• class_id не должен выходить за пределы массива names.
• Bounding boxes с нулевой или отрицательной площадью будут отброшены.
• Желательно избегать кириллицы и спецсимволов в именах файлов внутри архива, несмотря на то что YAML может читаться в нескольких кодировках.
• Для воспроизводимости фиксируйте версию разметки и набор классов вместе с датасетом.

Минимальный валидный пример

dataset/
├── data.yaml
├── images/
│   ├── train/
│   │   └── img1.jpg
│   └── val/
│       └── img2.jpg
└── labels/
    ├── train/
    │   └── img1.txt
    └── val/
        └── img2.txt

data.yaml:

path: .
train: images/train
val: images/val
names:
  0: defect

labels/train/img1.txt:

0 0.5 0.5 0.25 0.25

labels/val/img2.txt:

0 0.4 0.4 0.2 0.2