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

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

هيكل الإعدادات#

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

قسم المعاملات (Parameters)#

يحدد قسم 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).

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

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

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 كعنصر أساسي (backbone):

from ultralytics import YOLO

# Model with ConvNeXt backbone
model = YOLO("convnext_backbone.yaml")
results = model.train(data="imagenet10", epochs=100)

وحدة الفهرس (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

نموذج العمود الفقري (Backbone) لـ 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) للطبقة التالية في التسلسل.

استخدام الاتصالات التخطيّة (Skip Connections): استتفد من إعادة استخدام الميزات باستخدام أنماط [[-1, N], 1, Concat, [1]]. تساعد هذه الاتصالات في تدفق التدرج وتسمح للنموذج بدمج الميزات من مقاييس مختلفة.

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

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

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

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

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

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

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

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

نصائح التصحيح#

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

استخدم رأس الهوية (Identity Head) للاختبار

استبدل الرؤوس المعقدة بـ 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)

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