Migrare le tracce al formato di tabella più recente del catalogo Unity.

Se è stato configurato un esperimento MLflow per archiviare tracce in Unity Catalog durante la versione beta usando il formato collegato allo schema (catalog.schema), è possibile eseguire la migrazione di tali tracce al formato di prefisso tabella (catalog.schema.table_prefix) introdotto con la versione di anteprima pubblica.

Databricks consiglia il formato di prefisso di tabella per tutti i carichi di lavoro di traccia UC nuovi ed esistenti. Offre query di intervallo di tempo più veloci, tipi di attributi più avanzati, una tabella di annotazioni dedicate e supporto per più destinazioni di traccia per ogni schema.

La migrazione copia intervalli e annotazioni (tag, valutazioni, metadati) utilizzando Spark SQL.

Identificare gli esperimenti che usano il formato precedente

Gli esperimenti che archiviano le tracce in Unity Catalog usano uno dei due formati seguenti:

  • Schema collegato (usato durante la versione beta): la destinazione della traccia dell'esperimento è un percorso composto da due parti (catalog.schema). I dati di traccia vengono archiviati in tabelle con nome fisso come mlflow_experiment_trace_otel_spans e mlflow_experiment_trace_otel_logs. I tag, le valutazioni e i metadati vengono archiviati come eventi di log nella tabella dei log.
  • Prefisso tabella (usato durante la versione di anteprima pubblica e versioni successive): la destinazione di traccia dell'esperimento è un percorso in tre parti (catalog.schema.table_prefix). I dati di traccia vengono archiviati in tabelle con spazi dei nomi con prefisso, ad esempio <table_prefix>_otel_spans, e le annotazioni includono una tabella dedicata.

Se lo schema del catalogo Unity contiene tabelle denominate mlflow_experiment_trace_otel_spans e mlflow_experiment_trace_otel_logs, l'esperimento usa il formato collegato allo schema precedente ed è idoneo per la migrazione.

Prerequisiti

  • Un'area di lavoro abilitata per il Catalogo di Unity.

  • Un cluster Azure Databricks che esegue Databricks Runtime 15.3 o versione successiva.

  • Il pacchetto databricks-agents Python:

    pip install "databricks-agents>=1.10.0"

  • Le autorizzazioni seguenti:

    • USE_CATALOG e USE_SCHEMA nel catalogo sorgente e nello schema.
    • USE_CATALOG, USE_SCHEMA, e MODIFY nel catalogo di destinazione e nello schema.

Passaggio 1: Creare un esperimento di destinazione

Creare un esperimento collegato a una posizione predefinita della tabella di Unity Catalog. Le tracce di cui è stata eseguita la migrazione vengono archiviate qui. Per informazioni dettagliate sull'installazione completa, vedere Setup: Create an experiment with a Unity Catalog trace location (Configurare: Creare un esperimento con un percorso di traccia del catalogo Unity).

import mlflow
from mlflow.entities.trace_location import UnityCatalog

experiment = mlflow.set_experiment(
    experiment_name="/Workspace/Users/<user>/<experiment_name>",
    trace_location=UnityCatalog(
        catalog_name="<destination_catalog>",
        schema_name="<destination_schema>",
        table_prefix="<table_prefix>",
    ),
)

print(f"Experiment ID: {experiment.experiment_id}")

Salvare l'ID dell'esperimento. Utilizzarlo per configurare notebook, compiti o modelli distribuiti, al fine di memorizzare le tracce nella nuova destinazione.

Passaggio 2: Cambiare i log delle tracce e fermare le operazioni di scrittura nell'esperimento di origine

Aggiornare notebook, processi o modelli distribuiti per registrare le tracce al nuovo esperimento creato nel passaggio 1. In questo modo, le nuove tracce passano direttamente alle tabelle di destinazione.

Important

Interrompere tutte le scritture sull'esperimento di origine prima di eseguire la migrazione. Le tracce scritte nelle tabelle di origine durante la migrazione potrebbero non essere copiate. Verificare che nessun notebook, attività o modelli di apprendimento automatico distribuiti registrino attivamente tracce nell'esperimento sorgente.

Se si vuole eseguire prima un'esecuzione a secco, è possibile ignorare questo passaggio ed eseguire la migrazione senza cambiare i carichi di lavoro di produzione.

Passaggio 3: Eseguire la migrazione

In un notebook Azure Databricks nel cluster eseguire quanto segue:

from databricks.migrations.v1_to_v2 import V1ToV2SqlMigration

migration = V1ToV2SqlMigration(
    v1_source_schema="<source_catalog>.<source_schema>",
    v2_destination_prefix="<destination_catalog>.<destination_schema>.<table_prefix>",
)
migration.run()

Sostituire i segnaposto:

  • <source_catalog>.<source_schema>: Il catalogo e lo schema di Unity Catalog in cui sono memorizzate le tabelle di tracciamento dell'origine.
  • <destination_catalog>.<destination_schema>.<table_prefix>: il catalogo Unity Catalog, lo schema e il prefisso di tabella per la destinazione. Deve corrispondere al percorso configurato nel passaggio 1.

La migrazione è idempotente. Se l'operazione ha esito negativo, ad esempio a causa di un timeout del cluster, è possibile eseguirla di nuovo in modo sicuro. Le righe già migrate vengono ignorate automaticamente.

Al termine della migrazione, le tracce sono disponibili nel nuovo esperimento di destinazione. Le tabelle di origine non vengono modificate dalla migrazione e possono essere conservate come backup.

  • Last updated on