Integrazione con ClearML#

Informazioni su ClearML#

ClearML è una piattaforma MLOps open source progettata per semplificare i flussi di lavoro di machine learning e ridurre il tempo dedicato all'ingegneria.

• 🔨 Tieni traccia di ogni esecuzione di training di YOLOv5 nel gestore degli esperimenti.
• 🔧 Crea versioni e accedi ai tuoi dati di training personalizzati con lo strumento di versionamento dei dati integrato di ClearML.
• 🔦 Esegui e monitora da remoto le esecuzioni di YOLOv5 utilizzando ClearML Agent.
• 🔬 Trova il mAP migliore con l'ottimizzazione degli iperparametri di ClearML.
• 🔭 Trasforma il tuo modello YOLOv5 in un'API con pochi comandi utilizzando ClearML Serving.

Usa tanti o pochi di questi strumenti quanti te ne servono: inizia solo con il gestore degli esperimenti oppure collegali tutti in una pipeline completa.

🦾 Configurazione#

ClearML deve comunicare con un server per tenere traccia dei tuoi esperimenti e dei tuoi dati. Hai due opzioni:

• Registrati al servizio ClearML Hosted gratuito, oppure
• Implementa il tuo server ClearML: essendo open source, resta un'opzione valida anche per i dati sensibili.

Quindi installa il pacchetto Python clearml e collega l'SDK al tuo server:

pip install clearml

Genera le credenziali in Impostazioni → Workspace → Crea nuove credenziali (in alto a destra nell'interfaccia utente di ClearML), quindi esegui:

clearml-init

Segui le istruzioni. Fatto: la configurazione è completa.

🚀 Training di YOLOv5 con ClearML#

Per abilitare il monitoraggio degli esperimenti, installa il pacchetto pip di ClearML se non l'hai già fatto:

pip install clearml

Questo abiliterà l'integrazione con lo script di training di YOLOv5. D'ora in poi, ogni esecuzione di training verrà acquisita e archiviata dal gestore degli esperimenti di ClearML.

Per personalizzare i nomi del progetto e dell'attività, passa --project e --name a train.py. I valori predefiniti sono YOLOv5 e Training. ClearML utilizza / come delimitatore dei sottoprogetti, quindi evita / nei nomi dei progetti personalizzati.

python train.py --img 640 --batch 16 --epochs 3 --data coco8.yaml --weights yolov5s.pt --cache

Oppure con nomi personalizzati:

python train.py --project my_project --name my_training --img 640 --batch 16 --epochs 3 --data coco8.yaml --weights yolov5s.pt --cache

Ogni esecuzione acquisisce:

• Codice sorgente e modifiche non sottoposte a commit
• Pacchetti installati
• Iperparametri
• Checkpoint del modello (usa --save-period n per salvare ogni n epoche)
• Output della console
• Valori scalari (mAP_0.5, mAP_0.5:0.95, precisione, recall, perdite, learning rate)
• Dettagli della macchina, durata dell'esecuzione e data di creazione
• Grafici generati, come il correlogramma delle etichette e la matrice di confusione
• Immagini con riquadri di delimitazione per epoca
• Visualizzazioni a mosaico per epoca
• Immagini di validazione per epoca

Tutto viene visualizzato nell'interfaccia utente di ClearML, così puoi monitorare il training in un unico posto. Aggiungi colonne personalizzate (ad esempio, mAP_0.5) per ordinare i modelli in base alle prestazioni migliori, oppure seleziona più esperimenti per confrontarli fianco a fianco.

Continua a leggere per scoprire l'ottimizzazione degli iperparametri e l'esecuzione remota.

🔗 Gestione delle versioni dei dataset#

Il versionamento dei dati separatamente dal codice semplifica il recupero della versione più recente e garantisce la completa riproducibilità. Questo repository accetta l'ID di una versione del dataset, recupera automaticamente i dati se mancanti e registra l'ID come parametro dell'attività, così sai sempre quali dati sono stati utilizzati in ciascun esperimento.

Prepara il tuo dataset#

Il repository YOLOv5 supporta molti dataset tramite file di configurazione YAML. Per impostazione predefinita, i dataset vengono scaricati nella cartella ../datasets relativa alla radice del repository. Dopo aver scaricato coco128, la struttura delle cartelle è la seguente:

..
|_ yolov5
|_ datasets
    |_ coco128
        |_ images
        |_ labels
        |_ LICENSE
        |_ README.txt

È possibile utilizzare qualsiasi dataset, purché venga mantenuta questa struttura.

Quindi, copia il file YAML del dataset nella cartella radice del dataset: ClearML legge questo file per utilizzare correttamente il dataset. Puoi scrivere il tuo YAML seguendo la struttura di esempio e assicurandoti che definisca path, train, test, val, nc e names.

..
|_ yolov5
|_ datasets
    |_ coco128
        |_ images
        |_ labels
        |_ coco128.yaml  # <---- HERE
        |_ LICENSE
        |_ README.txt

Carica il tuo dataset#

Per registrare il dataset come dataset ClearML con versionamento, spostati nella relativa cartella radice ed esegui:

cd ../datasets/coco128
clearml-data sync --project YOLOv5 --name coco128 --folder .

clearml-data sync è una forma abbreviata della sequenza seguente, che puoi anche eseguire esplicitamente:

# Add --parent <parent_dataset_id> to base this version on a previous one.
# Duplicate files are not re-uploaded.
clearml-data create --name coco128 --project YOLOv5
clearml-data add --files .
clearml-data close

Esegui il training su un dataset ClearML#

Dopo aver registrato il dataset, indirizza il training a esso tramite l'ID:

python train.py --img 640 --batch 16 --epochs 3 --data clearml://YOUR_DATASET_ID --weights yolov5s.pt --cache

👀 Ottimizzazione degli iperparametri#

Dopo aver creato le versioni di esperimenti e dati, puoi basarti su di esse. Poiché ogni esperimento monitorato acquisisce l'intero ambiente — codice, pacchetti installati e configurazione — le esecuzioni sono completamente riproducibili. ClearML ti consente di clonare un esperimento, modificarne i parametri e rieseguirlo automaticamente: questa è la base dell'ottimizzazione degli iperparametri (HPO).

Per eseguire l'HPO localmente, usa lo script incluso. Prima assicurati che nel gestore degli esperimenti esista un'attività di training: lo script la clona e varia i relativi iperparametri.

Inserisci l'ID dell'attività modello in utils/loggers/clearml/hpo.py, quindi esegui:

# Install Optuna or change the optimizer to RandomSearch.
pip install optuna
python utils/loggers/clearml/hpo.py

Per eseguire invece i test su agenti remoti, sostituisci optimizer.start_locally() con optimizer.start() e imposta execution_queue nella chiamata a HyperParameterOptimizer sulla coda in cui gli agenti sono in ascolto.

🤯 Esecuzione remota (avanzata)#

Eseguire l'HPO localmente è comodo, ma spesso vorrai eseguire gli esperimenti su hardware più potente, come una macchina GPU on-premise o un'istanza cloud. Questo è il ruolo del ClearML Agent:

• Panoramica su YouTube
• Documentazione

Ogni esperimento monitorato contiene tutto il necessario per riprodurlo su un'altra macchina (pacchetti installati, modifiche non sottoposte a commit e configurazione). Un agent ClearML ascolta una coda, preleva le attività in arrivo, ricrea l'ambiente, esegue il job e trasmette valori scalari e grafici al gestore degli esperimenti.

Trasforma qualsiasi macchina — una VM cloud, una macchina locale con GPU o un laptop — in un agent ClearML con:

clearml-agent daemon --queue QUEUES_TO_LISTEN_TO [--docker]

Clonazione, modifica e accodamento#

Con un agent in esecuzione, puoi assegnargli direttamente il lavoro dall'interfaccia utente:

• 🪄 Fai clic con il pulsante destro del mouse su un esperimento e clonalo.
• 🎯 Modifica i relativi iperparametri.
• ⏳ Fai clic con il pulsante destro del mouse sull'attività clonata e accodala a una coda di destinazione.

Esecuzione remota di un'attività#

Puoi anche contrassegnare programmaticamente uno script in esecuzione per l'esecuzione remota aggiungendo task.execute_remotely() dopo l'inizializzazione del logger ClearML. Aggiungi la riga evidenziata a train.py:

# ...
# Loggers
data_dict = None
if RANK in {-1, 0}:
    loggers = Loggers(save_dir, weights, opt, hyp, LOGGER)  # loggers instance
    if loggers.clearml:
        loggers.clearml.task.execute_remotely(queue="my_queue")  # <------ ADD THIS LINE
        # data_dict is None unless the user selected a ClearML dataset, in which case ClearML fills it in.
        data_dict = loggers.clearml.data_dict
# ...

Dopo questa modifica, l'esecuzione dello script di training procederà fino a quella riga, impacchetterà il codice e lo invierà alla coda.

Worker con scalabilità automatica#

ClearML include autoscaler che avviano macchine remote in AWS, GCP o Azure quando una coda contiene esperimenti in attesa, le trasformano in agent ClearML e le arrestano al termine del lavoro: paghi così solo le risorse di calcolo effettivamente in esecuzione.

Guarda il video introduttivo qui sotto:

Scopri di più#

Per ulteriori informazioni sull'integrazione di ClearML con i modelli Ultralytics, consulta la nostra guida all'integrazione di ClearML e scopri come migliorare il tuo flusso di lavoro MLOps con altri strumenti di monitoraggio degli esperimenti.

FAQ#