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

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]

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

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

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="coco8.yaml", epochs=100)

backbone:
  - [-1, 1, TorchVision, [768, convnext_tiny, DEFAULT, True, 2, False]]
head:
  - [-1, 1, Classify, [nc]]

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 que começam com 'nn.' → torch.nn namespace
2. Operações TorchVision: Nomes que começam com 'ops.' → torchvision.ops namespace
3. 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:

1. Instale o Ultralytics no 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 às importações em ultralytics/nn/tasks.py:

   from ultralytics.nn.modules import CustomBlock  # noqa
   

5. Lidar com argumentos especiais (se necessário) dentro 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 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

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

1. Comece com o mínimo: 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 do canal e do tamanho espacial
4. 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 entrada
• repeats: número de vezes para repetir o módulo
• module: o tipo de camada
• args: 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.

📅 Criado há 1 mês ✏️ Atualizado há 14 dias

Comentários