Configuración del modelo YAML

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

Estructura de configuración

Los archivos YAML del modelo se organizan 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 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 establece el número de clases que predice el modelo.
• scales definir factores de escala compuestos que ajusten la profundidad, la anchura y los canales máximos del modelo para producir distintas variantes de tamaño (de nano a extragrande).
• 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 troncal y de cabecera

La arquitectura del modelo se compone de secciones troncales (extracción de características) y principales (tareas específicas):

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

Todas las capas siguen el mismo patrón: [from, repeats, module, args]

Patrones de conexión

El from crea patrones de flujo de datos flexibles en toda la 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 de módulos

El 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 número real de repeticiones se multiplica por el factor de escala de profundidad de la configuración del tamaño del modelo.

Módulos disponibles

Los módulos están organizados por funcionalidad y definidos en el directorio de módulosUltralytics . 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

Funciones avanzadas

Integración de TorchVision

El módulo TorchVision permite una integración perfecta 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)

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

Módulo índice para la selección de características

Cuando se utilizan modelos que producen múltiples mapas de características, el módulo Índice 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 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[4:]) if "ops." in m else globals()[m]

1. Módulos PyTorch: Nombres que empiezan por 'nn.' → torch.nn espacio de nombres
2. Operaciones de TorchVision: Nombres que empiezan por 'ops.' → torchvision.ops espacio de nombres
3. MódulosUltralytics : 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, E501
    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 resultar complicado. Para definir y utilizar un módulo personalizado, sigue estos pasos:

1. Defina su módulo en ultralytics/nn/modules/block.py:

   class CustomBlock(nn.Module):
       def __init__(self, c1, c2):
           super().__init__()
           self.layers = nn.Sequential(nn.Conv2d(c1, c2, 3, 1, 1), nn.BatchNorm2d(c2), nn.ReLU())
   
       def forward(self, x):
           return self.layers(x)
   

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

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

   from ultralytics.nn.modules import CustomBlock  # noqa
   

4. Tratar argumentos especiales (si es necesario) en el interior parse_model() en ultralytics/nn/tasks.py:

   elif m is CustomBlock:
       c1, c2 = ch[f], args[0]  # input channels, output channels
       args = [c1, c2, *args[1:]]
   

5. Utilice el módulo en su modelo YAML:

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

6. Comprueba los FLOP para asegurarte de que el pase hacia delante 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 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 TorchVision Backbone

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

Buenas prácticas

Consejos de diseño arquitectónico

Empiece por lo sencillo: Comience con arquitecturas probadas antes de personalizarlas. Utilice las configuraciones YOLO existentes como plantillas y modifíquelas gradualmente en lugar de empezar desde cero.

Pruebe de forma incremental: Valide cada modificación paso a paso. Añade un módulo personalizado cada vez y comprueba que funciona antes de pasar al siguiente cambio.

Supervisar canales: Asegúrese 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 siguiente capa de la secuencia.

Utilizar conexiones de salto: Aproveche la reutilización de funciones con [[-1, N], 1, Concat, [1]] patrones. Estas conexiones ayudan al flujo de gradiente y permiten al modelo combinar características de diferentes escalas.

Escala adecuada: Elija las escalas del modelo en función de sus limitaciones computacionales. Utilice nano (n) para los dispositivos de borde, pequeño (s) para un rendimiento equilibrado, y escalas mayores (m, l, x) para obtener la máxima precisión.

Consideraciones sobre el 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. Equilibre estas opciones en función de la complejidad de su tarea.

Saltar conexiones: Mejoran el flujo de gradientes 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 cuello de botella: Reducir el coste computacional manteniendo la expresividad del modelo. Módulos como C2f utilizan menos parámetros que las convoluciones estándar al tiempo que preservan la capacidad de aprendizaje de características.

Funciones multiescala: Esenciales para detectar objetos de diferentes tamaños en la misma imagen. Utilice patrones Feature Pyramid Network (FPN) con varios cabezales de detección a diferentes escalas.

Solución de problemas

Problemas comunes

Consejos de depuración

Cuando se desarrollan arquitecturas personalizadas, la depuración sistemática ayuda a identificar los problemas en una fase temprana:

Utilice Identity Head para las pruebas

Sustituya los cabezales complejos por 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 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, entonces es probable que haya un problema con el forward pass. Ejecutar un simple forward pass debería mostrar el error exacto que se está encontrando.

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. Empiece con lo mínimo: Pruebe primero con la arquitectura más sencilla posible
2. Añada gradualmente: Aumentar la complejidad capa a capa
3. Compruebe las dimensiones: Verificar la compatibilidad del canal y el tamaño espacial
4. Validar la escala: Pruebas con diferentes escalas de modelos (n, s, m)

Preguntas frecuentes

¿Cómo puedo cambiar el número de clases de mi modelo?

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

nc: 5 # 5 classes

¿Puedo utilizar una columna vertebral personalizada en mi modelo YAML?

Sí. Puede utilizar cualquier módulo soportado, 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 puedo escalar mi modelo para diferentes tamaños (nano, pequeño, mediano, etc.)?

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

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

Este formato especifica cómo se construye cada capa:

• fromFuente(s) de entrada
• repeatsnúmero de veces que se repite el módulo
• module: el tipo de capa
• argsargumentos para el módulo

¿Cómo se solucionan los errores de desajuste de canales?

Comprueba que los canales de salida de una capa coinciden con los canales de entrada previstos 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?

Consulte el código fuente en 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?

Defina su módulo en el código fuente, impórtelo como se muestra en Modificación del código fuente y haga referencia a él por su nombre en su archivo YAML.

¿Puedo utilizar pesos preentrenados con un YAML personalizado?

Sí, puede utilizar model.load("path/to/weights") para cargar pesos de un punto de control preentrenado. Sin embargo, sólo se cargarán correctamente los pesos de las capas que coincidan.

¿Cómo puedo validar la configuración de mi modelo?

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

📅 Creado hace 0 días ✏️ Actualizado hace 0 días