Data

Halaman ini berisi dokumentasi referensi API untuk sub-paket timm.data, serta gambaran umum tentang pipeline input yang disediakan: resolusi konfigurasi pra-pemrosesan model, pembuatan transformasi, pembuatan dataset dan loader, Mixup / CutMix, dan loader resolusi variabel NaFlex.

Penggunaan

Sebuah pipeline dibangun dalam empat langkah: resolve_model_data_config membaca konfigurasi pra-pemrosesan model, create_transform membangun transform untuk train atau eval, create_dataset membuat dataset berdasarkan nama dan root, dan create_loader membangun transform serta data loader untuk sebuah dataset.

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

quickstart menjelaskan langkah-langkah konfigurasi hingga transformasi untuk inferensi.

Skrip pelatihan (train.py) menyediakan opsi-opsi ini untuk setiap bagian dari pipeline.

Override konfigurasi input (resolve_input_data_config):

--input-size mengatur bentuk input (C, H, W).
--img-size adalah pintasan persegi untuk --input-size, yang mempertahankan jumlah channel model.
--in-chans mengatur saluran input.
--interpolation mengatur interpolasi resize.
--mean mengatur rata-rata normalisasi.
--std mengatur standar deviasi normalisasi.
--crop-pct mengatur fraksi crop evaluasi.

Pembuatan dataset (create_dataset) dan pengaturan target:

--dataset memilih dataset dan pembaca.
--data-dir mengatur root dataset.
--train-split memilih split pelatihan.
--val-split memilih split validasi.
--class-map menyediakan pemetaan kelas.
--input-img-mode mengatur mode konversi warna gambar.
--input-key memilih bidang gambar.
--target-key memilih bidang label atau beberapa bidang label.
--target-format memilih indeks kelas atau target multi-hot padat.

Opsi loader dan augmentasi (create_loader) meliputi:

--aa memilih kebijakan auto-augmentation.
--reprob mengatur probabilitas penghapusan acak.
--remode memilih mode pengisian penghapusan acak.
--scale mengatur rentang skala untuk random resized crop.
--ratio mengatur rentang rasio aspek untuk random resized crop.
--hflip mengatur probabilitas flip horizontal.
--color-jitter mengatur kekuatan color jitter.
--train-interpolation mengatur interpolasi pengubahan ukuran (resize) untuk pelatihan.
--workers mengatur jumlah worker loader.
--no-prefetcher menonaktifkan prefetcher.

Mixup dan CutMix (Mixup):

--mixup mengatur alpha Mixup.
--cutmix mengatur alpha CutMix.
--cutmix-minmax mengatur rentang ukuran kotak CutMix.
--mixup-prob mengatur probabilitas pencampuran.
--mixup-switch-prob mengatur probabilitas memilih CutMix ketika kedua metode diaktifkan.
--mixup-mode memilih pencampuran batch, pair, atau element-wise.
--smoothing mengatur label smoothing.

Lihat Scripts untuk contoh.

Konfigurasi data

resolve_data_config mengembalikan dict dengan kunci-kunci di bawah, yang sesuai dengan argumen dari create_transform dan create_loader. Nilai yang diset dalam args (sebuah dict, misalnya vars(args) dari argumen baris perintah yang diurai) memiliki prioritas lebih tinggi daripada argumen pretrained_cfg, yang secara default adalah model.pretrained_cfg. resolve_model_data_config memiliki fungsi yang sama dengan model sebagai argumen pertama.

Keduanya membaca ukuran input dan channel dari cfg pretrained, yang menjelaskan checkpoint sumber, bukan model yang dibuat atau diubah untuk menggunakan img_size atau in_chans yang berbeda. resolve_input_data_config, yang digunakan oleh skrip pelatihan, validasi, dan inferensi, menyelesaikan terhadap input saat ini dari model: model dengan ukuran input tetap selalu mendapatkan ukuran saat ini, args eksplisit yang bertentangan dengan channel atau ukuran tetap model akan memicu error, dan mean / std yang tidak sesuai dengan jumlah channel akan diganti dengan rata-ratanya (dengan peringatan).

Kunci	Kunci `args`	Deskripsi	Default
`input_size`	`input_size`, `img_size`, `in_chans`	Ukuran input `(C, H, W)`. Dengan `use_test_size=True`, `test_input_size` dari config digunakan jika ada	`(3, 224, 224)`
`interpolation`	`interpolation`	Interpolasi resize, `bilinear`, `bicubic`, …	`bicubic`
`mean`, `std`	`mean`, `std`	Normalisasi, satu nilai diulang untuk setiap channel	Mean / std ImageNet
`crop_pct`	`crop_pct`	Pada Eval crop, gambar di-resize menjadi `size / crop_pct` sebelum dipotong menjadi `size` (`test_crop_pct` dengan `use_test_size=True`)	`0.875`
`crop_mode`	`crop_mode`	Mode crop evaluasi, `center`, `squash` atau `border`	`center`

Mode crop eval, untuk output size dan scale_size = floor(size / crop_pct):

`crop_mode`	Perilaku
`center`	Perkecil sisi terpendek menjadi `scale_size` (rasio aspek dipertahankan), lalu crop tengah menjadi `size`
`squash`	Ukurkan kedua tepi menjadi `scale_size` (rasio aspek tidak dipertahankan), lalu potong tengah menjadi `size`
`border`	Perbesar sisi terpanjang menjadi `scale_size`, lakukan center crop dan pad dengan warna rata-rata, seluruh gambar dipertahankan pada `crop_pct=1.0`

Transforms

create_transform mengembalikan torchvision Compose. Transformasi eval melakukan resize dan crop seperti di atas, lalu mengonversi ke tensor dan menormalisasi. Transformasi pelatihan adalah random resized crop (scale=(0.08, 1.0), ratio=(3/4, 4/3) secara default), horizontal flip (hflip=0.5), color jitter (color_jitter=0.4), kebijakan auto_augment opsional, konversi tensor dan normalisasi, serta random erasing.

train_crop_mode='rkrc' atau 'rkrr' menggantikan random resized crop dengan random resize yang mempertahankan rasio aspek, diikuti oleh center (rkrc) atau random (rkrr) crop atau pad.
interpolation='random' (default train.py untuk pelatihan) memilih bilinear atau bicubic per gambar.
no_aug=True mengurangi pelatihan menjadi hanya resize dan center crop.

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

Token opsi RandAugment:

m mengatur magnitudo (default 10).
n mengatur jumlah operasi per gambar (default 2).
p mengatur probabilitas per op (default 0.5).
mstd mengatur standar deviasi noise magnitudo.
inc1 memilih operasi yang tingkat keparahannya meningkat seiring dengan besarnya magnitudo.
t<name> memilih set op (weights, 3a, 3aw).

Token opsi AugMix:

m mengatur tingkat keparahan (default 3).
w mengatur lebar (default 3).
d mengatur kedalaman (default -1, acak 1-3).
b1 memungkinkan augmentasi campuran.
mstd mengatur standar deviasi noise magnitudo.

AutoAugment menerima mstd, misalnya original-mstd0.5.

Perilaku transformasi:

Color jitter dinonaktifkan ketika auto_augment disetel, kecuali string tersebut mengandung 3a.
RandomErasing (re_prob, re_count) dijalankan pada tensor yang telah dinormalisasi. re_mode mengisi dengan nol (const, nilai default), warna normal acak per wilayah (rand) atau piksel normal acak (pixel, default train.py).
use_prefetcher=True mengakhiri transform pada tensor uint8, kemudian normalisasi dan penghapusan acak dilakukan oleh loader pada perangkat.
create_transform dan create_loader secara default menggunakan interpolasi bilinear serta mean / std ImageNet, bukan nilai dari model. Sampaikan konfigurasi data yang telah dipecahkan agar sesuai dengan pra-pelatihan model.

Dataset

create_dataset memilih implementasi dataset dan reader dari prefiks name:

`name`	Dataset	`root`	Diperlukan
`''` atau tanpa awalan	`ImageDataset`, gambar dalam sub-folder kelas (dicari secara rekursif, nama folder daun adalah kelasnya), atau satu file `.tar` tunggal dengan struktur yang sama	Folder dataset atau file `.tar`
`torch/<name>`	torchvision `cifar10`, `cifar100`, `mnist`, `kmnist`, `fashion_mnist`, `qmnist`, `inaturalist` (`inat`), `places365`, `imagenet` atau `image_folder` (`folder`)	root dataset torchvision
`hfds/<name>`	`ImageDataset` pada dataset Hugging Face Hub (atau path lokal) melalui `datasets.load_dataset`	Direktori cache (opsional)	`datasets`
`hfids/<name>`	`IterableImageDataset`, dataset Hugging Face yang di-streaming, atau diunduh dan disiapkan terlebih dahulu dengan `download=True`	Direktori cache (opsional)	`datasets`
`tfds/<name>`	`IterableImageDataset` pada TensorFlow Datasets, `download=True` mengunduh dan membangun	Direktori data TFDS	`tensorflow`, `tensorflow-datasets`
`wds/<name>`	`IterableImageDataset` pada tar shards WebDataset	Folder shard dengan `_info.json` (atau `info.json`) yang menjelaskan split	`webdataset`

Opsi dataset:

split memilih split dataset (default validation). Untuk WebDataset, ini juga bisa berupa pola shard dengan jumlah sampel, 'imagenet-train-{0000..1023}.tar|1281167'.
search_split=True (default) membuat dataset folder mencari sub-folder dari root yang bernama split atau, jika tidak ada, sinonim dari split train (train, training) atau eval (val, valid, validation, eval, evaluation).
add_img_extensions menambahkan ke ekstensi gambar bawaan (.png, .jpg dan .jpeg).
class_map memetakan ulang nama kelas ke indeks menggunakan dict, file .txt (satu kelas per baris), atau file .pkl.

Dataset iterable (hfids, tfds, wds) juga menerima:

is_training mengaktifkan pengacakan.
batch_size membulatkan bagian sampel setiap worker ke atas menjadi batch utuh saat pelatihan.
num_samples mengatur jumlah sampel, yang diperlukan ketika pembaca tidak dapat menentukannya (hfids tanpa info split).
seed mengatur seed acak.
repeats mengalikan jumlah sampel per epoch, sehingga pembaca melewati data sebanyak itu kali.

Panggil dataset.set_epoch() setiap epoch untuk mengacak ulang.

Argumen kata kunci lainnya diteruskan ke pembaca. Untuk pembaca Hugging Face, TFDS, dan WebDataset:

input_key memilih bidang gambar (image secara default, untuk wds berupa gambar jpg, png atau webp).
target_key memilih bidang label (secara default label, untuk wds berupa file .cls atau bidang sidecar .json yang dinamai oleh target_key). Nilai yang dipisahkan koma membaca satu bidang biner per kelas.
target_format='multihot' membaca vektor multi-hot padat alih-alih daftar indeks kelas untuk data multi-label.
target_transform=MultiLabelTarget(num_classes) mengkodekan target sebagai tensor multi-hot float. Lewatkan dense=True ke MultiLabelTarget untuk field multi-hot.

Pembaca folder dan tar menghasilkan indeks kelas tunggal. Lihat klasifikasi multi-label untuk detailnya.

Pemuat

create_loader membuat transform dengan create_transform dari argumennya sendiri, menugaskannya ke dataset.transform (menggantikan transform yang sudah ada) dan mengembalikan DataLoader. Loader pelatihan (is_training=True) mengacak dan membuang batch terakhir yang tidak lengkap.

Prefetcher. Dengan use_prefetcher=True (default), dataset menghasilkan tensor uint8, batch dipindahkan ke device (default cuda, pada side stream untuk CUDA), dikonversi ke img_dtype, dinormalisasi, dan dihapus secara acak di sana. Atur device ke perangkat pelatihan, atau use_prefetcher=False untuk DataLoader biasa dari tensor yang dinormalisasi.
Distribusi. distributed=True menggunakan DistributedSampler untuk dataset pelatihan gaya peta (atau sampler augmentasi berulang dengan num_aug_repeats) dan sampler berurutan untuk evaluasi yang mengisi setiap proses hingga jumlah sampel yang sama, yang dapat sedikit mengubah hasil validasi. Dataset iterable membagi diri mereka sendiri di antara proses dan pekerja.
Collate. collate_fn menggantikan default (fast_collate dengan prefetcher, default_collate tanpa), misalnya dengan FastCollateMixup.
Pembagian augmentasi. Untuk AugMix dengan loss JSD (--aug-splits), bungkus dataset dalam AugMixDataset(dataset, num_splits=n) dan teruskan num_aug_splits=n. Setiap batch berisi satu bagian bersih dan n - 1 bagian yang di-augmentasi, yang digabungkan sepanjang dimensi batch oleh prefetcher.
Resolusi terjadwal. input_size_choices (--train-img-sizes) memilih ukuran input per batch, secara opsional dengan ukuran batch per pilihan (batch_size_choices) dan jadwal progressive dari pilihan pertama hingga terakhir.

Mixup dan CutMix

Mixup mencampur batch gambar ternormalisasi di perangkat, setelah loader. FastCollateMixup mengambil argumen yang sama dan mencampur gambar uint8 saat melakukan collating di worker loader, dan memerlukan prefetcher. Keduanya mengembalikan target padat (batch_size, num_classes) dengan label_smoothing (default 0.1) yang diterapkan, untuk digunakan dengan loss target lunak seperti timm.loss.SoftTargetCrossEntropy, dan memerlukan ukuran batch yang genap.

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

Kontrol Mixup dan CutMix:

mixup_alpha > 0 mengaktifkan Mixup.
cutmix_alpha > 0 mengaktifkan CutMix.
cutmix_minmax mengaktifkan CutMix dengan rentang ukuran kotak.
switch_prob mengatur probabilitas memilih CutMix ketika kedua metode diaktifkan.
prob mengatur probabilitas pencampuran.
mode menggambar parameter sekali per batch, per pair elemen, atau per elem (elemen).
multi_label=True mencampur target multi-label padat, dengan menghaluskan setiap label menuju 0,5.
mixup_enabled = False mematikan pencampuran, misalnya untuk epoch terakhir (--mixup-off-epoch). Untuk FastCollateMixup, nilai ini dibaca di proses worker; worker yang persisten mempertahankan nilai yang mereka gunakan saat dimulai.

Resolusi variabel NaFlex

create_naflex_loader memuat gambar sebagai sekuens patch dengan panjang variabel, tanpa mengubah ukuran menjadi ukuran persegi tetap, untuk model yang menerima input patch NaFlex (misalnya model naflexvit_*). Setiap batch adalah dict dari patches, patch_coord, patch_valid dan seq_len, yang di-pad hingga panjang sekuens batch.

Pelatihan. Dataset dibungkus dalam NaFlexMapDatasetWrapper (hanya untuk dataset bergaya map), yang memilih salah satu dari train_seq_lens per batch dan melakukan random resize crop pada setiap gambar agar sesuai dengan jumlah patch tersebut. batch_size adalah ukuran batch pada panjang urutan terpanjang; panjang yang lebih pendek mendapatkan batch yang lebih besar secara proporsional (dibulatkan ke bawah menjadi kelipatan 8) sehingga jumlah token per batch tetap relatif konstan. patch_size_choices (dengan patch_size_choice_probs) juga memvariasikan ukuran patch per batch, untuk model yang mendukungnya.
Eval. Gambar di-resize agar muat max_seq_len patch pada patch_size yang diberikan (diperlukan untuk eval) dan di-pad hingga max_seq_len.
Mixup. Lewatkan NaFlexMixup sebagai mixup_fn, ia mencampur di dalam setiap batch dan tidak mendukung mode atau cutmix_minmax.

Opsi untuk train.py adalah:

--naflex-loader mengaktifkan pemuat NaFlex.
--naflex-train-seq-lens mengatur panjang sekuens pelatihan.
--naflex-max-seq-len mengatur panjang urutan evaluasi maksimum.
--naflex-patch-sizes mengatur ukuran patch untuk pelatihan ukuran patch variabel.
--naflex-patch-size-probs mengatur probabilitas untuk ukuran patch tersebut.
--naflex-loss-scale memilih penskalaan loss berdasarkan ukuran batch (none, sqrt atau linear).

timm

Data

Penggunaan

Konfigurasi data

Transforms

Dataset

Pemuat

Mixup dan CutMix

Resolusi variabel NaFlex

API

Konfigurasi data

timm.data.resolve_data_config

timm.data.resolve_model_data_config

timm.data.resolve_input_data_config

Transforms

timm.data.create_transform

timm.data.rand_augment_transform

timm.data.auto_augment_transform

timm.data.auto_augment.augment_and_mix_transform

kelas timm.data.random_erasing.RandomErasing

Dataset

timm.data.create_dataset

kelas timm.data.ImageDataset

kelas timm.data.IterableImageDataset

kelas timm.data.AugMixDataset

kelas timm.data.MultiLabelTarget

Pemuat

timm.data.create_loader

Mixup dan CutMix

kelas timm.data.Mixup

kelas timm.data.FastCollateMixup

NaFlex

timm.data.create_naflex_loader

kelas timm.data.NaFlexMapDatasetWrapper

set_epoch

kelas timm.data.NaFlexMixup

set_epoch