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 manière dont l'ensemble du réseau s'adapte aux différentes tailles de modèle.

Structure de la configuration

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

Section des paramètres

La section parameters spécifie les caractéristiques globales du modèle et le 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 que le modèle prédit.
• scales définit des facteurs d'échelle composés qui ajustent la profondeur, la largeur et le nombre maximal de canaux du modèle pour produire différentes variantes de taille (nano à extra-large).
• kpt_shape s'applique aux modèles de pose. Il peut s'agir de [N, 2] pour la (x, y) points clés ou [N, 3] pour la (x, y, visibility).

Architecture du Backbone et du Head

L'architecture du modèle se compose de sections backbone (extraction de caractéristiques) et head (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 même schéma : [from, repeats, module, args]

Schémas de connexion

L'argument from Ce champ crée des modèles de flux de données flexibles dans tout votre réseau :

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

- [[-1, 6], 1, Concat, [1]]    # Combines current layer with layer 6

- [[4, 6, 8], 1, Detect, [nc]] # Detection head using 3 feature scales

Répétition de modules

L'argument repeats Ce paramètre 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 d'échelle de profondeur de la configuration de la taille de votre 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, et beaucoup d'autres sont 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 tout modèle TorchVision en tant que backbone :

from ultralytics import YOLO

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

backbone:
  - [-1, 1, TorchVision, [768, convnext_tiny, DEFAULT, True, 2, False]]
head:
  - [-1, 1, Classify, [nc]]

Module d'index pour la sélection de caractéristiques

Lors de l'utilisation de modèles qui produisent 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 modules

Il est essentiel de comprendre comment Ultralytics localise et importe les modules pour la personnalisation :

Processus de recherche de modules

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[4:]) if "ops." in m else globals()[m]

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

Chaîne d'importation de modules

Les modules standard deviennent disponibles grâce aux importations dans tasks.py:

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

Intégration de modules personnalisés

Modification du code source

La modification du code source est le moyen le plus polyvalent d'intégrer vos modules personnalisés, mais cela peut être délicat. Pour définir et utiliser un module personnalisé, suivez ces étapes :

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

2. Définissez votre 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. Exposez votre 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. Ajoutez aux importations dans ultralytics/nn/tasks.py:

   from ultralytics.nn.modules import CustomBlock  # noqa
   

5. Gérez les arguments spéciaux (si nécessaire) à l'intérieur 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. Utilisez le module dans le YAML de votre modèle :

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

7. Vérifiez les FLOPs pour vous assurer que le passage direct 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

Commencez Simplement : Débutez avec des architectures éprouvées avant de personnaliser. Utilisez les configurations YOLO existantes comme modèles et modifiez-les de manière incrémentale plutôt que de construire à partir de zéro.

Testez de Manière Incrémentale : Validez chaque modification étape par étape. Ajoutez un module personnalisé à la fois et vérifiez qu'il fonctionne avant de passer au changement suivant.

Surveillez les canaux: Assurez-vous 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.

Utilisez les connexions Skip: Tirez parti de la réutilisation des fonctionnalités avec des [[-1, N], 1, Concat, [1]] modèles. Ces connexions aident au flux de gradient et permettent au modèle de combiner des caractéristiques provenant de différentes échelles.

Adaptez l'échelle de manière appropriée: Choisissez les échelles de modèle en fonction de vos contraintes de calcul. Utilisez nano (n) pour les appareils périphériques, small (s) pour des performances équilibrées, et des échelles plus grandes (m, l, x) pour une précision maximale.

Considérations relatives aux performances

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

Connexions Skip : Améliorez le flux de gradient pendant l'entraînement et permettez la réutilisation des caractéristiques dans tout le réseau. Elles sont particulièrement importantes dans les architectures plus profondes pour éviter la disparition des gradients.

Blocs Bottleneck: Réduisez les coûts de calcul tout en conservant l'expressivité du modèle. Modules comme C2f utilisent moins de paramètres que les convolutions standard tout en préservant la capacité d'apprentissage des caractéristiques.

Fonctionnalités multi-échelles: Essentielles pour détecter des objets de différentes tailles dans la même image. Utilisez des modèles de réseau de pyramides 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 systématique permet d'identifier rapidement les problèmes :

Utiliser une tête d'identité pour les tests

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

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

La vérification du nombre de FLOPs et l'impression de chaque couche peuvent également aider à déboguer les problèmes liés à la configuration de votre modèle personnalisé. Le nombre de FLOPs doit être non nul pour un modèle valide. S'il est nul, il y a probablement un problème avec la passe avant. L'exécution d'une simple passe avant 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. Démarrage minimal : Testez d'abord avec l'architecture la plus simple possible.
2. Ajout incrémentiel : Développez la complexité couche par couche.
3. Vérification des dimensions : Vérifiez la compatibilité des canaux et de la taille spatiale.
4. Valider la mise à l'échelle : Testez avec différentes échelles de modèle (n, s, m)

FAQ

Comment modifier le nombre de classes dans mon modèle ?

Définissez le paramètre nc en haut de votre fichier YAML pour qu'il corresponde au nombre de classes de votre ensemble de données.

nc: 5 # 5 classes

Puis-je utiliser un backbone personnalisé dans mon fichier YAML de modèle ?

Oui. Vous pouvez utiliser n'importe quel module pris en charge, y compris les backbones TorchVision, ou définir votre propre module personnalisé et l'importer comme décrit dans Intégration de module personnalisé.

Comment adapter mon modèle à différentes tailles (nano, small, medium, etc.) ?

Utilisez la scales section dans votre fichier YAML pour définir les facteurs d'échelle pour la profondeur, la largeur et les canaux max. Le modèle appliquera automatiquement ces facteurs lorsque vous chargerez le fichier YAML de base avec l'échelle ajoutée au nom de fichier (par exemple, yolo11n.yaml).

Que signifie le format [from, repeats, module, args]  ?

Ce format spécifie la manière dont chaque couche est construite :

• from : source(s) d'entrée
• repeats : nombre de fois où le module doit être répété
• module : le type de couche
• args : arguments pour le module

Comment résoudre les erreurs de non-concordance des canaux ?

Vérifiez que les canaux de sortie d'une couche correspondent aux canaux d'entrée attendus de la couche suivante. Utilisez print(model.model.model) pour inspecter l'architecture de votre modèle.

Où puis-je trouver une liste des modules disponibles et de leurs arguments ?

Vérifiez le code source dans le ultralytics/nn/modules répertoire pour tous les modules disponibles et leurs arguments.

Comment ajouter un module personnalisé à ma configuration YAML ?

Définissez votre module dans le code source, importez-le comme indiqué dans Modification du code source, et référencez-le par son nom dans votre fichier YAML.

Puis-je utiliser des poids pré-entraînés avec un fichier YAML personnalisé ?

Oui, vous pouvez utiliser model.load("path/to/weights") pour charger les poids d'un checkpoint pré-entraîné. Cependant, seuls les poids des couches correspondantes seront chargés avec succès.

Comment valider la configuration de mon modèle ?

Utilisez model.info() pour vérifier si le nombre de FLOPs est non nul. Un modèle valide doit afficher un nombre de FLOPs non nul. S'il est nul, suivez les suggestions dans Conseils de débogage pour trouver le problème.

📅 Créé il y a 1 mois ✏️ Mis à jour il y a 14 jours

Commentaires