Integración con ClearML

Sobre ClearML

ClearML es una plataforma MLOps de código abierto diseñada para optimizar los flujos de trabajo de aprendizaje automático y ahorrar tiempo de ingeniería.

• 🔨 Rastrea cada entrenamiento de YOLOv5 en el gestor de experimentos.
• 🔧 Gestiona versiones y accede a tus datos de entrenamiento personalizados con la herramienta de versionado de datos integrada de ClearML.
• 🔦 Entrena y supervisa de forma remota las ejecuciones de YOLOv5 usando el agente de ClearML.
• 🔬 Encuentra el mejor mAP con la optimización de hiperparámetros de ClearML.
• 🔭 Convierte tu modelo YOLOv5 entrenado en una API con unos pocos comandos usando ClearML Serving.

Usa tantas o tan pocas de estas herramientas como necesites: empieza solo con el gestor de experimentos o encadénalo todo en un pipeline completo.

🦾 Configuración

ClearML necesita comunicarse con un servidor para rastrear tus experimentos y datos. Tienes dos opciones:

• Regístrate en el servicio alojado de ClearML gratuito, o
• Despliega tu propio servidor ClearML; es de código abierto, por lo que sigue siendo una opción viable incluso para datos sensibles.

Luego instala el paquete clearml de Python y conecta el SDK a tu servidor:

pip install clearml

Genera las credenciales en Settings → Workspace → Create new credentials (esquina superior derecha de la interfaz de ClearML) y luego ejecuta:

clearml-init

Sigue las instrucciones en pantalla. Eso es todo, la configuración se ha completado.

🚀 Entrenamiento de YOLOv5 con ClearML

Para habilitar el seguimiento de experimentos, instala el paquete pip de ClearML si aún no lo has hecho:

pip install clearml

Esto permitirá la integración con el script de entrenamiento de YOLOv5. A partir de ahora, cada ejecución de entrenamiento será capturada y almacenada por el gestor de experimentos de ClearML.

Para personalizar los nombres del proyecto y la tarea, pasa --project y --name a train.py. Los valores predeterminados son YOLOv5 y Training. ClearML utiliza / como delimitador de subproyectos, así que evita usar / en los nombres de proyectos personalizados.

python train.py --img 640 --batch 16 --epochs 3 --data coco8.yaml --weights yolov5s.pt --cache

O con nombres personalizados:

python train.py --project my_project --name my_training --img 640 --batch 16 --epochs 3 --data coco8.yaml --weights yolov5s.pt --cache

Cada ejecución captura:

• Código fuente y cambios sin confirmar
• Paquetes instalados
• Hiperparámetros
• Puntos de control del modelo (usa --save-period n para guardar cada n épocas)
• Salida de la consola
• Escalares (mAP_0.5, mAP_0.5:0.95, precisión, recall, pérdidas, tasas de aprendizaje)
• Detalles de la máquina, tiempo de ejecución y fecha de creación
• Gráficos generados como el correlograma de etiquetas y la matriz de confusión
• Imágenes con cuadros delimitadores por época
• Visualizaciones en mosaico por época
• Imágenes de validación por época

Todo aparece en la interfaz de usuario de ClearML para que puedas supervisar el entrenamiento en un solo lugar. Añade columnas personalizadas (por ejemplo, mAP_0.5) para ordenar por el modelo de mejor rendimiento o selecciona varios experimentos para compararlos uno al lado del otro.

Sigue leyendo para obtener información sobre optimización de hiperparámetros y ejecución remota.

🔗 Gestión de versiones de datasets

Versionar los datos por separado del código facilita la obtención de la última versión y garantiza una reproducibilidad total. Este repositorio acepta un ID de versión del dataset, descarga los datos automáticamente si faltan y registra el ID como un parámetro de tarea para que siempre sepas qué datos se utilizaron en qué experimento.

Prepara tu dataset

El repositorio de YOLOv5 admite muchos datasets a través de archivos de configuración YAML. Por defecto, los datasets se descargan en la carpeta ../datasets relativa a la raíz del repositorio. Después de descargar coco128, la estructura de carpetas se ve así:

..
|_ yolov5
|_ datasets
    |_ coco128
        |_ images
        |_ labels
        |_ LICENSE
        |_ README.txt

Cualquier dataset funciona, siempre que conserves esta estructura.

A continuación, copia el archivo YAML del dataset en la carpeta raíz del dataset; ClearML lee este archivo para utilizar el dataset correctamente. Puedes escribir tu propio YAML siguiendo el diseño de ejemplo, asegurándote de definir path, train, test, val, nc y names.

..
|_ yolov5
|_ datasets
    |_ coco128
        |_ images
        |_ labels
        |_ coco128.yaml  # <---- HERE
        |_ LICENSE
        |_ README.txt

Sube tu dataset

Para registrar el dataset como un dataset versionado de ClearML, accede a su carpeta raíz y ejecuta:

cd ../datasets/coco128
clearml-data sync --project YOLOv5 --name coco128 --folder .

clearml-data sync es una abreviatura de la siguiente secuencia, que también puedes ejecutar explícitamente:

# Add --parent <parent_dataset_id> to base this version on a previous one.
# Duplicate files are not re-uploaded.
clearml-data create --name coco128 --project YOLOv5
clearml-data add --files .
clearml-data close

Entrena en un dataset de ClearML

Con el dataset registrado, apunta el entrenamiento hacia él mediante el ID:

python train.py --img 640 --batch 16 --epochs 3 --data clearml://YOUR_DATASET_ID --weights yolov5s.pt --cache

👀 Optimización de hiperparámetros

Con los experimentos y los datos versionados, puedes trabajar sobre ellos. Dado que cada experimento rastreado captura el entorno completo (código, paquetes instalados y configuración), las ejecuciones son totalmente reproducibles. ClearML te permite clonar un experimento, cambiar sus parámetros y volver a ejecutarlo automáticamente, lo cual es la base de la optimización de hiperparámetros (HPO).

Para ejecutar HPO localmente, usa el script incluido. Primero asegúrate de que exista una tarea de entrenamiento en el gestor de experimentos; el script la clona y varía sus hiperparámetros.

Rellena el ID de la tarea de plantilla en utils/loggers/clearml/hpo.py y luego ejecuta:

# Install Optuna or change the optimizer to RandomSearch.
pip install optuna
python utils/loggers/clearml/hpo.py

Cambia task.execute_locally() a task.execute() para enviar el trabajo a una cola de ClearML para que un agente remoto lo recoja.

🤯 Ejecución remota (Avanzado)

Ejecutar HPO localmente es práctico, pero a menudo querrás realizar experimentos en hardware más potente: una máquina con GPU local o una instancia en la nube. Ese es el papel del agente de ClearML:

• Resumen en YouTube
• Documentación

Cada experimento rastreado contiene todo lo necesario para reproducirlo en otra máquina (paquetes instalados, cambios sin confirmar y configuración). Un agente de ClearML escucha una cola, recoge las tareas entrantes, recrea el entorno, ejecuta el trabajo y transmite los escalares y gráficos de vuelta al gestor de experimentos.

Convierte cualquier máquina (una máquina virtual en la nube, un equipo con GPU local o un portátil) en un agente de ClearML con:

clearml-agent daemon --queue QUEUES_TO_LISTEN_TO [--docker]

Clonación, edición y puesta en cola

Con un agente en ejecución, puedes asignarle trabajo directamente desde la interfaz de usuario:

• 🪄 Haz clic derecho en un experimento y clónalo.
• 🎯 Edita sus hiperparámetros.
• ⏳ Haz clic derecho en la tarea clonada y ponla en cola en una cola de destino.

Ejecución de una tarea de forma remota

También puedes marcar un script en ejecución para la ejecución remota mediante programación añadiendo task.execute_remotely() después de que se haya instanciado el logger de ClearML. Añade la línea resaltada a train.py:

# ...
# Loggers
data_dict = None
if RANK in {-1, 0}:
    loggers = Loggers(save_dir, weights, opt, hyp, LOGGER)  # loggers instance
    if loggers.clearml:
        loggers.clearml.task.execute_remotely(queue="my_queue")  # <------ ADD THIS LINE
        # data_dict is None unless the user selected a ClearML dataset, in which case ClearML fills it in.
        data_dict = loggers.clearml.data_dict
# ...

Después de este cambio, al ejecutar el script de entrenamiento, se ejecuta hasta esa línea, se empaqueta el código y se envía a la cola.

Escalado automático de trabajadores

ClearML se envía con autoscalers que inician máquinas remotas en AWS, GCP o Azure cuando una cola tiene experimentos pendientes, los convierten en agentes de ClearML y los apagan cuando el trabajo ha terminado, por lo que solo pagas por la potencia de cálculo que realmente se está utilizando.

Mira el vídeo de introducción a continuación:

Más información

Para obtener más información sobre la integración de ClearML con modelos de Ultralytics, consulta nuestra guía de integración de ClearML y explora cómo puedes mejorar tu flujo de trabajo MLOps con otras herramientas de seguimiento de experimentos.