Données

Cette page contient la documentation de référence de l’API du sous-package timm.data, ainsi qu’un aperçu du pipeline d’entrée qu’il fournit : résolution de la configuration de prétraitement d’un modèle, construction des transformations, création de jeux de données et de chargeurs, Mixup / CutMix, et le chargeur de résolution variable NaFlex.

Utilisation

Un pipeline est construit en quatre étapes : resolve_model_data_config lit la configuration de prétraitement du modèle, create_transform construit la transformation d’entraînement ou d’évaluation, create_dataset crée un jeu de données à partir de son nom et de sa racine, et create_loader construit la transformation et un chargeur de données pour un jeu de données.

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,)

Le tutoriel de démarrage rapide détaille la configuration des étapes de transformation pour l’inférence.

Le script d'entraînement (train.py) expose ces options pour chaque partie du pipeline.

Remplacements de la configuration d'entrée (resolve_input_data_config) :

--input-size définit la forme d'entrée (C, H, W).
--img-size est le raccourci carré de --input-size, en conservant le nombre de canaux du modèle.
--in-chans définit les canaux d'entrée.
--interpolation définit l'interpolation de redimensionnement.
--mean définit la moyenne de normalisation.
--std définit l'écart-type de normalisation.
--crop-pct définit la fraction de recadrage pour l'évaluation.

Création du jeu de données (create_dataset) et configuration de la cible :

--dataset sélectionne le jeu de données et le lecteur.
--data-dir définit le répertoire racine du jeu de données.
--train-split sélectionne la partition d'entraînement.
--val-split sélectionne la partition de validation.
--class-map fournit la correspondance des classes.
--input-img-mode définit le mode de conversion des couleurs de l'image.
--input-key sélectionne le champ d’image.
--target-key sélectionne le ou les champs d'étiquette.
--target-format sélectionne les indices de classes ou les cibles multi-hot denses.

Les options de chargeur et d'augmentation (create_loader) incluent :

--aa sélectionne la politique d'auto-augmentation.
--reprob définit la probabilité d'effacement aléatoire.
--remode sélectionne le mode de remplissage de l'effacement aléatoire.
--scale définit la plage d'échelle pour le recadrage aléatoire redimensionné.
--ratio définit la plage de rapports d’aspect pour le recadrage aléatoire redimensionné.
--hflip définit la probabilité de retournement horizontal.
--color-jitter définit l'intensité du jitter de couleur.
--train-interpolation définit l'interpolation de redimensionnement pour l'entraînement.
--workers définit le nombre de workers du loader.
--no-prefetcher désactive le prefetcher.

Mixup et CutMix (Mixup) :

--mixup définit l'alpha de Mixup.
--cutmix définit l'alpha de CutMix.
--cutmix-minmax définit la plage de taille des boîtes CutMix.
--mixup-prob définit la probabilité de mélange.
--mixup-switch-prob définit la probabilité de choisir CutMix lorsque les deux méthodes sont activées.
--mixup-mode sélectionne le mélange par lot, par paire ou élément par élément.
--smoothing définit le lissage des étiquettes.

Voir Scripts pour des exemples.

Configuration des données

resolve_data_config renvoie un dictionnaire avec les clés ci-dessous, qui correspondent aux arguments de create_transform et create_loader. Les valeurs définies dans args (un dictionnaire, par exemple vars(args) des arguments de ligne de commande analysés) ont la priorité sur l'argument pretrained_cfg, dont la valeur par défaut est model.pretrained_cfg. resolve_model_data_config est identique, avec le modèle comme premier argument.

Les deux lisent la taille d’entrée et les canaux à partir de la configuration préentraînée, qui décrit le point de contrôle source, et non un modèle créé ou modifié pour utiliser une img_size ou des in_chans différents. resolve_input_data_config, utilisé par les scripts d’entraînement, de validation et d’inférence, résout par rapport à l’entrée actuelle du modèle : un modèle à taille d’entrée fixe reçoit toujours sa taille actuelle, des args explicites qui entrent en conflit avec les canaux ou la taille fixe du modèle déclenchent une erreur, et une moyenne / écart-type qui ne correspond pas au nombre de canaux est remplacée par sa moyenne (avec un avertissement).

Clé	clés de `args`	Description	Par défaut
`input_size`	`input_size`, `img_size`, `in_chans`	Taille d’entrée `(C, H, W)`. Avec `use_test_size=True`, la `test_input_size` de la configuration est utilisée si elle en possède une	`(3, 224, 224)`
`interpolation`	`interpolation`	Interpolation de redimensionnement, `bilinear`, `bicubic`, …	`bicubic`
`mean`, `std`	`mean`, `std`	Normalisation, une seule valeur est répétée pour chaque canal	Moyenne / écart-type d'ImageNet
`crop_pct`	`crop_pct`	Avec l'évaluation par recadrage, l'image est redimensionnée à `size / crop_pct` avant d'être recadrée à `size` (`test_crop_pct` avec `use_test_size=True`)	`0.875`
`crop_mode`	`crop_mode`	Mode de recadrage d'évaluation, `center`, `squash` ou `border`	`center`

Les modes de recadrage d'évaluation, pour une size de sortie et scale_size = floor(size / crop_pct) :

`crop_mode`	Comportement
`center`	Redimensionner le côté le plus court à `scale_size` (ratio d'aspect préservé), puis recadrer au centre à `size`
`squash`	Redimensionner les deux bords à `scale_size` (le ratio d'aspect n'est pas préservé), puis recadrer au centre à `size`
`border`	Redimensionner le plus long côté à `scale_size`, effectuer un recadrage centré et un remplissage avec la couleur moyenne, l'image entière est conservée à `crop_pct=1.0`

Transformations

create_transform renvoie un Compose de torchvision. La transformation d’évaluation redimensionne et recadre comme ci-dessus, puis convertit en tenseur et normalise. La transformation d’entraînement est un recadrage aléatoire redimensionné (scale=(0.08, 1.0), ratio=(3/4, 4/3) par défaut), un retournement horizontal (hflip=0.5), une variation de couleur (color_jitter=0.4), la politique optionnelle auto_augment, la conversion en tenseur et la normalisation, ainsi qu’un effacement aléatoire.

train_crop_mode='rkrc' ou 'rkrr' remplace le recadrage aléatoire redimensionné par un redimensionnement aléatoire qui préserve le ratio d’aspect, suivi d’un recadrage ou d’un remplissage centré (rkrc) ou aléatoire (rkrr).
interpolation='random' (la valeur par défaut de train.py pour l’entraînement) sélectionne l’interpolation bilinéaire ou bicubique pour chaque image.
no_aug=True réduit l'entraînement à un redimensionnement et un recadrage centré.

`auto_augment`	Augmentation
`rand-m9-mstd0.5-inc1`	`RandAugment` via `rand_augment_transform`
`augmix-m5-w4-d2`	AugMix via `augment_and_mix_transform`
`original`, `originalr`, `v0`, `v0r`, `3a`	politique AutoAugment via `auto_augment_transform`

Jetons d'options pour RandAugment :

m définit l'amplitude (10 par défaut).
n définit le nombre d'opérations par image (2 par défaut).
p définit la probabilité par opération (valeur par défaut 0,5).
mstd définit l'écart-type du bruit d'amplitude.
inc1 sélectionne les opérations dont la gravité augmente avec l'amplitude.
t<name> sélectionne le jeu d'opérations (weights, 3a, 3aw).

Jetons d'option AugMix :

m définit la sévérité (3 par défaut).
w définit la largeur (3 par défaut).
d définit la profondeur (valeur par défaut -1, aléatoire entre 1 et 3).
b1 permet l'augmentation de données mixte.
mstd définit l'écart-type du bruit d'amplitude.

AutoAugment accepte mstd, par exemple original-mstd0.5.

Comportement de transformation :

Le jitter de couleur est désactivé lorsque auto_augment est défini, sauf si la chaîne contient 3a.
RandomErasing (re_prob, re_count) s’exécute sur le tenseur normalisé. re_mode remplit avec des zéros (const, par défaut), une couleur normale aléatoire par région (rand) ou des pixels normaux aléatoires (pixel, la valeur par défaut de train.py).
use_prefetcher=True termine la transformation par un tenseur uint8, la normalisation et l’effacement aléatoire sont ensuite effectués par le chargeur sur l’appareil.
create_transform et create_loader utilisent par défaut l’interpolation bilinear et la moyenne / l’écart-type d’ImageNet, et non les valeurs du modèle. Transmettez la configuration de données résolue pour correspondre au pré-entraînement du modèle.

Jeux de données

create_dataset sélectionne l’implémentation du jeu de données et le lecteur à partir d’un préfixe de name :

`name`	Jeu de données	`root`	Nécessite
`''` ou aucun préfixe	`ImageDataset`, des images dans des sous-dossiers de classes (recherche récursive, le nom du dossier feuille est la classe) ou un seul fichier `.tar` de même	Dossier de jeu de données ou fichier `.tar`
`torch/<name>`	torchvision `cifar10`, `cifar100`, `mnist`, `kmnist`, `fashion_mnist`, `qmnist`, `inaturalist` (`inat`), `places365`, `imagenet` ou `image_folder` (`folder`)	racine du jeu de données torchvision
`hfds/<name>`	`ImageDataset` sur un jeu de données du Hugging Face Hub (ou un chemin local) via `datasets.load_dataset`	Répertoire de cache (facultatif)	`datasets`
`hfids/<name>`	`IterableImageDataset`, le jeu de données Hugging Face en flux, ou téléchargé et préparé au préalable avec `download=True`	Répertoire de cache (facultatif)	`datasets`
`tfds/<name>`	`IterableImageDataset` sur TensorFlow Datasets, `download=True` télécharge et construit	Répertoire de données TFDS	`tensorflow`, `tensorflow-datasets`
`wds/<name>`	`IterableImageDataset` sur des shards tar WebDataset	Dossier de shards avec un `_info.json` (ou `info.json`) décrivant les splits	`webdataset`

Options de jeu de données :

split sélectionne le split du jeu de données (par défaut validation). Pour WebDataset, il peut également s'agir d'un motif de shard avec un nombre d'échantillons, 'imagenet-train-{0000..1023}.tar|1281167'.
search_split=True (par défaut) fait en sorte que les jeux de données de dossiers recherchent le sous-dossier de root nommé split ou, à défaut, un synonyme d’un split d’entraînement (train, training) ou d’évaluation (val, valid, validation, eval, evaluation).
add_img_extensions ajoute aux extensions d’images par défaut (.png, .jpg et .jpeg).
class_map réaffecte les noms de classes à des indices à l'aide d'un dictionnaire, d'un fichier .txt (une classe par ligne) ou d'un fichier .pkl.

Les jeux de données itérables (hfids, tfds, wds) acceptent également :

is_training active le mélange.
batch_size arrondit la part d’échantillons de chaque travailleur à des lots entiers lors de l’entraînement.
num_samples définit le nombre d'échantillons, requis lorsque le lecteur ne peut pas le déterminer (hfids sans information de split).
seed définit la graine aléatoire.
repeats multiplie les échantillons par époque, les lecteurs parcourent les données autant de fois.

Appelez dataset.set_epoch() à chaque époque pour mélanger à nouveau.

Les autres arguments par mot-clé sont transmis au lecteur. Pour les lecteurs Hugging Face, TFDS et WebDataset :

input_key sélectionne le champ d’image (image par défaut, pour wds une image jpg, png ou webp).
target_key sélectionne le champ d’étiquette (par défaut label, pour wds le fichier .cls ou un champ de fichier compagnon .json nommé par target_key). Une valeur séparée par des virgules lit un champ binaire par classe.
target_format='multihot' lit des vecteurs multi-denses au lieu de listes d'indices de classes pour les données multi-étiquettes.
target_transform=MultiLabelTarget(num_classes) encode les cibles sous forme de tenseurs multi-hot flottants. Passez dense=True à MultiLabelTarget pour les champs multi-hot.

Les lecteurs de dossiers et de fichiers tar renvoient des indices de classes uniques. Consultez classification multi-étiquettes pour plus de détails.

Chargeurs

create_loader crée la transformation avec create_transform à partir de ses propres arguments, l’assigne à dataset.transform (en remplaçant toute transformation existante) et renvoie un DataLoader. Les chargeurs d’entraînement (is_training=True) mélangent les données et suppriment le dernier lot incomplet.

Préchargeur. Avec use_prefetcher=True (par défaut), le jeu de données produit des tenseurs uint8, les lots sont déplacés vers device (par défaut cuda, sur un flux latéral pour CUDA), convertis en img_dtype, normalisés et aléatoirement effacés sur place. Définissez device sur l’appareil d’entraînement, ou use_prefetcher=False pour un DataLoader simple de tenseurs normalisés.
Distribué. distributed=True utilise un DistributedSampler pour les jeux de données d'entraînement de type map (ou un échantillonneur d'augmentation répété avec num_aug_repeats) et un échantillonneur ordonné pour l'évaluation qui remplit chaque processus jusqu'au même nombre d'échantillons, ce qui peut légèrement altérer les résultats de validation. Les jeux de données itérables se partagent eux-mêmes entre les processus et les workers.
Collation. collate_fn remplace la fonction par défaut (fast_collate avec le prefetcher, default_collate sans), par exemple par un FastCollateMixup.
Segments d'augmentation. Pour AugMix avec la perte JSD (--aug-splits), enveloppez le jeu de données dans AugMixDataset(dataset, num_splits=n) et passez num_aug_splits=n. Chaque lot contient un segment propre et n - 1 segments augmentés, concaténés le long de la dimension du lot par le préchargeur.
Résolution planifiée. input_size_choices (--train-img-sizes) sélectionne la taille d'entrée par lot, éventuellement avec une taille de lot par choix (batch_size_choices) et un planning progressive allant du premier au dernier choix.

Mixup et CutMix

Mixup mélange un lot d’images normalisées sur l’appareil, après le chargeur. FastCollateMixup prend les mêmes arguments et mélange des images uint8 lors de la collation dans les workers du chargeur ; il nécessite le préchargeur. Les deux renvoient des cibles denses (batch_size, num_classes) avec label_smoothing (valeur par défaut 0.1) appliqué, à utiliser avec une perte à cible douce telle que timm.loss.SoftTargetCrossEntropy, et exigent une taille de lot paire.

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))

Contrôles de Mixup et CutMix :

mixup_alpha > 0 active Mixup.
cutmix_alpha > 0 active CutMix.
cutmix_minmax active CutMix avec une plage de taille de boîte.
switch_prob définit la probabilité de choisir CutMix lorsque les deux méthodes sont activées.
prob définit la probabilité de mélanger.
mode tire les paramètres une fois par batch, par pair d'éléments ou par elem (élément).
multi_label=True mélange les cibles multi-étiquettes denses, en lissant chaque étiquette vers 0,5.
mixup_enabled = False désactive le mélange, par exemple pour les dernières époques (--mixup-off-epoch). Pour FastCollateMixup, la valeur est lue dans les processus workers ; les workers persistants conservent la valeur avec laquelle ils ont démarré.

NaFlex à résolution variable

create_naflex_loader loads images as variable length sequences of patches, w/o resizing to a fixed square size, for models that take NaFlex patch inputs (e.g. the naflexvit_* models). Each batch is a dict of patches, patch_coord, patch_valid and seq_len, padded to the batch’s sequence length.

Entraînement. Le jeu de données est encapsulé dans un NaFlexMapDatasetWrapper (uniquement pour les jeux de données de type map), qui sélectionne l'une des valeurs de train_seq_lens par lot et applique un redimensionnement aléatoire avec recadrage à chaque image pour qu'elle corresponde à ce nombre de patches. batch_size est la taille du lot pour la longueur de séquence la plus longue ; les longueurs plus courtes reçoivent des lots proportionnellement plus grands (arrondis à un multiple de 8 inférieur) afin que le nombre de jetons par lot reste approximativement constant. patch_size_choices (avec patch_size_choice_probs) fait également varier la taille des patches par lot, pour les modèles qui le supportent.
Éval. Les images sont redimensionnées pour correspondre à max_seq_len patches à la patch_size donnée (requis pour l'évaluation) puis remplies jusqu'à max_seq_len.
Mixup. Passez un NaFlexMixup en tant que mixup_fn, il mélange au sein de chaque lot et ne prend pas en charge mode ou cutmix_minmax.

Les options de train.py sont :

--naflex-loader active le chargeur NaFlex.
--naflex-train-seq-lens définit les longueurs de séquence d'entraînement.
--naflex-max-seq-len définit la longueur maximale de la séquence d'évaluation.
--naflex-patch-sizes définit les tailles de patch pour l'entraînement avec des tailles de patch variables.
--naflex-patch-size-probs définit les probabilités pour ces tailles de patch.
--naflex-loss-scale sélectionne l'échelle de perte en fonction de la taille du lot (none, sqrt ou linear).

timm

Données

Utilisation

Configuration des données

Transformations

Jeux de données

Chargeurs

Mixup et CutMix

NaFlex à résolution variable

API

Configuration des données

timm.data.resolve_data_config

timm.data.resolve_model_data_config

timm.data.resolve_input_data_config

Transformations

timm.data.create_transform

timm.data.rand_augment_transform

timm.data.auto_augment_transform

timm.data.auto_augment.augment_and_mix_transform

classe timm.data.random_erasing.RandomErasing

Jeux de données

timm.data.create_dataset

classe timm.data.ImageDataset

classe timm.data.IterableImageDataset

classe timm.data.AugMixDataset

classe timm.data.MultiLabelTarget

Chargeurs

timm.data.create_loader

Mixup et CutMix

classe timm.data.Mixup

classe timm.data.FastCollateMixup

NaFlex

timm.data.create_naflex_loader

classe timm.data.NaFlexMapDatasetWrapper

set_epoch

classe timm.data.NaFlexMixup

set_epoch