Aller au contenu principal
Dernière mise à jour le

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.

Prérequis​

  • Un Workspace compatible avec Unity Catalog.

  • 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 .
    • USE_CATALOG, USE_SCHEMA et MODIFY sur le catalogue et le schéma de destination .

É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.

Sur cette page