Guida alla configurazione YAML del modello
Il file di configurazione YAML del modello funge da progetto architettonico per le reti neurali Ultralytics. Definisce come si connettono i livelli, quali parametri utilizza ciascun modulo e come l'intera rete si adatta alle diverse dimensioni del modello.
Struttura della Configurazione
I file YAML del modello sono organizzati in tre sezioni principali che lavorano insieme per definire l'architettura.
Sezione Parametri
La sezione parameters specifica le caratteristiche globali del modello e il comportamento di ridimensionamento:
# 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
imposta il numero di classi previste dal modello.scales
definiscono i fattori di ridimensionamento composti che regolano la profondità, la larghezza e i canali massimi del modello per produrre diverse varianti di dimensione (da nano a extra-large).kpt_shape
si applica ai modelli di posa. Può essere[N, 2]
per(x, y)
punti chiave o[N, 3]
per(x, y, visibility)
.
Riduci la ridondanza con scales
Il scales
il parametro consente di generare più dimensioni del modello da un singolo file YAML di base. Ad esempio, quando carichi yolo11n.yaml
, Ultralytics legge la base yolo11.yaml
e applica i n
fattori di scala (depth=0.50
, width=0.25
) per creare la variante nano.
nc
e kpt_shape
sono dipendenti dal set di dati
Se il tuo set di dati specifica un diverso nc
oppure kpt_shape
, Ultralytics sovrascriverà automaticamente la configurazione del modello in fase di esecuzione per corrispondere al file YAML del set di dati.
Architettura di Backbone e Head
L'architettura del modello è costituita da sezioni di backbone (estrazione delle caratteristiche) e head (specifiche per l'attività):
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
Formato di Specificazione del Livello
Ogni layer segue uno schema coerente: [from, repeats, module, args]
Componente | Scopo | Esempi |
---|---|---|
da | Connessioni di input | -1 (precedente), 6 (layer 6), [4, 6, 8] (multi-input) |
ripetizioni | Numero di ripetizioni | 1 (singola), 3 (ripeti 3 volte) |
modulo | Tipo di modulo | Conv , C2f , TorchVision , Detect |
args | Argomenti del modulo | [64, 3, 2] (canali, kernel, stride) |
Schemi di Connessione
Il from
crea pattern di flusso di dati flessibili all'interno della rete:
- [-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
Indicizzazione dei Livelli
I livelli sono indicizzati a partire da 0. Gli indici negativi fanno riferimento ai livelli precedenti (-1
= livello precedente), mentre gli indici positivi fanno riferimento a livelli specifici in base alla loro posizione.
Ripetizione del Modulo
Il repeats
Il parametro crea sezioni di rete più profonde:
- [-1, 3, C2f, [128, True]] # Creates 3 consecutive C2f blocks
- [-1, 1, Conv, [64, 3, 2]] # Single convolution layer
Il conteggio effettivo delle ripetizioni viene moltiplicato per il fattore di scala della profondità dalla configurazione della dimensione del modello.
Moduli Disponibili
I moduli sono organizzati per funzionalità e definiti nella directory dei moduli Ultralytics. Le tabelle seguenti mostrano i moduli comunemente utilizzati per categoria, con molti altri disponibili nel codice sorgente:
Operazioni di Base
Modulo | Scopo | Sorgente | Argomenti |
---|---|---|---|
Conv |
Convoluzione + BatchNorm + Attivazione | conv.py | [out_ch, kernel, stride, pad, groups] |
nn.Upsample |
Upsampling spaziale | PyTorch | [size, scale_factor, mode] |
nn.Identity |
Operazione pass-through | PyTorch | [] |
Blocchi Compositi
Modulo | Scopo | Sorgente | Argomenti |
---|---|---|---|
C2f |
Collo di bottiglia CSP con 2 convoluzioni | block.py | [out_ch, shortcut, expansion] |
SPPF |
Spatial Pyramid Pooling (veloce) | block.py | [out_ch, kernel_size] |
Concat |
Concatenazione channel-wise | conv.py | [dimension] |
Moduli Specializzati
Modulo | Scopo | Sorgente | Argomenti |
---|---|---|---|
TorchVision |
Carica qualsiasi modello torchvision | block.py | [out_ch, model_name, weights, unwrap, truncate, split] |
Index |
Estrai un tensor specifico dalla lista | block.py | [out_ch, index] |
Detect |
Head di rilevamento YOLO | head.py | [nc, anchors, ch] |
Elenco completo dei moduli
Questo rappresenta un sottoinsieme dei moduli disponibili. Per l'elenco completo dei moduli e dei loro parametri, esplora la directory dei moduli.
Funzionalità Avanzate
Integrazione TorchVision
Il modulo TorchVision consente l'integrazione perfetta di qualsiasi modello TorchVision come 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]]
Analisi dei parametri:
768
: Canali di output previsticonvnext_tiny
: Architettura del modello (modelli disponibili)DEFAULT
: Usa pesi pre-addestratiTrue
: Rimuovi l'head di classificazione2
: Tronca gli ultimi 2 layerFalse
: Restituisci un singolo tensor (non una lista)
Funzionalità Multi-Scala
Imposta l'ultimo parametro su True
per ottenere feature map intermedie per il rilevamento multi-scala.
Modulo Indice per la Selezione delle Feature
Quando si utilizzano modelli che restituiscono più feature map, il modulo Index seleziona output specifici:
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
Sistema di Risoluzione del Modulo
Comprendere come Ultralytics individua e importa i moduli è fondamentale per la personalizzazione:
Processo di Ricerca del Modulo
Ultralytics utilizza un sistema a tre livelli in 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]
- moduli PyTorch: Nomi che iniziano con
'nn.'
→torch.nn
namespace - Operazioni TorchVision: Nomi che iniziano con
'ops.'
→torchvision.ops
namespace - Moduli Ultralytics: Tutti gli altri nomi → namespace globale tramite importazioni
Catena di Importazione del Modulo
I moduli standard diventano disponibili tramite importazioni in tasks.py
:
from ultralytics.nn.modules import ( # noqa: F401, E501
SPPF,
C2f,
Conv,
Detect,
# ... many more modules
Index,
TorchVision,
)
Integrazione di Moduli Personalizzati
Modifica del Codice Sorgente
Modificare il codice sorgente è il modo più versatile per integrare i tuoi moduli personalizzati, ma può essere complicato. Per definire e utilizzare un modulo personalizzato, segui questi passaggi:
-
Installa Ultralytics in modalità di sviluppo usando il metodo di clonazione Git dalla guida rapida.
-
Definisci il tuo modulo in
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)
-
Esponi il tuo modulo a livello di pacchetto in
ultralytics/nn/modules/__init__.py
:from .block import CustomBlock # noqa makes CustomBlock available as ultralytics.nn.modules.CustomBlock
-
Aggiungi alle importazioni in
ultralytics/nn/tasks.py
:from ultralytics.nn.modules import CustomBlock # noqa
-
Gestisci argomenti speciali (se necessario) all'interno di
parse_model()
inultralytics/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:]]
-
Usa il modulo nel tuo YAML del modello:
# custom_model.yaml nc: 1 backbone: - [-1, 1, CustomBlock, [64]] head: - [-1, 1, Classify, [nc]]
-
Verifica i FLOP per assicurarti che il forward pass funzioni:
from ultralytics import YOLO model = YOLO("custom_model.yaml", task="classify") model.info() # should print non-zero FLOPs if working
Configurazioni di esempio
Modello di Rilevamento di 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
Modello 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
Modello di classificazione
# 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]]
Best practice
Suggerimenti per la progettazione dell'architettura
Inizia in modo semplice: Inizia con architetture collaudate prima di personalizzare. Utilizza le configurazioni YOLO esistenti come modelli e modificale in modo incrementale piuttosto che costruirle da zero.
Testa in modo incrementale: Convalida ogni modifica passo dopo passo. Aggiungi un modulo personalizzato alla volta e verifica che funzioni prima di procedere alla modifica successiva.
Monitora i canali: Assicurati che le dimensioni dei canali corrispondano tra i livelli connessi. I canali di output (c2
) di un livello devono corrispondere ai canali di input (c1
) del livello successivo nella sequenza.
Utilizza le connessioni skip: Sfrutta il riutilizzo delle feature con pattern di [[-1, N], 1, Concat, [1]]
. Queste connessioni aiutano il flusso del gradiente e consentono al modello di combinare le feature da scale diverse.
Scala in modo appropriato: Scegli le scale del modello in base ai tuoi vincoli computazionali. Utilizza nano (n
) per i dispositivi edge, small (s
) per prestazioni bilanciate e scale più grandi (m
, l
, x
) per la massima precisione.
Considerazioni sulle prestazioni
Profondità vs Ampiezza: Le reti profonde catturano feature gerarchiche complesse attraverso più livelli di trasformazione, mentre le reti ampie elaborano più informazioni in parallelo a ogni livello. Bilancia questi aspetti in base alla complessità della tua attività.
Connessioni Skip: Migliora il flusso del gradiente durante l'addestramento e abilita il riutilizzo delle feature in tutta la rete. Sono particolarmente importanti nelle architetture più profonde per prevenire la scomparsa dei gradienti.
Blocchi Bottleneck: Riduci i costi computazionali mantenendo l'espressività del modello. Moduli come C2f
utilizzano meno parametri rispetto alle convoluzioni standard, preservando al contempo la capacità di apprendimento delle feature.
Feature Multi-Scala: Essenziali per rilevare oggetti di diverse dimensioni nella stessa immagine. Utilizza pattern Feature Pyramid Network (FPN) con più detection head a scale diverse.
Risoluzione dei problemi
Problemi comuni
Problema | Causa | Soluzione |
---|---|---|
KeyError: 'ModuleName' |
Modulo non importato | Aggiungi a tasks.py importazioni |
Mancata corrispondenza della dimensione del canale | Non corretto args specifica |
Verificare la compatibilità dei canali di input/output |
AttributeError: 'int' object has no attribute |
Tipo di argomento errato | Consultare la documentazione del modulo per i tipi di argomento corretti |
Il modello non riesce a essere costruito | Non valido from riferimento |
Assicurarsi che i layer a cui si fa riferimento esistano |
Suggerimenti per il debug
Quando si sviluppano architetture personalizzate, il debug sistematico aiuta a identificare i problemi in anticipo:
Usare Identity Head per il testing
Sostituire gli head complessi con nn.Identity
per isolare i problemi del backbone:
nc: 1
backbone:
- [-1, 1, CustomBlock, [64]]
head:
- [-1, 1, nn.Identity, []] # Pass-through for debugging
Questo permette l'ispezione diretta degli output del 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
Ispezione dell'architettura del modello
Controllare il conteggio dei FLOP e stampare ogni layer può anche aiutare a risolvere i problemi con la configurazione del modello personalizzato. Il conteggio dei FLOP dovrebbe essere diverso da zero per un modello valido. Se è zero, allora c'è probabilmente un problema con il forward pass. Eseguire un semplice forward pass dovrebbe mostrare l'esatto errore che si sta verificando.
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}")
Validazione passo dopo passo
- Iniziare in modo minimale: Testare prima con l'architettura più semplice possibile
- Aggiungere in modo incrementale: Costruire la complessità layer per layer
- Controllare le dimensioni: Verificare la compatibilità delle dimensioni spaziali e dei canali
- Validare lo scaling: Testare con diverse scale del modello (
n
,s
,m
)
FAQ
Come posso modificare il numero di classi nel mio modello?
Impostare il nc
il parametro nella parte superiore del file YAML in modo che corrisponda al numero di classi del tuo set di dati.
nc: 5 # 5 classes
Posso usare un backbone personalizzato nel mio file YAML del modello?
Sì. Puoi utilizzare qualsiasi modulo supportato, inclusi i backbone di TorchVision, oppure definire il tuo modulo personalizzato e importarlo come descritto in Integrazione di moduli personalizzati.
Come posso scalare il mio modello per diverse dimensioni (nano, small, medium, ecc.)?
Utilizzare il scales
sezione nel tuo YAML per definire i fattori di scala per profondità, larghezza e canali massimi. Il modello li applicherà automaticamente quando carichi il file YAML di base con la scala aggiunta al nome del file (ad esempio, yolo11n.yaml
).
Cosa significa il [from, repeats, module, args]
formato?
Questo formato specifica come viene costruito ogni livello:
from
: sorgente/i di inputrepeats
: numero di volte in cui ripetere il modulomodule
: il tipo di livelloargs
: argomenti per il modulo
Come posso risolvere gli errori di mancata corrispondenza dei canali?
Verifica che i canali di output di un livello corrispondano ai canali di input previsti del livello successivo. Usa print(model.model.model)
per ispezionare l'architettura del tuo modello.
Dove posso trovare un elenco dei moduli disponibili e dei relativi argomenti?
Controlla il codice sorgente nel ultralytics/nn/modules
directory per tutti i moduli disponibili e i relativi argomenti.
Come posso aggiungere un modulo personalizzato alla mia configurazione YAML?
Definisci il tuo modulo nel codice sorgente, importalo come mostrato in Modifica del codice sorgente e fai riferimento ad esso per nome nel tuo file YAML.
Posso usare pesi pre-addestrati con un file YAML personalizzato?
Sì, puoi usare model.load("path/to/weights")
per caricare i pesi da un checkpoint pre-addestrato. Tuttavia, solo i pesi per i livelli corrispondenti verranno caricati correttamente.
Come posso convalidare la configurazione del mio modello?
Usa model.info()
per verificare se il conteggio FLOPs è diverso da zero. Un modello valido dovrebbe mostrare un conteggio FLOPs diverso da zero. Se è zero, segui i suggerimenti in Suggerimenti per il debug per trovare il problema.