Guía de configuración de modelos YAML#

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

Estructura de la configuración#

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

Sección de parámetros#

La sección parameters especifica las características globales y el comportamiento de escalado del 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 el número de clases que predice el modelo.
• scales define factores de escala compuestos que ajustan la profundidad, la anchura y los canales máximos del modelo para producir diferentes variantes de tamaño (desde nano hasta 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 Backbone y Head#

La arquitectura del modelo consiste en secciones de backbone (extracción de características) y head (específicas 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 constante: [from, repeats, module, args]

Patrones de conexión#

El campo from crea patrones de flujo de datos flexibles en toda tu red:

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

Repetición de módulos#

El parámetro repeats 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 real de repeticiones se multiplica por el factor de escalado de profundidad de la configuración de tu tamaño de modelo.

Módulos disponibles#

Los módulos se organizan por funcionalidad y se definen en el directorio de módulos de Ultralytics. Las siguientes tablas muestran los módulos más utilizados 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 con TorchVision#

El módulo TorchVision permite la integración fluida de cualquier modelo TorchVision como columna vertebral:

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 selección de características#

Cuando uses modelos que generen 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#

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

Proceso de búsqueda de módulos#

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[16:])
    if "torchvision.ops." in m
    else globals()[m]
)

1. Módulos de PyTorch: Nombres que empiezan con 'nn.' → espacio de nombres torch.nn
2. Operaciones de TorchVision: Nombres que empiezan con 'torchvision.ops.' → espacio de nombres torchvision.ops
3. Módulos de Ultralytics: Todos los demás nombres → espacio de nombres global mediante importaciones

Cadena de importación de módulos#

Los módulos estándar están disponibles mediante 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 tus módulos personalizados, pero puede ser complicado. Para definir y utilizar un módulo personalizado, sigue estos pasos:

1. Instala Ultralytics en modo de desarrollo utilizando el método de clonación de 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. Expón tu 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ñádelo a las importaciones en ultralytics/nn/tasks.py:

   from ultralytics.nn.modules import CustomBlock  # noqa

5. Maneja los 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. Utiliza el módulo en tu YAML de modelo:

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

7. Comprueba los FLOPs para asegurar que el pase hacia adelante (forward pass) funciona:

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

Ejemplos de configuraciones#

Modelo de detección 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 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 arquitectura#

Empieza de forma sencilla: Comienza con arquitecturas probadas antes de personalizar. Usa configuraciones de YOLO existentes como plantillas y modifícalas de forma incremental en lugar de construir desde cero.

Prueba de forma incremental: Valida cada modificación paso a paso. Añade un módulo personalizado cada vez y verifica que funciona antes de proceder con el siguiente cambio.

Supervisa los canales: Asegúrate de que las dimensiones de los canales coincidan entre las capas conectadas. Los canales de salida (c2) de una capa deben coincidir con los canales de entrada (c1) de la capa siguiente en la secuencia.

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

Escala adecuadamente: Elige las escalas del modelo según tus restricciones computacionales. Utiliza nano (n) para dispositivos de borde, pequeño (s) para un rendimiento equilibrado y escalas más grandes (m, l, x) para la máxima precisión.

Consideraciones de rendimiento#

Profundidad frente a anchura: 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. Equilibra esto según la complejidad de tu tarea.

Conexiones de salto (skip connections): Mejoran el flujo de gradiente durante el entrenamiento y permiten la reutilización de características en toda la red. Son especialmente importantes en arquitecturas más profundas para evitar la desaparición de gradientes.

Bloques de cuello de botella: Reduce el costo computacional manteniendo la expresividad del modelo. Los módulos como C2f utilizan menos parámetros que las convoluciones estándar a la vez que preservan la capacidad de aprendizaje de características.

Características multiescala: Esenciales para detectar objetos de diferentes tamaños en la misma imagen. Usa patrones de Feature Pyramid Network (FPN) con múltiples cabezales de detección a diferentes escalas.

Solución de problemas#

Problemas comunes#

Consejos de depuración#

Al desarrollar arquitecturas personalizadas, la depuración sistemática ayuda a identificar problemas pronto:

Usar cabezal de identidad para pruebas

Reemplaza las cabezas complejas con nn.Identity para aislar los problemas de la columna vertebral:

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

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 personalizada de tu modelo. 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 (forward pass). Ejecutar 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. Empieza de forma mínima: Prueba primero con la arquitectura más simple posible
2. Añade de forma incremental: Construye la complejidad capa por capa
3. Comprueba las dimensiones: Verifica la compatibilidad de canales y tamaño espacial
4. Valida el escalado: Prueba con diferentes escalas de modelo (n, s, m)

FAQ#