دليل تكوين YAML للنموذج#

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

بنية التكوين#

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

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

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

# 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

# Model with ConvNeXt backbone
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:

# Core resolution logic
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]
)  # get module

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,
    # ... many more modules
    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(
       {
           # Existing modules...
           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()  # should print non-zero FLOPs if working

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

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

# 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]]. تساعد هذه الوصلات على تدفق التدرجات، وتتيح للنموذج دمج الميزات من مقاييس مختلفة.

وسّع النطاق على نحو مناسب: اختر مقاييس النموذج استنادًا إلى قيودك الحسابية. استخدم المقياس النانوي (n) للأجهزة الطرفية، والصغير (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)

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