ClearML-Integration#

Über ClearML#

ClearML ist eine Open-Source-MLOps-Plattform, die entwickelt wurde, um Workflows für maschinelles Lernen zu optimieren und Zeit bei der Entwicklung zu sparen.

• 🔨 Verfolge jeden YOLOv5-Trainingslauf im Experimentmanager.
• 🔧 Verwalte Versionen deiner benutzerdefinierten Trainingsdaten und greife mit dem integrierten ClearML-Tool zur Datenversionierung darauf zu.
• 🔦 Trainiere und überwache YOLOv5-Läufe remote mit dem ClearML Agent.
• 🔬 Finde den besten mAP mit der ClearML-Hyperparameteroptimierung.
• 🔭 Mache dein trainiertes YOLOv5-Modell mit wenigen Befehlen zu einer API – mithilfe von ClearML Serving.

Verwende so viele oder wenige dieser Tools, wie du brauchst – beginne nur mit dem Experimentmanager oder verknüpfe alles zu einer vollständigen Pipeline.

🦾 Einrichtung#

ClearML muss mit einem Server kommunizieren, um deine Experimente und Daten zu verfolgen. Du hast zwei Möglichkeiten:

• Registriere dich für den kostenlosen gehosteten ClearML-Dienst oder
• Stelle deinen eigenen ClearML-Server bereit – er ist Open Source und bleibt daher auch für sensible Daten eine praktikable Option.

Installiere anschließend das clearml-Python-Paket und verbinde das SDK mit deinem Server:

pip install clearml

Erstelle unter Settings → Workspace → Create new credentials (oben rechts in der ClearML-Benutzeroberfläche) Zugangsdaten und führe anschließend Folgendes aus:

clearml-init

Folge den Anweisungen. Das war's – die Einrichtung ist abgeschlossen.

🚀 YOLOv5 mit ClearML trainieren#

Um die Experimentverfolgung zu aktivieren, installiere das ClearML-pip-Paket, falls du es noch nicht getan hast:

pip install clearml

Dadurch wird die Integration in das YOLOv5-Trainingsskript aktiviert. Jeder weitere Trainingslauf wird vom ClearML-Experimentmanager erfasst und gespeichert.

Um die Namen von Projekt und Aufgabe anzupassen, übergib --project und --name an train.py. Die Standardwerte sind YOLOv5 und Training. ClearML verwendet / als Trennzeichen für Unterprojekte. Vermeide daher / in benutzerdefinierten Projektnamen.

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

Oder mit benutzerdefinierten Namen:

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

Jeder Lauf erfasst:

• Quellcode und nicht festgeschriebene Änderungen
• Installierte Pakete
• Hyperparameter
• Modellprüfpunkte (verwende --save-period n, um nach jeweils n Epochen zu speichern)
• Konsolenausgabe
• Skalare (mAP_0.5, mAP_0.5:0.95, Präzision, Trefferquote, Verluste, Lernraten)
• Details zur Maschine, Laufzeit und Erstellungsdatum
• Erstellte Diagramme wie das Label-Korrelogramm und die Konfusionsmatrix
• Bilder mit Begrenzungsrahmen pro Epoche
• Mosaikvisualisierungen pro Epoche
• Validierungsbilder pro Epoche

Alles erscheint in der ClearML-Benutzeroberfläche, sodass du das Training an einer Stelle überwachen kannst. Füge benutzerdefinierte Spalten hinzu (zum Beispiel mAP_0.5), um nach dem leistungsstärksten Modell zu sortieren, oder wähle mehrere Experimente aus, um sie nebeneinander zu vergleichen.

Lies weiter zur Hyperparameteroptimierung und zur Remote-Ausführung.

🔗 Verwaltung von Dataset-Versionen#

Wenn du Daten unabhängig vom Code versionierst, kannst du einfach die neueste Version abrufen und die vollständige Reproduzierbarkeit sicherstellen. Dieses Repository akzeptiert eine Dataset-Versions-ID, ruft die Daten automatisch ab, falls sie fehlen, und speichert die ID als Aufgabenparameter. So weißt du immer, welche Daten in welchem Experiment verwendet wurden.

Dataset vorbereiten#

Das YOLOv5-Repository unterstützt viele Datasets über YAML-Konfigurationsdateien. Standardmäßig werden Datasets relativ zum Stammverzeichnis des Repositorys in den Ordner ../datasets heruntergeladen. Nach dem Herunterladen von coco128 sieht die Ordnerstruktur so aus:

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

Jedes Dataset funktioniert, solange du diese Struktur beibehältst.

Kopiere als Nächstes die YAML-Datei des Datasets in dessen Stammordner – ClearML liest diese Datei ein, um das Dataset korrekt zu verwenden. Du kannst dein eigenes YAML erstellen, indem du dich am Beispielaufbau orientierst und sicherstellst, dass path, train, test, val, nc und names definiert sind.

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

Dataset hochladen#

Um das Dataset als versioniertes ClearML-Dataset zu registrieren, wechsle in dessen Stammordner und führe Folgendes aus:

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

clearml-data sync ist eine Kurzform für die folgende Befehlsfolge, die du auch explizit ausführen kannst:

# 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

Auf einem ClearML-Dataset trainieren#

Nachdem das Dataset registriert wurde, verweise beim Training über seine ID darauf:

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

👀 Hyperparameteroptimierung#

Wenn Experimente und Daten versioniert sind, kannst du darauf aufbauen. Da jedes aufgezeichnete Experiment die vollständige Umgebung erfasst – Code, installierte Pakete und Konfiguration –, sind die Läufe vollständig reproduzierbar. Mit ClearML kannst du ein Experiment klonen, seine Parameter ändern und es automatisch erneut ausführen. Das bildet die Grundlage der Hyperparameteroptimierung (HPO).

Um HPO lokal auszuführen, verwende das mitgelieferte Skript. Stelle zunächst sicher, dass im Experimentmanager eine Trainingsaufgabe vorhanden ist – das Skript klont sie und variiert ihre Hyperparameter.

Trage die ID der Vorlageaufgabe in utils/loggers/clearml/hpo.py ein und führe anschließend Folgendes aus:

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

Ändere task.execute_locally() in task.execute(), um den Auftrag an eine ClearML-Warteschlange zu senden, aus der ihn ein Remote-Agent abholt.

🤯 Remote-Ausführung (erweitert)#

HPO lokal auszuführen ist praktisch, aber häufig möchtest du Experimente auf leistungsfähigerer Hardware ausführen – auf einer GPU-Maschine vor Ort oder einer Cloud-Instanz. Genau dafür ist der ClearML Agent zuständig:

• YouTube-Übersicht
• Dokumentation

Jedes aufgezeichnete Experiment enthält alles, was für die Reproduktion auf einer anderen Maschine erforderlich ist (installierte Pakete, nicht festgeschriebene Änderungen und Konfiguration). Ein ClearML-Agent überwacht eine Warteschlange, übernimmt eingehende Aufgaben, stellt die Umgebung wieder her, führt den Auftrag aus und überträgt Skalare und Diagramme zurück an den Experimentmanager.

Mache jede Maschine – eine Cloud-VM, einen lokalen GPU-Rechner oder einen Laptop – mit folgendem Befehl zu einem ClearML-Agenten:

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

Klonen, Bearbeiten und Einreihen#

Wenn ein Agent läuft, kannst du ihm direkt über die Benutzeroberfläche Arbeit zuweisen:

• 🪄 Klicke mit der rechten Maustaste auf ein Experiment und klone es.
• 🎯 Bearbeite seine Hyperparameter.
• ⏳ Klicke mit der rechten Maustaste auf die geklonte Aufgabe und reihe sie in eine Zielwarteschlange ein.

Aufgabe remote ausführen#

Du kannst ein laufendes Skript auch programmgesteuert für die Remote-Ausführung markieren, indem du nach der Instanziierung des ClearML-Loggers task.execute_remotely() hinzufügst. Füge die hervorgehobene Zeile zu train.py hinzu:

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

Nach dieser Änderung führt die Ausführung des Trainingsskripts die Verarbeitung bis zu dieser Zeile aus, paketiert den Code und sendet ihn an die Warteschlange.

Worker automatisch skalieren#

ClearML enthält Autoscaler, die Remote-Maschinen in AWS, GCP oder Azure starten, sobald eine Warteschlange ausstehende Experimente enthält, diese in ClearML-Agenten umwandeln und nach Abschluss der Arbeit herunterfahren – du bezahlst also nur für tatsächlich laufende Rechenleistung.

Sieh dir unten das Video für den Einstieg an:

Mehr erfahren#

Weitere Informationen zur Integration von ClearML in Ultralytics-Modelle findest du in unserem Leitfaden zur ClearML-Integration. Außerdem erfährst du, wie du deinen MLOps-Workflow mit anderen Tools zur Experimentverfolgung verbessern kannst.