Registrare metriche, parametri e file con MLflow

SI APPLICA A: SDK di Python azure-ai-ml v2 (corrente)

Azure Machine Learning supporta la registrazione e il monitoraggio degli esperimenti tramite il rilevamento di MLflow. È possibile registrare modelli, metriche, parametri e artefatti con MLflow, localmente nel computer o in un ambiente cloud.

Importante

A differenza di Azure Machine Learning SDK v1, non esiste alcuna funzionalità di registrazione in Azure Machine Learning SDK per Python (v2). Se in precedenza è stato usato Azure Machine Learning SDK v1, è consigliabile sfruttare MLflow per tenere traccia degli esperimenti. Per indicazioni specifiche, vedere Eseguire la migrazione della registrazione dall'SDK v1 a MLflow.

I log consentono di diagnosticare gli errori e gli avvisi o di tenete traccia di metriche delle prestazioni come parametri e prestazioni modello. Questo articolo illustra come abilitare la registrazione negli scenari seguenti:

• Registrare metriche, parametri e modelli durante l'invio di processi.
• Tenere traccia delle esecuzioni quando si esegue il training in modo interattivo.
• Registrare le metriche in modo asincrono.
• Visualizzare le informazioni di diagnostica sul training.

Suggerimento

Questo articolo illustra come monitorare il processo di training dei modelli. Per informazioni sul monitoraggio dell'utilizzo delle risorse e di eventi di Azure Machine Learning, come quote, processi di training o distribuzioni di modelli completate, vedere Monitoraggio di Azure Machine Learning.

Prerequisiti

• È necessario avere un'area di lavoro di Azure Machine Learning. Se non è disponibile, vedere Creare risorse dell'area di lavoro.

• È necessario che siano installati i pacchetti mlflow e azureml-mlflow. In caso contrario, usare il comando seguente per installarli nell'ambiente di sviluppo:

  pip install mlflow azureml-mlflow
  

  Nota

  Per la registrazione asincrona delle metriche, è necessario avere MLflow la versione 2.8.0+ e azureml-mlflow la versione 1.55+.

• Se si esegue il rilevamento remoto (verifica degli esperimenti eseguiti all'esterno di Azure Machine Learning), configurare MLflow per tenere traccia degli esperimenti. Per altre informazioni, vedere Configurare MLflow per Azure Machine Learning.

• Per registrare metriche, parametri, artefatti e modelli negli esperimenti in Azure Machine Learning usando MLflow, è sufficiente importare MLflow nello script:

  import mlflow
  

Configurare gli esperimenti

MLflow organizza le informazioni negli esperimenti e nelle esecuzioni (in Azure Machine Learning le esecuzioni sono denominate processi). Esistono alcune differenze in come configurarle a seconda della modalità di esecuzione del codice:

Training interattivo

Quando si esegue il training in modo interattivo, ad esempio in un Jupyter Notebook, usare il modello seguente:

1. Creare o impostare l'esperimento attivo.
2. Avviare il processo.
3. Usare i metodi di registrazione per registrare le metriche e altre informazioni.
4. Terminare il processo.

Ad esempio, il frammento di codice seguente configura l'esperimento e quindi registra durante un processo:

import mlflow
# Set the experiment
mlflow.set_experiment("mlflow-experiment")

# Start the run
mlflow_run = mlflow.start_run()
# Log metrics or other information
mlflow.log_metric('mymetric', 1)
# End run 
mlflow.end_run()

Suggerimento

Tecnicamente non è necessario chiamare start_run() perché, se non esiste e si chiama un'API di registrazione, viene creata una nuova esecuzione. In tal caso, è possibile usare mlflow.active_run() per recuperare l'esecuzione attualmente in uso. Per altre informazioni, vedere mlflow.active_run().

È anche possibile usare il paradigma del gestore del contesto:

import mlflow
mlflow.set_experiment("mlflow-experiment")

# Start the run, log metrics, end the run
with mlflow.start_run() as run:
    # Run started when context manager is entered, and ended when context manager exits
    mlflow.log_metric('mymetric', 1)
    mlflow.log_metric('anothermetric',1)
    pass

Quando si avvia una nuova esecuzione con mlflow.start_run, può essere utile indicare il parametro run_name, che viene quindi convertito nel nome dell'esecuzione nell'interfaccia utente di Azure Machine Learning e consente di identificare più rapidamente l'esecuzione:

with mlflow.start_run(run_name="iris-classifier-random-forest") as run:
    mlflow.log_metric('mymetric', 1)
    mlflow.log_metric('anothermetric',1)

Per altre informazioni sulle API di registrazione MLflow, vedere le informazioni di riferimento su MLflow.

Formazione con i processi

Quando si eseguono processi di training in Azure Machine Learning, non è necessario chiamare mlflow.start_run perché le esecuzioni vengono avviate automaticamente. Di conseguenza, è possibile usare le funzionalità di rilevamento MLflow direttamente negli script di training:

import mlflow

mlflow.autolog()

mlflow.log_metric('mymetric', 1)
mlflow.log_metric('anothermetric',1)

Suggerimento

Quando si inviano processi usando l'interfaccia della riga di comando di Azure Machine Learning v2, è possibile impostare il nome dell'esperimento usando la proprietà experiment_name nella definizione YAML del processo. Non è necessario configurarlo nello script di training. Per informazioni dettagliate, vedere YAML: nome visualizzato, nome dell'esperimento, descrizione e tag.

Parametri del log

MLflow supporta i parametri di registrazione usati dagli esperimenti. I parametri possono essere di qualsiasi tipo e possono essere registrati usando la sintassi seguente:

mlflow.log_param("num_epochs", 20)

MLflow offre anche un modo pratico per registrare più parametri indicandoli tutti usando un dizionario. Diversi framework possono anche passare parametri ai modelli usando dizionari e quindi questo è un modo pratico per registrarli nell'esperimento.

params = {
    "num_epochs": 20,
    "dropout_rate": .6,
    "objective": "binary_crossentropy"
}

mlflow.log_params(params)

Metriche di log

Le metriche, invece dei parametri, sono sempre numeriche e possono essere registrate in modo sincrono o asincrono. Quando vengono registrate le metriche, sono immediatamente disponibili per l'utilizzo al ritorno delle chiamate. La tabella seguente descrive come registrare tipi numerici specifici:

Valore registrato	Codice di esempio	Note
Registrare un valore numerico (int o float)	mlflow.log_metric("my_metric", 1)
Registrare un valore numerico (int o float) nel tempo	mlflow.log_metric("my_metric", 1, step=1)	Usare il parametro step per indicare il passaggio in cui si registra il valore della metrica. Può essere qualsiasi numero intero. Il valore predefinito è zero.
Registrare un valore booleano	mlflow.log_metric("my_metric", 0)	0 = True, 1 = False

Importante

Considerazioni sulle prestazioni: se è necessario registrare più metriche (o più valori per la stessa metrica), evitare di effettuare chiamate a mlflow.log_metric su cicli. È possibile ottenere prestazioni migliori usando la registrazione asincrona con mlflow.log_metric("metric1", 9.42, synchronous=False) o registrando un batch di metriche.

Metriche di log in modo asincrono

MLflow consente anche la registrazione delle metriche in modo asincrono. La registrazione asincrona delle metriche è particolarmente utile nei casi con velocità effettiva elevata in cui processi di training di grandi dimensioni con centinaia di nodi di calcolo potrebbero essere in esecuzione e provare a registrare le metriche contemporaneamente.

La registrazione asincrona delle metriche consente di registrare le metriche e attendere che vengano inserite prima di provare a leggerle. Questo approccio si adatta a routine di training di grandi dimensioni che registrano centinaia di migliaia di valori delle metriche.

MLflow registra le metriche in modo sincrono per impostazione predefinita, tuttavia, è possibile modificare questo comportamento in qualsiasi momento:

import mlflow

mlflow.config.enable_async_logging()

È possibile impostare la stessa proprietà usando una variabile di ambiente:

export MLFLOW_ENABLE_ASYNC_LOGGING=True

Per registrare metriche specifiche in modo asincrono, usare l'API di registrazione MLflow come in genere, ma aggiungere il parametro aggiuntivo synchronous=False.

import mlflow

with mlflow.start_run():
    # (...)
    mlflow.log_metric("metric1", 9.42, synchronous=False)
    # (...)

Quando si usa log_metric(synchronous=False), il controllo viene restituito automaticamente al chiamante dopo che l'operazione è stata accettata. Tuttavia, non esiste alcuna garanzia in quel momento che il valore della metrica è stato salvato in modo permanente.

Importante

Anche con synchronous=False, Azure Machine Learning garantisce l'ordinamento delle metriche.

Se è necessario attendere che un determinato valore venga salvato in modo permanente nel back-end, è possibile usare l'operazione metrica restituita per attenderlo, come illustrato nell'esempio seguente:

import mlflow

with mlflow.start_run():
    # (...)
    run_operation = mlflow.log_metric("metric1", 9.42, synchronous=False)
    # (...)
    run_operation.wait()
    # (...)

È possibile registrare in modo asincrono una metrica alla volta o registrare un batch di metriche, come illustrato nell'esempio seguente:

import mlflow
import time
from mlflow.entities import Metric

with mlflow.start_run() as current_run:
    mlflow_client = mlflow.tracking.MlflowClient()

    metrics = {"metric-0": 3.14, "metric-1": 6.28}
    timestamp = int(time.time() * 1000)
    metrics_arr = [Metric(key, value, timestamp, 0) for key, value in metrics.items()]

    run_operation = mlflow_client.log_batch(
        run_id=current_run.info.run_id,
        metrics=metrics_arr,
        synchronous=False,
    )

L'operazione wait() è disponibile anche quando si registra un batch di metriche:

run_operation.wait()

Non è necessario chiamare wait() le routine se non è necessario l'accesso immediato ai valori delle metriche. Azure Machine Learning attende automaticamente il completamento del processo per verificare se è presente una metrica in sospeso da rendere persistente. Al termine di un processo in Azure Machine Learning, è garantito che tutte le metriche siano persistenti.

Curve di log o elenco di valori

Le curve (o un elenco di valori numerici) possono essere registrate con MLflow registrando la stessa metrica più volte. Nell'esempio seguente viene illustrato come effettuare questa operazione:

list_to_log = [1, 2, 3, 2, 1, 2, 3, 2, 1]
from mlflow.entities import Metric
from mlflow.tracking import MlflowClient
import time

client = MlflowClient()
client.log_batch(mlflow.active_run().info.run_id, 
                 metrics=[Metric(key="sample_list", value=val, timestamp=int(time.time() * 1000), step=0) for val in list_to_log])

Immagini di log

MLflow supporta due modi per registrare le immagini. Entrambi i modi per rendere persistente l'immagine specificata come artefatto all'interno dell'esecuzione.

Valore registrato	Codice di esempio	Note
Metriche di log o oggetti immagine PIL	mlflow.log_image(img, "figure.png")	img deve essere un'istanza di numpy.ndarray o PIL.Image.Image. figure.png è il nome dell'artefatto generato all'interno dell'esecuzione. Non deve essere un file esistente.
Registrare un tracciato matlotlib o un file immagine	mlflow.log_figure(fig, "figure.png")	figure.png è il nome dell'artefatto generato all'interno dell'esecuzione. Non deve essere un file esistente.

File di registro

In generale, i file in MLflow sono denominati artefatti. È possibile registrare gli artefatti in diversi modi in Mlflow:

Valore registrato	Codice di esempio	Note
Testo del log in un file di testo	mlflow.log_text("text string", "notes.txt")	Il testo viene salvato in modo permanente all'interno dell'esecuzione in un file di testo con nome notes.txt.
Dizionari di log come file JSON e YAML	mlflow.log_dict(dictionary, "file.yaml"	dictionary è un oggetto dizionario contenente tutta la struttura che si vuole rendere persistente come file JSON o YAML.
Registrare un file semplice già esistente	mlflow.log_artifact("path/to/file.pkl")	I file vengono sempre registrati nella radice dell'esecuzione. Se si specifica artifact_path, il file viene registrato in una cartella, come indicato in tale parametro.
Registrare tutti gli artefatti in una cartella esistente	mlflow.log_artifacts("path/to/folder")	La struttura di cartelle viene copiata nell'esecuzione, ma la cartella radice indicata non è inclusa.

Suggerimento

Quando si registrano file di grandi dimensioni con log_artifact o log_model, è possibile che si verifichino errori di timeout prima del completamento del caricamento del file. Prendere in considerazione l'aumento del valore di timeout modificando la variabile di ambiente AZUREML_ARTIFACTS_DEFAULT_TIMEOUT. Il valore predefinito è 300 (secondi).

Modelli di log

MLflow introduce il concetto di modelli come un modo per creare un pacchetto di tutti gli artefatti necessari per il funzionamento di un determinato modello. I modelli in MLflow sono sempre una cartella con un numero arbitrario di file, a seconda del framework usato per generare il modello. I modelli di registrazione hanno il vantaggio di tenere traccia di tutti gli elementi del modello come singola entità che può essere registrata e quindi distribuita. Oltre a questo, i modelli MLflow godono del vantaggio della distribuzione senza codice e possono essere usati con la dashboard di intelligenza artificiale responsabile in Studio. Per altre informazioni, vedere Da artefatti a modelli in MLflow.

Per salvare il modello da un'esecuzione di training, usare l'API log_model() per il framework usato. Ad esempio, mlflow.sklearn.log_model(). Per altre informazioni, vedere Registrazione di modelli MLflow. Per la migrazione di modelli esistenti a MLflow, vedere Convertire modelli personalizzati in MLflow.

Suggerimento

Quando si registrano modelli di grandi dimensioni, è possibile che venga visualizzato l'errore Failed to flush the queue within 300 seconds. In genere, significa che l'operazione si verifica il timeout prima del completamento del caricamento degli artefatti del modello. Prendere in considerazione l'aumento del valore di timeout modificando la variabile di ambiente AZUREML_ARTIFACTS_DEFAULT_TIMEOUT.

Registrazione automatica

Con Azure Machine Learning e MLflow, gli utenti possono registrare automaticamente metriche, parametri del modello e artefatti del modello durante il training di un modello. Ogni framework decide cosa tenere traccia automaticamente. Sono supportate diverse librerie di apprendimento automatico più diffuse. Altre informazioni sulla registrazione automatica con MLflow.

Per abilitare la registrazione automatica, inserire il codice seguente prima del codice di training:

mlflow.autolog()

Suggerimento

È possibile controllare ciò che viene registrato automaticamente con il log automatico. Ad esempio, se si indica mlflow.autolog(log_models=False), MLflow registra tutti gli elementi tranne i modelli. Questo controllo è utile nei casi in cui si vuole registrare manualmente i modelli, ma è comunque possibile registrare automaticamente metriche e parametri. Si noti anche che alcuni framework potrebbero disabilitare la registrazione automatica dei modelli se il modello sottoposto a training supera limiti specifici. Questo comportamento dipende dalla versione usata, pertanto se ciò si applica al proprio caso, si consiglia di consultare la documentazione.

Visualizzare informazioni sui processi o sulle esecuzioni con MLflow

È possibile visualizzare le informazioni registrate usando MLflow tramite l'oggetto MLflow.entities.Run:

import mlflow

run = mlflow.get_run(run_id="<RUN_ID>")

È possibile visualizzare le metriche, i parametri e i tag per l'esecuzione nel campo dati dell'oggetto run.

metrics = run.data.metrics
params = run.data.params
tags = run.data.tags

Nota

Il dizionario delle metriche restituito da mlflow.get_run o mlflow.search_runs restituisce solo il valore registrato più di recente per un determinato nome di metrica. Ad esempio, se si registra una metrica denominata iteration più volte con valori, 1, 2, quindi 3 e 4, viene restituito solo 4 quando si chiama run.data.metrics['iteration'].

Per ottenere tutte le metriche registrate per un nome di metrica specifico, è possibile usare MlFlowClient.get_metric_history() come illustrato nell'esempio Recupero di parametri e metriche da un'esecuzione.

Suggerimento

MLflow può recuperare metriche e parametri da più esecuzioni contemporaneamente, consentendo confronti rapidi tra più versioni di valutazione. Per altre informazioni, vedere Eseguire query e confrontare esperimenti ed esecuzioni con MLflow.

MLflow può eseguire query su qualsiasi artefatto registrato da un'esecuzione. Non è possibile accedere agli artefatti usando l'oggetto run stesso e il client MLflow deve essere invece usato:

client = mlflow.tracking.MlflowClient()
client.list_artifacts("<RUN_ID>")

Questo metodo elenca tutti gli artefatti registrati nell'esecuzione, ma rimangono archiviati nell'archivio artefatti (archiviazione di Azure Machine Learning). Per scaricarli, usare il metodo download_artifact:

file_path = client.download_artifacts("<RUN_ID>", path="feature_importance_weight.png")

Per altre informazioni, vedere Recupero di metriche, parametri, artefatti e modelli.

Visualizzare informazioni sui processi o sulle esecuzioni in studio

È possibile esplorare i record dei processi completati, incluse le metriche registrate, nello studio di Azure Machine Learning.

Passare alla scheda Processi. Per visualizzare tutti i processi nell'area di lavoro in Esperimenti, selezionare la scheda Tutti i processi. È possibile eseguire il drill-down dei processi per esperimenti specifici applicando il filtro Esperimento nella barra dei menu superiore. Selezionare il processo di interesse per immettere la visualizzazione dei dettagli e quindi selezionare la scheda Metriche.

Selezionare le metriche registrate per eseguire il rendering dei grafici sul lato destro. È possibile personalizzare i grafici applicando lo smoothing, modificando il colore o tracciando più metriche in un singolo grafico. È anche possibile ridimensionare e riorganizzare il layout come desiderato. Dopo aver creato la visualizzazione desiderata, è possibile salvarla per usarla in futuro e condividerla con i membri del team usando un collegamento diretto.

Visualizzare e scaricare i log di diagnostica

I file di log sono una risorsa essenziale per il debug dei carichi di lavoro di Azure Machine Learning. Dopo aver inviato un processo di training, eseguire il drill-down a un'esecuzione specifica per visualizzare i log e gli output:

1. Passare alla scheda Processi.
2. Selezionare il runID per un'esecuzione specifica.
3. Selezionare Output e log nella parte superiore della pagina.
4. Selezionare Scarica tutto per scaricare tutti i log in una cartella ZIP.
5. È anche possibile scaricare singoli file di log scegliendo il file di log e selezionando Scarica

Cartella user_logs

Questa cartella contiene informazioni sui log generati dall'utente. Questa cartella è aperta per impostazione predefinita e viene selezionato il log std_log.txt. std_log.txt è la posizione in cui vengono visualizzati i log del codice (ad esempio, le istruzioni di stampa). Questo file contiene il log stdout e i log stderr dello script di controllo e dello script di training, uno per processo. Nella maggior parte dei casi, è possibile monitorare i log qui.

Cartella system_logs

Questa cartella contiene i log generati da Azure Machine Learning e viene chiuso per impostazione predefinita. I log generati dal sistema vengono raggruppati in cartelle diverse, in base alla fase del processo nel runtime.

Altre cartelle

Per il training dei processi in cluster con più risorse di calcolo, sono presenti log per ogni nodo IP. La struttura per ogni nodo è identica a quella dei processi a nodo singolo. È disponibile una cartella di log per l'esecuzione complessiva, stderr e i log stdout.

Azure Machine Learning registra le informazioni provenienti da varie origini durante il training, ad esempio AutoML o il contenitore Docker che esegue il processo di training. Molti di questi log non sono documentati. Se si verificano problemi e si contatta il supporto tecnico Microsoft, l'agente potrebbe essere in grado di utilizzare questi log durante la risoluzione dei problemi.

Contenuto correlato

• Eseguire il training dei modelli di Machine Learning con MLflow e Azure Machine Learning
• Eseguire la migrazione dalla registrazione dell'SDK v1 al rilevamento MLflow