Tracciamento degli esperimenti con Neptune#

Neptune è un archivio di metadati per MLOps, creato per i team che eseguono molti esperimenti. Ti offre un unico luogo in cui registrare, archiviare, visualizzare, organizzare, confrontare e interrogare tutti i metadati di creazione del modello.

Ultralytics YOLO26 si integra con Neptune per semplificare il experiment tracking. Questa integrazione ti consente di registrare automaticamente le metriche di addestramento, visualizzare le predizioni del modello e archiviare gli artefatti del modello senza scrivere codice di registrazione personalizzato.

Caratteristiche principali#

• Automated Logging: registra automaticamente le metriche chiave dell'addestramento come box loss, classification loss e mAP.
• Visualizzazione delle immagini: visualizza i mosaici di training e le predizioni di validazione direttamente nella dashboard di Neptune.
• Model Checkpointing: carica ed esegui il controllo di versione dei pesi del modello addestrato (best.pt) automaticamente alla fine dell'addestramento.
• Tracciamento degli iperparametri: registra tutti i parametri di configurazione per garantire la totale riproducibilità dei tuoi esperimenti.
• Grafici interattivi: visualizza le matrici di confusione e le curve precision-recall per analizzare le prestazioni del modello.

Installazione#

Per utilizzare Neptune con Ultralytics, dovrai installare il pacchetto client neptune insieme a ultralytics.

# Install the required packages
pip install ultralytics neptune

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

Configurazione#

Prima di iniziare il training, devi collegare il tuo ambiente locale al tuo progetto Neptune. Avrai bisogno del tuo API Token e del Project Name dalla tua dashboard Neptune.

Ottieni le tue credenziali#

1. Accedi a Neptune.ai.
2. Crea un nuovo progetto (o selezionane uno esistente).
3. Vai al tuo menu utente e ottieni il tuo API Token.

Imposta le variabili d'ambiente#

Il modo più sicuro per gestire le credenziali è tramite le variabili d'ambiente. Nota che la callback Neptune di Ultralytics legge l'argomento YOLO project e non usa NEPTUNE_PROJECT. Passa lo slug Neptune completo (es. workspace/name) tramite project= nel tuo comando di addestramento; altrimenti Neptune proverà a usare il valore predefinito letterale "Ultralytics" e l'esecuzione fallirà.

export NEPTUNE_API_TOKEN="your_long_api_token_here" # required

Utilizzo#

Una volta configurato, puoi iniziare ad addestrare i tuoi modelli YOLO26. L'integrazione di Neptune funziona automaticamente quando il pacchetto neptune è installato e l'integrazione è abilitata nelle impostazioni.

Esempio di addestramento#

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

Comprendere l'integrazione#

Il seguente diagramma illustra come la pipeline di training di Ultralytics interagisce con Neptune per registrare vari artefatti e metriche.

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

Cosa viene registrato?#

Quando esegui il comando di training, l'integrazione con Neptune acquisisce automaticamente la seguente struttura dati nella tua esecuzione:

1. Configurazione/Iperparametri: tutti gli argomenti di training (epochs, lr0, optimizer, ecc.) vengono registrati nella sezione Configuration.
2. Configurazione/Modello: l'architettura e la definizione del modello.
3. Metriche:
   • Train: box_loss, cls_loss, l1_loss (dfl_loss sui modelli basati su DFL), lr (tasso di apprendimento).
   • Metrics: precision, recall, mAP50, mAP50-95.
4. Immagini:
   • Mosaic: batch di addestramento che mostrano l'aumento dei dati.
   • Validation: etichette di ground truth e predizioni del modello sui dati di validazione.
   • Plots: matrici di confusione, curve Precision-Recall.
5. Weights: il modello addestrato finale (best.pt) viene caricato nella cartella weights nell'esecuzione di Neptune.

Utilizzo avanzato#

Organizzazione delle esecuzioni (Runs)#

Puoi utilizzare i normali argomenti Ultralytics project e name per organizzare le tue esecuzioni in Neptune.

• project: deve essere lo slug del progetto Neptune workspace/name; questo è ciò che la callback passa a neptune.init_run.
• name: funge da identificatore per la specifica esecuzione.

Logging personalizzato#

Se hai bisogno di registrare metriche personalizzate aggiuntive insieme al logging automatico, puoi accedere all'istanza dell'esecuzione Neptune. Nota che dovrai modificare la logica del trainer o creare un callback personalizzato per accedere allo specifico oggetto dell'esecuzione, poiché l'integrazione di Ultralytics gestisce internamente il ciclo di vita dell'esecuzione.

FAQ#