Datos

Esta página contiene la documentación de referencia de la API del subpaquete timm.data y una descripción general del pipeline de entrada que proporciona: resolución de la configuración de preprocesamiento de un modelo, construcción de transformaciones, creación de conjuntos de datos y cargadores, Mixup / CutMix y el cargador de resolución variable NaFlex.

Uso

Un pipeline se construye en cuatro pasos: resolve_model_data_config lee la configuración de preprocesamiento del modelo, create_transform crea la transformación de entrenamiento o evaluación, create_dataset crea un conjunto de datos por nombre y raíz, y create_loader construye la transformación y un cargador de datos para un conjunto de datos.

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

El quickstart explica la configuración y los pasos de transformación para la inferencia.

El script de entrenamiento (train.py) expone estas opciones para cada parte del pipeline.

Sobrescrituras de la configuración de entrada (resolve_input_data_config):

--input-size establece la forma de entrada (C, H, W).
--img-size es el atajo cuadrado para --input-size, manteniendo el número de canales del modelo.
--in-chans establece los canales de entrada.
--interpolation establece la interpolación de redimensionado.
--mean establece la media de normalización.
--std establece la desviación estándar de la normalización.
--crop-pct establece la fracción de recorte para la evaluación.

Creación del dataset (create_dataset) y configuración del objetivo:

--dataset selecciona el conjunto de datos y el lector.
--data-dir establece la raíz del conjunto de datos.
--train-split selecciona la división de entrenamiento.
--val-split selecciona la división de validación.
--class-map proporciona el mapeo de clases.
--input-img-mode establece el modo de conversión de color de la imagen.
--input-key selecciona el campo de imagen.
--target-key selecciona el campo o los campos de etiqueta.
--target-format selecciona índices de clase o objetivos multi-hot densos.

Las opciones de cargador y aumento (create_loader) incluyen:

--aa selecciona la política de auto-aumentación.
--reprob establece la probabilidad de borrado aleatorio.
--remode selecciona el modo de relleno del borrado aleatorio.
--scale establece el rango de escala para el recorte redimensionado aleatorio.
--ratio establece el rango de la relación de aspecto para el recorte aleatorio redimensionado.
--hflip establece la probabilidad de volteo horizontal.
--color-jitter establece la intensidad del ajuste de color.
--train-interpolation establece la interpolación de redimensionamiento para el entrenamiento.
--workers establece el número de workers del loader.
--no-prefetcher desactiva el prefetcher.

Mixup y CutMix (Mixup):

--mixup establece el alpha de Mixup.
--cutmix establece el alfa de CutMix.
--cutmix-minmax establece el rango de tamaño de la caja de CutMix.
--mixup-prob establece la probabilidad de mezcla.
--mixup-switch-prob establece la probabilidad de elegir CutMix cuando ambos métodos están habilitados.
--mixup-mode selecciona la mezcla por lote, por par o por elemento.
--smoothing establece el suavizado de etiquetas.

Vea Scripts para ver ejemplos.

Configuración de datos

resolve_data_config devuelve un diccionario con las claves siguientes, que coinciden con los argumentos de create_transform y create_loader. Los valores establecidos en args (un diccionario, p. ej. vars(args) de los argumentos de línea de comandos analizados) tienen prioridad sobre el argumento pretrained_cfg, cuyo valor predeterminado es model.pretrained_cfg. resolve_model_data_config es lo mismo, pero con el modelo como primer argumento.

Ambos leen el tamaño de entrada y los canales de la configuración preentrenada, que describe el punto de control de origen, no un modelo creado o modificado para usar un img_size o in_chans diferente. resolve_input_data_config, utilizado por los scripts de entrenamiento, validación e inferencia, resuelve en contra de la entrada actual del modelo: un modelo con tamaño de entrada fijo siempre obtiene su tamaño actual, los args explícitos que entran en conflicto con los canales o el tamaño fijo del modelo generan un error, y una media / desviación estándar que no coincide con el número de canales se reemplaza por su promedio (con una advertencia).

Clave	claves de `args`	Descripción	Predeterminado
`input_size`	`input_size`, `img_size`, `in_chans`	Tamaño de entrada `(C, H, W)`. Con `use_test_size=True`, se utiliza `test_input_size` de la configuración si está definido	`(3, 224, 224)`
`interpolation`	`interpolation`	Interpolación de redimensionado, `bilinear`, `bicubic`, …	`bicubic`
`mean`, `std`	`mean`, `std`	Normalización, un único valor se repite para cada canal	Media / desviación estándar de ImageNet
`crop_pct`	`crop_pct`	En el recorte de evaluación, la imagen se redimensiona a `size / crop_pct` antes de recortarla a `size` (`test_crop_pct` con `use_test_size=True`)	`0.875`
`crop_mode`	`crop_mode`	Modo de recorte de evaluación, `center`, `squash` o `border`	`center`

Los modos de recorte de evaluación, para un size de salida y scale_size = floor(size / crop_pct):

`crop_mode`	Comportamiento
`center`	Redimensionar el borde más corto a `scale_size` (conservando la relación de aspecto) y recortar al centro a `size`
`squash`	Redimensiona ambos bordes a `scale_size` (sin preservar la relación de aspecto) y recorta al centro hasta `size`
`border`	Redimensiona el borde más largo a `scale_size`, realiza un recorte centrado y rellena con el color medio; la imagen completa se mantiene en `crop_pct=1.0`

Transformaciones

create_transform devuelve un Compose de torchvision. La transformación de evaluación redimensiona y recorta como se indicó anteriormente, y luego convierte a tensor y normaliza. La transformación de entrenamiento es un recorte redimensionado aleatorio (scale=(0.08, 1.0), ratio=(3/4, 4/3) por defecto), volteo horizontal (hflip=0.5), variación de color (color_jitter=0.4), la política opcional auto_augment, la conversión a tensor y la normalización, y el borrado aleatorio.

train_crop_mode='rkrc' o 'rkrr' reemplaza el recorte aleatorio redimensionado con un redimensionamiento aleatorio que mantiene la relación de aspecto, seguido de un recorte o relleno central (rkrc) o aleatorio (rkrr).
interpolation='random' (el valor predeterminado de train.py para el entrenamiento) elige interpolación bilineal o bicúbica para cada imagen.
no_aug=True reduce el entrenamiento a un redimensionado y un recorte centrado.

`auto_augment`	Aumento
`rand-m9-mstd0.5-inc1`	`RandAugment` a través de `rand_augment_transform`
`augmix-m5-w4-d2`	AugMix mediante `augment_and_mix_transform`
`original`, `originalr`, `v0`, `v0r`, `3a`	Política de AutoAugment mediante `auto_augment_transform`

Tokens de opciones de RandAugment:

m establece la magnitud (valor predeterminado 10).
n establece el número de operaciones por imagen (valor predeterminado 2).
p establece la probabilidad por operación (valor predeterminado 0.5).
mstd establece la desviación estándar del ruido de magnitud.
inc1 selecciona operaciones cuya severidad aumenta con la magnitud.
t<name> selecciona el conjunto de operaciones (weights, 3a, 3aw).

Tokens de la opción AugMix:

m establece la severidad (valor predeterminado 3).
w establece el ancho (predeterminado 3).
d establece la profundidad (valor predeterminado -1, aleatorio 1-3).
b1 habilita la aumentación combinada.
mstd establece la desviación estándar del ruido de magnitud.

AutoAugment acepta mstd, por ejemplo, original-mstd0.5.

Comportamiento de Transform:

El ajuste de color (color jitter) se desactiva cuando se establece auto_augment, a menos que la cadena contenga 3a.
RandomErasing (re_prob, re_count) se ejecuta en el tensor normalizado. re_mode rellena con ceros (const, el valor predeterminado), un color normal aleatorio por región (rand) o píxeles normales aleatorios (pixel, el valor predeterminado de train.py).
use_prefetcher=True finaliza la transformación en un tensor uint8; la normalización y el borrado aleatorio se realizan después en el dispositivo por el loader.
create_transform y create_loader usan por defecto interpolación bilinear y la media / desviación estándar de ImageNet, no los valores del modelo. Pasa la configuración de datos resuelta para que coincida con el preentrenamiento del modelo.

Conjuntos de datos

create_dataset selecciona la implementación del conjunto de datos y el lector a partir de un prefijo de name:

`name`	Dataset	`root`	Requisitos
`''` o sin prefijo	`ImageDataset`, imágenes en subcarpetas de clases (se busca de forma recursiva, el nombre de la carpeta hoja es la clase) o un único archivo `.tar` con el mismo	Carpeta de datos o archivo `.tar`
`torch/<name>`	torchvision `cifar10`, `cifar100`, `mnist`, `kmnist`, `fashion_mnist`, `qmnist`, `inaturalist` (`inat`), `places365`, `imagenet` o `image_folder` (`folder`)	raíz del dataset de torchvision
`hfds/<name>`	`ImageDataset` en un conjunto de datos de Hugging Face Hub (o ruta local) mediante `datasets.load_dataset`	Directorio de caché (opcional)	`datasets`
`hfids/<name>`	`IterableImageDataset`, el conjunto de datos de Hugging Face transmitido, o descargado y preparado primero con `download=True`	Directorio de caché (opcional)	`datasets`
`tfds/<name>`	`IterableImageDataset` en TensorFlow Datasets, `download=True` descarga y construye	Directorio de datos de TFDS	`tensorflow`, `tensorflow-datasets`
`wds/<name>`	`IterableImageDataset` en fragmentos tar de WebDataset	Carpeta de fragmentos con un `_info.json` (o `info.json`) que describe las divisiones	`webdataset`

Opciones de conjunto de datos:

split selecciona la división del conjunto de datos (por defecto, validation). Para WebDataset, también puede ser un patrón de fragmento con un recuento de muestras, 'imagenet-train-{0000..1023}.tar|1281167'.
search_split=True (por defecto) hace que los conjuntos de datos de carpetas busquen la subcarpeta de root llamada split o, si no la encuentra, un sinónimo de un split de entrenamiento (train, training) o de evaluación (val, valid, validation, eval, evaluation).
add_img_extensions añade a las extensiones de imagen predeterminadas (.png, .jpg y .jpeg).
class_map remapea los nombres de clases a índices mediante un diccionario, un archivo .txt (una clase por línea) o un archivo .pkl.

Los conjuntos de datos iterables (hfids, tfds, wds) también aceptan:

is_training habilita el barajado.
batch_size redondea hacia arriba la parte de muestras de cada worker a lotes completos durante el entrenamiento.
num_samples establece la cantidad de muestras, que es obligatoria cuando el lector no puede determinarla (hfids sin información de división).
seed establece la semilla aleatoria.
repeats multiplica las muestras por época; los lectores recorren los datos esa cantidad de veces.

Llama a dataset.set_epoch() en cada época para barajar de nuevo.

Otros argumentos de palabras clave se pasan al lector. Para los lectores de Hugging Face, TFDS y WebDataset:

input_key selecciona el campo de imagen (por defecto, image; para wds, una imagen jpg, png o webp).
target_key selecciona el campo de etiqueta (por defecto, label; para wds, el archivo .cls o un campo lateral .json denominado por target_key). Un valor separado por comas lee un campo binario por clase.
target_format='multihot' lee vectores multi-hot densos en lugar de listas de índices de clase para datos de múltiples etiquetas.
target_transform=MultiLabelTarget(num_classes) codifica los objetivos como tensores multi-hot de tipo float. Pasa dense=True a MultiLabelTarget para campos multi-hot.

Los lectores de carpetas y archivos tar generan índices de una sola clase. Consulte clasificación multietiqueta para obtener más detalles.

Cargadores

create_loader crea la transformación con create_transform a partir de sus propios argumentos, la asigna a dataset.transform (reemplazando cualquier transformación existente) y devuelve un DataLoader. Los loaders de entrenamiento (is_training=True) barajan y descartan el último lote incompleto.

Prefetcher. Con use_prefetcher=True (predeterminado), el conjunto de datos genera tensores uint8, los lotes se mueven a device (predeterminado cuda, en un flujo lateral para CUDA), se convierten a img_dtype, se normalizan y se borran aleatoriamente allí. Establezca device en el dispositivo de entrenamiento, o use_prefetcher=False para un DataLoader simple de tensores normalizados.
Distribuido. distributed=True utiliza un DistributedSampler para conjuntos de datos de entrenamiento de estilo mapa (o un muestreador de aumentación repetida con num_aug_repeats) y un muestreador ordenado para la evaluación que rellena cada proceso hasta el mismo número de muestras, lo que puede alterar ligeramente los resultados de validación. Los conjuntos de datos iterables se dividen por sí mismos entre procesos y trabajadores.
Collate. collate_fn reemplaza la función predeterminada (fast_collate con el prefetcher, default_collate sin él), por ejemplo, con una FastCollateMixup.
Divisiones de aumento. Para AugMix con la pérdida JSD (--aug-splits), envuelva el conjunto de datos en AugMixDataset(dataset, num_splits=n) y pase num_aug_splits=n. Cada lote contiene una división limpia y n - 1 divisiones aumentadas, concatenadas a lo largo de la dimensión del lote por el prefetcher.
Resolución programada. input_size_choices (--train-img-sizes) selecciona el tamaño de entrada por lote, opcionalmente con un tamaño de lote por opción (batch_size_choices) y un programa progressive desde la primera hasta la última opción.

Mixup y CutMix

Mixup mezcla un lote de imágenes normalizadas en el dispositivo, después del loader. FastCollateMixup toma los mismos argumentos y mezcla imágenes uint8 mientras se realiza el collate en los workers del loader; requiere el prefetcher. Ambos devuelven objetivos densos (batch_size, num_classes) con label_smoothing (por defecto 0.1) aplicado, para ser usados con una pérdida de objetivo suave como timm.loss.SoftTargetCrossEntropy, y requieren un tamaño de lote par.

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

Controles de Mixup y CutMix:

mixup_alpha > 0 habilita Mixup.
cutmix_alpha > 0 habilita CutMix.
cutmix_minmax habilita CutMix con un rango de tamaño de caja.
switch_prob establece la probabilidad de elegir CutMix cuando ambos métodos están habilitados.
prob establece la probabilidad de mezclar en absoluto.
mode extrae los parámetros una vez por batch, por pair de elementos o por elem (elemento).
multi_label=True mezcla objetivos multietiqueta densos, suavizando cada etiqueta hacia 0.5.
mixup_enabled = False desactiva la mezcla, por ejemplo, para las épocas finales (--mixup-off-epoch). En el caso de FastCollateMixup, se lee en los procesos de trabajo; los trabajadores persistentes mantienen el valor con el que comenzaron.

NaFlex con resolución variable

create_naflex_loader carga imágenes como secuencias de longitud variable de parches, sin redimensionarlas a un tamaño cuadrado fijo, para modelos que aceptan entradas de parches NaFlex (p. ej., los modelos naflexvit_*). Cada lote es un diccionario de patches, patch_coord, patch_valid y seq_len, rellenado hasta la longitud de secuencia del lote.

Entrenamiento. El conjunto de datos se envuelve en un NaFlexMapDatasetWrapper (solo para conjuntos de datos de estilo mapa), que elige una de las longitudes de train_seq_lens por lote y realiza recortes de redimensionamiento aleatorios en cada imagen para que quepan esa cantidad de parches. batch_size es el tamaño del lote en la longitud de secuencia más larga; las longitudes más cortas obtienen lotes proporcionalmente más grandes (redondeados hacia abajo a un múltiplo de 8) para que los tokens por lote se mantengan aproximadamente constantes. patch_size_choices (con patch_size_choice_probs) también varía el tamaño del parche por lote, para los modelos que lo admiten.
Eval. Las imágenes se redimensionan para que quepan en max_seq_len parches con el patch_size indicado (necesario para la evaluación) y se rellenan hasta max_seq_len.
Mixup. Pasa un NaFlexMixup como mixup_fn; mezcla dentro de cada lote y no admite mode ni cutmix_minmax.

Las opciones de train.py son:

--naflex-loader habilita el cargador NaFlex.
--naflex-train-seq-lens establece las longitudes de secuencia de entrenamiento.
--naflex-max-seq-len establece la longitud máxima de la secuencia de evaluación.
--naflex-patch-sizes establece los tamaños de parche para el entrenamiento con tamaño de parche variable.
--naflex-patch-size-probs establece las probabilidades para esos tamaños de parche.
--naflex-loss-scale selecciona la escala de pérdida según el tamaño del lote (none, sqrt o linear).

timm

Datos

Uso

Configuración de datos

Transformaciones

Conjuntos de datos

Cargadores

Mixup y CutMix

NaFlex con resolución variable

API

Configuración de datos

timm.data.resolve_data_config

timm.data.resolve_model_data_config

timm.data.resolve_input_data_config

Transformaciones

timm.data.create_transform

timm.data.rand_augment_transform

timm.data.auto_augment_transform

timm.data.auto_augment.augment_and_mix_transform

clase timm.data.random_erasing.RandomErasing

Conjuntos de datos

timm.data.create_dataset

clase timm.data.ImageDataset

clase timm.data.IterableImageDataset

clase timm.data.AugMixDataset

clase timm.data.MultiLabelTarget

Cargadores

timm.data.create_loader

Mixup y CutMix

clase timm.data.Mixup

clase timm.data.FastCollateMixup

NaFlex

timm.data.create_naflex_loader

clase timm.data.NaFlexMapDatasetWrapper

set_epoch

clase timm.data.NaFlexMixup

set_epoch