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)
.
Réduisez la redondance avec scales
L'argument scales
Le paramètre vous permet de générer plusieurs tailles de modèle à partir d'un seul fichier YAML de base. Par exemple, lorsque vous chargez yolo11n.yaml
, Ultralytics lit le fichier de base yolo11.yaml
et applique les n
facteurs d'échelle (depth=0.50
, width=0.25
) pour construire la variante nano.
nc
et kpt_shape
dépendent de l'ensemble de données
Si votre ensemble de données spécifie un nc
ou kpt_shape
différent, Ultralytics remplacera automatiquement la configuration du modèle au moment de l'exécution pour correspondre au fichier YAML de l'ensemble de données.
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]
Composant | Objectif | Exemples |
---|---|---|
de | Connexions d'entrée | -1 (précédent), 6 (couche 6), [4, 6, 8] (multi-entrée) |
répétitions | Nombre de répétitions | 1 (unique), 3 (répéter 3 fois) |
module | Type de module | Conv , C2f , TorchVision , Detect |
args | Arguments du module | [64, 3, 2] (canaux, noyau, pas) |
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
Indexation des couches
Les couches sont indexées à partir de 0. Les indices négatifs font référence aux couches précédentes (-1
= couche précédente), tandis que les indices positifs font référence à des couches spécifiques par leur position.
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
Module | Objectif | Source | Arguments |
---|---|---|---|
Conv |
Convolution + BatchNorm + Activation | conv.py | [out_ch, kernel, stride, pad, groups] |
nn.Upsample |
Suréchantillonnage spatial | PyTorch | [size, scale_factor, mode] |
nn.Identity |
Opération de transfert | PyTorch | [] |
Blocs composites
Module | Objectif | Source | Arguments |
---|---|---|---|
C2f |
Goulot d'étranglement CSP avec 2 convolutions | block.py | [out_ch, shortcut, expansion] |
SPPF |
Spatial Pyramid Pooling (rapide) | block.py | [out_ch, kernel_size] |
Concat |
Concaténation par canal | conv.py | [dimension] |
Modules spécialisés
Module | Objectif | Source | Arguments |
---|---|---|---|
TorchVision |
Charger n'importe quel modèle torchvision | block.py | [out_ch, model_name, weights, unwrap, truncate, split] |
Index |
Extraire un tenseur spécifique de la liste | block.py | [out_ch, index] |
Detect |
Tête de détection YOLO | head.py | [nc, anchors, ch] |
Liste complète des modules
Ceci représente un sous-ensemble des modules disponibles. Pour la liste complète des modules et de leurs paramètres, explorez le répertoire des modules.
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]]
Répartition des paramètres :
768
: Nombre de canaux de sortie attenduconvnext_tiny
: Architecture du modèle (modèles disponibles)DEFAULT
: Utiliser les poids pré-entraînésTrue
: Supprimer la tête de classification2
: Tronquer les 2 dernières couchesFalse
: Retourner un seul tenseur (pas une liste)
Fonctionnalités multi-échelles
Définissez le dernier paramètre sur True
pour obtenir des cartes de caractéristiques intermédiaires pour la détection multi-échelle.
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]
- les modules PyTorch: Noms commençant par
'nn.'
→torch.nn
espace de noms - Opérations TorchVision: Noms commençant par
'ops.'
→torchvision.ops
espace de noms - 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 :
-
Installez Ultralytics en mode développement en utilisant la méthode de clonage Git à partir du guide de démarrage rapide.
-
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)
-
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
-
Ajoutez aux importations dans
ultralytics/nn/tasks.py
:from ultralytics.nn.modules import CustomBlock # noqa
-
Gérez les arguments spéciaux (si nécessaire) à l'intérieur
parse_model()
dansultralytics/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:]]
-
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]]
-
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
Problème | Cause | Solution |
---|---|---|
KeyError: 'ModuleName' |
Module non importé | Ajouter à tasks.py imports |
Incompatibilité de la dimension du canal | Incorrect args spécification |
Vérifiez la compatibilité des canaux d'entrée/sortie |
AttributeError: 'int' object has no attribute |
Type d'argument incorrect | Consultez la documentation du module pour connaître les types d'arguments corrects |
Le modèle ne parvient pas à se construire | Référence from invalide |
Assurez-vous que les couches référencées existent |
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
- Démarrage minimal : Testez d'abord avec l'architecture la plus simple possible.
- Ajout incrémentiel : Développez la complexité couche par couche.
- Vérification des dimensions : Vérifiez la compatibilité des canaux et de la taille spatiale.
- 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éerepeats
: nombre de fois où le module doit être répétémodule
: le type de coucheargs
: 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.