Guide de configuration YAML des modèles#

Le fichier de configuration YAML du modèle sert de plan architectural pour les réseaux neuronaux Ultralytics. Il définit la manière dont les couches sont connectées, les paramètres utilisés par chaque module et la façon dont le réseau entier s’adapte à différentes tailles de modèle.

Structure de la configuration#

Les fichiers YAML des modèles sont organisés en trois sections principales qui définissent ensemble l’architecture.

Section des paramètres#

La section parameters spécifie les caractéristiques globales du modèle et son comportement de mise à l’échelle :

# 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 définit le nombre de classes prédites par le modèle.
• scales définit des facteurs de mise à l’échelle composée qui ajustent la profondeur, la largeur et le nombre maximal de canaux du modèle pour produire différentes variantes de taille (de nano à extra-large).
• kpt_shape s’applique aux modèles de pose. Il peut être [N, 2] pour les points clés (x, y) ou [N, 3] pour (x, y, visibility).

Architecture du backbone et de la tête#

L’architecture du modèle comprend les sections du backbone (extraction des caractéristiques) et de la tête (spécifique à la tâche) :

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

Les indices des couches se poursuivent du backbone à la tête, et les cartes de caractéristiques concaténées doivent avoir des dimensions spatiales identiques.

Format de spécification des couches#

Chaque couche suit le modèle uniforme suivant : [from, repeats, module, args]

Modèles de connexion#

Le champ from crée des flux de données flexibles dans l’ensemble de ton réseau :

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

Répétition des modules#

Le paramètre repeats crée des sections de réseau plus profondes :

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

Le nombre réel de répétitions est multiplié par le facteur de mise à l’échelle de la profondeur défini dans la configuration de taille de ton modèle.

Modules disponibles#

Les modules sont classés par fonctionnalité et définis dans le répertoire des modules Ultralytics. Les tableaux suivants présentent les modules couramment utilisés, classés par catégorie ; de nombreux autres sont disponibles dans le code source :

Opérations de base#

Blocs composites#

Modules spécialisés#

Fonctionnalités avancées#

Intégration TorchVision#

Le module TorchVision permet d’intégrer facilement n’importe quel modèle TorchVision comme backbone :

from ultralytics import YOLO

# Modèle avec un backbone ConvNeXt
model = YOLO("convnext_backbone.yaml")
results = model.train(data="imagenet10", epochs=100)

Module Index pour la sélection des caractéristiques#

Lorsque tu utilises des modèles qui produisent plusieurs cartes de caractéristiques, le module Index sélectionne des sorties spécifiques :

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

Système de résolution des modules#

Comprendre comment Ultralytics localise et importe les modules est essentiel pour les personnaliser :

Processus de recherche des modules#

Ultralytics utilise un système à trois niveaux dans parse_model :

# Logique de résolution principale
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]
)  # obtenir le module

1. Modules PyTorch : les noms commençant par 'nn.' → espace de noms torch.nn
2. Opérations TorchVision : les noms commençant par 'torchvision.ops.' → espace de noms torchvision.ops
3. Modules Ultralytics : tous les autres noms → espace de noms global via les imports

Chaîne d’importation des modules#

Les modules standard sont disponibles grâce aux imports dans tasks.py :

from ultralytics.nn.modules import (  # noqa: F401
    SPPF,
    C2f,
    Conv,
    Detect,
    # ... de nombreux autres modules
    Index,
    TorchVision,
)

Intégration de modules personnalisés#

Modification du code source#

Modifier le code source est la méthode la plus polyvalente pour intégrer tes modules personnalisés, mais cela peut être délicat. Pour définir et utiliser un module personnalisé, suis ces étapes :

1. Installe Ultralytics en mode développement en utilisant la méthode de clonage Git du guide de démarrage rapide.

2. Définis ton module dans 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. Expose ton module au niveau du package dans ultralytics/nn/modules/__init__.py :

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

4. Ajoute-le aux imports dans ultralytics/nn/tasks.py :

   from ultralytics.nn.modules import CustomBlock  # noqa

5. Ajoute le module à base_modules dans parse_model(). Les modules de cet ensemble reçoivent automatiquement les canaux d’entrée et de sortie :

   base_modules = frozenset(
       {
           # Modules existants...
           CustomBlock,
       }
   )

6. Utilise le module dans le YAML de ton modèle :

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

7. Vérifie les FLOPs pour t’assurer que la passe avant fonctionne :

   from ultralytics import YOLO
   
   model = YOLO("custom_model.yaml", task="classify")
   model.info()  # devrait afficher une valeur FLOPs non nulle si tout fonctionne

Exemples de configuration#

Modèle de détection de base#

# 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

Modèle avec backbone 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

Modèle de classification#

# 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 effectue déjà un pooling moyen adaptatif en interne.

Bonnes pratiques#

Conseils de conception de l’architecture#

Commence par une solution simple : commence par utiliser des architectures éprouvées avant de les personnaliser. Utilise les configurations YOLO existantes comme modèles et modifie-les progressivement plutôt que de partir de zéro.

Teste progressivement : valide chaque modification étape par étape. Ajoute un seul module personnalisé à la fois et vérifie qu’il fonctionne avant de passer à la modification suivante.

Surveille les canaux : assure-toi que les dimensions des canaux correspondent entre les couches connectées. Les canaux de sortie (c2) d’une couche doivent correspondre aux canaux d’entrée (c1) de la couche suivante dans la séquence.

Utilise des connexions de saut : exploite la réutilisation des caractéristiques avec les motifs [[-1, N], 1, Concat, [1]]. Ces connexions facilitent la propagation du gradient et permettent au modèle de combiner des caractéristiques provenant de différentes échelles.

Choisis une échelle adaptée : choisis les échelles du modèle en fonction de tes contraintes de calcul. Utilise nano (n) pour les appareils en périphérie, small (s) pour un bon équilibre entre performances et coût, et des échelles supérieures (m, l, x) pour une précision maximale.

Considérations relatives aux performances#

Profondeur et largeur : les réseaux profonds capturent des caractéristiques hiérarchiques complexes grâce à plusieurs couches de transformation, tandis que les réseaux larges traitent davantage d’informations en parallèle à chaque couche. Trouve un équilibre en fonction de la complexité de ta tâche.

Connexions de saut : elles améliorent la propagation du gradient pendant l’entraînement et permettent de réutiliser les caractéristiques dans tout le réseau. Elles sont particulièrement importantes dans les architectures plus profondes pour prévenir la disparition des gradients.

Blocs goulots d’étranglement : ils réduisent le coût de calcul tout en préservant la capacité d’expression du modèle. Des modules comme C2f utilisent moins de paramètres que les convolutions standard tout en préservant la capacité d’apprentissage des caractéristiques.

Caractéristiques multi-échelles : elles sont essentielles pour détecter des objets de différentes tailles dans une même image. Utilise des motifs de réseau pyramidal de caractéristiques (FPN) avec plusieurs têtes de détection à différentes échelles.

Dépannage#

Problèmes courants#

Conseils de débogage#

Lors du développement d’architectures personnalisées, un débogage méthodique aide à repérer rapidement les problèmes :

Utilise une tête identité pour les tests

Remplace les têtes complexes par nn.Identity pour isoler les problèmes du backbone :

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

Cela permet d’examiner directement les sorties du backbone :

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

Inspection de l’architecture du modèle

Vérifier le nombre de FLOPs et afficher chaque couche peut aussi aider à déboguer les problèmes liés à la configuration de ton modèle personnalisé. Le nombre de FLOPs doit être différent de zéro pour qu’un modèle soit valide. S’il est égal à zéro, il y a probablement un problème lors de la propagation avant. Une simple propagation avant devrait révéler l’erreur exacte rencontrée.

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

Validation étape par étape

1. Commence par le minimum : teste d’abord l’architecture la plus simple possible
2. Ajoute progressivement : augmente la complexité couche par couche
3. Vérifie les dimensions : vérifie la compatibilité des canaux et des dimensions spatiales
4. Valide la mise à l’échelle : teste différentes échelles du modèle (n, s, m)

FAQ#