ClearML-Integration

Über ClearML

ClearML ist eine Open-Source MLOps-Plattform, die entwickelt wurde, um Machine-Learning-Workflows zu optimieren und Zeit in der Entwicklung zu sparen.

• 🔨 Verfolge jeden YOLOv5-Trainingsdurchlauf im Experiment-Manager.
• 🔧 Erstelle Versionen und greife auf deine benutzerdefinierten Trainingsdaten mit dem integrierten ClearML Daten-Versionierungstool zu.
• 🔦 Trainiere und überwache YOLOv5-Durchläufe aus der Ferne mit dem ClearML Agent.
• 🔬 Finde das beste mAP mit der ClearML Hyperparameter-Optimierung.
• 🔭 Verwandle dein trainiertes YOLOv5-Modell in eine API mit wenigen Befehlen unter Verwendung von ClearML Serving.

Nutze so viele oder so wenige dieser Tools, wie du benötigst – starte nur mit dem Experiment-Manager 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 Optionen:

• Melde dich für den kostenlosen ClearML Hosted Service an, oder
• Stelle deinen eigenen ClearML server bereit – da er Open-Source ist, bleibt er eine gangbare Option selbst für sensible Daten.

Installiere dann das clearml Python-Paket und verbinde das SDK mit deinem Server:

pip install clearml

Generiere Anmeldedaten unter Settings → Workspace → Create new credentials (oben rechts in der ClearML UI) und führe dann Folgendes aus:

clearml-init

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

🚀 YOLOv5 mit ClearML trainieren

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

pip install clearml

Dies ermöglicht die Integration in das YOLOv5-Trainingsskript. Jeder Trainingsdurchlauf wird von nun an vom ClearML Experiment-Manager erfasst und gespeichert.

Um die Projekt- und Tasknamen 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 Durchlauf erfasst:

• Quellcode und nicht übertragene Änderungen
• Installierte Pakete
• Hyperparameter
• Modell-Checkpoints (nutze --save-period n, um alle n Epochen zu speichern)
• Konsolenausgabe
• Skalare (mAP_0.5, mAP_0.5:0.95, Präzision, Recall, Verluste, Lernraten)
• Maschinendetails, Laufzeit und Erstellungsdatum
• Generierte Diagramme wie das Label-Korrelogramm und die Konfusionsmatrix
• Bilder mit Begrenzungsrahmen pro Epoche
• Mosaik-Visualisierungen pro Epoche
• Validierungsbilder pro Epoche

Alles erscheint in der ClearML UI, sodass du das Training zentral überwachen kannst. Füge benutzerdefinierte Spalten hinzu (z. B. mAP_0.5), um nach dem leistungsstärksten Modell zu sortieren, oder wähle mehrere Experimente aus, um sie direkt miteinander zu vergleichen.

Lies weiter für Hyperparameter-Optimierung und Remote-Ausführung.

🔗 Datensatz-Versionsmanagement

Das Versionieren von Daten getrennt vom Code erleichtert das Abrufen der neuesten Version und sorgt für vollständige Reproduzierbarkeit. Dieses Repository akzeptiert eine Datensatz-Versions-ID, lädt die Daten bei Fehlen automatisch herunter und zeichnet die ID als Task-Parameter auf, sodass du immer weißt, welche Daten in welchem Experiment verwendet wurden.

Bereite deinen Datensatz vor

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

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

Jeder Datensatz funktioniert, solange du diese Struktur beibehältst.

Als Nächstes kopiere die YAML-Datei des Datensatzes in den Datensatz-Root-Ordner – ClearML liest diese Datei, um den Datensatz korrekt zu verwenden. Du kannst dein eigenes YAML schreiben, indem du dem Beispiel-Layout folgst und sicherstellst, dass path, train, test, val, nc und names definiert sind.

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

Lade deinen Datensatz hoch

Um den Datensatz als versionierten ClearML-Datensatz zu registrieren, wechsle in dessen Root-Ordner und führe aus:

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

clearml-data sync ist eine Abkürzung für die folgende Sequenz, 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-Datensatz trainieren

Wenn der Datensatz registriert ist, verweise das Training per ID darauf:

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

👀 Hyperparameter-Optimierung

Mit versionierten Experimenten und Daten kannst du darauf aufbauen. Da jedes verfolgte Experiment die vollständige Umgebung erfasst – Code, installierte Pakete und Konfiguration –, sind Durchläufe vollständig reproduzierbar. ClearML erlaubt es dir, ein Experiment zu klonen, seine Parameter zu ändern und es automatisch erneut auszuführen, was die Grundlage der Hyperparameter-Optimierung (HPO) bildet.

Um HPO lokal auszuführen, verwende das mitgelieferte Skript. Stelle zuerst sicher, dass ein Trainings-Task im Experiment-Manager existiert – das Skript klont ihn und variiert seine Hyperparameter.

Trage die Template-Task-ID in utils/loggers/clearml/hpo.py ein und führe dann aus:

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

Wechsle task.execute_locally() zu task.execute(), um den Job in eine ClearML-Warteschlange zu verschieben, damit ein Remote-Agent ihn übernehmen kann.

🤯 Remote-Ausführung (Fortgeschritten)

Die lokale Ausführung von HPO ist bequem, aber oft möchtest du Experimente auf leistungsstärkerer Hardware ausführen – eine On-Premise GPU-Maschine oder eine Cloud-Instanz. Das ist die Aufgabe des ClearML Agent:

• YouTube-Übersicht
• Dokumentation

Jedes verfolgte Experiment enthält alles, was zur Reproduktion auf einer anderen Maschine benötigt wird (installierte Pakete, nicht übertragene Änderungen und Konfiguration). Ein ClearML-Agent hört auf eine Warteschlange, nimmt eingehende Tasks entgegen, stellt die Umgebung wieder her, führt den Job aus und streamt Skalare und Diagramme zurück an den Experiment-Manager.

Verwandle jede Maschine – eine Cloud-VM, eine lokale GPU-Box oder einen Laptop – mit folgendem Befehl in einen ClearML-Agenten:

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

Klonen, Bearbeiten und Einreihen

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

• 🪄 Rechtsklick auf ein Experiment und klone es.
• 🎯 Bearbeite die Hyperparameter.
• ⏳ Rechtsklick auf den geklonten Task und füge ihn einer Ziel-Warteschlange hinzu.

Einen Task remote ausführen

Du kannst ein laufendes Skript auch programmatisch 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 das Ausführen des Trainingsskripts den Code bis zu dieser Zeile aus, packt den Code und sendet ihn an die Warteschlange.

Automatische Skalierung von Workern

ClearML wird mit Autoscalern geliefert, die Remote-Maschinen in AWS, GCP oder Azure hochfahren, wenn eine Warteschlange anstehende Experimente hat, sie in ClearML-Agenten umwandeln und wieder herunterfahren, wenn die Arbeit erledigt ist – so zahlst du nur für die Rechenleistung, die tatsächlich genutzt wird.

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

Mehr erfahren

Für weitere Informationen zur Integration von ClearML mit Ultralytics-Modellen sieh dir unseren ClearML-Integrationsleitfaden an und entdecke, wie du deinen MLOps-Workflow mit anderen Tools zur Experiment-Verfolgung verbessern kannst.