Guia de configuração do YAML do modelo#

O ficheiro de configuração YAML do modelo serve como projeto arquitetónico das redes neuronais da Ultralytics. Define como as camadas se ligam, que parâmetros cada módulo utiliza e como toda a rede é dimensionada para diferentes tamanhos de modelo.

Estrutura da configuração#

Os ficheiros YAML do modelo estão organizados em três secções principais que, em conjunto, definem a arquitetura.

Secção de parâmetros#

A secção parameters especifica as características globais e o comportamento de dimensionamento 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 dimensionamento compostos que ajustam a profundidade, a largura e o número máximo de canais do modelo para produzir variantes de diferentes tamanhos (de nano a extra-large).
• 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 da head#

A arquitetura do modelo é composta pelas secções do backbone (extração de características) e da head (específica da 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 das camadas continuam ao longo do backbone e da head, e os mapas de características concatenados têm de ter dimensões espaciais correspondentes.

Formato da especificação das camadas#

Todas as camadas seguem o padrão consistente: [from, repeats, module, args]

Padrões de ligaçã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ódulos#

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

O número real de repetições é multiplicado pelo fator de dimensionamento da profundidade da configuração do tamanho do teu modelo.

Módulos disponíveis#

Os módulos estão organizados por funcionalidade e definidos no diretório de módulos da Ultralytics. As tabelas seguintes mostram os módulos mais utilizados por categoria, estando muitos outros disponíveis no código-fonte:

Operações básicas#

Blocos compostos#

Módulos especializados#

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="imagenet10", epochs=100)

Módulo Index para seleção de características#

Ao utilizar modelos que produzem vários 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#

Compreender como a Ultralytics localiza e importa módulos é fundamental para a personalização:

Processo de pesquisa 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 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 que começam por 'nn.' → namespace torch.nn
2. Operações TorchVision: nomes que começam por 'torchvision.ops.' → namespace torchvision.ops
3. Módulos da Ultralytics: todos os outros nomes → namespace global através de importações

Cadeia de importação de módulos#

Os módulos padrão ficam disponíveis através das 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 forma mais versátil de integrar os teus módulos personalizados, mas pode ser complexo. Para definir e utilizar um módulo personalizado, segue estes passos:

1. Instala a Ultralytics em modo de desenvolvimento utilizando o método de clonagem do Git 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-o à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 deste conjunto recebem automaticamente os canais de entrada e saída:

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

6. Utiliza o módulo no YAML do teu modelo:

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

7. Verifica os FLOPs para garantir que a passagem forward funciona:

   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 básico de deteção#

# 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 com 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á executa internamente o average pooling adaptativo.

Boas práticas#

Dicas de design da arquitetura#

Comece de forma simples: Comece com arquiteturas comprovadas antes de personalizar. Use configurações YOLO existentes como modelos e faça modificações incrementais em vez de criar tudo 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 avançar 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 camada seguinte na sequência.

Use conexões de atalho: Aproveite a reutilização de características com padrões [[-1, N], 1, Concat, [1]]. Essas conexões ajudam no fluxo dos gradientes e permitem que o modelo combine características de diferentes escalas.

Escale adequadamente: Escolha as escalas do modelo com base nas suas limitações computacionais. Use nano (n) para dispositivos de borda, small (s) para um desempenho equilibrado e escalas maiores (m, l, x) para obter a máxima precisão.

Considerações de desempenho#

Profundidade vs. largura: As redes profundas capturam características hierárquicas complexas por meio de várias camadas de transformação, enquanto as redes largas processam mais informações em paralelo em cada camada. Equilibre esses fatores com base na complexidade da sua tarefa.

Conexões de atalho: Melhoram o fluxo dos gradientes durante o treinamento e permitem a reutilização de características em toda a rede. São particularmente importantes em arquiteturas mais profundas para evitar o desaparecimento dos gradientes.

Blocos de gargalo: Reduzem o custo computacional mantendo a capacidade expressiva do modelo. Módulos como C2f usam menos parâmetros do que as convoluções padrão, preservando a capacidade de aprendizagem de características.

Características multiescala: São essenciais para detetar objetos de diferentes tamanhos na mesma imagem. Use padrões de rede de pirâmide de características (FPN) com várias cabeças de deteção em diferentes escalas.

Resolução de problemas#

Problemas comuns#

Dicas de depuração#

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

Use uma cabeça de identidade para testes

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

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

Isso permite inspecionar diretamente as 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 na configuração do seu modelo personalizado. A contagem de FLOPs deve ser diferente de zero para um modelo válido. Se for zero, é provável que exista um problema na passagem direta. Executar uma passagem direta simples deve mostrar o erro exato que está a ocorrer.

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 pelo mínimo: Teste primeiro a arquitetura mais simples possível
2. Adicione incrementalmente: Aumente a complexidade camada a camada
3. Verifique as dimensões: Confirme a compatibilidade dos canais e do tamanho espacial
4. Valide o escalonamento: Teste com diferentes escalas de modelo (n, s, m)

Perguntas frequentes#