Link to this sectionTracciamento degli esperimenti con Neptune#

Neptune è un archivio di metadati per MLOps, progettato per team che gestiscono molti esperimenti. Ti offre un unico luogo per registrare, archiviare, visualizzare, organizzare, confrontare e interrogare tutti i metadati relativi alla creazione dei tuoi modelli.

Ultralytics YOLO26 si integra con Neptune per semplificare il tracciamento degli esperimenti. Questa integrazione ti consente di registrare automaticamente le metriche di training, visualizzare le predizioni del modello e archiviare gli artefatti del modello senza scrivere codice di logging personalizzato.

Link to this sectionCaratteristiche principali#

• Logging automatizzato: registra automaticamente metriche chiave del training 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.
• Checkpoint dei modelli: carica ed effettua il versionamento dei pesi del modello addestrato (best.pt) automaticamente al termine del training.
• 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.

Link to this sectionInstallazione#

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

Link to this sectionConfigurazione#

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.

Link to this sectionOttieni 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.

Link to this sectionImposta 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 training; in caso contrario, Neptune cercherà di utilizzare il valore predefinito letterale "Ultralytics" e l'esecuzione fallirà.

export NEPTUNE_API_TOKEN="your_long_api_token_here" # required

Link to this sectionUtilizzo#

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.

Link to this sectionEsempio 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")

Link to this sectionComprendere 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

Link to this sectionCosa 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, dfl_loss, lr (learning rate).
   • Metriche: precision, recall, mAP50, mAP50-95.
4. Immagini:
   • Mosaic: batch di training che mostrano l'aumento dei dati (data augmentation).
   • 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.

Link to this sectionUtilizzo avanzato#

Link to this sectionOrganizzazione delle esecuzioni (Runs)#

Puoi usare 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: funge da identificatore per la specifica esecuzione.

Link to this sectionLogging 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.

Link to this sectionFAQ#

Link to this sectionCome posso disabilitare 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

Link to this sectionLe mie immagini non vengono caricate. Qual è il problema?#

Assicurati che la tua rete consenta le connessioni ai server di Neptune. Inoltre, il logging delle immagini avviene solitamente a intervalli specifici (ad esempio, alla fine delle epoche o del training). Se interrompi il training prematuramente usando Ctrl+C, alcuni artefatti finali come le matrici di confusione o i pesi del modello migliore potrebbero non essere caricati.

Link to this sectionPosso registrare verso un ID esecuzione di Neptune specifico?#

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

Link to this sectionDove posso trovare i pesi del modello in Neptune?#

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