البرامج النصية

سكربت لتنظيف التدريب والتحقق والاستدلال ونقاط الحفظ، مضمّن في مجلد الجذر في github. لا يتم حاليًا تضمين السكربتات في إصدار pip.

تطورت سكربتات التدريب والتحقق من الإصدارات المبكرة من PyTorch Imagenet Examples. وقد أضفت وظائف مهمة مع مرور الوقت، بما في ذلك تحسينات أداء محددة لـ CUDA مبنية على NVIDIA’s APEX Examples.

سكربت التدريب

تنوع حِجج التدريب كبير، ولم يتم اختبار جميع تركيبات الخيارات (أو حتى الخيارات نفسها) بشكل كامل. بالنسبة لمجلد مجموعة بيانات التدريب، حدد المجلد الأساسي الذي يحتوي على مجلد train ومجلد validation.

لتشغيل على عقدة واحدة، استخدم torchrun بعملية واحدة لكل وحدة معالجة رسومية. على سبيل المثال، بعد حفظ إعدادات MobileNetV4 باسم mobilenetv4.yaml:

torchrun --standalone --nproc_per_node=2 train.py \
  --config mobilenetv4.yaml --data-dir /data/imagenet --experiment mobilenetv4-cm

./distributed_train.sh 2 ... هو غلاف ميسّر حول torchrun. لوحدة معالجة رسومات واحدة، استخدم python train.py ... وعدّل حجم الدفعة ومعدل التعلم كما هو موضح في HParams.

`--amp` uses PyTorch native mixed precision, with float16 by default. Use `--amp-dtype bfloat16` on supported hardware. The examples below use native PyTorch AMP and DDP; Apex is not required.

ملفات الإعداد

يمكن تقديم أي حجة تدريب في ملف YAML عبر --config، حيث تُستخدم أسماء الحُجج مع خط سفلي كمفاتيح (--weight-decay تصبح weight_decay). تتفوق حُجج سطر الأوامر على تلك الموجودة في الملف. تكتب كل عملية التدريب مجموعة الحُجج الفعالة الكاملة في ملف args.yaml داخل مجلد الإخراج الخاص بها، وهذا الملف بحد ذاته ملف --config صالح، لذا يمكن إعادة إنتاج عملية التدريب باستخدام python train.py --config output/train/my-run/args.yaml --experiment my-run-2. يسجّل الملف أيضاً output وexperiment وresume، لذا فإن الأمر دون اسم تجربة جديد سيكتب في المجلد الأصلي، ومع --resume auto سيستمر في العملية الأصلية بدلاً من تكرارها. يتم التحقق من مفاتيح الإعداد مقابل حُجج السكربت: المفاتيح غير المعروفة تُصدر تحذيراً، بينما الخيارات غير الصالحة أو القيم غير الرقمية للحُجج الرقمية تُسبب خطأً.

استئناف نقاط التفتيش الرئيسية

تكتب كل عملية تشغيل last.pth.tar (دائماً آخر حقبة، مع حالة النموذج، والمُحسِّن، وEMA، ومقياس AMP)، وmodel_best.pth.tar، وسجلًا مرتبًا من ملفات checkpoint-N.pth.tar محدودة بواسطة --checkpoint-hist.

• --resume PATH يستعيد ذلك الحالة ويواصل الجدولة من حقبة نقطة التفتيش. هذه هي الطريقة المعتادة لبدء مجلد تجربة جديد من نقطة تفتيش موجودة مسبقًا.
• --resume auto يستأنف التنفيذ في مكانه: عند ضبط --output و--experiment، يستمر من last.pth.tar في مجلد التجربة ذلك إذا كان موجودًا، وإلا يبدأ تشغيلًا جديدًا. يمكن إعادة تشغيل الأمر نفسه بعد انقطاع. تتواصل سجلات نقاط التفتيش وتتبع أفضل مقاييس الأداء وsummary.csv بشكل متسق، لذا تبقى عملية الإزالة الخاصة ب--checkpoint-hist وmodel_best صحيحة عبر إعادة التشغيل.
• --stop-epoch N يوقف التدريب بعد N من الفترات المكتملة دون تغيير الجدول الزمني المحدد بواسطة --epochs. يتم دائمًا تقييم الفترة النهائية وإنشاء نقطة تحقق منها، مما يتيح تدريب النموذج على مراحل.
• يحافظ --save-epochs N [N ...] على لقطات غير قابلة للتعديل باسم milestone-N.pth.tar (حيث N هو عدد الحقب المكتملة) خارج سجل الترتيب. يتم إنشاء روابط صلبة لهذه اللقطات من last.pth.tar حيثما سمح نظام الملفات بذلك، فلا تستهلك مساحة إضافية، كما يُجبر النظام على إجراء تقييم عند تلك الحقب.

مجتمعةً، تُسهّل هذه العناصر إجراء تجارب الإحماء-الثبات-التلاشي (WSD) يدويًا: درّب جذعًا مستقرًا مرة واحدة، ثم افرع عمليات تبريد مستقلة من نقاطه المحورية مع الحفاظ على كامل حالة المُحسِّن.

# stable trunk through 30 completed epochs, keeping milestones at 18, 24 and 30. The 1 epoch decay is never reached.
python train.py --config configs/vit.yaml --sched wsd --sched-on-updates --epochs 31 --decay-epochs 1 \
    --stop-epoch 30 --save-epochs 18 24 30 --output output/wsd --experiment stable --resume auto

# a 6 epoch 1-sqrt cooldown branched from epoch 24, i.e. a 30 epoch run that shares the first 24 epochs with the trunk
python train.py --config configs/vit.yaml --sched wsd --sched-on-updates --epochs 30 --decay-epochs 6 --lr-decay-fn 1-sqrt \
    --resume output/wsd/stable/milestone-24.pth.tar --output output/wsd --experiment decay-p24-d6

يشغل التلاشي آخر --decay-epochs من الجدول الزمني، لذا فإن فترة التبريد المكونة من D حقبة بعد P حقبة مكتملة هي --epochs P+D --decay-epochs D (اطرح --warmup-epochs من --epochs عند استخدام --warmup-prefix). يقوم sweep.py أدناه بأتمتة هذا.

مسح المعلمات الفائقة

sweep.py (PyTorch 2.5 أو أحدث) يخطط وينفّذ عمليات مسح على أي من معاملات train.py، مع إمكانية استخدام تفرع WSD. يكتب ملف train.py --config كاملًا لكل مهمة، بالإضافة إلى plan.json يحتوي على رسم اعتماديات المهام، ثم يشغّل المهام الجاهزة على مجموعة من وحدات معالجة الرسوميات المحلية. يبقى الخطة ثابتة أثناء تشغيل العمال. كل مهمة هي استدعاء عادي لـ train.py بمجلد تجربة خاص بها، ويمكن تشغيل كل run.sh المولّد يدويًا أو تسليمه إلى مجدول آخر.

لا يتطلب المسح السريع أي ملف مواصفات. تأتي محاور البحث من --sweep، والإعداد الأساسي من حجة train.py المتأخرة بعد --:

python sweep.py run --name lr-wd --sweep lr=1e-4,3e-4,1e-3 --sweep weight_decay=0.05,0.1 --gpus 0,1,2,3 \
    -- --model vit_small_patch16_224 --data-dir /data/imagenet --sched cosine --epochs 100 --amp

--gpus يعرض وحدات معالجة الرسومات التي سيتم التشغيل عليها، كمؤشرات إلى CUDA_VISIBLE_DEVICES عند ضبطها (في تخصيص Slurm، على سبيل المثال).

تشارك عملية مسح WSD جذعًا مستقرًا واحدًا لكل تركيبة من معاملات الضبط عبر فترات التبريد العديدة. بالنسبة لكل معدل تعلم أدناه، يعمل الجذع حتى 30 حقبة مع نقاط تحول عند 18 و24 و30، وتُفرع فترة تبريد مدتها 6 حقب من كل نقطة تحول، أي 4 جذوع و12 فترة تبريد إجمالًا بدلاً من 12 تشغيلًا كاملًا. تبدأ فترات التبريد بمجرد وجود نقطة التحول الخاصة بها، بينما يستمر الجذع. تُطلق المهام التي تتطلب أكثر من وحدة معالجة رسومية واحدة باستخدام torchrun:

python sweep.py run --name vit-wsd --sweep lr=1e-3,5e-4,2e-4,1e-4 \
    --wsd-points 18 24 30 --wsd-decay-epochs 6 --wsd-decay-fn 1-sqrt --gpus-per-job 2 --gpus 0,1 \
    -- --model vit_small_patch16_224 --data-dir /data/imagenet --warmup-epochs 3 --warmup-prefix --amp

يملك المخطط الأعلام التالية، لذا لا يمكن تقديمها في سطر الأوامر أو مسحها.

في كل جولة:

• --output
• --experiment
• --resume
• --stop-epoch
• --save-epochs

بالإضافة إلى ذلك، في مسح WSD:

• --sched (يمكن تقديمه على أنه wsd، وهو ما يحدده المخطط على أي حال)
• --epochs
• --decay-epochs
• --lr-decay-fn

تضيف مواصفة YAML بحثًا عشوائيًا مع توزيعات، ومحاور مزاوجة (مضغوطة)، وتكرارات عبر البذور، وملف إعداد أساسي، راجع سلسلة التوثيق في أعلى sweep.py لمعرفة المخطط. تكتب python sweep.py plan spec.yaml الإعدادات وgraph.dot دون تشغيل أي شيء.

تُحفظ عملية المسح في output/sweeps/<name>/، نسبةً إلى ملف المواصفات (أو إلى مجلد العمل في حالة مسح سطر الأوامر)، مع مجلد واحد لكل تجربة، يُسمّى باسم القيم المُسحوبة (trial-000-lr0.001)، ويحتوي كلٌّ منها على مجلدات تجارب المهمة. كل نقطة تحقق محفوظة هي نسخة كاملة تتضمن حالة المُحسِّن، لذا تحتفظ مهام المسح بنقطة تحقق واحدة مرتّبة إلى جانب last.pth.tar وmodel_best.pth.tar (--checkpoint-hist 1)، وتُحدِّد عمليات مسح WSD الجدولة لكل تحديث (--sched-on-updates). ضبط أيٍّ منهما في الإعداد الأساسي يتجاوز ذلك. أثناء تشغيلها، أو بعد ذلك:

python sweep.py status output/sweeps/vit-wsd    # job states and progress
python sweep.py results output/sweeps/vit-wsd   # ranked endpoint metrics, written to results.csv

تقارن النتائج التجارب عند ميزانيات متساوية. يُظهر مسح WSD صفًا واحدًا لكل تجربة وعمودًا واحدًا لكل فترة تهدئة (p24-d6 هي فترة تهدئة لمدة 6 فترات تدريب من أصل 24 فترة) مع المقياس النهائي، المُتوسط عبر التكرارات، مع تحديد الأفضل في كل عمود. يُرتَّب المسح العادي حسب مقياسه النهائي ضمن كل ميزانية فترات تدريب. يحتوي results.csv على كل مهمة، بما في ذلك مقاطع الجذع، مع أفضل فترة تدريب لكل منها. في غياب مجموعة التحقق، يعود الترتيب إلى خسارة التدريب، ويمكن تقييم نقاط النهاية باستخدام validate.py.

عند تشغيل sweep.py run مرة أخرى على مسح (sweep) مُقاطَع، يتم استئنافه: حيث تُتخطى المهام المكتملة، وتُستأنف المهمة ذات التشغيل الجزئي من ملف last.pth.tar الخاص بها. يمكن لكل عامل (Worker) على عدة أجهزة تشارك مجلد المسح تشغيل الأمر. يتنسيقون من خلال أقفال flock الموجودة تحت state/locks، والتي يحتفظ بها كل عملية تدريب للمهمة أيضًا، بحيث لا تُعاد بدء المهمة التي مات عاملها ولا تُعاد تخطيطها حتى تنهي آخر عملية لها. يتطلب المسح المشترك بين عدة أجهزة نظام ملفات يعمل فيه flock عبر جميعها، مثل NFSv4 أو Lustre المُركَّب مع -o flock. التركيبات ذات القفل المحلي فقط لا تتنسيق عبر الأجهزة، لذا تحقق من القفل من كل عميل. إيقاف عامل (Ctrl-C، أو SIGTERM من scancel) يوقف مهامه، وتشغيل run.sh للمهمة يدويًا يتجاوز آلية التنسيق.

ملفات القفل الموجودة تحت state/locks دائمة: لا تحذفها أو تستبدلها أبدًا لتفريغ مسح مشغول. بدلاً من ذلك، أوقف عمّاله وعمليات التدريب الخاصة به أو انتظر حتى تنتهي. حالة running (gone) تعني أن قفل التدريب متاح لكن المحاولة لم تُسوّى بعد؛ شغّل عاملًا لتسويتها واستئناف العمل غير المكتمل. status وresults لا يُصلحان حالة المهمة.

تقرأ وحدة العمل الخطة مرة واحدة عند بدء تشغيلها. لتغيير مسح، أوقف جميع وحدات العمل وعمليات التدريب الخاصة به، ثم أعد التخطيط باستخدام --force، ثم أعد تشغيلها. قبل بدء أي مهمة، يمكن تغيير أي شيء يتعلق بالخطة. بعد ذلك، يمكن فقط تمديد مهام التدريب الخاصة بها: مزيد من المحاولات، أو فترات التبريد، أو نقاط WSD بعد الموجودة، حيث يستمر كل جذع من حيث توقف. تتطلب التغييرات على مهام التدريب الموجودة مسحًا جديدًا. المسارات المولدة ثابتة عند كتابة الخطة، لذا أعد التخطيط في موقع جديد بدلاً من نقل مجلد المسح.

إذا انقطع التخطيط، فإنّ العمّال يكتشفون الإعدادات أو المُشغِّلات من كتابة خطة غير مكتملة ويرفضون البدء. أعد تشغيل أمر التخطيط الأصلي مع --force لإكمال الخطة أو إصلاحها، ثم أعد تشغيل العمّال. تنشر كل كتابة ناجحة للخطة جيلًا مطابقًا في plan.json، إلى جانب الإعدادات والمُشغِّلات؛ أمّا الخطة غير المتغيّرة والمكتملة فلا تكتب شيئًا.

على سبيل المثال، لتوسيع مسح CLI WSD المذكور أعلاه إلى 36 حقبة مستقرة، أوقف عمّاله ومهامه، ثم كرر حُجج التخطيط الأصلية مع إضافة النقطة اللاحقة:

python sweep.py plan --force --name vit-wsd --sweep lr=1e-3,5e-4,2e-4,1e-4 \
    --wsd-points 18 24 30 36 --wsd-decay-epochs 6 --wsd-decay-fn 1-sqrt --gpus-per-job 2 \
    -- --model vit_small_patch16_224 --data-dir /data/imagenet --warmup-epochs 3 --warmup-prefix --amp
python sweep.py run output/sweeps/vit-wsd --gpus 0,1

في حالة مسح YAML، أضِف النقطة إلى المواصفة الأصلية ثم نفّذ python sweep.py plan spec.yaml --force قبل إعادة التشغيل. حافظ على وضوح wsd.decay_epochs وعدم تغييره ([6] في هذا المثال): إذ إن القيمة الافتراضية له هي 20% من النقطة النهائية، لذا فإن تمديد الأفق قد يغيّر فترات التهدئة الموجودة إذا لم يُثبَّت. حافظ على معرّفات التجارب الحالية؛ فإعادة ترتيب محاور الشبكة أو توسيعها قد تعيد ترقيم التجارب. مع lr_noise، يعتمد جدول الجذع على أفقه، لذا فإن إضافة نقطة لاحقة إلى مسح قيد التنفيذ تتطلب مسحًا جديدًا.

تُدرج إعدادات التدريب في الخطة: استخدم كتلة train في المواصفات، أو الحُجج بعد -- عند إنشاء مسح عبر سطر الأوامر. لا توجد تجاوزات للتدريب أثناء التشغيل. يمكن تغيير إعدادات الإبلاغ، مثل مقياس الترتيب، وإعدادات الإخراج (checkpoint_hist، log_wandb، wandb_project، wandb_tags) دون اتصال باستخدام --force دون إعادة تعيين حالة المهمة أو تغيير هوية التدريب. تُطبَّق إعدادات الإخراج على المحاولات المستقبلية؛ ولا تُعاد تشغيل المهام المكتملة.

يتطلب sweep.py قفل flock الخاص بنظام Unix: تم اختباره على Linux، ومن المتوقع أن يعمل على macOS لكن دون اختبار. لا يُدعم نظام Windows الأصلي؛ استخدم WSL2. لا تبقى القُفل سليمة بعد انقطاع شبكة يتجاوز مدته عقد NFS: قد يستمر عملية منفصلة في التدريب بعد فقدان قُفلها، مما يتيح لجهاز آخر بدء محاولة متداخلة.

سكربتات التحقق / الاستدلال

تتشابه سكربتات التحقق والاستدلال في طريقة الاستخدام. يُخرج أحدها مقاييس على مجموعة التحقق، بينما يُخرج الآخر معرّفات أعلى topk للفئات في ملف csv. حدّد المجلد الذي يحتوي على صور التحقق، وليس المجلد الأساسي كما في سكربت التدريب.

للتحقق باستخدام أوزان النموذج المُدرَّبة مسبقًا (إن وُجدت):

python validate.py --data-dir /imagenet/validation/ --model seresnext26_32x4d --pretrained

لتشغيل الاستدلال من نقطة تحقق:

python inference.py --data-dir /imagenet/validation/ --model mobilenetv3_large_100 --checkpoint ./output/train/model_best.pth.tar

أمثلة التدريب

وصفات تدريب ImageNet

تتوافق هذه الأوامر مع وصفات HParams المحددة، حيث يمكنك العثور على إعدادات YAML قابلة للنسخ، ومصادر gists، ونتائج نقاط التفتيش المنشورة. تفترض هذه الأوامر وجود بيانات ImageFolder تحت /data/imagenet/train/ و/data/imagenet/validation/. يكون --batch-size لكل وحدة معالجة رسومية (GPU). تُطبَّق معدلات التعلم الصريحة في أمثلة MobileNetV4 وConvNeXt على أحجام الدفعة العالمية المذكورة؛ فلا يتم تحديدها تلقائيًا إذا تغيّر عدد وحدات معالجة الرسومات.

MobileNetV4 Conv Medium، ImageNet-1k

من mnv4_cm_r256_e500_gpu2.yaml: وحدة GPU واحدة، حجم دفعة عالمي 1024، تدريب بدقة 256 بكسل، و20 دورة إحماء + 500 دورة جيبية. الأوزان المقابلة هي mobilenetv4_conv_medium.e500_r256_in1k.

torchrun --standalone --nproc_per_node=2 train.py --data-dir /data/imagenet \
  --model mobilenetv4_conv_medium.e500_r256_in1k --img-size 256 --crop-pct 0.95 --batch-size 512 \
  --opt adamw --lr 0.002 --weight-decay 0.1 --clip-grad 5.0 \
  --sched cosine --sched-on-updates --epochs 500 --warmup-epochs 20 --warmup-prefix \
  --warmup-lr 0 --min-lr 0 --cooldown-epochs 0 \
  --aa rand-m8-inc1-mstd1.0 --mixup 0.2 --mixup-prob 0.8 --smoothing 0.1 \
  --reprob 0.25 --remode pixel --drop 0.2 --drop-path 0.1 \
  --model-ema --model-ema-decay 0.9998 --model-ema-warmup --dist-bn reduce \
  --amp --amp-dtype bfloat16 --torchcompile inductor --experiment mobilenetv4-cm

استخدم --amp-dtype float16 إذا لم يدعم معالج الرسوميات لديك bfloat16؛ --torchcompile inductor اختياري.

ViT Medium مع السجلات، ImageNet-1k

من train-vit_medium_reg4-4gpu-in1k.yaml: 4 وحدات معالجة رسومية، حجم دفعة إجمالي 1024، و600 دورة تدريبية تشمل الإحماء + 10 دورات تبريد. الأوزان المقابلة هي vit_medium_patch16_reg4_gap_256.sbb_in1k.

torchrun --standalone --nproc_per_node=4 train.py --data-dir /data/imagenet \
  --model vit_medium_patch16_reg4_gap_256.sbb_in1k --model-kwargs fix_init=True --head-init-scale 0 \
  --img-size 256 --crop-pct 0.95 --batch-size 256 \
  --opt adamw --opt-eps 1e-8 --lr-base 0.0008 --lr-base-size 512 --lr-base-scale sqrt \
  --weight-decay 0.07 --clip-grad 5.0 --sched cosine --sched-on-updates \
  --epochs 600 --warmup-epochs 20 --warmup-lr 5e-7 --min-lr 5e-7 --cooldown-epochs 10 \
  --aa rand-m7-inc1-mstd1.0-n3 --aug-repeats 3 --color-jitter 0 \
  --mixup 0.8 --cutmix 1.0 --smoothing 0.1 --reprob 0.2 --remode pixel --drop-path 0.2 \
  --seed 0 --amp --amp-dtype float16 --torchcompile inductor --experiment vit-medium-sbb

تستخدم هذه الجولة AdamW دون EMA. يبلغ ذروة معدل التعلم فيها تقريبًا 0.001131 عند الدفعة العالمية 1024.

ConvNeXt Tiny، ضبط دقيق من ImageNet-12k إلى ImageNet-1k

من hparams_84_00-convnext_tiny.in12k-args.yaml: 8 وحدات GPU، حجم دفعة عالمي 4096، و75 دورة تدريبية تشمل الإحماء + 10 دورات تبريد. حمّل أوزان ImageNet-12k و اضبط --num-classes 1000 لاستبدال المصنّف من أجل الضبط الدقيق. عائلة نقاط التفتيش الناتجة هي convnext_tiny.in12k_ft_in1k.

torchrun --standalone --nproc_per_node=8 train.py --data-dir /data/imagenet \
  --model convnext_tiny.in12k --pretrained --num-classes 1000 \
  --img-size 224 --crop-pct 1.0 --batch-size 512 --grad-checkpointing \
  --opt adamw --lr 1e-4 --weight-decay 0.05 --layer-decay 0.75 --clip-grad 3.0 \
  --sched cosine --epochs 75 --warmup-epochs 10 --warmup-lr 1e-6 --min-lr 5e-7 \
  --cooldown-epochs 10 --lr-noise 0.1 1.0 \
  --aa rand-m8-inc1-mstd101 --mixup 0.8 --cutmix 1.0 --smoothing 0.1 \
  --reprob 0.3 --remode pixel --drop-path 0.1 --model-ema --model-ema-decay 0.9998 \
  --amp --amp-dtype float16 --experiment convnext-tiny-ft

تصنيف متعدد التسميات

استخدم --task multilabel للصور التي تحتوي على عدة تسميات مستقلة.

• يحدد --num-classes حجم المفردات.
• --target-format indices (الافتراضي) يقرأ العمود المستهدف كقائمة من معرّفات الفئات الموجبة التي تبدأ من الصفر. تُحوَّل التسميات إلى أهداف متعددة الحارة من نوع float قبل التجميع في الدفعات، وتمثل القوائم الفارغة الصور التي لا تحتوي على تسميات موجبة.
• --target-format multihot يقرأ متجهًا كثيفًا متعدد النقاط (multi-hot) بطول --num-classes (قيم من نوع bool أو int أو float ضمن [0, 1]). يُستخدم المتجه كما هو، لذا تُدرَّب القيم الناعمة مباشرةً باستخدام BCE وتُحوَّل إلى قيم ثنائية عند 0.5 لمقاييس التقييم. يجب أن تكون خرائط الفئات لأهداف multi-hot مفهرسة بمؤشر فئة المصدر.

بدون هذا العلم، تُقرأ كل قائمة كمؤشرات فئات، لأن متجه متعدد القيم الصحيح لا يمكن تمييزه عن قائمة مؤشرات.

يوفر مجموعة بيانات أمراض النبات هذا التنسيق: عمود image وعمود labels يحتوي على تسلسل من قيم ClassLabel. فئاته الست هي complex وfrog_eye_leaf_spot وhealthy وpowdery_mildew وrust وscab. على سبيل المثال، يتحول [5, 1, 0] إلى [1, 1, 0, 0, 0, 1].

python train.py --dataset hfds/timm/plant-pathology-2021 \
  --task multilabel --target-key labels --num-classes 6 \
  --model resnet50 --pretrained --batch-size 32 --epochs 30 \
  --opt adamw --lr 1e-4 --weight-decay 0.01 --amp

python validate.py --dataset hfds/timm/plant-pathology-2021 \
  --task multilabel --target-key labels --num-classes 6 \
  --model resnet50 --checkpoint ./output/train/<experiment>/model_best.pth.tar

يدعم hfids/timm/plant-pathology-2021 البث باستخدام نفس الصيغة المستهدفة. دعم القارئ:

• تدعم Hugging Face hfds وhfids أهدافًا متعددة التسميات.
• يدعم WebDataset (wds) قوائم معرّفات الفئات المخزّنة في ملف .json المرافق لكل عيّنة تحت الحقل المُسمّى بواسطة --target-key. في غياب --target-key، يوفّر ملف .cls فهرس فئة واحدة.
• Folder and tar readers yield single class indices.

تستخدم مجموعات البيانات التي تخزن حقلًا ثنائيًا واحدًا لكل تسمية، مثل Wake Vision، هذه الإعدادات:

• يحدد --target-key person,depiction,body_part قائمة حقول مفصولة بفواصل. يصبح كل حقل فئة واحدة بالترتيب المذكور، وتُحتسب القيم الأكبر من صفر كقيم موجبة. يعمل هذا مع قارئات hfds وhfids وtfds، ومع WebDataset عندما تكون الحقول في ملف .json المرافق.
• يجب أن يساوي --num-classes عدد الحقول.
• يبقى --target-format على قيمته الافتراضية، لأن المفاتيح متعددة الحقول تُعرّف صيغتها الخاصة.
• تستخدم مسارات الحقول المتداخلة /، على سبيل المثال --input-key input --target-key output/pollen_output,output/wasps_output لمجموعة بيانات bee_dataset الخاصة بـ TFDS. تقبل مفاتيح الهدف المفردة المسارات نفسها. يأخذ اسم الحرفي للحقل الذي يحتوي على / (مثل image/filename في TFDS) الأولوية على المسار.

تدعم محمّلات Standard وNaFlex أهدافًا متعددة التسميات، بما في ذلك mixup وcutmix؛ ويتطلب تدريب NaFlex حاليًا مجموعة بيانات بنمط خريطة مثل hfds.

تُدرَّب المهمة باستخدام دالة الخسارة التبادلية الثنائية مع القيم اللوغاريتمية. القيمة الافتراضية للتنعيم هي صفر عند التدريب متعدد التسميات؛ وعند تعيين --smoothing s، تُحرَّك كل قيمة هدف ثنائية إلى target * (1 - s) + 0.5 * s، وتُطبَّق هذه العملية بواسطة Mixup/CutMix عندما تكون مفعّلة، وبواسطة دالة الخسارة في الحالات الأخرى. كما تنطبق الخيارات الموجودة --bce-sum و--bce-target-thresh. ولا تدعم هذه المهمة التقطير أو خسارة JSD.

--loss يختار خسائر أخرى (bce هو الافتراضي للتسميات المتعددة):

• asl: Asymmetric Loss. يتبع نفس سلوك التنعيم وMixup/CutMix كما في BCE ويُحسب في float32 لذا فهو آمن مع --amp.

  • --asl-gamma-neg يحدد التركيز للأهداف السالبة (الافتراضي 4).
  • --asl-gamma-pos يحدد التركيز للأهداف الإيجابية (الافتراضي 1).
  • --asl-clip يحدد هامش الاحتمال للعناصر السلبية (الافتراضي 0.05).
  • --asl-reduction افتراضيًا batchmean، حيث يجمع الخسارة عبر الفئات ويحسب متوسطها عبر الدفعة. sum يعيد اختزال ASL الأصلي، الذي يجمع أيضًا عبر الدفعة بحيث يتناسب معدل التعلم الفعلي مع حجم الدفعة.

• twoway: دالة خسارة متعددة التسميات ثنائية الاتجاه، تقوم بمقارنة القيم المنطقية الموجبة والسالبة عبر فئات كل عينة وعينات كل فئة. قيمها المنطقية هي درجات ترتيب، لذا فإن mAP هو المقياس الدلالي؛ بينما F1 عند عتبة سيجمويد غير مُعايرة.

  • يحدد --twoway-tp درجة حرارة اللوجيت الإيجابي (الافتراضي 4).
  • --twoway-tn يحدد درجة حرارة اللوجيت السلبية (الافتراضي 1).

• zlpr: ZLPR، وهو امتداد متعدد التسميات خالٍ من المعلمات الفائقة لـ softmax cross-entropy، حيث يُستخدم 0 كعتبة مدمجة لقيم logit.

• db: Distribution-Balanced Loss للبيانات متعددة التسميات ذات الذيل الطويل. BCE مع أوزان إعادة توازن لكل عينة تأخذ في الاعتبار التواجد المشترك للتسميات، وتنظيم متسامح مع القيم السالبة لـ logits، وحالة focal. يدعم Mixup/CutMix والتنعيم، مع قيم افتراضية من إعدادات DB المرجعية:

  • يحدد --db-neg-scale مقياس اللوجيت السالب (الافتراضي 2).
  • --db-init-bias يحدد عامل إزاحة اللوجيت المسبق للفئات (الافتراضي 0.05).
  • يحدد --db-focal-gamma تركيز فوكال (الافتراضي 2).
  • يوفر --class-stats أعداد التسميات التدريبية المطلوبة كملف إحصاءات فئات (فيما يلي).

يتطلب twoway وzlpr أهدافًا ثنائية، لذا لا يدعمان Mixup/CutMix أو --smoothing.

لتوزيعات التسميات غير المتوازنة، يدعم bce وasl علمَي وزن:

• --loss-pos-weight يوزّن الحد الموجب لكل فئة، مما يحقق التوازن بين الأمثلة الموجبة والسالبة داخل الفئة الواحدة. كما يؤدي هذا إلى إزاحة التوقعات نحو الجانب الموجب (مما يزيد من الاستدعاء عند عتبة ثابتة، ويقلل من معايرة الاحتمالات).
• --loss-class-weight يوزّع خسارة كل فئة بالكامل، مما يحقق التوازن بين الفئات ويحافظ على المعايرة.

تستقبل كل علامة أوزانًا صريحة (قيمة واحدة، أو قائمة مفصولة بفواصل بقيمة واحدة لكل فئة، أو ملفًا) أو اسم طريقة تُشتق منها الأوزان من أعداد التسميات التدريبية المُعطاة عبر --class-stats:

• --loss-pos-weight neg_pos: عدد العيّنات السالبة إلى عدد العيّنات الموجبة لكل فئة.
• --loss-class-weight inv_freq: تردد الفئة العكسي، مُعايَر بحيث يكون متوسطه 1.
• --loss-class-weight effective_num: أوزان class-balanced مشتقة من العدد الفعلي للعينات، ومعايرة بحيث يكون متوسطها 1.

خيارات الأوزان المشتقة:

• --loss-weight-power يحدد الأسّ الخاص بـ neg_pos و inv_freq (الافتراضي 1)، مع استخدام 0.5 لإعادة وزن جذر تربيعي أكثر نعومة.
• --loss-weight-beta يحدد قيمة بيتا لأوزان effective_num (الافتراضي 0.999).
• --loss-weight-max يحدد الحد الأقصى للأوزان المشتقة.

يمكن لكلتا علمَي الوزن استخدام الإحصاءات نفسها. يعدّ class_weights.py تسميات تقسيم، باستخدام نفس حُجج مجموعة البيانات كما في train.py، ويكتب ملف إحصاءات الفئات (يُظهر --method أوزان طريقة معينة):

python class_weights.py --dataset hfds/timm/plant-pathology-2021 --split train \
  --task multilabel --target-key labels --num-classes 6 --output stats.json

python train.py --dataset hfds/timm/plant-pathology-2021 \
  --task multilabel --target-key labels --num-classes 6 \
  --class-stats stats.json --loss-pos-weight neg_pos --loss-weight-power 0.5 ...

أعلام غير مدعومة:

تُقدّم تقارير التحقق خسارة BCE، وmap (متوسط الدقة المتوسطة)، وmicro_f1، وmacro_f1، وsample_f1. تُعبَّر المقاييس كنسب مئوية وتُحسب باستخدام مجموعة التحقق الكاملة، بما في ذلك التنبؤات المجمّعة عبر الرتب الموزّعة. يُستبعد الحشو الخاص بمُعيّن التوزيع المرتّب. يحتفظ mAP الدقيق بالتنبؤات على وحدة المعالجة المركزية (CPU) حتى انتهاء التقييم، لذا فإن استهلاك الذاكرة يتناسب مع عدد الأمثلة والفئات. تساهم الفئات التي لا تحتوي على قيم إيجابية بصفر في AP؛ وتكون قيم F1 ذات المقام صفرًا تساوي صفرًا.

--eval-metric map هو الافتراضي لاختيار نقاط التفتيش والجدولة. يستخدم F1 عتبة احتمالية سيجمويد تساوي 0.5، ويمكن ضبطها عبر --multilabel-threshold؛ بينما يكون mAP مستقلاً عن هذه العتبة. تبقى مخرجات النموذج على شكل logits، لذا يُطبَّق سيجمويد للحصول على احتمالات فئات مستقلة عند استخدام النموذج المدرَّب.

وصفات ImageNet التاريخية

تظل هذه التشغيلات السابقة مراجع مفيدة لتدريب RMSProp وSGD وAugMix/JSD. أما العتاد والمقاييس المُبلَّغ عنها فتصف التشغيلات الأصلية. أما بخصوص وصفات AdamW الأحدث، فابدأ بالأمثلة أعلاه أو مجموعات gist.

EfficientNet-B2 مع RandAugment - 80.4 أعلى من الدرجة الأولى، 95.1 أعلى من الدرجة الخامسة

استخدم التشغيل الأصلي بطاقتي Titan RTX مزدوجتين مع NVIDIA Apex؛ بينما يستخدم --amp الحالي AMP الأصلي في PyTorch:

./distributed_train.sh 2 --data-dir /imagenet/ --model efficientnet_b2 -b 128 --sched step --epochs 450 --decay-epochs 2.4 --decay-rate .97 --opt rmsproptf --opt-eps .001 -j 8 --warmup-lr 1e-6 --weight-decay 1e-5 --drop 0.3 --drop-path 0.2 --model-ema --model-ema-decay 0.9999 --aa rand-m9-mstd0.5 --remode pixel --reprob 0.2 --amp --lr .016

MixNet-XL مع RandAugment - 80.5 top-1، 94.9 top-5

استخدم التشغيل الأصلي بطاقتي Titan RTX مزدوجتين مع NVIDIA Apex؛ بينما يستخدم --amp الحالي AMP الأصلي في PyTorch:

./distributed_train.sh 2 --data-dir /imagenet/ --model mixnet_xl -b 128 --sched step --epochs 450 --decay-epochs 2.4 --decay-rate .969 --opt rmsproptf --opt-eps .001 -j 8 --warmup-lr 1e-6 --weight-decay 1e-5 --drop 0.3 --drop-path 0.2 --model-ema --model-ema-decay 0.9999 --aa rand-m9-mstd0.5 --remode pixel --reprob 0.3 --amp --lr .016 --dist-bn reduce

SE-ResNeXt-26-D وSE-ResNeXt-26-T

تعمل هذه المعلمات (أو ما يشابهها) بشكل جيد لمجموعة واسعة من معماريات ResNet، وعادةً ما يُنصح بزيادة عدد الفترات (epochs) كلما زاد حجم النموذج… أي حوالي 180-200 لـ ResNe(X)t50، و220+ للنماذج الأكبر. قم بزيادة حجم الدفعة (batch size) ومعدل التعلم (LR) بشكل متناسب للحصول على أداء أفضل مع بطاقات رسومية أقوى أو عند تفعيل AMP. كانت هذه المعلمات مخصصة لبطاقتين من نوع 1080Ti:

./distributed_train.sh 2 --data-dir /imagenet/ --model seresnext26t_32x4d --lr 0.1 --warmup-epochs 5 --epochs 160 --weight-decay 1e-4 --sched cosine --reprob 0.4 --remode pixel -b 112

EfficientNet-B3 مع RandAugment - 81.5 أعلى-1، 95.7 أعلى-5

بدأ تدريب هذا النموذج بنفس سطر الأوامر المستخدم في EfficientNet-B2 w/ RA أعلاه. بعد ما يقرب من ثلاثة أسابيع من التدريب، تعطلت العملية. لم تكن النتائج مبهرة، لذا استأنفت التدريب عدة مرات مع إجراء تعديلات على بعض المعاملات (زيادة احتمال RE، تقليل rand-aug، زيادة ema-decay). لم تبدو أي من النتائج جيدة. في النهاية، قمت بحساب متوسط أفضل نقاط التفتيش (checkpoints) من جميع عمليات إعادة التشغيل. النتيجة متوسطة عند استخدام الدقة/القص الافتراضي، لكنها بشكل غريب تتفوق بكثير عند استخدام قص اختبار كامل للصورة بقيمة 1.0.

EfficientNet-B0 مع RandAugment - 77.7 أعلى-1، 95.3 أعلى-5

Michael Klachko حقق هذه النتائج باستخدام سطر الأوامر الخاص بـ B2 مع تكييفه لحجم دفعة أكبر، مع معدل dropout الموصى به لـ B0 وهو 0.2.

./distributed_train.sh 2 --data-dir /imagenet/ --model efficientnet_b0 -b 384 --sched step --epochs 450 --decay-epochs 2.4 --decay-rate .97 --opt rmsproptf --opt-eps .001 -j 8 --warmup-lr 1e-6 --weight-decay 1e-5 --drop 0.2 --drop-path 0.2 --model-ema --model-ema-decay 0.9999 --aa rand-m9-mstd0.5 --remode pixel --reprob 0.2 --amp --lr .048

ResNet50 مع خسارة JSD وRandAugment (نظيف + 2x RA augs) - 79.04 top-1، 94.39 top-5

تم تدريب النموذج على بطاقتين قديمتين من طراز 1080Ti، مما استغرق وقتاً طويلاً. كانت نتيجة التحقق على ImageNet أفضل بقليل فقط، وبشكل غير ذي دلالة إحصائية، مقارنةً بأول تدريب جيد لـ AugMix حققت فيه 78.99. ومع ذلك، فإن هذه الأوزان أكثر متانة في الاختبارات باستخدام ImageNetV2 وImageNet-Sketch وغيرها. على عكس عمليات تشغيل AugMix الأولى لديّ، قمت بتفعيل SplitBatchNorm، وتعطيل المسح العشوائي على الجزء النظيف، ورفع احتمال المسح العشوائي على المسارين المُعزَّزين.

./distributed_train.sh 2 --data-dir /imagenet -b 64 --model resnet50 --sched cosine --epochs 200 --lr 0.05 --amp --remode pixel --reprob 0.6 --aug-splits 3 --aa rand-m9-mstd0.5-inc1 --resplit --split-bn --loss jsd --dist-bn reduce

EfficientNet-ES (EdgeTPU-Small) مع RandAugment - 78.066 top-1، 93.926 top-5

تم تدريبه بواسطة Andrew Lavin باستخدام 8 بطاقات V100. لم يُستخدم نموذج EMA، والنقطة النهائية هي متوسط أفضل 8 نقاط أثناء التدريب.

./distributed_train.sh 8 --data-dir /imagenet --model efficientnet_es -b 128 --sched step --epochs 450 --decay-epochs 2.4 --decay-rate .97 --opt rmsproptf --opt-eps .001 -j 8 --warmup-lr 1e-6 --weight-decay 1e-5 --drop 0.2 --drop-path 0.2  --aa rand-m9-mstd0.5 --remode pixel --reprob 0.2 --amp --lr .064

MobileNetV3-Large-100 - 75.766 top-1، 92.542 top-5

./distributed_train.sh 2 --data-dir /imagenet/ --model mobilenetv3_large_100 -b 512 --sched step --epochs 600 --decay-epochs 2.4 --decay-rate .973 --opt rmsproptf --opt-eps .001 -j 7 --warmup-lr 1e-6 --weight-decay 1e-5 --drop 0.2 --drop-path 0.2 --model-ema --model-ema-decay 0.9999 --aa rand-m9-mstd0.5 --remode pixel --reprob 0.2 --amp --lr .064 --lr-noise 0.42 0.9

ResNeXt-50 32x4d مع RandAugment - 79.762 top-1، 94.60 top-5

ستعمل هذه المعلمات أيضًا بشكل جيد مع SE-ResNeXt-50 وSK-ResNeXt-50 وعلى الأرجح مع 101. استخدمتها مع SK-ResNeXt-50 32x4d الذي درّبته باستخدام GPU واحد مع معدل تعلم أعلى قليلاً لكل حجم دفعة فعال (lr=0.18، b=192 لكل GPU). أوامر السطر أدناه مُعدّة للتدريب باستخدام 8 GPU.

./distributed_train.sh 8 --data-dir /imagenet --model resnext50_32x4d --lr 0.6 --warmup-epochs 5 --epochs 240 --weight-decay 1e-4 --sched cosine --reprob 0.4 --recount 3 --remode pixel --aa rand-m7-mstd0.5-inc1 -b 192 -j 6 --amp --dist-bn reduce