دليل إعدادات YAML للنموذج#

يُعد ملف إعدادات YAML للنموذج المخطط المعماري للشبكات العصبية من Ultralytics. ويحدد كيفية اتصال الطبقات، والمعلمات التي تستخدمها كل وحدة، وكيفية تحجيم الشبكة بالكامل لتناسب أحجام النماذج المختلفة.

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

تُنظَّم ملفات YAML للنموذج في ثلاثة أقسام رئيسية تعمل معًا لتحديد البنية.

قسم المعلمات#

يحدد قسم parameters الخصائص العامة للنموذج وسلوكه عند التحجيم:

# Parameters
nc: 80 # number of classes
scales: # compound scaling constants [depth, width, max_channels]
    n: [0.50, 0.25, 1024] # nano: shallow layers, narrow channels
    s: [0.50, 0.50, 1024] # small: shallow depth, standard width
    m: [0.50, 1.00, 512] # medium: moderate depth, full width
    l: [1.00, 1.00, 512] # large: full depth and width
    x: [1.00, 1.50, 512] # extra-large: maximum performance
kpt_shape: [17, 3] # pose models only

• يحدد nc عدد الفئات التي يتنبأ بها النموذج.
• يحدد scales عوامل التحجيم المركب التي تضبط عمق النموذج وعرضه والحد الأقصى للقنوات لإنتاج متغيرات بأحجام مختلفة (من النانوي إلى الكبير جدًا).
• ينطبق kpt_shape على نماذج تقدير الوضعيات. ويمكن أن يكون [N, 2] لـ (x, y) من النقاط المفتاحية أو [N, 3] لـ (x, y, visibility).

بنية العمود الفقري والرأس#

تتكون بنية النموذج من قسمي العمود الفقري (استخراج الميزات) والرأس (المخصص للمهمة):

nc: 80

backbone:
    # [from, repeats, module, args]
    - [-1, 1, Conv, [64, 3, 2]] # 0: Initial convolution
    - [-1, 1, Conv, [128, 3, 2]] # 1: Downsample
    - [-1, 3, C2f, [128, True]] # 2: Feature processing

head:
    - [-1, 1, nn.Upsample, [None, 2, nearest]] # 3: Upsample
    - [[-1, 0], 1, Concat, [1]] # 4: Spatially compatible skip connection
    - [-1, 3, C2f, [256]] # 5: Process features
    - [[5], 1, Detect, [nc]] # 6: Detection layer

تستمر فهارس الطبقات عبر العمود الفقري والرأس، ويجب أن تتطابق الأبعاد المكانية لخرائط الميزات التي تُدمج.

تنسيق مواصفات الطبقة#

تتبع كل طبقة النمط الموحد التالي: [from, repeats, module, args]

أنماط الاتصال#

ينشئ الحقل from أنماطًا مرنة لتدفق البيانات في شبكتك:

- [-1, 1, Conv, [64, 3, 2]]    # Takes input from previous layer

تكرار الوحدة#

تنشئ المعلمة repeats أقسامًا أعمق في الشبكة:

- [-1, 3, C2f, [128, True]] # Creates 3 consecutive C2f blocks
- [-1, 1, Conv, [64, 3, 2]] # Single convolution layer

يُضرب عدد مرات التكرار الفعلي في عامل تحجيم العمق المحدد في إعدادات حجم النموذج.

الوحدات المتاحة#

تُنظَّم الوحدات بحسب وظائفها وتُعرَّف في دليل وحدات Ultralytics. تعرض الجداول التالية وحدات شائعة الاستخدام حسب الفئة، ويتوفر الكثير غيرها في الشيفرة المصدرية:

العمليات الأساسية#

الكتل المركبة#

الوحدات المتخصصة#

الميزات المتقدمة#

التكامل مع TorchVision#

تتيح وحدة TorchVision دمج أي نموذج TorchVision بسلاسة بوصفه عمودًا فقريًا:

from ultralytics import YOLO

# ⁨نموذج بعمود فقري ConvNeXt⁩
model = YOLO("convnext_backbone.yaml")
results = model.train(data="imagenet10", epochs=100)

وحدة Index لاختيار الميزات#

عند استخدام نماذج تُخرج خرائط ميزات متعددة، تختار وحدة Index مخرجات محددة:

nc: 80

backbone:
    - [-1, 1, TorchVision, [768, convnext_tiny, DEFAULT, True, 2, True]] # Multi-output
head:
    - [0, 1, Index, [192, 4]] # Select 4th feature map (192 channels)
    - [0, 1, Index, [384, 6]] # Select 6th feature map (384 channels)
    - [0, 1, Index, [768, 8]] # Select 8th feature map (768 channels)
    - [[1, 2, 3], 1, Detect, [nc]] # Multi-scale detection

نظام تحديد الوحدات#

يُعد فهم كيفية تحديد Ultralytics لمواقع الوحدات واستيرادها أمرًا أساسيًا للتخصيص:

آلية البحث عن الوحدات#

يستخدم Ultralytics نظامًا من ثلاث طبقات في parse_model:

# ⁨منطق تحديد الوحدات الأساسي⁩
m = (
    getattr(torch.nn, m[3:])
    if m.startswith("nn.")
    else getattr(__import__("torchvision").ops, m[16:])
    if m.startswith("torchvision.ops.")
    else globals()[m]
)  # ⁨الحصول على الوحدة⁩

1. وحدات PyTorch: الأسماء التي تبدأ بـ 'nn.' ← مساحة الأسماء torch.nn
2. عمليات TorchVision: الأسماء التي تبدأ بـ 'torchvision.ops.' ← مساحة الأسماء torchvision.ops
3. وحدات Ultralytics: جميع الأسماء الأخرى ← المساحة العامة عبر عمليات الاستيراد

سلسلة استيراد الوحدات#

تصبح الوحدات القياسية متاحة عبر عمليات الاستيراد في tasks.py:

from ultralytics.nn.modules import (  # noqa: F401
    SPPF,
    C2f,
    Conv,
    Detect,
    # ⁨... وحدات كثيرة أخرى⁩
    Index,
    TorchVision,
)

دمج الوحدات المخصصة#

تعديل الشيفرة المصدرية#

يُعد تعديل الشيفرة المصدرية الطريقة الأكثر مرونة لدمج وحداتك المخصصة، لكنه قد يكون صعبًا. لتعريف وحدة مخصصة واستخدامها، اتبع الخطوات التالية:

1. ثبّت Ultralytics في وضع التطوير باستخدام طريقة استنساخ Git الواردة في دليل البدء السريع.

2. عرّف وحدتك في ultralytics/nn/modules/block.py:

   class CustomBlock(nn.Module):
       """Custom block with Conv-BatchNorm-ReLU sequence."""
   
       def __init__(self, c1, c2):
           """Initialize CustomBlock with input and output channels."""
           super().__init__()
           self.layers = nn.Sequential(nn.Conv2d(c1, c2, 3, 1, 1), nn.BatchNorm2d(c2), nn.ReLU())
   
       def forward(self, x):
           """Forward pass through the block."""
           return self.layers(x)

3. اجعل وحدتك متاحة على مستوى الحزمة في ultralytics/nn/modules/__init__.py:

   from .block import CustomBlock  # noqa makes CustomBlock available as ultralytics.nn.modules.CustomBlock

4. أضف عمليات الاستيراد في ultralytics/nn/tasks.py:

   from ultralytics.nn.modules import CustomBlock  # noqa

5. أضف الوحدة إلى base_modules داخل parse_model(). تحصل الوحدات في هذه المجموعة تلقائيًا على قنوات الإدخال والإخراج:

   base_modules = frozenset(
       {
           # ⁨الوحدات الحالية...⁩
           CustomBlock,
       }
   )

6. استخدم الوحدة في ملف YAML للنموذج:

   # custom_model.yaml
   nc: 1
   backbone:
       - [-1, 1, CustomBlock, [64]]
   head:
       - [-1, 1, Classify, [nc]]

7. تحقق من FLOPs للتأكد من عمل المرور الأمامي:

   from ultralytics import YOLO
   
   model = YOLO("custom_model.yaml", task="classify")
   model.info()  # ⁨ينبغي أن يطبع قيمة FLOPs غير صفرية إذا كان يعمل⁩

أمثلة على الإعدادات#

نموذج كشف أساسي#

# Simple YOLO detection model
nc: 80
scales:
    n: [0.33, 0.25, 1024]

backbone:
    - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2
    - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4
    - [-1, 3, C2f, [128, True]] # 2
    - [-1, 1, Conv, [256, 3, 2]] # 3-P3/8
    - [-1, 6, C2f, [256, True]] # 4
    - [-1, 1, SPPF, [256, 5]] # 5

head:
    - [-1, 1, Conv, [256, 3, 1]] # 6
    - [[6], 1, Detect, [nc]] # 7

نموذج ذو عمود فقري من TorchVision#

# ConvNeXt backbone with YOLO head
nc: 80

backbone:
    - [-1, 1, TorchVision, [768, convnext_tiny, DEFAULT, True, 2, True]]

head:
    - [0, 1, Index, [192, 4]] # P3 features
    - [0, 1, Index, [384, 6]] # P4 features
    - [0, 1, Index, [768, 8]] # P5 features
    - [[1, 2, 3], 1, Detect, [nc]] # Multi-scale detection

نموذج تصنيف#

# Simple classification model
nc: 1000

backbone:
    - [-1, 1, Conv, [64, 7, 2, 3]]
    - [-1, 1, nn.MaxPool2d, [3, 2, 1]]
    - [-1, 4, C2f, [64, True]]
    - [-1, 1, Conv, [128, 3, 2]]
    - [-1, 8, C2f, [128, True]]

head:
    - [-1, 1, Classify, [nc]]

يجري Classify بالفعل تجميعًا متوسطًا تكيفيًا داخليًا.

أفضل الممارسات#

نصائح لتصميم البنية#

ابدأ ببساطة: ابدأ بالبنى المثبتة قبل تخصيصها. استخدم إعدادات YOLO الحالية كقوالب، وأجرِ التعديلات تدريجيًا بدلًا من البناء من الصفر.

اختبر تدريجيًا: تحقّق من صحة كل تعديل خطوةً بخطوة. أضف وحدة مخصصة واحدة في كل مرة، وتأكد من عملها قبل الانتقال إلى التغيير التالي.

راقب القنوات: تأكد من تطابق أبعاد القنوات بين الطبقات المتصلة. يجب أن تطابق قنوات الإخراج (c2) لإحدى الطبقات قنوات الإدخال (c1) للطبقة التالية في التسلسل.

استخدم الوصلات التخطيّة: استفد من إعادة استخدام السمات باستخدام أنماط [[-1, N], 1, Concat, [1]]. تساعد هذه الوصلات على تدفق التدرجات، وتمكّن النموذج من دمج السمات من مقاييس مختلفة.

اختر المقياس المناسب: اختر مقاييس النموذج استنادًا إلى قيودك الحسابية. استخدم مقياس nano (n) للأجهزة الطرفية، وsmall (s) لتحقيق أداء متوازن، والمقاييس الأكبر (m، l، x) لتحقيق أقصى دقة.

اعتبارات الأداء#

العمق مقابل العرض: تستخرج الشبكات العميقة سمات هرمية معقدة عبر طبقات تحويل متعددة، بينما تعالج الشبكات العريضة معلومات أكثر بالتوازي في كل طبقة. وازن بينهما وفقًا لتعقيد مهمتك.

الوصلات التخطيّة: تحسّن تدفق التدرجات أثناء التدريب، وتتيح إعادة استخدام السمات في جميع أنحاء الشبكة. وهي مهمة بوجه خاص في البنى الأعمق لمنع تلاشي التدرجات.

كتل عنق الزجاجة: تقلل التكلفة الحسابية مع الحفاظ على قدرة النموذج التعبيرية. تستخدم وحدات مثل C2f معلمات أقل من الالتفافات القياسية، مع الحفاظ على قدرة تعلم السمات.

السمات متعددة المقاييس: ضرورية لكشف الكائنات ذات الأحجام المختلفة في الصورة نفسها. استخدم أنماط شبكة هرم السمات (FPN) مع رؤوس كشف متعددة بمقاييس مختلفة.

استكشاف الأخطاء وإصلاحها#

المشكلات الشائعة#

نصائح لتصحيح الأخطاء#

عند تطوير بنى مخصصة، يساعد التصحيح المنهجي على اكتشاف المشكلات مبكرًا:

استخدم رأس الهوية للاختبار

استبدل الرؤوس المعقدة بـ nn.Identity لعزل مشكلات العمود الفقري:

nc: 1
backbone:
    - [-1, 1, CustomBlock, [64]]
head:
    - [-1, 1, nn.Identity, []] # Pass-through for debugging

يتيح ذلك فحص مخرجات العمود الفقري مباشرةً:

import torch

from ultralytics import YOLO

model = YOLO("debug_model.yaml", task="detect")
output = model.model(torch.randn(1, 3, 640, 640))
print(f"Output shape: {output.shape}")  # Should match expected dimensions

فحص بنية النموذج

يمكن أن يساعد التحقق من عدد FLOPs وطباعة كل طبقة أيضًا في تصحيح المشكلات في إعداد النموذج المخصص. ينبغي أن يكون عدد FLOPs غير صفري للنموذج الصالح. إذا كان صفرًا، فمن المرجح وجود مشكلة في المرور الأمامي. ينبغي أن يكشف تنفيذ مرور أمامي بسيط عن الخطأ المحدد الذي يحدث.

from ultralytics import YOLO

# Build model with verbose output to see layer details
model = YOLO("debug_model.yaml", task="detect", verbose=True)

# Check model FLOPs. Failed forward pass causes 0 FLOPs.
model.info()

# Inspect individual layers
for i, layer in enumerate(model.model.model):
    print(f"Layer {i}: {layer}")

التحقق خطوةً بخطوة

1. ابدأ بأبسط ما يمكن: اختبر أولًا أبسط بنية ممكنة
2. أضف تدريجيًا: ابنِ التعقيد طبقةً تلو الأخرى
3. تحقّق من الأبعاد: تأكد من توافق القنوات والأبعاد المكانية
4. تحقّق من القياس: اختبر مقاييس نموذج مختلفة (n، s، m)

الأسئلة الشائعة#