Intégration de ClearML#

À propos de ClearML#

ClearML est une plateforme MLOps open source conçue pour simplifier les workflows de machine learning et faire gagner du temps aux équipes d’ingénierie.

• 🔨 Suis chaque exécution d’entraînement YOLOv5 dans le gestionnaire d’expériences.
• 🔧 Versionne et consulte tes données d’entraînement personnalisées avec l’outil de gestion des versions des données intégré à ClearML.
• 🔦 Entraîne et surveille à distance tes exécutions YOLOv5 avec ClearML Agent.
• 🔬 Trouve le meilleur mAP avec l’optimisation des hyperparamètres de ClearML.
• 🔭 Transforme ton modèle YOLOv5 en API en quelques commandes avec ClearML Serving.

Utilise autant ou aussi peu de ces outils que nécessaire : commence uniquement par le gestionnaire d’expériences ou relie-les tous pour créer un pipeline complet.

🦾 Mise en place#

ClearML doit communiquer avec un serveur pour suivre tes expériences et tes données. Deux options s’offrent à toi :

• Inscris-toi au service hébergé ClearML gratuit, ou
• Déploie ton propre serveur ClearML — il est open source et reste donc une option viable, même pour les données sensibles.

Installe ensuite le package Python clearml et connecte le SDK à ton serveur :

pip install clearml

Génère tes identifiants dans Settings → Workspace → Create new credentials (en haut à droite de l’interface ClearML), puis exécute :

clearml-init

Suis les instructions. C’est tout : la configuration est terminée.

🚀 Entraîner YOLOv5 avec ClearML#

Pour activer le suivi des expériences, installe le package pip ClearML si ce n’est pas déjà fait :

pip install clearml

Cela active l’intégration avec le script d’entraînement YOLOv5. Toutes les exécutions d’entraînement suivantes seront capturées et stockées par le gestionnaire d’expériences ClearML.

Pour personnaliser les noms du projet et de la tâche, passe --project et --name à train.py. Les valeurs par défaut sont YOLOv5 et Training. ClearML utilise / comme séparateur de sous-projet ; évite donc / dans les noms de projets personnalisés.

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

Ou avec des noms personnalisés :

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

Chaque exécution capture :

• Le code source et les modifications non validées
• Les packages installés
• Les hyperparamètres
• Les points de contrôle du modèle (utilise --save-period n pour enregistrer chaque n époques)
• La sortie de la console
• Les scalaires (mAP_0.5, mAP_0.5:0.95, précision, rappel, pertes, taux d’apprentissage)
• Les détails de la machine, la durée d’exécution et la date de création
• Les graphiques générés, comme le correlogramme des labels et la matrice de confusion
• Les images avec des boîtes englobantes à chaque époque
• Les visualisations en mosaïque à chaque époque
• Les images de validation à chaque époque

Tout apparaît dans l’interface ClearML, ce qui te permet de surveiller l’entraînement depuis un seul endroit. Ajoute des colonnes personnalisées (par exemple, mAP_0.5) pour trier les modèles selon leurs performances, ou sélectionne plusieurs expériences pour les comparer côte à côte.

Poursuis ta lecture pour découvrir l’optimisation des hyperparamètres et l’exécution à distance.

🔗 Gestion des versions des jeux de données#

La gestion des versions des données séparément du code facilite la récupération de la dernière version et garantit une reproductibilité complète. Ce dépôt accepte un ID de version du jeu de données, récupère automatiquement les données si elles sont absentes et enregistre l’ID comme paramètre de tâche, afin que tu saches toujours quelles données ont été utilisées dans quelle expérience.

Préparer ton jeu de données#

Le dépôt YOLOv5 prend en charge de nombreux jeux de données via des fichiers de configuration YAML. Par défaut, les jeux de données sont téléchargés dans le dossier ../datasets relatif à la racine du dépôt. Après le téléchargement de coco128, la structure des dossiers est la suivante :

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

N’importe quel jeu de données convient, à condition de conserver cette structure.

Ensuite, copie le fichier YAML du jeu de données dans le dossier racine du jeu de données : ClearML lit ce fichier pour utiliser correctement le jeu de données. Tu peux rédiger ton propre fichier YAML en suivant la structure de l’exemple, en veillant à ce qu’il définisse path, train, test, val, nc et names.

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

Téléverser ton jeu de données#

Pour enregistrer le jeu de données en tant que jeu de données ClearML versionné, place-toi dans son dossier racine et exécute :

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

clearml-data sync est un raccourci pour la séquence suivante, que tu peux également exécuter explicitement :

# 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

Entraîner sur un jeu de données ClearML#

Une fois le jeu de données enregistré, indique son ID à l’entraînement :

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

👀 Optimisation des hyperparamètres#

Une fois les expériences et les données versionnées, tu peux t’appuyer dessus. Comme chaque expérience suivie capture l’environnement complet — code, packages installés et configuration — les exécutions sont entièrement reproductibles. ClearML te permet de cloner une expérience, d’en modifier les paramètres et de la relancer automatiquement, ce qui constitue la base de l’optimisation des hyperparamètres (HPO).

Pour exécuter HPO localement, utilise le script fourni. Vérifie d’abord qu’une tâche d’entraînement existe dans le gestionnaire d’expériences : le script la clone et fait varier ses hyperparamètres.

Renseigne l’ID de la tâche modèle dans utils/loggers/clearml/hpo.py, puis exécute :

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

Remplace task.execute_locally() par task.execute() pour envoyer la tâche vers une file d’attente ClearML, afin qu’un agent distant la récupère.

🤯 Exécution à distance (avancé)#

L’exécution locale de HPO est pratique, mais tu voudras souvent lancer tes expériences sur du matériel plus puissant — une machine GPU sur site ou une instance cloud. C’est le rôle de ClearML Agent :

• Présentation YouTube
• Documentation

Chaque expérience suivie contient tout ce qui est nécessaire pour la reproduire sur une autre machine (packages installés, modifications non validées et configuration). Un agent ClearML écoute une file d’attente, récupère les tâches entrantes, recrée l’environnement, exécute la tâche et renvoie les scalaires et les graphiques au gestionnaire d’expériences.

Transforme n’importe quelle machine — une VM cloud, une machine GPU locale ou un ordinateur portable — en agent ClearML avec :

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

Cloner, modifier et mettre en file d’attente#

Lorsqu’un agent est en cours d’exécution, tu peux lui attribuer directement du travail depuis l’interface :

• 🪄 Fais un clic droit sur une expérience et clone-la.
• 🎯 Modifie ses hyperparamètres.
• ⏳ Fais un clic droit sur la tâche clonée et ajoute-la à une file d’attente cible.

Exécuter une tâche à distance#

Tu peux également signaler par programmation un script en cours d’exécution pour l’exécuter à distance en ajoutant task.execute_remotely() après l’instanciation du logger ClearML. Ajoute la ligne mise en évidence à 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
# ...

Après cette modification, l’exécution du script d’entraînement se poursuit jusqu’à cette ligne, empaquette le code et l’envoie dans la file d’attente.

Workers à mise à l’échelle automatique#

ClearML inclut des autoscalers qui démarrent des machines distantes dans AWS, GCP ou Azure lorsqu’une file d’attente contient des expériences en attente, les transforment en agents ClearML et les arrêtent une fois le travail terminé — tu ne paies ainsi que les ressources de calcul réellement utilisées.

Regarde la vidéo de prise en main ci-dessous :

En savoir plus#

Pour plus d’informations sur l’intégration de ClearML avec les modèles Ultralytics, consulte notre guide d’intégration ClearML et découvre comment améliorer ton workflow MLOps avec d’autres outils de suivi des expériences.