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 prevê.
• scales definem fatores de escala compostos que ajustam a profundidade, largura e canais máximos do modelo para produzir variantes de diferentes tamanhos (do nano ao extra-grande).
• kpt_shape aplica-se a modelos de pose. Pode ser [N, 2] para keypoints (x, y) 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):

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#

Cada 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 mais profundas na rede:

- [-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 da Ultralytics. As tabelas a seguir mostram os módulos comumente usados 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 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:

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 utiliza 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[16:])
    if "torchvision.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 'torchvision.ops.' → namespace torchvision.ops
3. Módulos Ultralytics: Todos os outros nomes → namespace global via imports

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
    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 usando o método de clonagem Git do Guia de Início Rápido.

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

3. 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

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 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]]
    - [-1, 1, nn.AdaptiveAvgPool2d, [1]]

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

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.

Monitore os Canais: Garanta que as dimensões dos canais coincidam entre as camadas conectadas. Os canais de saída (c2) de uma camada devem coincidir com os 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, small (s) para 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 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 de Gargalo (Bottleneck): 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 enquanto preservam a capacidade de aprendizado de recursos.

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

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, 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", 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. Valide o escalonamento: 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 do 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ódulos Personalizados.

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 como mostrado em Modificação do Código-Fonte e faça referência a ele 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 minha configuração de 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.