Guia de Configuração de Modelo YAML

O arquivo de configuração de modelo YAML serve como o modelo 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 é escalada em diferentes tamanhos de modelo.

Estrutura de Configuração

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

Arquitetura de 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):

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 Camada

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

Padrões de Conexão

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

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

Repetição de Módulo

O parâmetro repeats 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 de tamanho do seu modelo.

Módulos Disponíveis

Os módulos são organizados por funcionalidade e definidos no diretório de módulos da Ultralytics. As tabelas a seguir mostram os módulos usados comumente por categoria, com muitos outros 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 um backbone:

from ultralytics import YOLO

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

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]

1. Módulos PyTorch: Nomes começando com 'nn.' → namespace torch.nn
2. Operações TorchVision: Nomes começando com '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 tornam-se disponíveis através de imports em tasks.py:

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

Integração de Módulo Personalizado

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:

1. Instale o Ultralytics em modo de desenvolvimento usando o método Git clone do guia de início rápido.

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

3. Exponha o seu 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. Adicione aos imports em ultralytics/nn/tasks.py:

   from ultralytics.nn.modules import CustomBlock  # noqa

5. Lide com argumentos especiais (se necessário) dentro de parse_model() em 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. Use o módulo no seu YAML de 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) funciona:

   from ultralytics import YOLO
   
   model = YOLO("custom_model.yaml", task="classify")
   model.info()  # should print non-zero FLOPs if working

Exemplos de Configurações

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 configurações existentes do YOLO 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 funciona antes de prosseguir para a próxima alteração.

Monitore os Canais: Garanta que as dimensões dos canais 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 de Salto (Skip Connections): Aproveite a reutilização de recursos com padrões [[-1, N], 1, Concat, [1]]. Essas conexões ajudam no fluxo de gradiente e permitem que o modelo combine recursos de diferentes escalas.

Escale Apropriadamente: Escolha escalas de modelo com base nas suas restrições computacionais. Use nano (n) para dispositivos de borda (edge devices), small (s) para um desempenho equilibrado e escalas maiores (m, l, x) para precisão máxima.

Considerações de Desempenho

Profundidade vs Largura: Redes profundas capturam recursos hierárquicos complexos através de múltiplas 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 (Skip Connections): Melhoram o fluxo de gradiente durante o treinamento e permitem a reutilização de recursos por toda a rede. São particularmente importantes em arquiteturas mais profundas para evitar gradientes desaparecendo.

Blocos de Gargalo (Bottleneck Blocks): Reduzem o custo computacional enquanto mantêm a expressividade do modelo. Módulos como C2f usam menos parâmetros do que convoluções padrão, preservando a capacidade de aprendizado de recursos.

Recursos Multi-Escala: 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.

Resoluçã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 para Testes

Substitua cabeças complexas por nn.Identity para isolar problemas no backbone:

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")
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, é provável que haja um problema com a passagem direta (forward pass). Executar uma passagem direta simples deve mostrar o erro exato que está ocorrendo.

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

1. Comece mínimo: Teste primeiro com a arquitetura mais simples possível
2. Adicione incrementalmente: Construa a complexidade camada por camada
3. Verifique dimensões: Verifique a compatibilidade do canal e do tamanho espacial
4. Valide a escala: 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 no topo 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 de modelo?

Sim. Você pode usar qualquer módulo suportado, incluindo backbones do TorchVision, ou definir seu próprio módulo personalizado e importá-lo conforme descrito em Integração de Módulo Personalizado.

Como escalo meu modelo para diferentes tamanhos (nano, small, medium, etc.)?

Use a seção scales no seu YAML para definir fatores de escala para profundidade, largura e canais máximos. O modelo aplicará isso automaticamente quando você carregar o arquivo YAML base com a escala anexada ao nome do arquivo (por exemplo, yolo26n.yaml).

O que significa o formato [from, repeats, module, args]?

Este formato especifica como cada camada é construída:

• from: fonte(s) de entrada
• repeats: número de vezes para repetir o módulo
• module: o tipo de camada
• args: argumentos para o módulo

Como resolvo erros de incompatibilidade de canal?

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 de módulos disponíveis e seus argumentos?

Verifique o código-fonte no diretório ultralytics/nn/modules para todos os módulos disponíveis e seus argumentos.

Como adiciono um módulo personalizado à minha configuração YAML?

Defina seu módulo no código-fonte, importe-o conforme 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 pesos para camadas que correspondem serão carregados com sucesso.

Como valido 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.