Model YAML Yapılandırma Kılavuzu#

Model YAML yapılandırma dosyası, Ultralytics sinir ağlarının mimari planı olarak görev yapar. Katmanların nasıl bağlandığını, her modülün hangi parametreleri kullandığını ve ağın tamamının farklı model boyutlarına göre nasıl ölçeklendirildiğini tanımlar.

Yapılandırma Yapısı#

Model YAML dosyaları, mimariyi tanımlamak üzere birlikte çalışan üç ana bölüm halinde düzenlenir.

Parametreler Bölümü#

parameters bölümü, modelin genel özelliklerini ve ölçekleme davranışını belirtir:

# 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, modelin tahmin ettiği sınıf sayısını belirler.
• scales, farklı boyut varyantları (nano ile ekstra büyük arasında) üretmek üzere model derinliğini, genişliğini ve maksimum kanal sayısını ayarlayan bileşik ölçekleme faktörlerini tanımlar.
• kpt_shape, pose modelleri için geçerlidir. (x, y) anahtar noktaları için [N, 2] veya (x, y, visibility) için [N, 3] olabilir.

Omurga ve Başlık Mimarisi#

Model mimarisi, omurga (özellik çıkarma) ve başlık (göreve özgü) bölümlerinden oluşur:

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

Katman indeksleri omurga ve başlık boyunca devam eder ve birleştirilen özellik haritalarının uzamsal boyutları eşleşmelidir.

Katman Belirtim Biçimi#

Her katman tutarlı şu kalıbı izler: [from, repeats, module, args]

Bağlantı Kalıpları#

from alanı, ağının tamamında esnek veri akışı kalıpları oluşturur:

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

Modül Tekrarlama#

repeats parametresi daha derin ağ bölümleri oluşturur:

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

Gerçek tekrar sayısı, model boyutu yapılandırmandaki derinlik ölçekleme faktörüyle çarpılır.

Kullanılabilir Modüller#

Modüller işlevlerine göre düzenlenir ve Ultralytics modules directory içinde tanımlanır. Aşağıdaki tablolar, kategoriye göre sık kullanılan modülleri gösterir; kaynak kodunda çok daha fazlası bulunur:

Temel İşlemler#

Birleşik Bloklar#

Özelleştirilmiş Modüller#

Gelişmiş Özellikler#

TorchVision Entegrasyonu#

TorchVision modülü, herhangi bir TorchVision modelinin omurga olarak sorunsuz şekilde entegre edilmesini sağlar:

from ultralytics import YOLO

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

Özellik Seçimi için Index Modülü#

Birden fazla özellik haritası üreten modelleri kullanırken Index modülü belirli çıktıları seçer:

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

Modül Çözümleme Sistemi#

Özelleştirme için Ultralytics'in modülleri nasıl bulup içe aktardığını anlamak çok önemlidir:

Modül Arama Süreci#

Ultralytics, parse_model içinde üç katmanlı bir sistem kullanır:

# 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 modülleri: 'nn.' ile başlayan adlar → torch.nn ad alanı
2. TorchVision işlemleri: 'torchvision.ops.' ile başlayan adlar → torchvision.ops ad alanı
3. Ultralytics modülleri: Diğer tüm adlar → içe aktarmalar aracılığıyla global ad alanı

Modül İçe Aktarma Zinciri#

Standart modüller, tasks.py içindeki içe aktarmalar aracılığıyla kullanılabilir hale gelir:

from ultralytics.nn.modules import (  # noqa: F401
    SPPF,
    C2f,
    Conv,
    Detect,
    # ... many more modules
    Index,
    TorchVision,
)

Özel Modül Entegrasyonu#

Kaynak Kodu Değişikliği#

Kaynak kodunu değiştirmek, özel modüllerini entegre etmenin en esnek yoludur; ancak bu işlem zor olabilir. Özel bir modül tanımlamak ve kullanmak için şu adımları izle:

1. Quickstart guide içindeki Git clone yöntemini kullanarak Ultralytics'i geliştirme modunda yükle.

2. ultralytics/nn/modules/block.py içinde modülünü tanımla:

   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 içinde modülünü paket düzeyinde dışa aç:

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

4. ultralytics/nn/tasks.py içinde içe aktarmalara ekle:

   from ultralytics.nn.modules import CustomBlock  # noqa

5. parse_model() içindeki base_modules öğesine modülü ekle. Bu kümedeki modüller, girdi ve çıktı kanallarını otomatik olarak alır:

   base_modules = frozenset(
       {
           # Existing modules...
           CustomBlock,
       }
   )

6. Model YAML'ında modülü kullan:

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

7. İleri geçişin çalıştığından emin olmak için FLOPs'u kontrol et:

   from ultralytics import YOLO
   
   model = YOLO("custom_model.yaml", task="classify")
   model.info()  # should print non-zero FLOPs if working

Örnek Yapılandırmalar#

Temel Algılama Modeli#

# 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 Omurga Modeli#

# 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

Sınıflandırma Modeli#

# 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, uyarlamalı ortalama havuzlamayı zaten dahili olarak gerçekleştirir.

En İyi Uygulamalar#

Mimari Tasarım İpuçları#

Basit Başla: Özelleştirmeye geçmeden önce kendini kanıtlamış mimarilerle başla. Sıfırdan oluşturmak yerine mevcut YOLO yapılandırmalarını şablon olarak kullan ve aşamalı olarak değiştir.

Aşamalı Test Et: Her değişikliği adım adım doğrula. Bir seferde tek bir özel modül ekle ve sonraki değişikliğe geçmeden önce düzgün çalıştığını doğrula.

Kanalları İzle: Bağlı katmanlar arasındaki kanal boyutlarının eşleştiğinden emin ol. Bir katmanın çıkış kanalları (c2), dizideki sonraki katmanın giriş kanallarıyla (c1) eşleşmelidir.

Atlamalı Bağlantıları Kullan: [[-1, N], 1, Concat, [1]] kalıplarıyla özelliklerin yeniden kullanımından yararlan. Bu bağlantılar gradyan akışına yardımcı olur ve modelin farklı ölçeklerdeki özellikleri birleştirmesini sağlar.

Uygun Ölçeklendir: Model ölçeklerini hesaplama kısıtlarına göre seç. Uç cihazlar için nano (n), dengeli performans için small (s) ve en yüksek doğruluk için daha büyük ölçekleri (m, l, x) kullan.

Performansla İlgili Hususlar#

Derinlik ve Genişlik: Derin ağlar, birden fazla dönüşüm katmanı aracılığıyla karmaşık hiyerarşik özellikleri yakalarken geniş ağlar her katmanda daha fazla bilgiyi paralel olarak işler. Bunları görevin karmaşıklığına göre dengele.

Atlamalı Bağlantılar: Eğitim sırasında gradyan akışını iyileştirir ve ağ genelinde özelliklerin yeniden kullanılmasını sağlar. Kaybolan gradyanları önlemek için özellikle daha derin mimarilerde önemlidir.

Darboğaz Blokları: Modelin ifade gücünü korurken hesaplama maliyetini azaltır. C2f gibi modüller, özellik öğrenme kapasitesini korurken standart evrişimlerden daha az parametre kullanır.

Çok Ölçekli Özellikler: Aynı görüntüde farklı boyutlardaki nesneleri tespit etmek için gereklidir. Farklı ölçeklerde birden fazla algılama başlığıyla Özellik Piramidi Ağı (FPN) kalıplarını kullan.

Sorun Giderme#

Yaygın Sorunlar#

Hata Ayıklama İpuçları#

Özel mimariler geliştirirken sistematik hata ayıklama, sorunları erken belirlemene yardımcı olur:

Test için Identity Head Kullan

Omurga sorunlarını yalıtmak için karmaşık başlıkları nn.Identity ile değiştir:

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

Bu, omurga çıktılarının doğrudan incelenmesini sağlar:

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

Model Mimarisi İncelemesi

FLOPs sayısını kontrol etmek ve her katmanı yazdırmak da özel model yapılandırmandaki sorunların hata ayıklamasına yardımcı olabilir. Geçerli bir model için FLOPs sayısı sıfırdan farklı olmalıdır. Sıfırsa ileri geçişte muhtemelen bir sorun vardır. Basit bir ileri geçiş çalıştırmak, karşılaşılan hatayı tam olarak göstermelidir.

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}")

Adım Adım Doğrulama

1. Minimum düzeyde başla: Önce mümkün olan en basit mimariyle test et
2. Aşamalı olarak ekle: Karmaşıklığı katman katman oluştur
3. Boyutları kontrol et: Kanal ve uzamsal boyut uyumluluğunu doğrula
4. Ölçeklendirmeyi doğrula: Farklı model ölçekleriyle (n, s, m) test et

SSS#