البيانات

تحتوي هذه الصفحة على توثيق مرجع واجهة برمجة التطبيقات (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 فهارس الفئات أو الأهداف الكثيفة متعددة الحارة (dense multi-hot).

تشمل خيارات التحميل والتعزيز (create_loader):

يحدد --aa سياسة التوسيع التلقائي.
يحدد --reprob احتمال المسح العشوائي.
يحدد --remode وضع التعبئة للمسح العشوائي.
--scale يحدد نطاق مقياس المحاصيل المعاد تغيير حجمها عشوائياً.
يحدد --ratio نطاق نسبة أبعاد المحاصيل المُعاد تغيير حجمها عشوائياً.
يحدد --hflip احتمال الانقلاب الأفقي.
يحدد --color-jitter قوة اهتزاز الألوان.
يحدد --train-interpolation طريقة الاستيفاء لإعادة تغيير حجم التدريب.
يحدد --workers عدد عمّال المُحمِّل.
--no-prefetcher يعطّل المُسبِق.

مزج البيانات وقطع المزج (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 هي نفسها مع النموذج كحجة أولى.

Both read the input size and channels from the pretrained cfg, which describes the source checkpoint, not a model created or changed to use a different img_size or in_chans. resolve_input_data_config, used by the training, validation and inference scripts, resolves against the model’s current input instead: a fixed input size model always gets its current size, explicit args that conflict with the model’s channels or fixed size raise an error, and a mean / std that doesn’t match the channel count is replaced by its average (with a warning).

المفتاح	مفاتيح `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`	في حالة قص التقييم، يتم تغيير حجم الصورة إلى `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. يقوم تحويل التقييم بتغيير حجم الصورة وقصّها كما هو موضح أعلاه، ثم تحويلها إلى متجه (tensor) وتطبيعها. أما تحويل التدريب فيشمل قصًا عشوائيًا مع تغيير الحجم (scale=(0.08, 1.0)، ratio=(3/4, 4/3) افتراضيًا)، انعكاس أفقي (hflip=0.5)، اضطراب ألوان (color_jitter=0.4)، سياسة auto_augment الاختيارية، تحويل إلى متجه وتطبيع، ومسح عشوائي.

train_crop_mode='rkrc' or 'rkrr' replaces the random resized crop with a random resize that keeps the aspect ratio, followed by a center (rkrc) or random (rkrr) crop or pad.
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.

سلوك التحويل:

يتم تعطيل تذبذب اللون عند تعيين 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 لمجموعات بيانات التدريب بنمط الخريطة (أو عيّنة زيادة متكررة مع num_aug_repeats) وعيّنة مرتبة للتقييم تُضيف لكل عملية عددًا متساويًا من العينات، مما قد يُغيّر نتائج التحقق بشكل طفيف. تتوزّع مجموعات البيانات القابلة للتكرار ذاتيًا عبر العمليات والعمال.
تجميع. يستبدل collate_fn الافتراضي (fast_collate مع المُسبِق، 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 عندما يكون mixup_alpha > 0
تفعيل cutmix_alpha > 0 يفعّل CutMix.
تُمكّن cutmix_minmax من تفعيل CutMix مع نطاق لحجم الصندوق.
يحدد switch_prob احتمال اختيار CutMix عند تمكين كلا الطريقتين.
prob يحدد احتمال الخلط على الإطلاق.
يرسم mode المعاملات مرة واحدة لكل batch، أو لكل pair من العناصر، أو لكل elem (عنصر).
يخلط multi_label=True بين أهداف متعددة التسميات الكثيفة، مع تنعيم كل تسمية باتجاه 0.5.
mixup_enabled = False turns mixing off, e.g. for the final epochs (--mixup-off-epoch). For FastCollateMixup it is read in the worker processes, persistent workers keep the value they started with.

دقة متغيرة لـ NaFlex

تحمّل create_naflex_loader الصور كسلاسل متغيرة الطول من الباتشات، دون إعادة تحجيمها إلى حجم مربع ثابت، وذلك للنماذج التي تستقبل مدخلات باتشات NaFlex (مثل نماذج naflexvit_*). كل دفعة (batch) هي قاموس (dict) يحتوي على patches وpatch_coord وpatch_valid وseq_len، مع ملء (padding) حتى طول السلسلة الخاص بالدفعة.

التدريب. يتم تغليف مجموعة البيانات في NaFlexMapDatasetWrapper (لمجموعات البيانات ذات نمط الخريطة فقط)، حيث يختار واحدة من train_seq_lens لكل دفعة، ويقوم بتغيير حجم كل صورة عشوائياً عبر اقتطاعها لتناسب عدد الباتشات المحدد. يمثل 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-train-seq-lens أطوال تسلسلات التدريب.
يحدد --naflex-max-seq-len الحد الأقصى لطول تسلسل التقييم.
يحدد --naflex-patch-sizes أحجام الباتشات (patch sizes) لتدريب أحجام الباتشات المتغيرة.
يحدد --naflex-patch-size-probs الاحتمالات الخاصة بأحجام البقع تلك.
يحدد --naflex-loss-scale توسيع الخسارة بناءً على حجم الدفعة (none أو sqrt أو linear).

timm

البيانات

الاستخدام

إعدادات البيانات

تحويلات

مجموعات البيانات

المحمِّلات

Mixup و CutMix

دقة متغيرة لـ NaFlex

واجهة برمجة التطبيقات

إعدادات البيانات

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

class timm.data.NaFlexMixup

set_epoch