Dữ liệu

Trang này chứa tài liệu tham khảo API cho sub-package timm.data, cùng với tổng quan về pipeline đầu vào mà nó cung cấp: xác định cấu hình tiền xử lý của model, xây dựng transforms, tạo datasets và loaders, Mixup / CutMix, và loader phân giải biến NaFlex.

Cách sử dụng

Một pipeline được xây dựng qua bốn bước: resolve_model_data_config đọc cấu hình tiền xử lý của mô hình, create_transform xây dựng transform cho tập huấn luyện hoặc đánh giá, create_dataset tạo một dataset theo tên và thư mục gốc, và create_loader xây dựng transform cùng data loader cho một 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 hướng dẫn các bước cấu hình để chuyển đổi cho suy luận.

Tệp huấn luyện (train.py) cung cấp các tùy chọn này cho từng phần của quy trình.

Ghi đè cấu hình đầu vào (resolve_input_data_config):

--input-size đặt hình dạng đầu vào (C, H, W).
--img-size là cú pháp rút gọn dạng vuông cho --input-size, giữ nguyên số kênh của mô hình.
--in-chans thiết lập số kênh đầu vào.
--interpolation thiết lập phương pháp nội suy khi thay đổi kích thước.
--mean đặt giá trị trung bình chuẩn hóa.
--std đặt độ lệch chuẩn của phép chuẩn hóa.
--crop-pct đặt tỷ lệ crop đánh giá.

Tạo Dataset (create_dataset) và thiết lập target:

--dataset chọn bộ dữ liệu và trình đọc.
--data-dir đặt thư mục gốc của bộ dữ liệu.
--train-split chọn tập dữ liệu huấn luyện.
--val-split chọn phần chia kiểm định.
--class-map cung cấp ánh xạ lớp.
--input-img-mode đặt chế độ chuyển đổi màu hình ảnh.
--input-key chọn trường ảnh.
--target-key chọn trường nhãn hoặc các trường nhãn.
--target-format chọn các chỉ số lớp hoặc các mục tiêu đa nhiệt độ dày đặc.

Các tùy chọn loader và augmentation (create_loader) bao gồm:

--aa chọn chính sách tăng cường tự động.
--reprob đặt xác suất xóa ngẫu nhiên.
--remode chọn chế độ điền cho việc xóa ngẫu nhiên.
--scale đặt phạm vi tỷ lệ crop được resize ngẫu nhiên.
--ratio đặt phạm vi tỷ lệ khung hình của thao tác crop có kích thước ngẫu nhiên.
--hflip đặt xác suất lật ngang.
--color-jitter thiết lập cường độ jitter màu.
--train-interpolation đặt phương pháp nội suy khi thay đổi kích thước trong quá trình huấn luyện.
--workers thiết lập số lượng worker của loader.
--no-prefetcher tắt prefetcher.

Mixup và CutMix (Mixup):

--mixup đặt alpha của Mixup.
--cutmix đặt alpha của CutMix.
--cutmix-minmax đặt phạm vi kích thước hộp CutMix.
--mixup-prob đặt xác suất trộn.
--mixup-switch-prob đặt xác suất chọn CutMix khi cả hai phương pháp đều được bật.
--mixup-mode chọn trộn theo batch, cặp hoặc từng phần tử.
--smoothing thiết lập làm mịn nhãn.

Xem Scripts để có ví dụ.

Cấu hình dữ liệu

resolve_data_config trả về một dict với các key bên dưới, khớp với các đối số của create_transform và create_loader. Các giá trị được đặt trong args (một dict, ví dụ vars(args) của các đối số dòng lệnh đã được phân tích) có độ ưu tiên cao hơn đối số pretrained_cfg, mặc định là model.pretrained_cfg. resolve_model_data_config hoạt động tương tự nhưng với model làm đối số đầu tiên.

Cả hai đều đọc kích thước đầu vào và số kênh từ cfg được huấn luyện trước, mô tả checkpoint nguồn, chứ không phải mô hình được tạo hoặc thay đổi để sử dụng img_size hoặc in_chans khác. resolve_input_data_config, được sử dụng bởi các script huấn luyện, xác thực và suy luận, sẽ đối chiếu với đầu vào hiện tại của mô hình: mô hình có kích thước đầu vào cố định luôn nhận kích thước hiện tại của nó, các args tường minh xung đột với số kênh hoặc kích thước cố định của mô hình sẽ gây ra lỗi, và mean / std không khớp với số kênh sẽ được thay thế bằng giá trị trung bình của chúng (kèm theo cảnh báo).

Khóa	Các khóa của `args`	Mô tả	Mặc định
`input_size`	`input_size`, `img_size`, `in_chans`	Kích thước đầu vào `(C, H, W)`. Với `use_test_size=True`, `test_input_size` của cấu hình sẽ được sử dụng nếu có	`(3, 224, 224)`
`interpolation`	`interpolation`	Nội suy thay đổi kích thước, `bilinear`, `bicubic`, …	`bicubic`
`mean`, `std`	`mean`, `std`	Chuẩn hóa, một giá trị duy nhất được lặp lại cho mỗi kênh	Trung bình / độ lệch chuẩn của ImageNet
`crop_pct`	`crop_pct`	Với Eval crop, ảnh được thay đổi kích thước thành `size / crop_pct` trước khi được cắt thành `size` (`test_crop_pct` với `use_test_size=True`)	`0.875`
`crop_mode`	`crop_mode`	Chế độ cắt khi đánh giá, `center`, `squash` hoặc `border`	`center`

Các chế độ cắt cho đánh giá, với size đầu ra và scale_size = floor(size / crop_pct):

`crop_mode`	Hành vi
`center`	Phóng to cạnh ngắn nhất thành `scale_size` (giữ nguyên tỷ lệ khung hình), sau đó cắt ở giữa thành `size`
`squash`	Phóng to cả hai cạnh lên `scale_size` (không giữ nguyên tỷ lệ khung hình), sau đó cắt ở giữa thành `size`
`border`	Phóng to cạnh dài nhất thành `scale_size`, cắt ở giữa và chèn viền bằng màu trung bình, toàn bộ hình ảnh được giữ ở `crop_pct=1.0`

Biến đổi

create_transform trả về một Compose của torchvision. Transform đánh giá sẽ resize và crop như ở trên, sau đó chuyển sang tensor và chuẩn hóa. Transform huấn luyện là random resized crop (mặc định scale=(0.08, 1.0), ratio=(3/4, 4/3)), lật ngang (hflip=0.5), color jitter (color_jitter=0.4), chính sách auto_augment tùy chọn, chuyển đổi tensor và chuẩn hóa, cùng với random erasing.

train_crop_mode='rkrc' hoặc 'rkrr' thay thế thao tác crop có kích thước ngẫu nhiên bằng thao tác resize ngẫu nhiên giữ nguyên tỷ lệ khung hình, sau đó thực hiện crop hoặc pad ở giữa (rkrc) hoặc ngẫu nhiên (rkrr).
interpolation='random' (mặc định của train.py khi huấn luyện) chọn bilinear hoặc bicubic cho từng ảnh.
no_aug=True giảm quy trình huấn luyện xuống còn thao tác thay đổi kích thước và cắt ở giữa.

`auto_augment`	Tăng cường
`rand-m9-mstd0.5-inc1`	`RandAugment` thông qua `rand_augment_transform`
`augmix-m5-w4-d2`	AugMix thông qua `augment_and_mix_transform`
`original`, `originalr`, `v0`, `v0r`, `3a`	AutoAugment policy thông qua `auto_augment_transform`

Các token tùy chọn của RandAugment:

m đặt độ lớn (mặc định là 10).
n đặt số lượng ops trên mỗi ảnh (mặc định là 2).
p đặt xác suất cho mỗi op (mặc định là 0.5).
mstd đặt độ lệch chuẩn của nhiễu biên độ.
inc1 chọn các op mà mức độ nghiêm trọng tăng theo biên độ.
t<name> chọn bộ toán tử (weights, 3a, 3aw).

Các token tùy chọn AugMix:

m đặt mức độ nghiêm trọng (mặc định là 3).
w đặt chiều rộng (mặc định là 3).
d đặt độ sâu (mặc định -1, ngẫu nhiên 1-3).
b1 cho phép tăng cường dữ liệu hỗn hợp.
mstd đặt độ lệch chuẩn của nhiễu biên độ.

AutoAugment chấp nhận mstd, ví dụ original-mstd0.5.

Hành vi của Transform:

Color jitter bị vô hiệu hóa khi auto_augment được đặt, trừ khi chuỗi chứa 3a.
RandomErasing (re_prob, re_count) chạy trên tensor đã chuẩn hóa. re_mode điền bằng số không (const, mặc định), một màu chuẩn ngẫu nhiên cho mỗi vùng (rand) hoặc các pixel chuẩn ngẫu nhiên (pixel, mặc định của train.py).
use_prefetcher=True kết thúc transform tại một tensor uint8, sau đó normalization và random erasing được thực hiện bởi loader trên thiết bị.
create_transform và create_loader mặc định sử dụng nội suy bilinear và giá trị trung bình / độ lệch chuẩn của ImageNet, thay vì các giá trị của mô hình. Hãy truyền cấu hình dữ liệu đã được giải quyết để khớp với quá trình tiền huấn luyện của mô hình.

Bộ dữ liệu

create_dataset chọn triển khai dataset và reader từ một tiền tố của name:

`name`	Bộ dữ liệu	`root`	Yêu cầu
`''` hoặc không có tiền tố	`ImageDataset`, các hình ảnh trong các thư mục con của lớp (tìm kiếm đệ quy, tên thư mục lá là tên lớp), hoặc một tệp `.tar` duy nhất có cùng	Thư mục Dataset hoặc tệp `.tar`
`torch/<name>`	torchvision `cifar10`, `cifar100`, `mnist`, `kmnist`, `fashion_mnist`, `qmnist`, `inaturalist` (`inat`), `places365`, `imagenet` hoặc `image_folder` (`folder`)	thư mục gốc của bộ dữ liệu torchvision
`hfds/<name>`	`ImageDataset` trên một dataset của Hugging Face Hub (hoặc đường dẫn cục bộ) thông qua `datasets.load_dataset`	Thư mục cache (tùy chọn)	`datasets`
`hfids/<name>`	`IterableImageDataset`, bộ dữ liệu Hugging Face được stream, hoặc được tải xuống và chuẩn bị trước với `download=True`	Thư mục cache (tùy chọn)	`datasets`
`tfds/<name>`	`IterableImageDataset` trên TensorFlow Datasets, `download=True` sẽ tải xuống và xây dựng	Thư mục dữ liệu TFDS	`tensorflow`, `tensorflow-datasets`
`wds/<name>`	`IterableImageDataset` trên các shard tar của WebDataset	Thư mục shard có `_info.json` (hoặc `info.json`) mô tả các phần chia	`webdataset`

Các tùy chọn bộ dữ liệu:

split chọn phần chia của bộ dữ liệu (mặc định là validation). Đối với WebDataset, nó cũng có thể là một mẫu shard kèm theo số lượng mẫu, 'imagenet-train-{0000..1023}.tar|1281167'.
search_split=True (mặc định) khiến các dataset dạng thư mục tìm kiếm thư mục con của root có tên là split hoặc, nếu không có, một từ đồng nghĩa của split train (train, training) hoặc eval (val, valid, validation, eval, evaluation).
add_img_extensions bổ sung vào các định dạng ảnh mặc định (.png, .jpg và .jpeg).
class_map ánh xạ lại tên lớp sang chỉ số bằng một dict, một tệp .txt (mỗi dòng một lớp) hoặc một tệp .pkl.

Các tập dữ liệu dạng lặp (hfids, tfds, wds) cũng nhận:

is_training cho phép xáo trộn.
batch_size làm tròn phần mẫu của mỗi worker lên thành các batch nguyên khi huấn luyện.
num_samples đặt số lượng mẫu, bắt buộc khi trình đọc không thể xác định được (hfids không có thông tin phân chia).
seed đặt hạt ngẫu nhiên.
repeats nhân số mẫu mỗi epoch, các reader sẽ quét qua dữ liệu bấy nhiêu lần.

Gọi dataset.set_epoch() mỗi epoch để xáo trộn lại.

Các đối số từ khóa khác được truyền tiếp đến trình đọc. Đối với các trình đọc Hugging Face, TFDS và WebDataset:

input_key chọn trường ảnh (mặc định là image, đối với wds là ảnh jpg, png hoặc webp).
target_key chọn trường nhãn (mặc định là label, với wds là tệp .cls hoặc trường sidecar .json được đặt tên bởi target_key). Giá trị phân tách bằng dấu phẩy đọc một trường nhị phân cho mỗi lớp.
target_format='multihot' đọc các vector multi-hot dày đặc thay vì các danh sách chỉ số lớp cho dữ liệu đa nhãn.
target_transform=MultiLabelTarget(num_classes) mã hóa các mục tiêu thành các tensor multi-hot dạng float. Truyền dense=True vào MultiLabelTarget cho các trường multi-hot.

Trình đọc thư mục và tar trả về các chỉ mục lớp đơn. Xem phân loại đa nhãn để biết thêm chi tiết.

Trình nạp

create_loader tạo transform bằng create_transform từ các đối số của chính nó, gán nó cho dataset.transform (thay thế mọi transform hiện có) và trả về một DataLoader. Các loader huấn luyện (is_training=True) sẽ xáo trộn và bỏ qua batch cuối cùng không đầy đủ.

Trình lấy trước (Prefetcher). Với use_prefetcher=True (mặc định), tập dữ liệu sẽ tạo ra các tensor uint8, các lô (batch) được chuyển đến device (mặc định là cuda, trên một luồng phụ cho CUDA), sau đó được chuyển đổi sang img_dtype, chuẩn hóa và xóa ngẫu nhiên ngay tại đó. Đặt device thành thiết bị huấn luyện, hoặc đặt use_prefetcher=False để sử dụng DataLoader thông thường với các tensor đã được chuẩn hóa.
Phân tán. distributed=True sử dụng DistributedSampler cho các tập dữ liệu huấn luyện theo kiểu map (hoặc một bộ lấy mẫu tăng cường lặp lại với num_aug_repeats) và một bộ lấy mẫu có thứ tự cho đánh giá, trong đó mỗi tiến trình được đệm để có cùng số lượng mẫu, điều này có thể làm thay đổi nhẹ kết quả xác thực. Các tập dữ liệu dạng iterable tự chia nhỏ (shard) trên các tiến trình và worker.
Collate. collate_fn thay thế mặc định (fast_collate với prefetcher, default_collate không có), ví dụ bằng FastCollateMixup.
Các phần chia tăng cường. Đối với AugMix có loss JSD (--aug-splits), bọc dataset trong AugMixDataset(dataset, num_splits=n) và truyền num_aug_splits=n. Mỗi batch chứa một phần chia sạch và n - 1 phần chia đã tăng cường, được nối theo chiều batch bởi prefetcher.
Giải quyết theo lịch trình. input_size_choices (--train-img-sizes) chọn kích thước đầu vào cho mỗi batch, tùy chọn kèm kích thước batch cho từng lựa chọn (batch_size_choices) và lịch trình progressive từ lựa chọn đầu tiên đến lựa chọn cuối cùng.

Mixup và CutMix

Mixup trộn một batch ảnh đã chuẩn hóa trên thiết bị, sau loader. FastCollateMixup nhận cùng các đối số và trộn các ảnh uint8 trong khi collate trong các worker của loader, nó yêu cầu prefetcher. Cả hai đều trả về các target dạng dense (batch_size, num_classes) với label_smoothing (mặc định là 0.1) được áp dụng, để sử dụng với một loss target mềm như timm.loss.SoftTargetCrossEntropy, và yêu cầu batch size chẵn.

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

Các điều khiển Mixup và CutMix:

mixup_alpha > 0 bật Mixup.
cutmix_alpha > 0 bật CutMix.
cutmix_minmax cho phép bật CutMix với một khoảng kích thước hộp.
switch_prob đặt xác suất chọn CutMix khi cả hai phương pháp đều được bật.
prob đặt xác suất của việc trộn lẫn.
mode vẽ các tham số một lần cho mỗi batch, cho mỗi pair các phần tử hoặc cho mỗi elem (phần tử).
multi_label=True trộn các mục tiêu đa nhãn dạng dense, làm mượt từng nhãn về phía 0.5.
mixup_enabled = False tắt tính năng trộn, ví dụ cho các epoch cuối (--mixup-off-epoch). Đối với FastCollateMixup, giá trị này được đọc trong các tiến trình worker; các worker bền (persistent) sẽ giữ nguyên giá trị ban đầu của chúng.

NaFlex độ phân giải biến

create_naflex_loader nạp ảnh dưới dạng các chuỗi patch có độ dài thay đổi, mà không resize về kích thước vuông cố định, dành cho các mô hình nhận đầu vào patch NaFlex (ví dụ các mô hình naflexvit_*). Mỗi batch là một dict gồm patches, patch_coord, patch_valid và seq_len, được pad đến độ dài chuỗi của batch.

Đào tạo. Bộ dữ liệu được bọc trong NaFlexMapDatasetWrapper (chỉ dành cho các bộ dữ liệu dạng map), trong đó mỗi batch sẽ chọn một trong số train_seq_lens và thực hiện random resize crop cho từng ảnh để vừa với số lượng patch tương ứng. batch_size là kích thước batch tại độ dài chuỗi dài nhất; các độ dài ngắn hơn sẽ có batch lớn hơn theo tỷ lệ (làm tròn xuống đến bội số của 8) để số token mỗi batch gần như không đổi. patch_size_choices (kết hợp với patch_size_choice_probs) cũng thay đổi kích thước patch theo từng batch, dành cho các mô hình hỗ trợ tính năng này.
Đánh giá. Ảnh được điều chỉnh kích thước để vừa với max_seq_len patch ở patch_size đã cho (bắt buộc cho đánh giá) và được đệm lên max_seq_len.
Mixup. Truyền một NaFlexMixup vào mixup_fn, nó sẽ trộn lẫn trong mỗi batch và không hỗ trợ mode hoặc cutmix_minmax.

Các tùy chọn của train.py là:

--naflex-loader bật trình nạp NaFlex.
--naflex-train-seq-lens thiết lập độ dài chuỗi huấn luyện.
--naflex-max-seq-len đặt độ dài chuỗi đánh giá tối đa.
--naflex-patch-sizes thiết lập kích thước patch cho việc huấn luyện với kích thước patch thay đổi.
--naflex-patch-size-probs thiết lập xác suất cho các kích thước patch đó.
--naflex-loss-scale chọn việc mở rộng loss theo kích thước batch (none, sqrt hoặc linear).

timm

Dữ liệu

Cách sử dụng

Cấu hình dữ liệu

Biến đổi

Bộ dữ liệu

Trình nạp

Mixup và CutMix

NaFlex độ phân giải biến

API

Cấu hình dữ liệu

timm.data.resolve_data_config

timm.data.resolve_model_data_config

timm.data.resolve_input_data_config

Biến đổi

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

Bộ dữ liệu

timm.data.create_dataset

lớp timm.data.ImageDataset

lớp timm.data.IterableImageDataset

class timm.data.AugMixDataset

lớp timm.data.MultiLabelTarget

Trình nạp

timm.data.create_loader

Mixup và CutMix

lớp timm.data.Mixup

lớp timm.data.FastCollateMixup

NaFlex

timm.data.create_naflex_loader

class timm.data.NaFlexMapDatasetWrapper

set_epoch

class timm.data.NaFlexMixup

set_epoch