Monitoraggio degli esperimenti con Neptune

Neptune è un archivio di metadati per MLOps, costruito per team che eseguono molti esperimenti. Ti fornisce un unico posto per registrare, archiviare, visualizzare, organizzare, confrontare e interrogare tutti i metadati di costruzione del tuo modello.

Ultralytics YOLO26 si integra con Neptune per semplificare il monitoraggio degli esperimenti. 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 logging personalizzato.

Caratteristiche principali

• Logging automatizzato: Registra automaticamente le metriche chiave dell'addestramento come box loss, classification loss e mAP.
• Visualizzazione delle immagini: Visualizza i mosaici di addestramento e le predizioni di validazione direttamente nella dashboard di Neptune.
• Checkpoint del modello: Carica e controlla la versione dei pesi del tuo modello addestrato (best.pt) automaticamente al termine dell'addestramento.
• Monitoraggio degli iperparametri: Registra tutti i parametri di configurazione per garantire la completa 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 l'addestramento, devi connettere il tuo ambiente locale al tuo progetto Neptune. Avrai bisogno del tuo API Token e del Project Name dalla tua dashboard di Neptune.

Ottieni le tue credenziali

1. Accedi a Neptune.ai.
2. Crea un nuovo progetto (o seleziona quello 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 il callback di Neptune per Ultralytics legge l'argomento project di YOLO e non usa NEPTUNE_PROJECT. Passa lo slug completo di Neptune (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 con 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 addestramento di Ultralytics interagisce con Neptune per registrare vari artefatti e metriche.

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]

Cosa viene registrato?

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

1. Configurazione/Iperparametri: Tutti gli argomenti di addestramento (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, dfl_loss, lr (learning rate).
   • Metriche: 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 finale addestrato (best.pt) viene caricato nella cartella weights nell'esecuzione di Neptune.

Utilizzo avanzato

Organizzazione delle esecuzioni

Puoi utilizzare gli argomenti standard di Ultralytics project e name per organizzare le tue esecuzioni in Neptune.

• project: Deve essere lo slug del progetto Neptune workspace/name; questo è ciò che il callback passa a neptune.init_run.
• name: Agisce come identificatore per l'esecuzione specifica.

Logging personalizzato

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

FAQ

Come disabilito il logging di Neptune?

Se hai installato neptune ma desideri disabilitare il logging per una sessione specifica o globalmente, puoi modificare le impostazioni di YOLO.

# Disable Neptune integration
yolo settings neptune=False

Le mie immagini non vengono caricate. Cosa c'è che non va?

Assicurati che la tua rete consenta le connessioni ai server di Neptune. Inoltre, il logging delle immagini avviene solitamente a intervalli specifici (es. fine delle epoche o fine dell'addestramento). Se interrompi l'addestramento in anticipo usando Ctrl+C, alcuni artefatti finali come le matrici di confusione o i pesi del miglior modello potrebbero non essere caricati.

Posso registrare su un ID di esecuzione Neptune specifico?

L'attuale integrazione crea automaticamente una nuova esecuzione per ogni sessione di addestramento. Per riprendere il logging su un'esecuzione esistente, dovresti gestire manualmente l'inizializzazione di Neptune nel codice Python, operazione che esula dallo scopo dell'integrazione automatica. Tuttavia, Ultralytics supporta la ripresa dell'addestramento localmente, il che creerà una nuova esecuzione in Neptune per tracciare le epoche riprese.

Dove posso trovare i pesi del modello in Neptune?

Nella tua dashboard di Neptune, naviga nella sezione Artifacts o All Metadata. Troverai una cartella weights contenente il tuo file best.pt, che puoi scaricare per il deployment.