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

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

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

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

- [[-1, 6], 1, Concat, [1]]    # Combines current layer with layer 6

- [[4, 6, 8], 1, Detect, [nc]] # Detection head using 3 feature scales

تكرار الوحدة النمطية

في 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)

backbone:
  - [-1, 1, TorchVision, [768, convnext_tiny, DEFAULT, True, 2, False]]
head:
  - [-1, 1, Classify, [nc]]

وحدة الفهرس لاختيار الميزات

عند استخدام النماذج التي تنتج خرائط ميزات متعددة، تحدد وحدة الفهرس (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[4:]) if "ops." in m else globals()[m]

1. وحدات PyTorch: الأسماء التي تبدأ بـ 'nn.' → torch.nn مساحة الاسم
2. عمليات 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
   

أمثلة على التكوينات

نموذج الـ detect الأساسي

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

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

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

نصائح لتصميم الهيكلة

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

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

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

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

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

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

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

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

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

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

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

مشكلات شائعة

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

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

استخدم 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 backbones، أو تحديد الوحدة المخصصة الخاصة بك واستيرادها كما هو موضح في Custom Module Integration.

كيف يمكنني توسيع نطاق النموذج الخاص بي لأحجام مختلفة (nano ، small ، medium ، إلخ)؟

استخدم scales القسم في ملف YAML الخاص بك لتحديد عوامل القياس للعمق والعرض والحد الأقصى للقنوات. سيقوم النموذج بتطبيقها تلقائيًا عند تحميل ملف YAML الأساسي مع المقياس الملحق باسم الملف (على سبيل المثال، yolo11n.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 غير صفري. إذا كان صفراً، فاتبع الاقتراحات في نصائح لتصحيح الأخطاء للعثور على المشكلة.

📅 تم إنشاؤها منذ 2 شهر مضى ✏️ تم التحديث منذ 1 شهر

تعليقات