Gestire il codice di training con le esecuzioni MLflow

Questo articolo descrive le esecuzioni di MLflow per la gestione del training di Machine Learning. Include anche indicazioni su come gestire e confrontare le esecuzioni tra esperimenti.

Un'esecuzione MLflow corrisponde a una singola esecuzione del codice del modello. Ogni esecuzione registra le informazioni seguenti:

• Origine: nome del notebook che ha avviato l'esecuzione o il nome del progetto e il punto di ingresso per l'esecuzione.
  • Versione: hash del commit di Git se il notebook viene archiviato in una cartella Git di Databricks o eseguito da un progetto MLflow. In caso contrario, revisione del notebook.
  • Ora di inizio e fine: ora di inizio e di fine dell'esecuzione.
  • Parametri: parametri del modello salvati come coppie chiave-valore. Entrambe le chiavi e i valori sono stringhe.
  • Metriche: metriche di valutazione del modello salvate come coppie chiave-valore. Il valore è numerico. Ogni metrica può essere aggiornata durante l'esecuzione (ad esempio, per tenere traccia della convergenza della funzione di perdita del modello) e dei record MLflow e consente di visualizzare la cronologia della metrica.
  • Tag: metadati di esecuzione salvati come coppie chiave-valore. È possibile aggiornare i tag durante e dopo il completamento di un'esecuzione. Entrambe le chiavi e i valori sono stringhe.
  • Artefatti: file di output in qualsiasi formato. Ad esempio, è possibile registrare immagini, modelli (ad esempio, un modello scikit-learn selezionato) e file di dati (ad esempio, un file Parquet) come artefatto.

Tutte le esecuzioni di MLflow vengono registrate nell'esperimento attivo. Se non è stato impostato in modo esplicito un esperimento come esperimento attivo, le esecuzioni vengono registrate nell'esperimento del notebook.

Visualizza esecuzioni

È possibile accedere a un'esecuzione dalla relativa pagina dell'esperimento padre o direttamente dal notebook che ha creato l'esecuzione.

Nella tabella delle esecuzioni della pagina dell'esperimento, cliccare l'ora di inizio di un'esecuzione.

Nella barra laterale Esecuzioni esperimenti cliccare l'icona accanto a data e ora.

La schermata di esecuzione mostra i parametri usati per l'esecuzione, le metriche risultanti dall'esecuzione ed eventuali tag o note. Per visualizzare note, parametri, metriche o tag per questa esecuzione, cliccare a sinistra dell'etichetta.

È anche possibile accedere agli artefatti salvati da un'esecuzione in questa schermata.

Frammenti di codice per la previsione

Se si registra un modello da un'esecuzione, il modello viene visualizzato nella sezione Artefatti di questa pagina. Per visualizzare frammenti di codice che illustrano come caricare e usare il modello per eseguire stime sui dataframe Spark e pandas, cliccare il nome del modello.

Visualizzare il notebook o il progetto Git utilizzati per un'esecuzione

Per visualizzare la versione del notebook che ha creato un'esecuzione:

• Nella pagina dell'esperimento cliccare il collegamento nella colonna Origine.
• Nella pagina di esecuzione cliccare il collegamento posto accanto a Origine.
• Nel notebook, accedere alla barra laterale Esecuzioni di esperimenti e cliccare l'icona Notebook nella casella relativa all'esecuzione dell'esperimento.

La versione del notebook associato all'esecuzione viene visualizzata nella finestra principale con una barra di evidenziazione che mostra la data e l'ora dell'esecuzione.

Se l'esecuzione è stata avviata in remoto da un progetto Git, cliccare il collegamento nel campo Git Commit per aprire la versione specifica del progetto usato nell'esecuzione. Il collegamento nel campo Origine apre il ramo principale del progetto Git usato nell'esecuzione.

Aggiungere un tag a un'esecuzione

I tag sono coppie chiave-valore che è possibile creare e usare in un secondo momento per cercare le esecuzioni.

1. Nella pagina di esecuzione cliccare se non è già aperta. Compare la tabella dei tag.

   

2. Cliccare i campi Nome e Valore e digitare la chiave e il valore per il tag.

3. Cliccare Aggiungi.

   

Modificare o eliminare un tag per un'esecuzione

Per modificare o eliminare un tag esistente, usare le icone nella colonna Azioni.

Riprodurre l'ambiente software di un'esecuzione

È possibile riprodurre l'ambiente software esatto per l'esecuzione facendo clic su Riproduci esecuzione. Viene visualizzata la seguente finestra di dialogo:

Con le impostazioni predefinite, quando si fa clic su Conferma:

• Il notebook viene clonato nel percorso visualizzato nella finestra di dialogo.
• Se il cluster originale esiste ancora, il notebook clonato viene collegato al cluster originale e il cluster viene avviato.
• Se il cluster originale non esiste più, viene creato e avviato un nuovo cluster con la stessa configurazione, incluse le librerie installate. Il notebook è collegato al nuovo cluster.

È possibile selezionare un percorso diverso per il notebook clonato ed esaminare la configurazione del cluster e le librerie installate:

• Per selezionare una cartella diversa per salvare il notebook clonato, cliccare Modifica cartella.
• Per visualizzare la specifica del cluster, cliccare Visualizza specifica. Per clonare solo il notebook e non il cluster, deselezionare questa opzione.
• Per visualizzare le librerie installate nel cluster originale, cliccare Visualizza librerie. Se non è importante installare le stesse librerie del cluster originale, deselezionare questa opzione.

Gestire le esecuzioni

Rinominare l'esecuzione

Per rinominare un'esecuzione, cliccare nell'angolo in alto a destra della pagina di esecuzione e selezionare Rinomina.

Esecuzioni di filtri

È possibile cercare le esecuzioni in base ai valori dei parametri o delle metriche. È anche possibile cercare le esecuzioni in base al tag.

• Per cercare esecuzioni che corrispondono a un'espressione contenente i valori di parametro e metrica, immettere una query nel campo di ricerca e cliccare Cerca. Alcuni esempi di sintassi di query sono:

  metrics.r2 > 0.3

  params.elasticNetParam = 0.5

  params.elasticNetParam = 0.5 AND metrics.avg_areaUnderROC > 0.3

  MIN(metrics.rmse) <= 1

  MAX(metrics.memUsage) > 0.9

  LATEST(metrics.memUsage) = 0 AND MIN(metrics.rmse) <= 1

  Per impostazione predefinita, i valori delle metriche vengono filtrati in base all'ultimo valore registrato. L'uso di MIN o di MAX consente di cercare le esecuzioni rispettivamente in base ai valori minimi o ai valori massimi delle metriche. Solo le esecuzioni registrate dopo agosto 2024 hanno valori di metrica minimi e massimi.

• Per cercare le esecuzioni in base al tag, immettere i tag nel formato: tags.<key>="<value>". I valori stringa devono essere racchiusi tra virgolette come mostrato.

  tags.estimator_name="RandomForestRegressor"

  tags.color="blue" AND tags.size=5

  Sia le chiavi che i valori possono contenere spazi. Se la chiave include spazi, è necessario racchiuderla nei backtick come illustrato.

  tags.`my custom tag` = "my value"
  

È anche possibile filtrare le esecuzioni in base al relativo stato (Attivo o Eliminato) e in base al fatto che una versione del modello sia associata all'esecuzione. A tale scopo, effettuare le selezioni rispettivamente dai menu a discesa Stato e Ora di creazione.

Scarica esecuzioni

1. Selezionare una o più esecuzioni.

2. Cliccare Scarica CSV. Un file CSV contenente i campi seguenti scarica:

   Run ID,Name,Source Type,Source Name,User,Status,<parameter1>,<parameter2>,...,<metric1>,<metric2>,...
   

Eliminazione di esecuzioni

È possibile eliminare le esecuzioni usando l'interfaccia utente di Databricks Mosaic AI applicando la procedura seguente:

1. Nell'esperimento selezionare una o più esecuzioni facendo clic sulla casella di controllo a sinistra dell'esecuzione.
2. Fai clic su Elimina.
3. Se l'esecuzione è un'esecuzione padre, decidere se eliminare anche le esecuzioni discendenti. Questa opzione è selezionata per impostazione predefinita.
4. Cliccare Elimina per confermare. Le esecuzioni eliminate vengono salvate per 30 giorni. Per visualizzare le esecuzioni eliminate, selezionare Eliminato nel campo Stato.

L'eliminazione in blocco viene eseguita in base all'ora di creazione

È possibile usare Python per eliminare in blocco le esecuzioni di un esperimento creato in precedenza a o in corrispondenza di un timestamp UNIX. Usando Databricks Runtime 14.1 o versione successiva, è possibile richiamare l'API mlflow.delete_runs per eliminare le esecuzioni e restituire il numero di esecuzioni eliminate.

Di seguito sono riportati i parametri mlflow.delete_runs:

• experiment_id: ID dell'esperimento contenente le esecuzioni da eliminare.
• max_timestamp_millis: timestamp di creazione massimo in millisecondi del periodo UNIX per l'eliminazione delle esecuzioni. Vengono eliminate solo le esecuzioni create prima o in corrispondenza di questo timestamp.
• max_runs: facoltativo. Intero positivo che indica il numero massimo di esecuzioni da eliminare. Il valore massimo consentito per max_runs è 10000. Se non specificato, max_runs viene impostato automaticamente su 10000.

import mlflow

# Replace <experiment_id>, <max_timestamp_ms>, and <max_runs> with your values.
runs_deleted = mlflow.delete_runs(
  experiment_id=<experiment_id>,
  max_timestamp_millis=<max_timestamp_ms>,
  max_runs=<max_runs>
)
# Example:
runs_deleted = mlflow.delete_runs(
  experiment_id="4183847697906956",
  max_timestamp_millis=1711990504000,
  max_runs=10
)

Usando Databricks Runtime 13.3 LTS o versioni precedenti, è possibile eseguire il codice client seguente in un notebook di Azure Databricks.

from typing import Optional

def delete_runs(experiment_id: str,
                max_timestamp_millis: int,
                max_runs: Optional[int] = None) -> int:
    """
    Bulk delete runs in an experiment that were created prior to or at the specified timestamp.
    Deletes at most max_runs per request.

    :param experiment_id: The ID of the experiment containing the runs to delete.
    :param max_timestamp_millis: The maximum creation timestamp in milliseconds
                                 since the UNIX epoch for deleting runs. Only runs
                                 created prior to or at this timestamp are deleted.
    :param max_runs: Optional. A positive integer indicating the maximum number
                     of runs to delete. The maximum allowed value for max_runs
                     is 10000. If not specified, max_runs defaults to 10000.
    :return: The number of runs deleted.
    """
    from mlflow.utils.databricks_utils import get_databricks_host_creds
    from mlflow.utils.request_utils import augmented_raise_for_status
    from mlflow.utils.rest_utils import http_request

    json_body = {"experiment_id": experiment_id, "max_timestamp_millis": max_timestamp_millis}
    if max_runs is not None:
        json_body["max_runs"] = max_runs
    response = http_request(
        host_creds=get_databricks_host_creds(),
        endpoint="/api/2.0/mlflow/databricks/runs/delete-runs",
        method="POST",
        json=json_body,
    )
    augmented_raise_for_status(response)
    return response.json()["runs_deleted"]

Vedere la documentazione Azure Databricks Experiments API per i parametri e le specifiche dei valori restituiti per l'eliminazione delle esecuzioni in base all'ora di creazione.

Esecuzioni di ripristino

È possibile ripristinare le esecuzioni eliminate in precedenza usando l'interfaccia utente di Databricks Mosaic AI.

1. Nella pagina Esperimento selezionare Eliminato nel campo Stato per visualizzare le esecuzioni eliminate.
2. Selezionare una o più esecuzioni facendo clic sulla casella di controllo a sinistra dell'esecuzione.
3. Cliccare Ripristina.
4. Cliccare Ripristina per confermare. Per visualizzare le esecuzioni ripristinate, selezionare Attivo nel campo Stato.

Il ripristino in blocco viene eseguito in base al tempo di eliminazione

È anche possibile usare Python per ripristinare in blocco le esecuzioni di un esperimento eliminato in corrispondenza o dopo un timestamp UNIX. Usando Databricks Runtime 14.1 o versione successiva, è possibile chiamare l'API mlflow.restore_runs per ripristinare le esecuzioni e restituire il numero di esecuzioni ripristinate.

Di seguito sono riportati i parametri mlflow.restore_runs:

• experiment_id: ID dell'esperimento contenente le esecuzioni da ripristinare.
• min_timestamp_millis: timestamp di eliminazione minimo in millisecondi dall'epoca UNIX per il ripristino delle esecuzioni. Vengono eseguite solo le esecuzioni eliminate in corrispondenza o dopo il ripristino di questo timestamp.
• max_runs: facoltativo. Numero intero positivo che indica il numero massimo di esecuzioni da ripristinare. Il valore massimo consentito per max_runs è 10000. Se non specificato, max_runs viene impostato automaticamente su 10000.

import mlflow

# Replace <experiment_id>, <min_timestamp_ms>, and <max_runs> with your values.
runs_restored = mlflow.restore_runs(
  experiment_id=<experiment_id>,
  min_timestamp_millis=<min_timestamp_ms>,
  max_runs=<max_runs>
)
# Example:
runs_restored = mlflow.restore_runs(
  experiment_id="4183847697906956",
  min_timestamp_millis=1711990504000,
  max_runs=10
)

Usando Databricks Runtime 13.3 LTS o versioni precedenti, è possibile eseguire il codice client seguente in un notebook di Azure Databricks.

from typing import Optional

def restore_runs(experiment_id: str,
                 min_timestamp_millis: int,
                 max_runs: Optional[int] = None) -> int:
    """
    Bulk restore runs in an experiment that were deleted at or after the specified timestamp.
    Restores at most max_runs per request.

    :param experiment_id: The ID of the experiment containing the runs to restore.
    :param min_timestamp_millis: The minimum deletion timestamp in milliseconds
                                 since the UNIX epoch for restoring runs. Only runs
                                 deleted at or after this timestamp are restored.
    :param max_runs: Optional. A positive integer indicating the maximum number
                     of runs to restore. The maximum allowed value for max_runs
                     is 10000. If not specified, max_runs defaults to 10000.
    :return: The number of runs restored.
    """
    from mlflow.utils.databricks_utils import get_databricks_host_creds
    from mlflow.utils.request_utils import augmented_raise_for_status
    from mlflow.utils.rest_utils import http_request
    json_body = {"experiment_id": experiment_id, "min_timestamp_millis": min_timestamp_millis}
    if max_runs is not None:
        json_body["max_runs"] = max_runs
    response = http_request(
        host_creds=get_databricks_host_creds(),
        endpoint="/api/2.0/mlflow/databricks/runs/restore-runs",
        method="POST",
        json=json_body,
    )
    augmented_raise_for_status(response)
    return response.json()["runs_restored"]

Vedere la documentazione Azure Databricks Experiments API per i parametri e le specifiche dei valori restituiti per il ripristino delle esecuzioni in base al tempo di eliminazione.

Confrontare le esecuzioni

È possibile confrontare le esecuzioni da un singolo esperimento o da più esperimenti. La pagina Confronto esecuzioni presenta informazioni sulle esecuzioni selezionate in formati grafici e tabulari. È anche possibile creare visualizzazioni di risultati di esecuzione e tabelle di informazioni sull'esecuzione, parametri di esecuzione e metriche.

Per creare una visualizzazione:

1. Selezionare il tipo di tracciato (Tracciato delle coordinate parallele, Grafico a dispersione o Tracciato di contorno).

   1. Per un Tracciato delle coordinate parallele, selezionare i parametri e le metriche da tracciare. Da qui è possibile identificare le relazioni tra i parametri selezionati e le metriche, che consentono di definire meglio lo spazio di ottimizzazione degli iperparametri per i modelli.

      

   2. Per un grafico a dispersione o un un tracciato di contorno, selezionare il parametro o la metrica da visualizzare su ogni asse.

Le tabelle Parametri e Metriche visualizzano i parametri di esecuzione e le metriche di tutte le esecuzioni selezionate. Le colonne di queste tabelle sono identificate dalla tabella Dettagli esecuzione immediatamente sopra. Per semplicità, è possibile nascondere parametri e metriche identici in tutte le esecuzioni selezionate attivando o disattivando .

Confrontare le esecuzioni da un singolo esperimento

1. Nella pagina dell'esperimento selezionare due o più esecuzioni facendo clic sulla casella di controllo a sinistra dell'esecuzione oppure selezionando tutte le esecuzioni selezionando la casella nella parte superiore della colonna.
2. Cliccare Confronta. Viene visualizzata la schermata Confronto <N> esecuzioni.

Confrontare le esecuzioni ottenute da più esperimenti

1. Nella pagina degli esperimenti selezionare gli esperimenti da confrontare facendo clic nella casella a sinistra del nome dell'esperimento.
2. Cliccare Confronta (n) (dove n è il numero di esperimenti selezionati). Viene visualizzata una schermata che mostra tutte le esecuzioni degli esperimenti selezionati.
3. Selezionare due o più esecuzioni facendo clic sulla casella di controllo a sinistra dell'esecuzione oppure selezionando tutte le esecuzioni attivando la casella nella parte superiore della colonna.
4. Cliccare Confronta. Viene visualizzata la schermata Confronto <N> esecuzioni.

Copia delle esecuzioni tra aree di lavoro

Per importare o esportare esecuzioni MLflow nell'area di lavoro di Databricks, è possibile usare il progetto open source basato sulla community MLflow Export-Import.