Implementa detección de objetos personalizada con YOLOv8

La detección de objetos, la tarea de identificar y localizar objetos dentro de una imagen, ha pasado de ser un tema de investigación a un motor clave de negocio para industrias como el comercio minorista, la fabricación, los sistemas autónomos y la atención médica. Si bien los modelos pre-entrenados en grandes conjuntos de datos como COCO son potentes, fallan al enfrentarse a objetos específicos de un dominio: piezas de maquinaria propietarias, productos minoristas únicos o plagas agrícolas específicas.

La solución es detección de objetos personalizada. Entre las numerosas arquitecturas, la familia YOLO (You Only Look Once) destaca. Su diseño de un solo paso logra un equilibrio excepcional entre la velocidad de inferencia en tiempo real y la precisión de última generación, lo que la convierte en el estándar de facto para sistemas de producción.

Este artículo proporciona una guía técnica completa y detallada para líderes de ingeniería y desarrolladores senior, sobre cómo construir y desplegar un modelo de detección de objetos personalizado utilizando el moderno YOLOv8 framework de Ultralytics. Evitaremos las teorías complejas y nos centraremos en los detalles prácticos, arquitectónicos e de implementación necesarios para pasar de imágenes brutas a un punto final de inferencia de nivel de producción.

1. Decisiones arquitectónicas y configuración del entorno

Antes de escribir una sola línea de código, deben tomarse decisiones cruciales sobre el sistema.

Hardware y Marco de Trabajo

• Hardware de entrenamiento: No negociable. El entrenamiento requiere una GPU NVIDIA con soporte para CUDA. Para instancias en la nube, esto significa g4dn (T4), g5 (A10G), o p3/p4 (V100/A100) en AWS, o sus equivalentes en GCP/Azure. El entrenamiento en una CPU no es computacionalmente factible.
• Framework: Utilizaremos Ultralytics YOLOv8. Está implementado en PyTorch, está excepcionalmente bien mantenido, y proporciona una interfaz de línea de comandos (CLI) y un SDK de Python unificados para el entrenamiento, la validación y la exportación. Esta elección simplifica las complejidades de la definición del modelo y las funciones de pérdida, permitiendo a los equipos centrarse en los datos y el despliegue.

Configuración del entorno

Cree un entorno de Python aislado.

# Create and activate a virtual environment
python3 -m venv yolo_env
source yolo_env/bin/activate

# Install the core dependencies
# 'torch' and 'torchvision' are required for GPU support
# 'ultralytics' is the YOLOv8 framework
pip install torch torchvision ultralytics

# Verify CUDA is available for PyTorch
python -c "import torch; print(f'CUDA Available: {torch.cuda.is_available()}')"

2. Paso 1: El flujo de datos — El verdadero desafío de ingeniería

El modelo es un producto estándar; los datos son su activo de propiedad. "La calidad de la entrada determina la calidad de la salida" es la ley fundamental en el aprendizaje automático.

Comentario

YOLO requiere anotaciones en un formato específico. Para cada imagen image.jpg, se requiere un archivo correspondiente image.txt..txt representa un objeto:

Clase ID <x-centro-norm> <y-centro-norm> <ancho-norm> <alto-norm>

• <class-id>: Un entero sin índice para la clase del objeto (por ejemplo, 0 para 'widget', 1 para 'gadget').
• Todas las coordenadas están normalizadas de 0 a 1 en relación con el ancho y la altura totales de la imagen.

Decisión sobre las herramientas: La anotación manual es un cuello de botella importante.

• Para individuos/prototipos: LabelImg es una herramienta simple y centrada en el local.
• Para equipos de ingeniería: CVAT (Herramienta de anotación de visión por ordenador) o Roboflow son superiores. Ofrecen plataformas colaborativas basadas en la web, control de versiones para anotaciones y funciones robustas de exportación/preprocesamiento. Invertir en una plataforma de anotación adecuada es fundamental para gestionar la calidad de los datos a gran escala.

Estructura del conjunto de datos

YOLO v8 espera una estructura de directorios específica. Esta estructura separa los datos de entrenamiento y validación, lo cual es esencial para una evaluación imparcial del modelo.

/path/to/dataset/
├── images/
│   ├── train/
│   │   ├── 00001.jpg
│   │   ├── 00002.jpg
│   │   └── ...
│   └── val/
│       ├── 00801.jpg
│       ├── 00802.jpg
│       └── ...
├── labels/
│   ├── train/
│   │   ├── 00001.txt
│   │   ├── 00002.txt
│   │   └── ...
│   └── val/
│       ├── 00801.txt
│       ├── 00802.txt
│       └── ...
└── data.yaml

Eldata.yamlManifest

Este archivo es el centro de control para su conjunto de datos. Indica al entrenador dónde encontrar las imágenes y cuáles son los nombres de las clases.

# /path/to/dataset/data.yaml

# Paths are relative to this file or absolute
train: ./images/train  # path to train images
val: ./images/val      # path to val images
# test: ./images/test  # (Optional) path to test images

# Number of classes
nc: 2

# Class names in order (maps to class-id)
names: ['widget', 'gadget']

3. Paso 2: Selección y entrenamiento del modelo

Con los datos preparados, podemos comenzar con el entrenamiento. Esto implica la transferencia de aprendizaje—ajustar un modelo previamente entrenado en el conjunto de datos COCO de 80 clases para reconocer nuestras nuevas clases, creadas a medida.

Elegir un Modelo Base

YOLO v8 ofrece una variedad de modelos, priorizando la velocidad sobre la precisión.

Orientación Arquitectónica:

• Edge/Móvil: Comience con yolov8n o yolov8s.
• En el servidor (Equilibrado): Comience con yolov8m. Suele ser la opción ideal.
• Alta precisión (en la nube): Use yolov8l o yolov8x si la latencia de inferencia no es la principal restricción.

Capacitación a través del SDK de Python

Si bien la interfaz de línea de comandos es sencilla (yolo train...), el SDK de Python es superior para la integración, el registro y el manejo de errores.yolo train...), el SDK de Python es superior para la integración, el registro y la gestión de errores.

from ultralytics import YOLO
import torch
import logging

# Configure logging
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')

def train_custom_yolo():
    """
    Initializes and trains a custom YOLOv8 model.
    """
    # 1. Select the base model
    # This will download yolov8m.pt if not present
    model = YOLO('yolov8m.pt')
    
    # 2. Check for GPU
    device = 0 if torch.cuda.is_available() else 'cpu'
    if device == 'cpu':
        logging.warning("CUDA not available. Training on CPU will be extremely slow.")
        
    logging.info(f"Starting training on device: {device}")

    try:
        # 3. Train the model
        # This is the core command
        results = model.train(
            data='/path/to/dataset/data.yaml',
            epochs=100,
            imgsz=640,
            batch=16,  # Adjust based on GPU VRAM. -1 auto-batches.
            device=device,
            name='yolov8m_custom_run_1', # Experiment name
            patience=20, # Stop training if no improvement after 20 epochs
            exist_ok=True # Overwrite existing experiment
        )
        
        logging.info(f"Training complete. Results saved to {results.save_dir}")
        logging.info(f"Best model saved at: {results.best}")

    except Exception as e:
        logging.error(f"An error occurred during training: {e}", exc_info=True)

if __name__ == '__main__':
    train_custom_yolo()

Parámetros clave:

• épocas: 100 es un buen punto de partida. paciencia=20 se detendrá automáticamente si la métrica de precisión de validación no mejora.
• imgsz: 640 (píxeles) es el estándar. Las imágenes más grandes (por ejemplo, 1280) pueden detectar objetos más pequeños, pero requieren significativamente más VRAM y son más lentas.
• lote: Maximice esto para adaptarse a la VRAM de su GPU. Los lotes más grandes estabilizan el descenso del gradiente. Un tamaño de lote de 16 es típico para una GPU con 16 GB de VRAM (como una T4 o V100). Si recibe un error de "CUDA Out-of-Memory", reduzca este valor.

Supervisión de la formación

Los resultados del entrenamiento se guardan en runs/detect/<name>/. Los archivos más importantes son:

• weights/best.pt: Este es el punto de control de su modelo con mejor rendimiento, basado en el mAP de validación. Este es el archivo que utilizará para la producción.
• results.png: Un gráfico de todas las métricas.
• mAP50-95(B) / mAP50(B): mAP (mean Average Precision) es su métrica principal. mAP50 es la puntuación de precisión utilizando un umbral de IoU de 0.50. mAP50-95 es el estándar COCO, que calcula el promedio del mAP en función de los umbrales de IoU de 0.50 a 0.95. Un mAP más alto significa un modelo más preciso.
• val/box_loss & val/cls_loss: Pérdida de validación. Si esta comienza a aumentar mientras la pérdida de entrenamiento disminuye, su modelo está sobreajustado.

4. Paso 3: Ajuste de hiperparámetros (Opcional, para el estado del arte)

Su primer modelo es una base. Para obtener un rendimiento óptimo, debe ajustar los hiperparámetros. El marco ultralyticsultralyticsFunciones de seguimiento de Weights & Biases (W&B)Weights & Biases (W&B) Sweeps

Una "Sweep" de W&B implica tres partes:

1. Configuración de Sweep (YAML): Define el espacio de búsqueda.
2. Función de Entrenamiento: Una función (como nuestra train_custom_yolo) modificada para aceptar wandb.config parámetros.
3. Agente de W&B: El proceso que ejecuta los experimentos.

Ejemplo sweep.yaml:

program: train.py     # Your training script
method: bayes         # Use Bayesian search (smarter than random)
metric:
  name: metrics/mAP50-95(B)  # The metric to optimize
  goal: maximize
parameters:
  learning_rate:
    distribution: uniform
    min: 1e-4
    max: 1e-2
  batch_size:
    values: [8, 16, 32]
  optimizer:
    values: ['SGD', 'Adam', 'AdamW']
  augmentation_hsv_h: # Tune data augmentation
    distribution: uniform
    min: 0.0
    max: 0.05

Luego, lanzarías un agente con wandb agent <SWEEP_ID> y dejarías que se ejecutara, encontrando la combinación óptima de hiperparámetros para tu conjunto de datos específico.

5. Paso 4: Validación e Inferencia

Una vez que tenga su archivo best.pt más adecuado, debe validar su rendimiento con datos no vistos y utilizarlo para la inferencia.

Validación

Realice la validación contra un conjunto de pruebas separado (si está definido en data.yaml) para obtener una puntuación de rendimiento final e imparcial.

# Validate the best model on the 'test' split
yolo val model=runs/detect/yolov8m_custom_run_1/weights/best.pt data=/path/to/dataset/data.yaml split=test imgsz=640

Esto produce una matriz de confusión final y una puntuación de mAP.

Inferencia (SDK de Python)

Este script demuestra cómo cargar y ejecutar su modelo personalizado en una nueva imagen.

from ultralytics import YOLO
from PIL import Image
import cv2
import logging

def run_inference(model_path: str, image_path: str):
    """
    Loads a custom YOLO model and runs inference on an image.
    """
    logging.info(f"Loading custom model from {model_path}")
    try:
        model = YOLO(model_path)
    except Exception as e:
        logging.error(f"Failed to load model: {e}")
        return

    logging.info(f"Running inference on {image_path}")
    
    # Run inference
    # conf=0.25: Only detect objects with > 25% confidence
    # iou=0.45: Non-Maximal Suppression (NMS) threshold
    try:
        results = model.predict(source=image_path, conf=0.25, iou=0.45)
    except Exception as e:
        logging.error(f"Inference failed: {e}")
        return

    # Process the results
    result = results[0]  # Get results for the first (and only) image
    
    # Print statistics
    logging.info(f"Detected {len(result.boxes)} objects.")

    # Iterate over detected boxes
    for box in result.boxes:
        class_id = int(box.cls)
        class_name = model.names[class_id]
        confidence = float(box.conf)
        # Coordinates in [x_min, y_min, x_max, y_max] format
        coords = box.xyxy[0].cpu().numpy().astype(int)
        
        print(f"--- Object Found ---")
        print(f"  Class: {class_name} (ID: {class_id})")
        print(f"  Confidence: {confidence:.4f}")
        print(f"  Coordinates: {coords}")

    # Save or display the annotated image
    try:
        # result.plot() returns a numpy array (BGR)
        annotated_image_bgr = result.plot()
        
        # Convert BGR to RGB for PIL
        annotated_image_rgb = cv2.cvtColor(annotated_image_bgr, cv2.COLOR_BGR2RGB)
        
        im = Image.fromarray(annotated_image_rgb)
        im.save('inference_output.jpg')
        logging.info(f"Saved annotated image to 'inference_output.jpg'")
        # im.show() # Uncomment to display image
        
    except Exception as e:
        logging.error(f"Failed to save or display image: {e}")


if __name__ == '__main__':
    logging.basicConfig(level=logging.INFO)
    
    # CRITICAL: Use the path to YOUR best model
    MODEL_PATH = 'runs/detect/yolov8m_custom_run_1/weights/best.pt'
    IMAGE_PATH = '/path/to/your/test_image.jpg'
    
    run_inference(MODEL_PATH, IMAGE_PATH)

6. Paso 5: Estrategia de Implementación para la Producción (La Perspectiva del Director de Tecnología)

Un file.ptEste archivo es un punto de control de PyTorch, no un artefacto de producción. Es lento y tiene fuertes dependencias. El despliegue requiereexportación y optimización.

Exportar modelo

El ultralytics exporter es la clave.

# 1. Export to ONNX
# ONNX is a cross-platform format for deep learning models.
yolo export model=runs/detect/yolov8m_custom_run_1/weights/best.pt format=onnx imgsz=640

# 2. Export to TensorRT (For MAXIMUM NVIDIA GPU performance)
# This performs graph optimization and FP16 quantization
# This can result in a 5-10x speedup over the PyTorch model.
yolo export model=runs/detect/yolov8m_custom_run_1/weights/best.pt format=tensorrt half=True imgsz=640

• Obtendrá los mejores archivos .onnx los mejores archivos .engine

Servicio de inferencia

• Prototipado (Baja Capacidad): Envolver el modelo ONNX en un servidor FastAPI utilizando la biblioteca onnxruntime. Es rápido de implementar, pero ineficiente para una alta concurrencia.
• Producción (Alta Capacidad): Utilizar el servidor de inferencia NVIDIA Triton.
  • Triton es una solución de despliegue de código abierto y lista para producción.
  • Puede servir modelos TensorRT, ONNX y otros formatos.
  • Gestiona automáticamente el agrupamiento dinámico (agrupa las solicitudes concurrentes para saturar la GPU).
  • Proporciona puntos finales gRPC y HTTP/REST, métricas de salud y versionado de modelos.
  • Es la solución arquitectónicamente sólida para microservicios de alto rendimiento.

El ciclo de retroalimentación de MLOps

El modelo implementado no es el final. Es el comienzo de un ciclo.

1. ImplementarmodeloeficienteSupervisar
2. : Implemente el registro en su aplicación. Cuando el modelo devuelve una predicción con baja confianza: Implemente el registro en su aplicación. Cuando el modelo devuelve una predicción con (p.ej., conf < 0.40(por ejemplo,), o cuando un usuario indica manualmente un error) o cuando un usuario, su aplicación debería guardar esa imagen de inferencia en un contenedor S3 denominado "necesita revisión".Etiquetar
3. Etiqueta: Este contenedor S3 se convierte en la cola de entrada para su equipo de anotación (utilizando CVAT o Roboflow).
4. Reentrenar: Periódicamente (p. ej., mensualmente o trimestralmente), agregue este nuevo conjunto de datos etiquetado a su conjunto de entrenamiento original.
5. Reimplementar: Reentrene el modelo. Si el nuevo modelo tiene un mAP de validación superior, promóvelo a producción.

Esta retroalimentación de datos es el proceso más importante para garantizar que la precisión de su modelo mejore con el tiempo y se adapte a los cambios en el modelo.

Finalmente

Construir un detector de objetos YOLO personalizado ya no es un proyecto de investigación; es una tarea de ingeniería sencilla y completa. El framework Ultralytics YOLOv8 ha automatizado las partes complejas de la arquitectura y el entrenamiento del modelo.

Para los directores de tecnología y líderes de ingeniería, el enfoque debe cambiar de "cómo construimos el modelo?" a "cómo construimos el sistema?". El éxito no se define por la primera mAP obtenida, sino por la robustez del proceso de etiquetado de datos y la eficiencia del ciclo de retroalimentación de MLOps. Los pasos técnicos descritos aquí proporcionan el plan, pero el verdadero valor comercial, defendible, reside en los datos propietarios y en los sistemas automatizados que se construyen en torno a ellos.

Preguntas frecuentes