Данные

На этой странице представлена справочная документация по API подпакета timm.data, а также обзор входного конвейера, который он предоставляет: разрешение конфигурации предобработки модели, построение трансформаций, создание наборов данных и загрузчиков, Mixup / CutMix и загрузчик с переменным разрешением NaFlex.

Использование

Пайплайн собирается в четыре шага: resolve_model_data_config читает конфигурацию предобработки модели, create_transform создаёт трансформ для обучения или оценки, create_dataset создаёт датасет по имени и корневому каталогу, а create_loader создаёт трансформ и загрузчик данных для датасета.

import os
import tempfile

import torch
from PIL import Image

import timm
from timm.data import create_dataset, create_loader, create_transform, resolve_model_data_config

model = timm.create_model('resnet50', pretrained=False).eval()

# Preprocessing config from the model's pretrained_cfg, the default pretrained tag's config is attached to the model
# with or without pretrained weights.
data_config = resolve_model_data_config(model)
print(data_config)
# {'input_size': (3, 224, 224), 'interpolation': 'bicubic', 'mean': (0.485, 0.456, 0.406),
#  'std': (0.229, 0.224, 0.225), 'crop_pct': 0.95, 'crop_mode': 'center'}

# Eval transform for a PIL image, resize to 224 / crop_pct, center crop 224, to tensor and normalize.
transform = create_transform(**data_config, is_training=False)
img = Image.new('RGB', (320, 240), color=(200, 120, 40))
with torch.no_grad():
    output = model(transform(img).unsqueeze(0))  # (1, 1000)

# A folder dataset, <root>/<split>/<class>/<image>, two classes w/ four generated images each.
root = tempfile.mkdtemp()
for i, cls in enumerate(('cat', 'dog')):
    os.makedirs(os.path.join(root, 'validation', cls))
    for j in range(4):
        path = os.path.join(root, 'validation', cls, f'{j}.jpg')
        Image.new('RGB', (300, 200), color=(60 * i, 40 * j, 128)).save(path)

dataset = create_dataset('', root=root, split='validation')  # finds the 'validation' sub-folder
print(len(dataset), dataset.reader.class_to_idx)  # 8 {'cat': 0, 'dog': 1}

# The loader creates the transform from the same config and assigns it to the dataset.
loader = create_loader(dataset, **data_config, batch_size=4, use_prefetcher=False, num_workers=0)
with torch.no_grad():
    for images, targets in loader:
        output = model(images)  # images (4, 3, 224, 224), targets (4,)

В быстром старте описаны шаги настройки и преобразования для вывода.

Скрипт обучения (train.py) предоставляет следующие параметры для каждой части конвейера.

Переопределения конфигурации входных данных (resolve_input_data_config):

--input-size задаёт форму входных данных (C, H, W).
--img-size — это квадратная альтернатива для --input-size, сохраняющая количество каналов модели.
--in-chans задаёт количество входных каналов.
--interpolation задаёт метод интерполяции при изменении размера.
--mean задает среднее значение нормализации.
--std задает стандартное отклонение нормализации.
--crop-pct задает долю обрезки для оценки.

Создание набора данных (create_dataset) и настройка целевой переменной:

--dataset выбирает набор данных и считыватель.
--data-dir задаёт корневой каталог набора данных.
--train-split выбирает обучающую выборку.
--val-split выбирает валидационную часть данных.
--class-map задаёт сопоставление классов.
--input-img-mode задаёт режим преобразования цвета изображения.
--input-key выбирает поле изображения.
--target-key выбирает поле или поля меток.
--target-format выбирает индексы классов или плотные многогорячие целевые значения.

Варианты загрузчика и аугментации (create_loader) включают:

--aa выбирает политику автоматической аугментации.
--reprob задает вероятность случайного стирания.
--remode выбирает режим заполнения для случайного стирания.
--scale задаёт диапазон масштаба для случайного обрезания с изменением размера.
--ratio задаёт диапазон соотношения сторон для случайного обрезания с изменением размера.
--hflip задает вероятность горизонтального отражения.
--color-jitter задает силу изменения цвета.
--train-interpolation задаёт интерполяцию для изменения размера при обучении.
--workers задает количество рабочих процессов загрузчика.
--no-prefetcher отключает предзагрузчик.

Mixup и CutMix (Mixup):

--mixup задает альфа Mixup.
--cutmix задает альфа-параметр CutMix.
--cutmix-minmax задаёт диапазон размеров CutMix-коробок.
--mixup-prob задает вероятность смешивания.
--mixup-switch-prob задает вероятность выбора CutMix, когда оба метода включены.
--mixup-mode выбирает смешивание на уровне батча, пары или элемента.
--smoothing задаёт сглаживание меток.

См. примеры в разделе Scripts.

Конфигурация данных

resolve_data_config возвращает словарь со следующими ключами, которые соответствуют аргументам create_transform и create_loader. Значения, установленные в args (словарь, например, vars(args) разобранных аргументов командной строки), имеют приоритет над аргументом pretrained_cfg, который по умолчанию равен model.pretrained_cfg. resolve_model_data_config делает то же самое, но принимает модель первым аргументом.

Обе функции читают размер входа и количество каналов из предобученного cfg, который описывает исходный чекпоинт, а не модель, созданную или изменённую для использования другого img_size или in_chans. resolve_input_data_config, используемая в скриптах обучения, валидации и инференса, разрешает параметры относительно текущего входа модели: модель с фиксированным размером входа всегда получает свой текущий размер, явные args, конфликтующие с каналами или фиксированным размером модели, вызывают ошибку, а mean / std, не соответствующие количеству каналов, заменяются их средним значением (с предупреждением).

Ключ	Ключи `args`	Описание	По умолчанию
`input_size`	`input_size`, `img_size`, `in_chans`	Размер входных данных `(C, H, W)`. Если `use_test_size=True`, используется `test_input_size` из конфигурации, если он там задан	`(3, 224, 224)`
`interpolation`	`interpolation`	Интерполяция при изменении размера, `bilinear`, `bicubic`, …	`bicubic`
`mean`, `std`	`mean`, `std`	Нормализация, одно значение повторяется для каждого канала	Среднее / стандартное отклонение ImageNet
`crop_pct`	`crop_pct`	Eval crop: изображение масштабируется до `size / crop_pct` перед обрезкой до `size` (`test_crop_pct` при `use_test_size=True`)	`0.875`
`crop_mode`	`crop_mode`	Режим обрезки для оценки, `center`, `squash` или `border`	`center`

Режимы обрезки для оценки, для выходного size и scale_size = floor(size / crop_pct):

`crop_mode`	Поведение
`center`	Масштабировать самую короткую сторону до `scale_size` (с сохранением соотношения сторон), затем выполнить центрированный кроп до `size`
`squash`	Измените размер обоих краёв до `scale_size` (соотношение сторон не сохраняется), затем выполните центрированный кроп до `size`
`border`	Масштабируйте самую длинную сторону до `scale_size`, выполните центрированный кроп и заполните края средним цветом; при этом всё изображение сохраняется при `crop_pct=1.0`

Преобразования

create_transform возвращает torchvision Compose. Преобразование для оценки выполняет изменение размера и обрезку, как описано выше, затем преобразует изображение в тензор и нормализует. Преобразование для обучения включает случайную обрезку с изменением размера (scale=(0.08, 1.0), ratio=(3/4, 4/3) по умолчанию), горизонтальное отражение (hflip=0.5), изменение цвета (color_jitter=0.4), необязательную политику auto_augment, преобразование в тензор и нормализацию, а также случайное стирание.

train_crop_mode='rkrc' или 'rkrr' заменяет случайный обрезанный кадр со случайным изменением размера на случайное изменение размера с сохранением соотношения сторон, за которым следует центральный (rkrc) или случайный (rkrr) обрезанный кадр или заполнение.
interpolation='random' (значение по умолчанию в train.py для обучения) выбирает для каждого изображения либо билинейную, либо бикубическую интерполяцию.
no_aug=True сводит обучение к операции изменения размера и центральному кадрированию.

`auto_augment`	Аугментация
`rand-m9-mstd0.5-inc1`	`RandAugment` с помощью `rand_augment_transform`
`augmix-m5-w4-d2`	AugMix с помощью `augment_and_mix_transform`
`original`, `originalr`, `v0`, `v0r`, `3a`	Политика AutoAugment через `auto_augment_transform`

Токены опций RandAugment:

m задает величину (по умолчанию 10).
n задает количество операций на изображение (по умолчанию 2).
p задаёт вероятность для каждой операции (по умолчанию 0.5).
mstd задает стандартное отклонение шума амплитуды.
inc1 выбирает операции, серьёзность которых растёт вместе с величиной.
t<name> выбирает набор операций (weights, 3a, 3aw).

Токены опции AugMix:

m задаёт уровень серьёзности (по умолчанию 3).
w задаёт ширину (по умолчанию 3).
d задаёт глубину (по умолчанию -1, случайное значение от 1 до 3).
b1 позволяет использовать смешанное аугментирование.
mstd задает стандартное отклонение шума амплитуды.

AutoAugment принимает mstd, например original-mstd0.5.

Поведение трансформации:

Color jitter отключается, если задан параметр auto_augment, если только строка не содержит 3a.
RandomErasing (re_prob, re_count) выполняется на нормализованном тензоре. re_mode заполняет области нулями (const, значение по умолчанию), случайным нормальным цветом для каждой области (rand) или случайными нормальными пикселями (pixel, значение по умолчанию в train.py).
use_prefetcher=True завершает трансформацию тензором uint8, после чего нормализация и случайное стирание выполняются загрузчиком на устройстве.
create_transform и create_loader по умолчанию используют интерполяцию bilinear и среднее/стандартное отклонение ImageNet, а не значения модели. Передайте настроенную конфигурацию данных, чтобы соответствовать предобучению модели.

Наборы данных

create_dataset выбирает реализацию набора данных и считыватель по префиксу name:

`name`	Набор данных	`root`	Требуется
`''` или без префикса	`ImageDataset`, изображения в подпапках классов (поиск выполняется рекурсивно, имя конечной папки является классом) или один файл `.tar` с тем же	Папка с набором данных или файл `.tar`
`torch/<name>`	torchvision `cifar10`, `cifar100`, `mnist`, `kmnist`, `fashion_mnist`, `qmnist`, `inaturalist` (`inat`), `places365`, `imagenet` или `image_folder` (`folder`)	Корень датасета torchvision
`hfds/<name>`	`ImageDataset` на датасете Hugging Face Hub (или локальном пути) через `datasets.load_dataset`	Каталог кэша (необязательно)	`datasets`
`hfids/<name>`	`IterableImageDataset`, набор данных Hugging Face, передаваемый потоком, либо предварительно загруженный и подготовленный с `download=True`	Каталог кэша (необязательно)	`datasets`
`tfds/<name>`	`IterableImageDataset` в TensorFlow Datasets, `download=True` загружает и строит	Каталог данных TFDS	`tensorflow`, `tensorflow-datasets`
`wds/<name>`	`IterableImageDataset` на tar-шардах WebDataset	Папка с шардами, содержащая `_info.json` (или `info.json`) с описанием разбиений	`webdataset`

Варианты набора данных:

split выбирает разделение набора данных (по умолчанию validation). Для WebDataset это также может быть шаблон шарда с количеством образцов, 'imagenet-train-{0000..1023}.tar|1281167'.
search_split=True (по умолчанию) заставляет датасеты в формате папок искать подпапку root с именем split или, если её нет, синоним обучающего (train, training) или оценочного (val, valid, validation, eval, evaluation) сплита.
add_img_extensions добавляет расширения к стандартным расширениям изображений (.png, .jpg и .jpeg).
class_map переназначает имена классов на индексы с помощью словаря, файла .txt (один класс на строку) или файла .pkl.

Итерируемые наборы данных (hfids, tfds, wds) также принимают:

is_training включает перемешивание.
batch_size округляет долю каждого воркера вверх до целых батчей при обучении.
num_samples задаёт количество выборок, что обязательно, если считыватель не может определить его самостоятельно (hfids без информации о сплите).
seed задает случайный посев.
repeats умножает количество образцов на эпоху, и читатели проходят по данным столько же раз.

Вызывайте dataset.set_epoch() в каждой эпохе для перемешивания.

Другие именованные аргументы передаются в читатель. Для читателей Hugging Face, TFDS и WebDataset:

input_key выбирает поле изображения (по умолчанию image, для wds — изображение в формате jpg, png или webp).
target_key выбирает поле метки (по умолчанию label, для wds — файл .cls или поле в сопутствующем файле .json с именем, заданным в target_key). Значение, разделённое запятыми, читает одно бинарное поле на каждый класс.
target_format='multihot' читает плотные многогорячие векторы вместо списков индексов классов для данных с несколькими метками.
target_transform=MultiLabelTarget(num_classes) кодирует целевые значения как float-тензоры с мульти-горячим кодированием. Передайте dense=True в MultiLabelTarget для полей с мульти-горячим кодированием.

Читатели папок и tar-архивов возвращают индексы одного класса. Подробности см. в разделе многоклассовая классификация.

Загрузчики

create_loader создаёт трансформ с помощью create_transform на основе собственных аргументов, присваивает его dataset.transform (заменяя существующий трансформ) и возвращает DataLoader. Загрузчики для обучения (is_training=True) перемешивают данные и отбрасывают последний неполный батч.

Предварительный загрузчик (Prefetcher). При use_prefetcher=True (по умолчанию) набор данных возвращает тензоры типа uint8, батчи перемещаются на device (по умолчанию cuda, на отдельном потоке для CUDA), преобразуются в img_dtype, нормализуются и случайно стираются там. Укажите device как устройство обучения или задайте use_prefetcher=False для обычного DataLoader с нормализованными тензорами.
Распределённый режим. distributed=True использует DistributedSampler для обучающих наборов данных map-style (или повторный сэмплер аугментации с num_aug_repeats) и упорядоченный сэмплер для оценки, который дополняет каждый процесс до одинакового количества образцов, что может незначительно изменить результаты валидации. Итерируемые наборы данных сами распределяются по процессам и воркерам.
Collate. collate_fn заменяет стандартную (fast_collate с prefetcher, default_collate без него), например, на FastCollateMixup.
Разделения аугментации. Для AugMix с потерей JSD (--aug-splits) оберните датасет в AugMixDataset(dataset, num_splits=n) и передайте num_aug_splits=n. Каждая партия содержит чистое разделение и n - 1 аугментированных разделений, которые конкатенируются вдоль измерения партии префетчером.
Планируемое разрешение. input_size_choices (--train-img-sizes) выбирает размер входных данных для каждой партии, при необходимости с указанием размера партии для каждого варианта (batch_size_choices) и progressive расписанием от первого до последнего варианта.

Mixup и CutMix

Mixup смешивает батч нормализованных изображений на устройстве, после загрузчика. FastCollateMixup принимает те же аргументы и смешивает изображения uint8 во время коллации в воркерах загрузчика, для этого требуется префетчер. Оба возвращают плотные целевые значения (batch_size, num_classes) с применённым label_smoothing (по умолчанию 0.1), которые предназначены для использования с потерей для мягких целевых значений, например timm.loss.SoftTargetCrossEntropy, и требуют чётный размер батча.

from timm.data import Mixup, FastCollateMixup

# Continuing the example above.
device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
mixup_args = dict(mixup_alpha=0.8, cutmix_alpha=1.0, label_smoothing=0.1, num_classes=1000)

# Prefetcher enabled (default), mixed in the loader's collate.
loader = create_loader(
    dataset,
    **data_config,
    batch_size=4,
    is_training=True,
    collate_fn=FastCollateMixup(**mixup_args),
    device=device,
)
for images, targets in loader:
    ...  # images normalized on device, targets (4, 1000)

# Prefetcher disabled, mixed in the training loop.
loader = create_loader(dataset, **data_config, batch_size=4, is_training=True, use_prefetcher=False)
mixup_fn = Mixup(**mixup_args)
for images, targets in loader:
    images, targets = mixup_fn(images.to(device), targets.to(device))

Параметры Mixup и CutMix:

mixup_alpha > 0 включает Mixup.
cutmix_alpha > 0 включает CutMix.
cutmix_minmax включает CutMix с диапазоном размеров рамки.
switch_prob задает вероятность выбора CutMix, когда оба метода включены.
prob задает вероятность смешивания.
mode выполняет выборку параметров один раз на batch, на pair элементов или на elem (элемент).
multi_label=True смешивает плотные многометочные целевые значения, сглаживая каждую метку в сторону 0.5.
mixup_enabled = False отключает смешивание, например, для последних эпох (--mixup-off-epoch). Для FastCollateMixup значение читается в рабочих процессах; постоянные рабочие процессы сохраняют значение, с которым они были запущены.

НаFlex переменное разрешение

create_naflex_loader загружает изображения как последовательности патчей переменной длины, без изменения размера до фиксированного квадрата, для моделей, принимающих вход в виде патчей NaFlex (например, модели naflexvit_*). Каждая партия представляет собой словарь с ключами patches, patch_coord, patch_valid и seq_len, дополненный до длины последовательности партии.

Обучение. Набор данных оборачивается в NaFlexMapDatasetWrapper (только для map-style наборов данных), который выбирает одно из значений train_seq_lens для каждой партии и выполняет случайный resize-crop каждого изображения, чтобы оно соответствовало выбранному количеству патчей. batch_size — это размер партии при максимальной длине последовательности; для более коротких последовательностей размер партии увеличивается пропорционально (округляется вниз до кратного 8), чтобы количество токенов в партии оставалось примерно постоянным. patch_size_choices (вместе с patch_size_choice_probs) также варьирует размер патча для каждой партии, если модель это поддерживает.
Оценка. Изображения масштабируются так, чтобы вписать max_seq_len патчей при заданном patch_size (обязательно для оценки), и дополняются до max_seq_len.
Mixup. Передайте NaFlexMixup в качестве mixup_fn: он выполняет смешивание внутри каждой партии и не поддерживает mode или cutmix_minmax.

Варианты train.py:

--naflex-loader включает загрузчик NaFlex.
--naflex-train-seq-lens задаёт длины последовательностей для обучения.
--naflex-max-seq-len задает максимальную длину последовательности для оценки.
--naflex-patch-sizes задаёт размеры патчей для обучения с переменным размером патчей.
--naflex-patch-size-probs задаёт вероятности для указанных размеров патчей.
--naflex-loss-scale выбирает масштабирование потерь в зависимости от размера батча (none, sqrt или linear).

timm

Данные

Использование

Конфигурация данных

Преобразования

Наборы данных

Загрузчики

Mixup и CutMix

НаFlex переменное разрешение

API

Конфигурация данных

timm.data.resolve_data_config

timm.data.resolve_model_data_config

timm.data.resolve_input_data_config

Преобразования

timm.data.create_transform

timm.data.rand_augment_transform

timm.data.auto_augment_transform

timm.data.auto_augment.augment_and_mix_transform

class timm.data.random_erasing.RandomErasing

Наборы данных

timm.data.create_dataset

класс timm.data.ImageDataset

класс timm.data.IterableImageDataset

класс timm.data.AugMixDataset

класс timm.data.MultiLabelTarget

Загрузчики

timm.data.create_loader

Mixup и CutMix

класс timm.data.Mixup

класс timm.data.FastCollateMixup

NaFlex

timm.data.create_naflex_loader

класс timm.data.NaFlexMapDatasetWrapper

set_epoch

класс timm.data.NaFlexMixup

set_epoch