Link to this sectionExperiment-Tracking mit Neptune#

Neptune ist ein Metadatenspeicher für MLOps, der für Teams entwickelt wurde, die viele Experimente durchführen. Er bietet dir einen zentralen Ort zum Protokollieren, Speichern, Anzeigen, Organisieren, Vergleichen und Abfragen all deiner Metadaten zur Modellerstellung.

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 benutzerdefinierten Protokollierungscode schreiben zu müssen.

Link to this sectionHauptfunktionen#

• Automatisierte Protokollierung: Protokolliere automatisch wichtige Trainingsmetriken wie Box-Loss, Klassifizierungs-Loss und mAP.
• Bildvisualisierung: Sieh dir Trainings-Mosaike und Validierungsvorhersagen direkt im Neptune-Dashboard an.
• Modell-Checkpointing: Lade deine trainierten Modellgewichte (best.pt) am Ende des Trainings automatisch hoch und kontrolliere ihre Versionen.
• Hyperparameter-Tracking: Protokolliere alle Konfigurationsparameter, um die vollständige Reproduzierbarkeit deiner Experimente sicherzustellen.
• Interaktive Plots: Visualisiere Konfusionsmatrizen und Precision-Recall-Kurven, um die Modellleistung zu analysieren.

Link to this sectionInstallation#

Um Neptune mit Ultralytics zu nutzen, 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

Link to this sectionKonfiguration#

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

Link to this sectionDeine Anmeldedaten abrufen#

1. Melde dich bei Neptune.ai an.
2. Erstelle ein neues Projekt (oder wähle ein bestehendes aus).
3. Gehe in dein Benutzermenü und rufe dein API-Token ab.

Link to this sectionUmgebungsvariablen festlegen#

Der sicherste Weg, Anmeldedaten zu handhaben, ist über 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

Link to this sectionVerwendung#

Sobald die Konfiguration abgeschlossen 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.

Link to this sectionTrainingsbeispiel#

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")

Link to this sectionDie Integration verstehen#

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

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

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

    G --> H[Neptune Web Dashboard]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef decide fill:#FF9800,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef extern fill:#607D8B,color:#fff

Link to this sectionWas 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: Trainingsbatches, die Datenaugmentation zeigen.
   • Validation: Ground-Truth-Labels und Modellvorhersagen auf Validierungsdaten.
   • Plots: Konfusionsmatrizen, Precision-Recall-Kurven.
5. Gewichte: Das endgültig trainierte Modell (best.pt) wird in den weights-Ordner im Neptune-Lauf hochgeladen.

Link to this sectionFortgeschrittene Nutzung#

Link to this sectionLäufe organisieren#

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

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

Link to this sectionBenutzerdefinierte Protokollierung#

Wenn du neben der automatischen Protokollierung weitere benutzerdefinierte Metriken protokollieren möchtest, kannst du auf die Neptune-Laufinstanz zugreifen. Beachte, dass du die Trainer-Logik ändern oder einen benutzerdefinierten Callback erstellen musst, um auf das spezifische Laufobjekt zuzugreifen, da die Ultralytics-Integration den Lebenszyklus des Laufs intern verwaltet.

Link to this sectionFAQ#

Link to this sectionWie deaktiviere ich die Neptune-Protokollierung?#

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

# Disable Neptune integration
yolo settings neptune=False

Link to this sectionMeine Bilder werden nicht hochgeladen. Was ist los?#

Stelle sicher, dass dein Netzwerk Verbindungen zu den Neptune-Servern zulässt. Zudem erfolgt die Bildprotokollierung normalerweise in bestimmten Intervallen (z. B. am Ende von Epochen oder am 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.

Link to this sectionKann ich an eine spezifische Neptune-Lauf-ID protokollieren?#

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

Link to this sectionWo finde ich die Modellgewichte in Neptune?#

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