Guide de configuration YAML du modèle#

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 se connectent, les paramètres utilisés par chaque module et la façon dont l'ensemble du réseau s'adapte aux différentes tailles de modèles.

Structure de la configuration#

Les fichiers YAML de modèle sont organisés en trois sections principales qui collaborent pour définir l'architecture.

Section des paramètres#

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

# 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 que le modèle prédit.
• scales définit des facteurs de mise à l'échelle composés qui ajustent la profondeur, la largeur et les canaux maximums 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 s'agir de [N, 2] pour (x, y) points clés ou de [N, 3] pour (x, y, visibility).

Architecture de la dorsale (Backbone) et de la tête (Head)#

L'architecture du modèle se compose de sections dorsale (extraction de caractéristiques) et tête (spécifique à la tâche) :

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

Format de spécification des couches#

Chaque couche suit le modèle cohérent suivant : [from, repeats, module, args]

Modèles de connexion#

Le champ from crée des modèles de flux de données flexibles dans tout ton réseau :

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

Répétition de module#

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 issu de la configuration de la taille de ton modèle.

Modules disponibles#

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

Opérations de base#

Blocs composites#

Modules spécialisés#

Fonctionnalités avancées#

Intégration de TorchVision#

Le module TorchVision permet une intégration transparente de n'importe quel modèle TorchVision en tant que squelette :

from ultralytics import YOLO

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

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

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

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 de module#

Comprendre comment Ultralytics localise et importe les modules est crucial pour la personnalisation :

Processus de recherche de module#

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

# 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. Modules PyTorch : Noms commençant par 'nn.' → espace de noms torch.nn
2. Opérations TorchVision : Noms commençant par 'torchvision.ops.' → espace de noms torchvision.ops
3. Modules Ultralytics : Tous les autres noms → espace de noms global via des imports

Chaîne d'importation de modules#

Les modules standard deviennent disponibles via les importations dans tasks.py :

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

Intégration de modules personnalisés#

Modification du code source#

Modifier le code source est la méthode la plus flexible pour intégrer tes propres modules, 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 paquet dans ultralytics/nn/modules/__init__.py :

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

4. Ajoute aux importations dans ultralytics/nn/tasks.py :

   from ultralytics.nn.modules import CustomBlock  # noqa

5. Gère les arguments spéciaux (si nécessaire) dans parse_model() dans 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. Utilise le module dans ton fichier YAML de 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 (forward pass) fonctionne :

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

Exemples de configurations#

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 de 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]]
    - [-1, 1, nn.AdaptiveAvgPool2d, [1]]

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

Meilleures pratiques#

Conseils de conception d'architecture#

Commence simplement : Débute avec des architectures éprouvées avant de personnaliser. Utilise les configurations YOLO existantes comme modèles et modifie-les progressivement plutôt que de repartir de zéro.

Teste de façon incrémentale : Valide chaque modification étape par étape. Ajoute un module personnalisé à la fois et vérifie qu'il fonctionne avant de passer au changement suivant.

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 les connexions sautées : Tire parti de la réutilisation des caractéristiques avec les motifs [[-1, N], 1, Concat, [1]]. Ces connexions aident à la propagation du gradient et permettent au modèle de combiner des caractéristiques de différentes échelles.

Mets à l'échelle de manière appropriée : Choisis les échelles du modèle en fonction de tes contraintes de calcul. Utilise nano (n) pour les appareils de périphérie, small (s) pour des performances équilibrées et des échelles plus grandes (m, l, x) pour une précision maximale.

Considérations sur les performances#

Profondeur vs Largeur : Les réseaux profonds capturent des caractéristiques hiérarchiques complexes via de multiples couches de transformation, tandis que les réseaux larges traitent plus d'informations en parallèle à chaque couche. Équilibre ces aspects en fonction de la complexité de ta tâche.

Connexions de saut (skip connections) : Améliorent la circulation du gradient pendant l'entraînement et permettent la réutilisation des caractéristiques à travers le réseau. Elles sont particulièrement importantes dans les architectures plus profondes pour éviter la disparition des gradients.

Blocs goulets d'étranglement : Réduis le coût de calcul tout en maintenant l'expressivité du modèle. Les modules tels que 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 : Essentielles pour détecter des objets de différentes tailles dans la même image. Utilise des motifs de type Feature Pyramid Network (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, le débogage systématique aide à identifier les problèmes tôt :

Utiliser une tête d'identité (Identity Head) pour les tests

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

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

Cela permet une inspection directe des sorties du backbone :

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

Inspection de l'architecture du modèle

Vérifier le nombre de FLOPs et imprimer chaque couche peut également aider à déboguer les problèmes de ta configuration de modèle personnalisé. Le nombre de FLOPs doit être non nul pour un modèle valide. S'il est à zéro, il y a probablement un problème avec la passe avant. Exécuter une passe avant simple devrait montrer l'erreur exacte rencontrée.

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

Validation étape par étape

1. Commence au minimum : Teste d'abord avec l'architecture la plus simple possible
2. Ajoute progressivement : Construis la complexité couche par couche
3. Vérifie les dimensions : Valide la compatibilité des canaux et des tailles spatiales
4. Valide la mise à l'échelle : Teste avec différentes échelles de modèle (n, s, m)

FAQ#