Migrieren Sie Traces zum neuesten Unity Catalog-Tabellenformat

Wenn Sie ein MLflow-Experiment so konfiguriert haben, dass Ablaufverfolgungen im Unity-Katalog während der Betaversion mithilfe des schemaverknüpften Formats (catalog.schema) gespeichert werden, können Sie diese Ablaufverfolgungen in das mit der Public Preview-Version eingeführte Tabellenpräfixformat (catalog.schema.table_prefix) migrieren.

Databricks empfiehlt das Tabellenpräfix-Format für alle neuen und bestehenden UC-Trace-Workloads. Es bietet schnellere Zeitbereichsabfragen, umfangreichere Attributtypen, eine dedizierte Anmerkungstabelle und Unterstützung für mehrere Ablaufverfolgungsziele pro Schema.

Die Migration kopiert Spannen und Anmerkungen (Tags, Bewertungen, Metadaten) mit Hilfe von Spark SQL.

Identifizieren von Experimenten, die das ältere Format verwenden

Experimente, die Ablaufverfolgungen im Unity-Katalog speichern, verwenden eines von zwei Formaten:

• Schemaverknüpfung (wird während der Betaversion verwendet): Das Ablaufverfolgungsziel des Experiments ist ein zweiteiliger Pfad (catalog.schema). Ablaufverfolgungsdaten werden in Tabellen mit festen Namen wie mlflow_experiment_trace_otel_spans und mlflow_experiment_trace_otel_logs. Tags, Bewertungen und Metadaten werden als Protokollereignisse in der Protokolltabelle gespeichert.
• Tabellenpräfix (wird während der Öffentlichen Vorschauversion und nachfolgend verwendet): Das Ablaufverfolgungsziel des Experiments ist ein dreiteiliger Pfad (catalog.schema.table_prefix). Ablaufverfolgungsdaten werden in Tabellen mit Präfix-Namespace wie <table_prefix>_otel_spans gespeichert, und Anmerkungen verfügen über eine dedizierte Tabelle.

Wenn Ihr Unity-Katalogschema Tabellen mit den Namen mlflow_experiment_trace_otel_spans und mlflow_experiment_trace_otel_logs enthält, wird in Ihrem Experiment das ältere schemaverknüpfte Format verwendet und ist für die Migration berechtigt.

Voraussetzungen

• Ein Unity-Katalog-aktivierter Arbeitsbereich.

• Ein Azure Databricks Cluster mit Databricks Runtime 15.3 oder höher.

• Das paket databricks-agents Python:

  pip install "databricks-agents>=1.10.0"
  

• Die folgenden Berechtigungen:

  • USE_CATALOG und USE_SCHEMA im Quellkatalog und Quellschema.
  • USE_CATALOG, USE_SCHEMA und MODIFY im Zielkatalog und im Zielschema.

Schritt 1: Erstellen eines Zielexperiments

Erstellen Sie ein Experiment, das mit einem Tabellenpräfix-Standort des Unity-Katalogs verknüpft ist. Die migrierten Ablaufverfolgungen werden hier gespeichert. Umfassende Details zur Einrichtung finden Sie unter Einrichtung: Erstellen eines Experiments mit einer Unity Catalog-Ablaufverfolgung-Lokation.

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}")

Speichern Sie die Experiment-ID. Verwenden Sie sie, um Ihre Notizbücher, Aufträge oder bereitgestellten Modelle zu konfigurieren, um Ablaufverfolgungen am neuen Ziel zu protokollieren.

Schritt 2: Umschalten der Ablaufverfolgungsprotokollierung und Stoppen der Schreibvorgänge in das Quellexperiment.

Aktualisieren Sie Ihre Notizbücher, Aufträge oder bereitgestellten Modelle, um Ablaufverfolgungen beim neuen Experiment zu protokollieren, das in Schritt 1 erstellt wurde. Dadurch wird sichergestellt, dass neue Spuren direkt in die Zieltabellen gelangen.

Wenn Sie zuerst eine Trockenausführung ausführen möchten, können Sie diesen Schritt überspringen und die Migration ausführen, ohne Ihre Produktionsworkloads zu wechseln.

Schritt 3: Ausführen der Migration

Führen Sie in einem Azure Databricks Notizbuch im Cluster Folgendes aus:

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()

Ersetzen Sie die Platzhalter:

• <source_catalog>.<source_schema>: Der Unity-Katalogkatalog und das Schema, in dem Ihre Quellablaufverfolgungstabellen gespeichert sind.
• <destination_catalog>.<destination_schema>.<table_prefix>: Das Unity-Katalog-, Schema- und Tabellenpräfix für das Ziel. Dies muss mit dem in Schritt 1 konfigurierten Speicherort übereinstimmen.

Die Migration ist idempotent. Wenn es teilweise fehlschlägt (z. B. wegen eines Clustertimeouts), können Sie den Vorgang sicher erneut ausführen. Bereits migrierte Zeilen werden automatisch übersprungen.

Nach Abschluss der Migration sind Ihre Traces im neuen Zielexperiment verfügbar. Die Quelltabellen werden von der Migration nicht geändert und können als Sicherung aufbewahrt werden.