Model YAML Yapılandırma Kılavuzu#

Model YAML yapılandırma dosyası, Ultralytics sinir ağları için mimari 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üme ayrılmıştır.

Parametreler Bölümü#

parameters bölümü, modelin küresel ö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ı boyut varyantları (nanodan çok büyüğe kadar) üretmek için model derinliğini, genişliğini ve maksimum kanalları ayarlayan bileşik ölçekleme faktörlerini tanımlar.
• kpt_shape poz modellerine uygulanır. (x, y) eklemleri için [N, 2] veya (x, y, visibility) için [N, 3] olabilir.

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 Belirtme Formatı#

Her katman şu tutarlı deseni takip eder: [from, repeats, module, args]

Bağlantı Desenleri#

from alanı, ağınız boyunca esnek veri akışı kalıpları 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ırmandan gelen derinlik ölçeklendirme faktörü ile çarpılır.

Kullanılabilir Modüller#

Modüller işlevselliklerine göre düzenlenir ve Ultralytics modules directory içinde tanımlanır. Aşağıdaki tablolar, yaygın olarak kullanılan modülleri kategoriye göre göstermektedir ve kaynak kodunda çok daha fazlası mevcuttur:

Temel İşlemler#

Kompozit Bloklar#

Uzmanlaşmış Modüller#

Gelişmiş Özellikler#

TorchVision Entegrasyonu#

TorchVision modülü, herhangi bir TorchVision model modelinin omurga olarak sorunsuz bir şekilde entegre edilmesini 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ı çıkaran modeller 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[16:])
    if "torchvision.ops." in m
    else globals()[m]
)

1. PyTorch modules: 'nn.' ile başlayan isimler → torch.nn ad alanı
2. TorchVision operations: 'torchvision.ops.' ile başlayan isimler → torchvision.ops ad alanı
3. Ultralytics modülleri: Diğer tüm isimler → içe aktarmalar (imports) aracılığıyla genel isim 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 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ımlayıp kullanmak için şu adımları izle:

1. Quickstart guide kılavuzundaki Git klonlama yöntemini kullanarak Ultralytics'i geliştirme modunda yükleyin.

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

   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üzü paket düzeyinde açığa çıkarın:

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

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

   from ultralytics.nn.modules import CustomBlock  # noqa

5. ultralytics/nn/tasks.py içindeki parse_model() içinde özel argümanları yönet (gerekirse):

   # 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 geçişin (forward pass) çalıştığından emin olmak için FLOPs değerlerini 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 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ştirmeye başlamadan önce kanıtlanmış mimarilerle başla. Mevcut YOLO yapılandırmalarını şablon olarak kullan ve sıfırdan oluşturmak yerine kademeli olarak değişiklik yap.

Kademeli Test Et: Her değişiklik adımını doğrula. Bir sonraki değişikliğe geçmeden önce her seferinde tek bir özel modül ekle ve çalıştığını doğrula.

Kanalları İzleyin: Bağlı katmanlar arasında kanal boyutlarının eşleştiğinden emin olun. Bir katmanın çıkış kanalları (c2), sıradaki sonraki katmanın giriş kanallarıyla (c1) eşleşmelidir.

Atlama Bağlantılarını Kullanın: [[-1, N], 1, Concat, [1]] kalıplarıyla özellik yeniden kullanımından yararlanın. Bu bağlantılar gradyan akışına yardımcı olur ve modelin farklı ölçeklerdeki özellikleri birleştirmesine olanak tanır.

Uygun Ölçeklendirme Yapın: Hesaplama kısıtlamalarınıza göre model ölçeklerini seçin. Kenar 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ın.

Performans Hususları#

Derinlik vs 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 bilgi işler. Görevinin karmaşıklığına göre bunları dengele.

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

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

Çok Ölçekli Özellikler: Aynı görüntüdeki farklı boyutlardaki nesneleri algılamak için gereklidir. Farklı ölçeklerde birden fazla algılama başlığına sahip Feature Pyramid Network (FPN) kalıplarını kullan.

Sorun Giderme#

Yaygın Sorunlar#

Hata Ayıklama İpuçları#

Özel mimariler geliştirirken sistematik hata ayıklama, sorunları erkenden tespit etmene 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ştirin:

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

Bu, backbone çı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 Mimarisi İncelemesi

FLOPs sayısını kontrol etmek ve her katmanı yazdırmak, özel model yapılandırmanla ilgili sorunları gidermene de yardımcı olabilir. Geçerli bir model için FLOPs sayısı sıfır olmamalıdır. Eğer sıfırsa, büyük olasılıkla ileri geçişte bir sorun vardır. Basit bir ileri geçiş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. Kademeli ekle: Karmaşıklığı katman katman oluştur
3. Boyutları kontrol et: Kanal ve uzamsal boyut uyumluluğunu doğrula
4. Ölçeklendirmeyi doğrulayın: Farklı model ölçekleriyle test edin (n, s, m)

SSS#

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

Veri setinizin sınıf sayısıyla eşleşmesi için YAML dosyanızın en üstüne nc parametresini ayarlayın.

nc: 5 # 5 classes

Model YAML dosyamda özel bir backbone kullanabilir miyim?#

Evet. TorchVision omurgaları dahil olmak üzere desteklenen herhangi bir modülü kullanabilir veya kendi özel modülünüzü tanımlayıp Custom Module Integration bölümünde açıklandığı gibi içe aktarabilirsiniz.

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

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

[from, repeats, module, args] biçimi ne anlama gelir?#

Bu biçim, her katmanın nasıl oluşturulduğunu belirtir:

• from: giriş kaynağı/kaynakları
• repeats: modülün tekrarlanma sayısı
• module: katman türü
• args: modül argümanları

Kanal uyuşmazlığı hatalarını nasıl gideririm?#

Bir katmanın çıkış kanallarının sonrakinin beklenen giriş kanallarıyla eşleşip eşleşmediğini kontrol edin. Modelinizin mimarisini incelemek için print(model.model.model) kullanın.

Kullanılabilir modüllerin ve argümanlarının listesini nerede bulabilirim?#

Mevcut tüm modüller ve argümanları için ultralytics/nn/modules directory içindeki kaynak kodunu kontrol edin.

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

Modülünüzü kaynak kodunda tanımlayın, Source Code Modification bölümünde gösterildiği gibi içe aktarın ve YAML dosyanızda adına göre referans verin.

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

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

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

FLOP sayısının sıfır olup olmadığını kontrol etmek için model.info() kullanın. Geçerli bir model sıfırdan farklı bir FLOP sayısı göstermelidir. Sıfırsa, sorunu bulmak için Debugging Tips bölümündeki önerileri izleyin.