Model YAML Yapılandırma Kılavuzu#

Model YAML yapılandırma dosyası, Ultralytics sinir ağlarının mimari taslağıdır. Katmanların nasıl bağlandığını, her modülün hangi parametreleri kullandığını ve ağın farklı model boyutlarına nasıl ölçeklendiğini tanımlar.

Yapılandırma Yapısı#

Model YAML dosyaları, mimariyi tanımlamak üzere birlikte çalışan üç ana bölümden oluşur.

Parametreler Bölümü#

parameters bölümü, modelin genel özelliklerini ve ölçeklendirme 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ı boyutlardaki varyantları (nano'dan ekstra büyüğe) oluşturmak için model derinliğini, genişliğini ve maksimum kanal sayısını ayarlayan bileşik ölçeklendirme katsayılarını tanımlar.
• kpt_shape, pose modelleri için geçerlidir. (x, y) anahtar noktası için [N, 2] veya (x, y, visibility) için [N, 3] olabilir.

Backbone ve Head Mimarisi#

Model mimarisi, backbone (özellik çıkarımı) ve head (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 backbone ve head boyunca devam eder; birleştirilen özellik haritalarının uzamsal boyutları eşleşmelidir.

Katman Belirtim Biçimi#

Her katman tutarlı bir deseni izler: [from, repeats, module, args]

Bağlantı Desenleri#

from alanı, ağın genelinde esnek veri akışı desenleri oluşturur:

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

Modül Tekrarı#

repeats parametresi, ağın daha derin bölümlerini 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çeklendirme katsayısıyla çarpılır.

Kullanılabilir Modüller#

Modüller işlevlerine göre düzenlenir ve Ultralytics modülleri dizininde tanımlanır. Aşağıdaki tablolarda, kategoriye göre sık kullanılan modüller gösterilmiştir; kaynak kodda çok daha fazlası bulunur:

Temel İşlemler#

Bileşik Bloklar#

Özelleştirilmiş Modüller#

Gelişmiş Özellikler#

TorchVision Entegrasyonu#

TorchVision modülü, herhangi bir TorchVision modelinin backbone olarak sorunsuzca entegre edilmesini sağlar:

from ultralytics import YOLO

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

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

Birden fazla özellik haritası çıktısı veren 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#

Ultralytics'in modülleri nasıl bulup içe aktardığını anlamak, özelleştirme için kritik önem taşır:

Modül Arama Süreci#

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

# Temel çözümleme mantığı
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]
)  # modülü al

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 genel ad alanı

Modül İçe Aktarma Zinciri#

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

from ultralytics.nn.modules import (  # noqa: F401
    SPPF,
    C2f,
    Conv,
    Detect,
    # ... daha birçok modül
    Index,
    TorchVision,
)

Özel Modül Entegrasyonu#

Kaynak Kodunu Değiştirme#

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

1. Hızlı Başlangıç kılavuzundaki 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(
       {
           # Mevcut modüller...
           CustomBlock,
       }
   )

6. Model YAML dosyanda 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 FLOP sayısını kontrol et:

   from ultralytics import YOLO
   
   model = YOLO("custom_model.yaml", task="classify")
   model.info()  # çalışıyorsa sıfırdan büyük FLOP sayısı yazdırmalı

Örnek Yapılandırmalar#

Temel Tespit 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 zaten kendi içinde uyarlamalı ortalama havuzlama uygular.

En İyi Uygulamalar#

Mimari Tasarımı İpuçları#

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

Adım Adım Test Et: Her değişikliği adım adım doğrula. Her seferinde bir özel modül ekle ve sonraki değişikliğe geçmeden önce ç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 çıktı kanalları (c2), dizideki sonraki katmanın girdi kanallarıyla (c1) eşleşmelidir.

Atlama Bağlantılarını 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: Hesaplama kısıtlarına göre model ölçeklerini seç. Uç cihazlar için nano (n), dengeli performans için small (s), en yüksek doğruluk içinse daha büyük ölçekleri (m, l, x) kullan.

Performansla İlgili Hususlar#

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

Atlama Bağlantıları: Eğitim sırasında gradyan akışını iyileştirir ve ağ boyunca özelliklerin yeniden kullanılmasını sağlar. Gradyanların kaybolmasını önlemek için özellikle derin mimarilerde önemlidir.

Darboğaz Blokları: Modelin ifade gücünü korurken hesaplama maliyetini azaltır. C2f gibi modüller, özellik öğrenme kapasitesini koruyarak 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 tespit başlığı içeren Özellik Piramidi Ağı (FPN) kalıplarını kullan.

Sorun Giderme#

Sık Karşılaşılan Sorunlar#

Hata Ayıklama İpuçları#

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

Test için Kimlik Başlığı 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, özel model yapılandırmandaki sorunları ayıklamaya da yardımcı olabilir. Geçerli bir modelin FLOPs sayısı sıfırdan büyük 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. En basitinden başla: Önce mümkün olan en basit mimariyi test et
2. Adım adım ekle: Karmaşıklığı katman katman artır
3. Boyutları kontrol et: Kanal ve uzamsal boyutların uyumluluğunu doğrula
4. Ölçeklendirmeyi doğrula: Farklı model ölçekleriyle test et (n, s, m)

Sık Sorulan Sorular#