Model YAML Yapılandırma Kılavuzu

Model YAML yapılandırma dosyası, Ultralytics sinir ağları için mimari bir plan görevi görür. Katmanların nasıl bağlandığını, her modülün hangi parametreleri kullandığını ve tüm ağın farklı model boyutları genelinde nasıl ölçeklendiğini tanımlar.

Yapılandırma Yapısı

Model YAML dosyaları, mimariyi tanımlamak için birlikte çalışan üç ana bölümde düzenlenmiştir.

Parametreler Bölümü

parameters bölümü, modelin küresel ö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ı ayarlar.
• scales, farklı boyut varyantları (nano'dan ekstra-büyük boyuta kadar) üretmek için model derinliğini, genişliğini ve maksimum kanal sayısını ayarlayan bileşik ölçekleme faktörlerini tanımlar.
• kpt_shape applies to pose models. It can be [N, 2] for (x, y) keypoints or [N, 3] for (x, y, visibility).

Backbone (Omurga) ve Head (Baş) Mimarisi

Model mimarisi, backbone (özellik çıkarma) ve head (göreve özel) bölümlerinden oluşur:

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

Katman Belirleme Formatı

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

Bağlantı Desenleri

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

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

Modül Tekrarı

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ü ile çarpılır.

Kullanılabilir Modüller

Modüller işlevselliğe göre düzenlenmiş olup Ultralytics modüller dizininde tanımlanmıştır. Aşağıdaki tablolar, yaygın kullanılan modülleri kategoriye göre göstermektedir; kaynak kodunda çok daha fazlası mevcuttur:

Temel İşlemler

Kompozit Bloklar

Özelleştirilmiş Modüller

Gelişmiş Özellikler

TorchVision Entegrasyonu

TorchVision modülü, herhangi bir TorchVision modelinin backbone olarak sorunsuz entegrasyonunu sağlar:

from ultralytics import YOLO

# Model with ConvNeXt backbone
model = YOLO("convnext_backbone.yaml")
results = model.train(data="coco8.yaml", 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:

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ünürlük Sistemi

Ultralytics'in modülleri nasıl bulduğunu ve içe aktardığını anlamak, özelleştirme için ç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 "nn." in m else getattr(torchvision.ops, m[4:]) if "ops." in m else globals()[m]

1. PyTorch modülleri: 'nn.' ile başlayan isimler → torch.nn isim alanı
2. TorchVision işlemleri: 'ops.' ile başlayan isimler → torchvision.ops isim alanı
3. Ultralytics modülleri: Diğer tüm isimler → içe aktarmalar (imports) aracılığıyla global ad alanına (namespace)

Modül İçe Aktarma Zinciri

Standart modüller, tasks.py içindeki içe aktarmalarla 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 Kod Değişikliği

Kaynak kodu değiştirmek, özel modüllerini entegre etmenin en esnek yoludur ancak biraz karmaşık olabilir. Özel bir modül tanımlamak ve kullanmak için şu adımları izle:

1. Hızlı Başlangıç kılavuzundaki Git klonlama yöntemini kullanarak Ultralytics'i geliştirme modunda yükle.

2. Modülünü ultralytics/nn/modules/block.py içinde 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. Modülünü ultralytics/nn/modules/__init__.py içinde paket seviyesinde dışa aktar:

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

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

   from ultralytics.nn.modules import CustomBlock  # noqa

5. Handle special arguments (if needed) inside parse_model() in 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. Modülü model YAML dosyan içinde kullan:

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

7. İleri yönlü geçişin (forward pass) çalıştığından emin olmak için FLOPs değerini 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 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 (Backbone) 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]]
    - [-1, 1, nn.AdaptiveAvgPool2d, [1]]

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

En İyi Uygulamalar

Mimari Tasarım İpuçları

Basit Başla: Özelleştirme yapmadan önce kanıtlanmış mimarilerle başla. Sıfırdan inşa etmek 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 sonraki değişikliğe geçmeden önce her seferinde bir özel modül ekle ve ç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 bir sonraki katmanın giriş kanalları (c1) ile eşleşmelidir.

Atlama Bağlantıları (Skip Connections) Kullan: [[-1, N], 1, Concat, [1]] desenleriyle özellik yeniden kullanımından yararlan. Bu bağlantılar gradyan akışına yardımcı olur ve modelin farklı ölçeklerden gelen özellikleri birleştirmesini sağlar.

Uygun Şekilde Ölçeklendir: Hesaplama kısıtlamalarına göre model ölçeklerini seç. Uç cihazlar için nano (n), dengeli performans için küçük (s) ve maksimum doğruluk için daha büyük ölçekleri (m, l, x) kullan.

Performans Değerlendirmeleri

Derinlik ve Genişlik: Derin ağlar, çoklu dönüşüm katmanları aracılığıyla karmaşık hiyerarşik özellikleri yakalarken, geniş ağlar her katmanda paralel olarak daha fazla bilgiyi 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ğ genelinde özelliklerin yeniden kullanımını sağlar. Özellikle daha derin mimarilerde kaybolan gradyanları önlemek için önemlidirler.

Bottleneck Blokları: Model ifade yeteneğini korurken hesaplama maliyetini azaltır. C2f gibi modüller, standart evrişimlere (convolutions) göre daha az parametre kullanırken özellik öğrenme kapasitesini korur.

Çok Ölçekli Özellikler: Aynı görüntüdeki farklı boyutlardaki nesneleri tespit etmek için gereklidir. Farklı ölçeklerde birden fazla tespit başlığına sahip Özellik Piramidi Ağı (FPN) desenlerini 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 İçin Identity Head Kullan

Omurga sorunlarını izole etmek 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ı doğrudan incelemene olanak tanır:

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

Model Mimari İncelemesi

FLOPs sayısını kontrol etmek ve her katmanı yazdırmak, özel model yapılandırmanla ilgili sorunları gidermeye de yardımcı olabilir. Geçerli bir model için FLOPs sayısı sıfır olmamalıdır. Eğer sıfırsa, muhtemelen ileri yönlü geçişte bir sorun vardır. Basit bir ileri yönlü geçiş çalıştırmak, karşılaşılan tam hatayı gösterecektir.

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

Adım Adım Doğrulama

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

SSS

Modelimdeki sınıf sayısını nasıl değiştirebilirim?

YAML dosyanın en üstündeki nc parametresini, veri setindeki sınıf sayısıyla eşleşecek şekilde ayarla.

nc: 5 # 5 classes

Model YAML dosyamda özel bir omurga (backbone) kullanabilir miyim?

Evet. TorchVision omurgaları dahil olmak üzere desteklenen herhangi bir modülü kullanabilir veya kendi özel modülünü tanımlayıp Özel Modül Entegrasyonu bölümünde açıklandığı gibi içe aktarabilirsin.

Modelimi farklı boyutlar için (nano, small, medium vb.) nasıl ölçeklendirebilirim?

Derinlik, genişlik ve maksimum kanallar için ölçekleme faktörlerini tanımlamak üzere YAML dosyandaki scales bölümünü kullan. Temel YAML dosyasını, dosya adına ölçek eklenmiş şekilde (örneğin yolo26n.yaml) yüklediğinde model bunları otomatik olarak uygulayacaktır.

[from, repeats, module, args] formatı ne anlama geliyor?

Bu format, her katmanın nasıl oluşturulacağını belirtir:

• from: giriş kaynağı/kaynakları
• repeats: modülün kaç kez tekrarlanacağı
• module: katman türü
• args: modül için argümanlar

Kanal uyuşmazlığı hatalarını nasıl giderebilirim?

Bir katmanın çıkış kanallarının, bir sonrakinin beklenen giriş kanallarıyla eşleştiğini kontrol et. Modelinin mimarisini incelemek için print(model.model.model) kullan.

Mevcut modüllerin ve argümanlarının bir listesini nerede bulabilirim?

Mevcut tüm modüller ve argümanları için ultralytics/nn/modules dizinindeki kaynak koduna göz at.

YAML yapılandırmama nasıl özel bir modül eklerim?

Modülünü kaynak kodunda tanımla, Kaynak Kod Değişikliği bölümünde gösterildiği gibi içe aktar ve YAML dosyan içinde ismen referans ver.

Özel bir YAML ile önceden eğitilmiş ağırlıkları kullanabilir miyim?

Evet, önceden eğitilmiş bir kontrol noktasından (checkpoint) ağırlıkları yüklemek için model.load("path/to/weights") kullanabilirsin. Ancak, yalnızca eşleşen katmanlara ait ağırlıklar başarıyla yüklenecektir.

Model yapılandırmamı nasıl doğrularım?

FLOPs sayısının sıfır olup olmadığını kontrol etmek için model.info() kullan. Geçerli bir model, sıfır olmayan bir FLOPs sayısı göstermelidir. Eğer sıfırsa, sorunu bulmak için Hata Ayıklama İpuçları bölümündeki önerileri izle.