Migrez les tables de suivi de Unity Catalog héritées vers le format de préfixe de table

Si vous avez configuré une expérimentation MLflow pour stocker les traces dans Unity Catalog à l'aide de l'ancien format lié au schéma (catalog.schema), migrez ces traces vers le format actuel avec préfixe de table (catalog.schema.table_prefix).

Databricks recommande le format de préfixe de table pour toutes les charges de travail de traces UC nouvelles et existantes. Il fournit des requêtes plus rapides sur les plages de temps, des types d'attributs plus riches, une table d'annotations dédiée et un support pour plusieurs destinations de traces par schéma.

La migration copie les étendues et les annotations (balises, évaluations, métadonnées) à l'aide de Spark SQL.

Identifier les expérimentations qui utilisent l'ancien format

Les expérimentations qui stockent des traces dans Unity Catalog utilisent l'un des deux formats :

• Lié au schéma (ancien format) : La destination de la trace de l'expérimentation est un chemin en deux parties (catalog.schema). Les données de trace sont stockées dans des tables à nom fixe comme mlflow_experiment_trace_otel_spans et mlflow_experiment_trace_otel_logs. Les tags, les évaluations et les métadonnées sont stockés en tant qu'événements de log dans la table des logs.
• Préfixe de table (format actuel) : la destination de la trace de l'Experimentation est un chemin en trois parties (catalog.schema.table_prefix). Les données de trace sont stockées dans des tables nommées par préfixe, comme <table_prefix>_otel_spans, et les annotations ont une table dédiée.

Si votre schéma Unity Catalog contient des tables nommées mlflow_experiment_trace_otel_spans et mlflow_experiment_trace_otel_logs, votre Experimentation utilise l'ancien format lié au schéma et est éligible à la migration.

Exigences

• Les prérequis pour le stockage des traces dans Unity Catalog, y compris les aperçus de workspace requis. Voir Exigences.

• Un Databricks SQL warehouse avec l’autorisation CAN USE, utilisé pour afficher les traces migrées dans l’interface utilisateur. La migration exécute Spark SQL sur le cluster et n’utilise pas le warehouse.

• Un cluster Databricks exécutant Databricks Runtime 15.3 ou une version ultérieure.

• Le package Python databricks-agents :

  Bash

  pip install "databricks-agents>=1.10.0"

• Les autorisations suivantes :

  • USE_CATALOG et USE_SCHEMA sur le catalogue et le schéma source , ainsi que SELECT sur les tables mlflow_experiment_trace_otel_* sources. La migration lit ces tables avec Spark SQL.
  • USE_CATALOG et USE_SCHEMA sur le catalogue et le schéma de destination , ainsi que MODIFY et SELECT sur les tables de destination <table_prefix>_otel_*. SELECT est requis car la migration lit les lignes de destination existantes pour ignorer les données déjà migrées.
  • CREATE TABLE sur le schéma de destination , afin que l’étape 1 puisse créer les quatre tables de traces.

remarque

ALL_PRIVILEGES n’est pas suffisant pour les tables de traces Unity Catalog. Accorder explicitement MODIFY et SELECT.

Étape 1 : Créer une Experimentation de destination

Créez une expérimentation liée à un emplacement de préfixe de table Unity Catalog. Les traces migrées sont stockées ici. Pour des détails complets sur la configuration, consultez Configuration : créer une expérimentation avec un emplacement de trace Unity Catalog.

Python

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

Enregistrez l’ID d'expérimentation. Utilisez-le pour configurer vos Notebooks, Jobs ou modèles déployés afin de journaliser les traces vers la nouvelle destination.

Étape 2 : Basculez la journalisation des traces et arrêtez les écritures vers l'expérimentation source.

Mettez à jour vos notebooks, jobs ou modèles déployés pour log des traces dans la nouvelle expérimentation créée à l'étape 1. Ceci garantit que les nouvelles traces arrivent directement aux tables de destination.

important

Arrêtez toutes les écritures vers l'Experimentation source avant d'exécuter la migration. Toutes les traces écrites dans les tables source pendant la migration risquent de ne pas être copiées. Vérifiez qu'aucun Notebook, Job ou modèle déployé ne journalise activement les traces dans l'expérimentation source.

Si vous souhaitez effectuer une simulation au préalable, vous pouvez ignorer cette étape et exécuter la migration sans basculer vos charges de travail de production.

Étape 3 : Exécuter la migration

Dans un notebook Databricks sur le cluster, exécutez les éléments suivants :

Python

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

Remplacez les espaces réservés :

• <source_catalog>.<source_schema>: Le catalogue et le schéma Unity Catalog où vos tables de trace source sont stockés.
• <destination_catalog>.<destination_schema>.<table_prefix>: Le catalogue Unity Catalog, le schéma et le préfixe de table pour la destination. Cela doit correspondre à l'emplacement configuré à l'étape 1.

La migration est idempotente. Si cela échoue en cours de route (par exemple, en raison d'un délai d'attente de cluster), vous pouvez le relancer en toute sécurité. Les lignes déjà migrées sont ignorées automatiquement.

Une fois la migration terminée, vos traces sont disponibles dans la nouvelle Experimentation de destination. Les tables sources ne sont pas modifiées par la migration et peuvent être conservées à titre de sauvegarde.

Si vous utilisez le monitoring de la production, conservez un ID de SQL Warehouse sur l'expérimentation de destination avant d'enregistrer les évaluateurs. Consultez Activer le monitoring de la production.