Guía de configuración YAML del modelo

El archivo de configuración YAML del modelo sirve como plano arquitectónico para las redes neuronales de Ultralytics. Define cómo se conectan las capas, qué parámetros utiliza cada módulo y cómo escala toda la red a través de diferentes tamaños de modelo.

Estructura de configuración

Los archivos YAML del modelo están organizados en tres secciones principales que trabajan juntas para definir la arquitectura.

Sección de parámetros

La sección de parámetros especifica las características globales del modelo y el comportamiento de escalado:

# 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 establece el número de clases que predice el modelo.
• scales define factores de escala compuestos que ajustan la profundidad, el ancho y los canales máximos del modelo para producir diferentes variantes de tamaño (nano a extra grande).
• kpt_shape se aplica a los modelos de pose. Puede ser [N, 2] para (x, y) puntos clave o [N, 3] para (x, y, visibility).

Arquitectura de la Red Troncal y el Cabezal

La arquitectura del modelo consta de secciones de backbone (extracción de características) y head (específica para la tarea):

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 Especificación de Capas

Cada capa sigue el patrón consistente: [from, repeats, module, args]

Patrones de conexión

El from field crea patrones de flujo de datos flexibles en toda su red:

- [-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

Repetición del módulo

El repeats parameter crea secciones de red más profundas:

- [-1, 3, C2f, [128, True]] # Creates 3 consecutive C2f blocks
- [-1, 1, Conv, [64, 3, 2]] # Single convolution layer

El recuento de repeticiones real se multiplica por el factor de escala de profundidad de la configuración del tamaño de su modelo.

Módulos disponibles

Los módulos están organizados por funcionalidad y definidos en el directorio de módulos de Ultralytics. Las siguientes tablas muestran los módulos de uso común por categoría, con muchos más disponibles en el código fuente:

Operaciones Básicas

Bloques compuestos

Módulos especializados

Características Avanzadas

Integración de TorchVision

El módulo TorchVision permite la integración perfecta de cualquier 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 la selección de características

Cuando se utilizan modelos que generan múltiples mapas de características, el módulo Index selecciona salidas 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 resolución de módulos

Comprender cómo Ultralytics localiza e importa módulos es crucial para la personalización:

Proceso de búsqueda del módulo

Ultralytics utiliza un sistema de tres niveles en 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 de PyTorch: Nombres que comienzan con 'nn.' → torch.nn namespace
2. operaciones de TorchVision: Nombres que comienzan con 'ops.' → torchvision.ops namespace
3. Módulos de Ultralytics: Todos los demás nombres → espacio de nombres global a través de importaciones

Cadena de importación del módulo

Los módulos estándar están disponibles a través de importaciones en tasks.py:

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

Integración de Módulos Personalizados

Modificación del código fuente

Modificar el código fuente es la forma más versátil de integrar sus módulos personalizados, pero puede ser complicado. Para definir y utilizar un módulo personalizado, siga estos pasos:

1. Instale Ultralytics en modo de desarrollo utilizando el método de clonación Git de la guía de inicio rápido.

2. Define tu módulo en 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. Exponga su módulo a nivel de paquete en ultralytics/nn/modules/__init__.py:

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

4. Añadir a las importaciones en ultralytics/nn/tasks.py:

   from ultralytics.nn.modules import CustomBlock  # noqa
   

5. Manejar argumentos especiales (si es necesario) dentro de parse_model() en 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. Usar el módulo en el YAML de tu modelo:

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

7. Comprobar FLOPs para asegurar que el pase hacia adelante funcione:

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

Ejemplos de configuraciones

Modelo Básico de Detección

# 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 Backbone de 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 Clasificación

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

Mejores prácticas

Consejos de diseño de la arquitectura

Comience de forma sencilla: Comience con arquitecturas probadas antes de personalizar. Utilice las configuraciones YOLO existentes como plantillas y modifique de forma incremental en lugar de construir desde cero.

Prueba Incrementalmente: Valide cada modificación paso a paso. Agregue un módulo personalizado a la vez y verifique que funcione antes de continuar con el siguiente cambio.

Canales de monitorización: Asegúrese de que las dimensiones del canal coincidan entre las capas conectadas. Los canales de salida (c2) de una capa debe coincidir con los canales de entrada (c1) de la siguiente capa en la secuencia.

Usar conexiones de salto: Aproveche la reutilización de características con [[-1, N], 1, Concat, [1]] patrones. Estas conexiones ayudan con el flujo de gradiente y permiten que el modelo combine características de diferentes escalas.

Escalar Apropiadamente: Elija escalas de modelo basadas en sus limitaciones computacionales. Use nano (n) para dispositivos edge, small (s) para un rendimiento equilibrado, y escalas más grandes (m, l, x) para máxima precisión.

Consideraciones sobre el rendimiento

Profundidad vs. Ancho: Las redes profundas capturan características jerárquicas complejas a través de múltiples capas de transformación, mientras que las redes anchas procesan más información en paralelo en cada capa. Equilibre esto según la complejidad de su tarea.

Conexiones Skip: Mejoran el flujo de gradiente durante el entrenamiento y permiten la reutilización de características en toda la red. Son particularmente importantes en arquitecturas más profundas para prevenir la desaparición de gradientes.

Bloques de cuello de botella: Reducir el costo computacional manteniendo la expresividad del modelo. Módulos como C2f utiliza menos parámetros que las convoluciones estándar, a la vez que conserva la capacidad de aprendizaje de características.

Características Multi-Escala: Esencial para detect objetos a diferentes tamaños en la misma imagen. Utilice patrones de Red Piramidal de Características (FPN) con múltiples cabezales de detection a diferentes escalas.

Solución de problemas

Problemas comunes

Consejos para la depuración

Al desarrollar arquitecturas personalizadas, la depuración sistemática ayuda a identificar los problemas de forma temprana:

Usar Identity Head para pruebas

Reemplazar encabezados complejos con nn.Identity para aislar los problemas de la red troncal:

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

Esto permite la inspección directa de las salidas de la red troncal:

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

Inspección de la arquitectura del modelo

Comprobar el recuento de FLOPs e imprimir cada capa también puede ayudar a depurar problemas con la configuración de su modelo personalizado. El recuento de FLOPs debe ser distinto de cero para un modelo válido. Si es cero, es probable que haya un problema con el pase hacia adelante. La ejecución de un pase hacia adelante simple debería mostrar el error exacto que se está produciendo.

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}")

Validación Paso a Paso

1. Comience con lo mínimo: Pruebe primero con la arquitectura más simple posible
2. Añadir incrementalmente: Construye la complejidad capa por capa.
3. Comprobar dimensiones: Verificar la compatibilidad del canal y el tamaño espacial
4. Validar el escalado: Pruebe con diferentes escalas de modelo (n, s, m)

Preguntas frecuentes

¿Cómo cambio el número de clases en mi modelo?

Establecer el nc parameter en la parte superior de tu archivo YAML para que coincida con el número de clases de tu conjunto de datos.

nc: 5 # 5 classes

¿Puedo usar un backbone personalizado en mi archivo YAML del modelo?

Sí. Puede utilizar cualquier módulo compatible, incluyendo los backbones de TorchVision, o definir su propio módulo personalizado e importarlo como se describe en Integración de Módulos Personalizados.

¿Cómo escalo mi modelo para diferentes tamaños (nano, pequeño, mediano, etc.)?

Utilice el scales sección en tu YAML para definir los factores de escala para la profundidad, el ancho y los canales máximos. El modelo aplicará automáticamente estos factores cuando cargues el archivo YAML base con la escala añadida al nombre del archivo (por ejemplo, yolo11n.yaml).

¿Qué significa [from, repeats, module, args] ¿Qué significa formato?

Este formato especifica cómo se construye cada capa:

• from: fuente(s) de entrada
• repeats: número de veces que se repite el módulo
• module: el tipo de capa
• args: argumentos para el módulo

¿Cómo puedo solucionar los errores de desajuste de canales?

Compruebe que los canales de salida de una capa coinciden con los canales de entrada esperados de la siguiente. Utilice print(model.model.model) para inspeccionar la arquitectura de su modelo.

¿Dónde puedo encontrar una lista de los módulos disponibles y sus argumentos?

Compruebe el código fuente en el ultralytics/nn/modules directorio para todos los módulos disponibles y sus argumentos.

¿Cómo añado un módulo personalizado a mi configuración YAML?

Define tu módulo en el código fuente, impórtalo como se muestra en Modificación del código fuente y haz referencia a él por su nombre en tu archivo YAML.

¿Puedo usar pesos preentrenados con un archivo YAML personalizado?

Sí, puedes usar model.load("path/to/weights") para cargar pesos desde un punto de control preentrenado. Sin embargo, solo se cargarían correctamente los pesos de las capas que coincidan.

¿Cómo valido la configuración de mi modelo?

Utilice model.info() para comprobar si el recuento de FLOPs es distinto de cero. Un modelo válido debe mostrar un recuento de FLOPs distinto de cero. Si es cero, siga las sugerencias en Consejos para la depuración para encontrar el problema.

Creado hace 2 meses ✏️ Actualizado hace 1 mes

Comentarios