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 da Ultralytics. Ele define como as camadas se conectam, quais parâmetros cada módulo utiliza e como toda a rede escala através de diferentes tamanhos de modelo.

Estrutura de Configuração#

Os arquivos YAML de modelo são organizados em três seções principais que trabalham juntas para definir a arquitetura.

Seção de Parâmetros#

A seção parameters especifica as características globais e o comportamento de escala do modelo:

# 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 prediz.
• scales define fatores de escala compostos que ajustam a profundidade, a largura e os canais máximos do modelo para produzir diferentes variantes de tamanho (do nano ao extra-grande).
• kpt_shape aplica-se a modelos de pose. Pode ser [N, 2] para (x, y) pontos-chave ou [N, 3] para (x, y, visibility).

Arquitetura do Backbone e Head#

A arquitetura do modelo consiste em seções de backbone (extração de características) e head (específica para a tarefa):

nc: 80

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]] # 3: Upsample
    - [[-1, 0], 1, Concat, [1]] # 4: Spatially compatible skip connection
    - [-1, 3, C2f, [256]] # 5: Process features
    - [[5], 1, Detect, [nc]] # 6: Detection layer

Os índices de camadas continuam através do backbone e da head, e os mapas de características concatenados devem ter dimensões espaciais correspondentes.

Formato de Especificação de Camada#

Cada camada segue o padrão consistente: [from, repeats, module, args]

Padrões de Conexão#

O campo from cria padrões flexíveis de fluxo de dados em toda a tua rede:

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

Repetição de Módulo#

O parâmetro repeats cria secçõ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 do Ultralytics. As tabelas seguintes mostram os módulos mais utilizados por categoria, com muitos mais disponíveis no código-fonte:

Operações Básicas#

Blocos Compostos#

Módulos Especializados#

Recursos Avançados#

Integração com TorchVision#

O módulo TorchVision permite a integração perfeita de qualquer modelo TorchVision como uma espinha dorsal:

from ultralytics import YOLO

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

Módulo Index 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:

nc: 80

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#

O Ultralytics utiliza um sistema de três níveis em parse_model:

# Core resolution logic
m = (
    getattr(torch.nn, m[3:])
    if m.startswith("nn.")
    else getattr(__import__("torchvision").ops, m[16:])
    if m.startswith("torchvision.ops.")
    else globals()[m]
)  # get module

1. Módulos PyTorch: Nomes começados por 'nn.' → namespace torch.nn
2. Operações TorchVision: Nomes começados por 'torchvision.ops.' → namespace torchvision.ops
3. Módulos Ultralytics: Todos os outros nomes → namespace global via imports

Cadeia de Importação de Módulos#

Os módulos padrão ficam disponíveis através de importações em tasks.py:

from ultralytics.nn.modules import (  # noqa: F401
    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 complexo. Para definir e usar um módulo personalizado, siga estes passos:

1. Instala o Ultralytics em modo de desenvolvimento utilizando o método de clonagem do Git a partir do Guia de Início Rápido.

2. Define o teu 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)

3. Expõe o teu módulo ao nível do pacote em ultralytics/nn/modules/__init__.py:

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

4. Adiciona às importações em ultralytics/nn/tasks.py:

   from ultralytics.nn.modules import CustomBlock  # noqa

5. Adiciona o módulo a base_modules dentro de parse_model(). Os módulos neste conjunto recebem automaticamente canais de entrada e saída:

   base_modules = frozenset(
       {
           # Existing modules...
           CustomBlock,
       }
   )

6. Use o módulo no seu YAML do modelo:

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

7. Verifique os FLOPs para garantir que a passagem direta (forward pass) 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ásica#

# 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]]

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

Classify já realiza average pooling adaptativo internamente.

Melhores Práticas#

Dicas de Design de Arquitetura#

Comece Simples: Inicie com arquiteturas comprovadas antes de personalizar. Use 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 por vez e verifique se funciona antes de prosseguir para a próxima alteração.

Monitorizar Canais: Certifica-te de que as dimensões dos canais coincidem entre as camadas ligadas. Os canais de saída (c2) de uma camada devem corresponder aos canais de entrada (c1) da camada seguinte na sequência.

Usar Ligações de Salto: Aproveita a reutilização de características com os padrões [[-1, N], 1, Concat, [1]]. Estas ligações ajudam no fluxo de gradientes e permitem ao modelo combinar características de diferentes escalas.

Dimensionar Adequadamente: Escolhe as escalas do modelo com base nas tuas restrições computacionais. Usa nano (n) para dispositivos de borda, pequeno (s) para um desempenho equilibrado e escalas maiores (m, l, x) para máxima precisão.

Considerações de Desempenho#

Profundidade vs Largura: Redes profundas capturam recursos hierárquicos complexos através de várias camadas de transformação, enquanto redes largas processam mais informações em paralelo em cada camada. Equilibre isso com base na complexidade da sua tarefa.

Conexões de Salto: Melhoram o fluxo de gradiente durante o treinamento e permitem a reutilização de recursos em toda a rede. São particularmente importantes em arquiteturas mais profundas para prevenir gradientes desaparecidos.

Blocos Gargalo: Reduz o custo computacional enquanto manténs a expressividade do modelo. Módulos como C2f utilizam menos parâmetros do que as convoluções padrão, preservando a capacidade de aprendizagem de características.

Recursos Multiescala: Essenciais para detectar objetos de tamanhos diferentes na mesma imagem. Use padrões de Feature Pyramid Network (FPN) com múltiplas cabeças de detecção em diferentes escalas.

Solução de Problemas#

Problemas Comuns#

Dicas de Depuração#

Ao desenvolver arquiteturas personalizadas, a depuração sistemática ajuda a identificar problemas precocemente:

Use a Cabeça de Identidade (Identity Head) para Teste

Substitui cabeças complexas por nn.Identity para isolar problemas na espinha dorsal:

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

Isso permite a inspeção direta das saídas do backbone:

import torch

from ultralytics import YOLO

model = YOLO("debug_model.yaml", task="detect")
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 sua configuração de modelo personalizada. A contagem de FLOPs deve ser diferente de zero para um modelo válido. Se for zero, provavelmente há um problema na passagem direta (forward pass). Executar uma passagem direta 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", task="detect", 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

1. Comece minimamente: Teste primeiro com a arquitetura mais simples possível
2. Adicione incrementalmente: Construa a complexidade camada por camada
3. Verifique as dimensões: Verifique a compatibilidade de canal e tamanho espacial
4. Validar escala: Testa com diferentes escalas de modelo (n, s, m)

FAQ#