Guia de Configuração YAML do Modelo
O arquivo de configuração YAML do modelo serve como o projeto arquitetônico para as redes neurais Ultralytics. Ele define como as camadas se conectam, quais parâmetros cada módulo usa e como toda a rede é dimensionada em diferentes tamanhos de modelo.
Estrutura de Configuração
Os arquivos YAML do modelo são organizados em três seções principais que trabalham juntas para definir a arquitetura.
Secção de Parâmetros
A seção de parâmetros especifica as características globais do modelo e o comportamento de dimensionamento:
# 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
define o número de classes que o modelo prevê.scales
define fatores de dimensionamento compostos que ajustam a profundidade, a largura e os canais máximos do modelo para produzir diferentes variantes de tamanho (nano até extra-grande).kpt_shape
aplica-se a modelos de pose. Pode ser[N, 2]
para(x, y)
keypoints ou[N, 3]
para(x, y, visibility)
.
Reduza a redundância com scales
O scales
O parâmetro permite gerar vários tamanhos de modelo a partir de um único YAML base. Por exemplo, quando você carrega yolo11n.yaml
, Ultralytics lê a base yolo11.yaml
e aplica os n
fatores de dimensionamento (depth=0.50
, width=0.25
) para construir a variante nano.
nc
e kpt_shape
são dependentes do conjunto de dados
Se o seu conjunto de dados especificar um diferente nc
ou kpt_shape
, Ultralytics substituirá automaticamente a configuração do modelo em tempo de execução para corresponder ao YAML do conjunto de dados.
Arquitetura de Backbone e Head
A arquitetura do modelo consiste em seções de backbone (extração de recursos) e head (específica da tarefa):
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 de Especificação de Camadas
Cada camada segue o padrão consistente: [from, repeats, module, args]
Componente | Propósito | Exemplos |
---|---|---|
de | Conexões de entrada | -1 (anterior), 6 (camada 6), [4, 6, 8] (múltiplas entradas) |
repetições | Número de repetições | 1 (único), 3 (repetir 3 vezes) |
módulo | Tipo de módulo | Conv , C2f , TorchVision , Detect |
args | Argumentos do módulo | [64, 3, 2] (canais, kernel, stride) |
Padrões de Conexão
O from
cria padrões de fluxo de dados flexíveis em toda a sua rede:
- [-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
Indexação de Camadas
As camadas são indexadas a partir de 0. Índices negativos referenciam camadas anteriores (-1
= camada anterior), enquanto índices positivos referenciam camadas específicas por sua posição.
Repetição de Módulos
O repeats
parâmetro cria seções de rede mais profundas:
- [-1, 3, C2f, [128, True]] # Creates 3 consecutive C2f blocks
- [-1, 1, Conv, [64, 3, 2]] # Single convolution layer
A contagem real de repetições é multiplicada pelo fator de escala de profundidade da configuração do tamanho do seu modelo.
Módulos Disponíveis
Os módulos são organizados por funcionalidade e definidos no diretório de módulos Ultralytics. As tabelas a seguir mostram os módulos comumente usados por categoria, com muitos mais disponíveis no código-fonte:
Operações Básicas
Módulo | Propósito | Fonte | Argumentos |
---|---|---|---|
Conv |
Convolution + BatchNorm + Activation | conv.py | [out_ch, kernel, stride, pad, groups] |
nn.Upsample |
Upsampling espacial | PyTorch | [size, scale_factor, mode] |
nn.Identity |
Operação de passagem direta (Pass-through) | PyTorch | [] |
Blocos Compostos
Módulo | Propósito | Fonte | Argumentos |
---|---|---|---|
C2f |
Gargalo CSP com 2 convoluções | block.py | [out_ch, shortcut, expansion] |
SPPF |
Agrupamento Espacial Piramidal (rápido) | block.py | [out_ch, kernel_size] |
Concat |
Concatenação por canal | conv.py | [dimension] |
Módulos Especializados
Módulo | Propósito | Fonte | Argumentos |
---|---|---|---|
TorchVision |
Carregar qualquer modelo torchvision | block.py | [out_ch, model_name, weights, unwrap, truncate, split] |
Index |
Extrair tensor específico da lista | block.py | [out_ch, index] |
Detect |
Cabeçalho de detecção YOLO | head.py | [nc, anchors, ch] |
Lista Completa de Módulos
Isto representa um subconjunto dos módulos disponíveis. Para a lista completa de módulos e seus parâmetros, explore o diretório de módulos.
Funcionalidades Avançadas
Integração com TorchVision
O módulo TorchVision permite a integração perfeita de qualquer modelo TorchVision como 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]]
Detalhes dos Parâmetros:
768
: Canais de saída esperadosconvnext_tiny
: Arquitetura do modelo (modelos disponíveis)DEFAULT
: Usar pesos pré-treinadosTrue
: Remover o cabeçalho de classificação2
: Truncar as últimas 2 camadasFalse
: Retornar tensor único (não lista)
Características Multi-Escala
Defina o último parâmetro para True
para obter mapas de características intermediários para detecção multi-escala.
Módulo de Índice para Seleção de Características
Ao usar modelos que produzem múltiplos mapas de características, o módulo Index seleciona saídas específicas:
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 de Resolução de Módulos
Entender como a Ultralytics localiza e importa módulos é crucial para a personalização:
Processo de Busca de Módulos
A Ultralytics usa um sistema de três níveis em 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]
- módulos PyTorch: Nomes que começam com
'nn.'
→torch.nn
namespace - Operações TorchVision: Nomes que começam com
'ops.'
→torchvision.ops
namespace - Módulos Ultralytics: Todos os outros nomes → namespace global via importações
Cadeia de Importação de Módulos
Módulos padrão tornam-se disponíveis através de importações em tasks.py
:
from ultralytics.nn.modules import ( # noqa: F401, E501
SPPF,
C2f,
Conv,
Detect,
# ... many more modules
Index,
TorchVision,
)
Integração de Módulos Personalizados
Modificação do Código Fonte
Modificar o código fonte é a maneira mais versátil de integrar seus módulos personalizados, mas pode ser complicado. Para definir e usar um módulo personalizado, siga estes passos:
-
Instale o Ultralytics no modo de desenvolvimento usando o método de clonagem Git do guia de início rápido.
-
Defina seu módulo em
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)
-
Exponha seu módulo no nível do pacote em
ultralytics/nn/modules/__init__.py
:from .block import CustomBlock # noqa makes CustomBlock available as ultralytics.nn.modules.CustomBlock
-
Adicione às importações em
ultralytics/nn/tasks.py
:from ultralytics.nn.modules import CustomBlock # noqa
-
Lidar com argumentos especiais (se necessário) dentro
parse_model()
emultralytics/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:]]
-
Use o módulo no seu YAML do modelo:
# custom_model.yaml nc: 1 backbone: - [-1, 1, CustomBlock, [64]] head: - [-1, 1, Classify, [nc]]
-
Verifique os FLOPs para garantir que o passe direto funcione:
from ultralytics import YOLO model = YOLO("custom_model.yaml", task="classify") model.info() # should print non-zero FLOPs if working
Configurações de Exemplo
Modelo de Detecção Básico
# 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
Modelo 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
Modelo de Classificação
# 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]]
Melhores Práticas
Dicas de Design de Arquitetura
Comece Simples: Comece com arquiteturas comprovadas antes de personalizar. Use as configurações YOLO existentes como modelos e modifique incrementalmente em vez de construir do zero.
Teste Incrementalmente: Valide cada modificação passo a passo. Adicione um módulo personalizado de cada vez e verifique se ele funciona antes de prosseguir para a próxima alteração.
Monitorar Canais: Garanta que as dimensões do canal correspondam entre as camadas conectadas. Os canais de saída (c2
) de uma camada devem corresponder aos canais de entrada (c1
) da próxima camada na sequência.
Use Conexões Skip: Aproveite a reutilização de recursos com [[-1, N], 1, Concat, [1]]
padrões. Essas conexões auxiliam no fluxo do gradiente e permitem que o modelo combine características de diferentes escalas.
Dimensione Adequadamente: Escolha as escalas do modelo com base nas suas restrições computacionais. Use nano (n
) para dispositivos de borda, small (s
) para desempenho equilibrado e escalas maiores (m
, l
, x
) para máxima precisão.
Considerações sobre o Desempenho
Profundidade vs. Largura: Redes profundas capturam características hierárquicas complexas através de múltiplas camadas de transformação, enquanto redes largas processam mais informações em paralelo em cada camada. Equilibre-as com base na complexidade da sua tarefa.
Skip Connections: Melhore o fluxo do gradiente durante o treinamento e possibilite a reutilização de características em toda a rede. Elas são particularmente importantes em arquiteturas mais profundas para evitar o desaparecimento dos gradientes.
Blocos de Gargalo (Bottleneck): Reduza o custo computacional, mantendo a expressividade do modelo. Módulos como C2f
usam menos parâmetros do que as convoluções padrão, preservando a capacidade de aprendizado de características.
Características Multi-Escala: Essenciais para detectar objetos em diferentes tamanhos na mesma imagem. Use padrões de Rede de Pirâmide de Características (Feature Pyramid Network - FPN) com múltiplos cabeçalhos de detecção em diferentes escalas.
Resolução de Problemas
Problemas Comuns
Problema | Causa | Solução |
---|---|---|
KeyError: 'ModuleName' |
Módulo não importado | Adicionar a tasks.py imports |
Incompatibilidade da dimensão do canal | Especificação args incorreta |
Verifique a compatibilidade do canal de entrada/saída |
AttributeError: 'int' object has no attribute |
Tipo de argumento errado | Verifique a documentação do módulo para os tipos de argumentos corretos |
Falha ao construir o modelo | Inválido from referência |
Certifique-se de que as camadas referenciadas existem |
Dicas de Depuração
Ao desenvolver arquiteturas personalizadas, a depuração sistemática ajuda a identificar problemas precocemente:
Usar Identity Head para Testes
Substitua cabeças complexas por nn.Identity
para isolar problemas de backbone:
nc: 1
backbone:
- [-1, 1, CustomBlock, [64]]
head:
- [-1, 1, nn.Identity, []] # Pass-through for debugging
Isto permite a inspeção direta das saídas do 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
Inspeção da Arquitetura do Modelo
Verificar a contagem de FLOPs e imprimir cada camada também pode ajudar a depurar problemas com a configuração do seu modelo personalizado. A contagem de FLOPs deve ser diferente de zero para um modelo válido. Se for zero, então provavelmente há um problema com o passe forward. Executar um passe forward simples deve mostrar o erro exato que está sendo encontrado.
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}")
Validação Passo a Passo
- Comece com o mínimo: Teste primeiro com a arquitetura mais simples possível
- Adicione incrementalmente: Construa a complexidade camada por camada
- Verifique as dimensões: Verifique a compatibilidade do canal e do tamanho espacial
- Validar o dimensionamento: Teste com diferentes escalas de modelo (
n
,s
,m
)
FAQ
Como altero o número de classes no meu modelo?
Defina o parâmetro nc
na parte superior do seu arquivo YAML para corresponder ao número de classes do seu conjunto de dados.
nc: 5 # 5 classes
Posso usar um backbone personalizado no meu YAML do modelo?
Sim. Você pode usar qualquer módulo suportado, incluindo backbones TorchVision, ou definir seu próprio módulo personalizado e importá-lo conforme descrito em Integração de Módulo Personalizado.
Como dimensiono meu modelo para diferentes tamanhos (nano, pequeno, médio, etc.)?
Use o comando scales
seção no seu YAML para definir fatores de escala para profundidade, largura e canais máximos. O modelo aplicará automaticamente estes fatores quando você carregar o arquivo YAML base com a escala anexada ao nome do arquivo (por exemplo, yolo11n.yaml
).
O que significa o formato [from, repeats, module, args]
?
Este formato especifica como cada camada é construída:
from
: fonte(s) de entradarepeats
: número de vezes para repetir o módulomodule
: o tipo de camadaargs
: argumentos para o módulo
Como solucionar erros de incompatibilidade de canais?
Verifique se os canais de saída de uma camada correspondem aos canais de entrada esperados da próxima. Use print(model.model.model)
para inspecionar a arquitetura do seu modelo.
Onde posso encontrar uma lista dos módulos disponíveis e seus argumentos?
Verifique o código fonte em ultralytics/nn/modules
diretório para todos os módulos disponíveis e seus argumentos.
Como adicionar um módulo personalizado à minha configuração YAML?
Defina seu módulo no código fonte, importe-o como mostrado em Modificação do Código Fonte, e referencie-o pelo nome no seu arquivo YAML.
Posso usar pesos pré-treinados com um YAML personalizado?
Sim, você pode usar model.load("path/to/weights")
para carregar pesos de um checkpoint pré-treinado. No entanto, apenas os pesos das camadas correspondentes serão carregados com sucesso.
Como validar a configuração do meu modelo?
Use model.info()
para verificar se a contagem de FLOPs é diferente de zero. Um modelo válido deve mostrar uma contagem de FLOPs diferente de zero. Se for zero, siga as sugestões em Dicas de Depuração para encontrar o problema.