دليل إعدادات نموذج 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 تنطبق على نماذج الوضعية (pose). يمكن أن تكون [N, 2] لنقاط رئيسية (x, y) أو [N, 3] لـ (x, y, visibility).

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

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

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]] # 6: Upsample
    - [[-1, 2], 1, Concat, [1]] # 7: Skip connection
    - [-1, 3, C2f, [256]] # 8: Process features
    - [[8], 1, Detect, [nc]] # 9: 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="coco8.yaml", epochs=100)

وحدة الفهرس (Index) لاختيار الميزات#

عند استخدام النماذج التي تخرج خرائط ميزات متعددة، تقوم وحدة الفهرس باختيار مخرجات محددة:

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 "nn." in m
    else getattr(torchvision.ops, m[16:])
    if "torchvision.ops." in m
    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,
    # ... 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. تعامل مع الوسائط الخاصة (إذا لزم الأمر) داخل parse_model() في ultralytics/nn/tasks.py:

   # Add this condition in the parse_model() function
   if m is CustomBlock:
       c1, c2 = ch[f], args[0]  # input channels, output channels
       args = [c1, c2, *args[1:]]

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]]
    - [-1, 1, nn.AdaptiveAvgPool2d, [1]]

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

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

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

ابدأ ببساطة: ابدأ ببنيات أثبتت كفاءتها قبل التخصيص. استخدم تكوينات 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")
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", 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)

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

كيف يمكنني تغيير عدد الفئات في نموذجي؟#

اضبط معلمة nc في أعلى ملف YAML الخاص بك لتتوافق مع عدد الفئات في مجموعة البيانات الخاصة بك.

nc: 5 # 5 classes

هل يمكنني استخدام عمود فقري مخصص في ملف YAML الخاص بنموذجي؟#

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

كيف يمكنني تحجيم نموذجي لأحجام مختلفة (نانو، صغير، متوسط، إلخ)؟#

استخدم قسم scales في ملف YAML الخاص بك لتحديد عوامل التحجيم للعمق والعرض والحد الأقصى للقنوات. سيقوم النموذج بتطبيق هذه العوامل تلقائياً عند تحميل ملف YAML الأساسي مع إلحاق الحجم باسم الملف (على سبيل المثال، yolo26n.yaml).

ماذا يعني تنسيق [from, repeats, module, args]؟#

يحدد هذا التنسيق كيفية بناء كل طبقة:

• from: مصدر الإدخال
• repeats: عدد مرات تكرار الوحدة
• module: نوع الطبقة
• args: وسائط الوحدة

كيف يمكنني استكشاف أخطاء عدم تطابق القناة وإصلاحها؟#

تحقق من أن قنوات إخراج طبقة واحدة تتطابق مع قنوات الإدخال المتوقعة للطبقة التالية. استخدم print(model.model.model) لفحص بنية نموذجك.

أين يمكنني العثور على قائمة بالوحدات المتاحة ووسائطها؟#

تحقق من الكود المصدري في دليل ultralytics/nn/modules للحصول على جميع الوحدات المتاحة ووسائطها.

كيف يمكنني إضافة وحدة مخصصة إلى تكوين YAML الخاص بي؟#

عرف وحدتك في الكود المصدري، وقم باستيرادها كما هو موضح في تعديل الكود المصدري، وأشر إليها بالاسم في ملف YAML الخاص بك.

هل يمكنني استخدام الأوزان المدربة مسبقاً مع ملف YAML مخصص؟#

نعم، يمكنك استخدام model.load("path/to/weights") لتحميل الأوزان من نقطة فحص مدربة مسبقاً. ومع ذلك، سيتم تحميل أوزان الطبقات التي تتطابق فقط بنجاح.

كيف يمكنني التحقق من صحة تكوين نموذجي؟#

استخدم model.info() للتحقق مما إذا كان عدد FLOPs غير صفري. يجب أن يُظهر النموذج الصالح عدداً غير صفري من FLOPs. إذا كان صفراً، فاتبع الاقتراحات في نصائح التصحيح للعثور على المشكلة.