Experiment-Tracking mit Neptune

Neptune ist ein Metadaten-Speicher für MLOps, der für Teams entwickelt wurde, die viele Experimente durchführen. Er bietet dir einen zentralen Ort, um alle Metadaten deines Modellaufbaus zu protokollieren, zu speichern, anzuzeigen, zu organisieren, zu vergleichen und abzufragen.

Ultralytics YOLO26 lässt sich in Neptune integrieren, um das Experiment-Tracking zu optimieren. Diese Integration ermöglicht es dir, Trainingsmetriken automatisch zu protokollieren, Modellvorhersagen zu visualisieren und Modell-Artefakte zu speichern, ohne eigenen Logging-Code schreiben zu müssen.

Hauptmerkmale

• Automatisiertes Logging: Protokolliere automatisch wichtige Trainingsmetriken wie Box-Loss, Klassifizierungs-Loss und mAP.
• Bild-Visualisierung: Betrachte Trainings-Mosaike und Validierungsvorhersagen direkt im Neptune-Dashboard.
• Modell-Checkpointing: Lade deine trainierten Modellgewichte (best.pt) automatisch am Ende des Trainings hoch und versioniere sie.
• Hyperparameter-Tracking: Protokolliere alle Konfigurationsparameter, um die vollständige Reproduzierbarkeit deiner Experimente zu gewährleisten.
• Interaktive Plots: Visualisiere Konfusionsmatrizen und Precision-Recall-Kurven, um die Modellleistung zu analysieren.

Installation

Um Neptune mit Ultralytics zu verwenden, musst du das neptune-Client-Paket zusammen mit ultralytics installieren.

# Install the required packages
pip install ultralytics neptune

# Enable Neptune integration in Ultralytics settings
yolo settings neptune=True

Konfiguration

Bevor du mit dem Training beginnst, musst du deine lokale Umgebung mit deinem Neptune-Projekt verbinden. Du benötigst dazu deinen API Token und deinen Projektnamen aus deinem Neptune-Dashboard.

Hol dir deine Zugangsdaten

1. Logge dich bei Neptune.ai ein.
2. Erstelle ein neues Projekt (oder wähle ein bestehendes aus).
3. Gehe zu deinem Benutzermenü und rufe deinen API Token ab.

Umgebungsvariablen festlegen

Der sicherste Weg, Zugangsdaten zu handhaben, ist die Verwendung von Umgebungsvariablen. Beachte, dass der Ultralytics-Neptune-Callback das YOLO-project-Argument liest und nicht NEPTUNE_PROJECT verwendet. Übergebe den vollständigen Neptune-Slug (z. B. workspace/name) über project= in deinem Trainingsbefehl; andernfalls versucht Neptune, den Standardwert "Ultralytics" zu verwenden, und der Lauf schlägt fehl.

export NEPTUNE_API_TOKEN="your_long_api_token_here" # required

Verwendung

Sobald alles konfiguriert ist, kannst du mit dem Training deiner YOLO26-Modelle beginnen. Die Neptune-Integration funktioniert automatisch, wenn das neptune-Paket installiert und die Integration in den Einstellungen aktiviert ist.

Trainingsbeispiel

from ultralytics import YOLO

# Load a model
model = YOLO("yolo26n.pt")

# Train the model
# Pass the Neptune project slug as the 'project' argument (workspace/name)
results = model.train(data="coco8.yaml", epochs=10, project="my-workspace/my-project", name="experiment-1")

Verständnis der Integration

Das folgende Diagramm veranschaulicht, wie die Ultralytics-Trainings-Pipeline mit Neptune interagiert, um verschiedene Artefakte und Metriken zu protokollieren.

graph LR
    A[YOLO Training Loop] --> B{Neptune Callback}
    B -->|Log Scalars| C[Loss, mAP, LR]
    B -->|Log Images| D[Mosaics, Preds]
    B -->|Log Artifacts| E[Model Weights]
    B -->|Log Metadata| F[Hyperparameters]

    C --> G[Neptune Server]
    D --> G
    E --> G
    F --> G

    G --> H[Neptune Web Dashboard]

Was wird protokolliert?

Wenn du den Trainingsbefehl ausführst, erfasst die Neptune-Integration automatisch die folgende Datenstruktur in deinem Lauf:

1. Konfiguration/Hyperparameter: Alle Trainingsargumente (Epochen, lr0, Optimizer usw.) werden unter dem Abschnitt Konfiguration protokolliert.
2. Konfiguration/Modell: Die Modellarchitektur und -definition.
3. Metriken:
   • Train: box_loss, cls_loss, dfl_loss, lr (Lernrate).
   • Metriken: precision, recall, mAP50, mAP50-95.
4. Bilder:
   • Mosaic: Trainings-Batches, die Datenaugmentierung zeigen.
   • Validation: Ground-Truth-Labels und Modellvorhersagen auf Validierungsdaten.
   • Plots: Konfusionsmatrizen, Precision-Recall-Kurven.
5. Gewichte: Das finale trainierte Modell (best.pt) wird in den weights-Ordner im Neptune-Lauf hochgeladen.

Fortgeschrittene Nutzung

Läufe organisieren

Du kannst die Standard-Argumente project und name von Ultralytics verwenden, um deine Läufe in Neptune zu organisieren.

• project: Muss der Neptune-Projekt-Slug workspace/name sein; dies ist das, was der Callback an neptune.init_run übergibt.
• name: Dient als Bezeichner für den spezifischen Lauf.

Benutzerdefiniertes Logging

Wenn du neben dem automatischen Logging zusätzliche benutzerdefinierte Metriken protokollieren musst, kannst du auf die Neptune-Laufinstanz zugreifen. Beachte, dass du die Trainer-Logik modifizieren oder einen benutzerdefinierten Callback erstellen musst, um auf das spezifische Lauf-Objekt zuzugreifen, da die Ultralytics-Integration den Lebenszyklus des Laufs intern verwaltet.

FAQ

Wie deaktiviere ich das Neptune-Logging?

Wenn du neptune installiert hast, aber das Logging für eine bestimmte Sitzung oder global deaktivieren möchtest, kannst du die YOLO-Einstellungen anpassen.

# Disable Neptune integration
yolo settings neptune=False

Meine Bilder werden nicht hochgeladen. Was ist falsch?

Stelle sicher, dass dein Netzwerk Verbindungen zu den Neptune-Servern zulässt. Zudem erfolgt das Bild-Logging normalerweise in bestimmten Intervallen (z. B. Ende der Epochen oder Ende des Trainings). Wenn du das Training vorzeitig mit Ctrl+C abbrichst, werden einige endgültige Artefakte wie Konfusionsmatrizen oder die besten Modellgewichte möglicherweise nicht hochgeladen.

Kann ich in eine spezifische Neptune-Run-ID protokollieren?

Die aktuelle Integration erstellt automatisch einen neuen Lauf für jede Trainingssitzung. Um das Logging in einem bestehenden Lauf fortzusetzen, müsstest du die Neptune-Initialisierung normalerweise manuell im Python-Code handhaben, was außerhalb des Rahmens der automatischen Integration liegt. Ultralytics unterstützt jedoch das lokale Fortsetzen des Trainings, wodurch ein neuer Lauf in Neptune erstellt wird, um die fortgesetzten Epochen zu verfolgen.

Wo finde ich die Modellgewichte in Neptune?

Navigiere in deinem Neptune-Dashboard zum Abschnitt Artifacts oder All Metadata. Dort findest du einen weights-Ordner, der deine best.pt-Datei enthält, die du für die Bereitstellung herunterladen kannst.