Aller au contenu principal
Dernière mise à jour le

Migrer les traces existantes vers Unity Catalog

Unity Catalog is the recommended storage location for MLflow traces. This page covers two migration paths:

  • Stockage d’expérimentation → Unity Catalog : si vos traces sont stockées dans une expérimentation MLflow (legacy default), migrez-les vers Unity Catalog pour bénéficier d’un accès gouverné, de la possibilité d’exécuter des requêtes SQL et d’une absence de limite de stockage.
  • Format Unity Catalog hérité → format Unity Catalog actuel : si vous avez configuré le stockage des traces Unity Catalog à l’aide de l’ancien format lié au schéma (catalog.schema), migrez vers le format actuel avec préfixe de table (catalog.schema.table_prefix) pour des requêtes de plage temporelle plus rapides, des types d’attributs plus riches, une table d’annotations dédiée et la prise en charge de plusieurs destinations de traces par schéma.

Si vous partez de zéro sans aucune trace existante à migrer, consultez la page Stocker des traces dans Unity Catalog pour configurer directement une nouvelle expérimentation.

Migrer du stockage des expérimentations vers Unity Catalog​

Cette migration copie les traces, les portées, les évaluations, les tags et les métadonnées d'une Experimentation MLflow source vers des tables Delta Unity Catalog. L'expérimentation source n'est pas modifiée.

remarque

La migration ne copie pas les traces archivées ou supprimées, les enregistrements de dataset, les sessions d’étiquetage, les exécutions ou les entités sans trace.

Exigences​

  • Les conditions préalables au stockage des traces dans Unity Catalog, y compris les aperçus de workspace requis. Consultez la rubrique Configuration requise.

  • Un warehouse Databricks SQL avec l’autorisation CAN USE. The migration command runs on the cluster and does not use the warehouse; the warehouse is needed to view migrated traces in the UI.

  • A Databricks cluster running Databricks Runtime 15.3 or above.

  • Le package Python databricks-agents :

    Bash
    pip install "databricks-agents>=1.10.1"

  • Les autorisations suivantes :

    • Accès en lecture à l’expérimentation source.
    • USE_CATALOG et USE_SCHEMA sur le catalogue et le schéma de destination.
    • CREATE TABLE sur le schéma de destination. La migration crée également une table _migration_skipped dans le même schéma si des traces sont ignorées.
    • MODIFY et SELECT sur les tables de destination <prefix>_otel_*. SELECT est requis, car la migration lit les lignes existantes pour ignorer les traces déjà migrées. ALL_PRIVILEGES n’est pas suffisant ; accordez explicitement MODIFY et SELECT. Consultez Accorder les autorisations.

Étape 1 : créer une expérimentation de destination​

Créer une expérimentation MLflow liée à un emplacement de trace Unity Catalog. L’emplacement de trace est un chemin en trois parties (catalog.schema.table_prefix), et la migration écrit dans quatre tables Delta : <prefix>_otel_spans, <prefix>_otel_annotations, <prefix>_otel_logs et <prefix>_otel_metrics.

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"Destination experiment ID: {experiment.experiment_id}")

Enregistrez l’ID de l’Experimentation — vous l’utiliserez dans les étapes 2 et 3. Vous pouvez ingérer quelques traces de test pour vérifier que le traçage Unity Catalog fonctionne avant de continuer. Consultez Log traces to the Unity Catalog tables.

Étape 2 : désactiver la journalisation des traces et arrêter les écritures​

Avant d’exécuter la migration, redirigez la journalisation des traces vers la nouvelle destination et arrêtez les écritures vers l’Experimentation source. Cela garantit qu’aucune trace n’est perdue pendant la migration.

  1. Arrêtez toutes les écritures vers l’expérimentation source. Vérifiez qu’aucun Notebook, Job ou modèle déployé n’y consigne activement de données.

  2. Remplacez tout appel set_experiment qui pointe vers l'expérimentation source :

    Python
    import mlflow

    # By experiment name
    mlflow.set_experiment(
        experiment_name="/Workspace/Users/<user>/<destination_experiment_name>",
    )

    # Or by experiment ID
    mlflow.set_experiment(experiment_id="<destination_experiment_id>")
remarque

Trace location can also be configured through the MLFLOW_EXPERIMENT_NAME and MLFLOW_EXPERIMENT_ID environment variables, which are used by deployed agents, containerized services, model serving endpoint configurations, and IDE or local development setups. For details, see Tracing overview and Export MLflow traces to OpenTelemetry.

Étape 3 : exécuter la migration​

Dans un Notebook Databricks sur le cluster, exécutez :

Python
from databricks.migrations.migrate_traces_to_uc import run

run(
    source_experiment_id="<source_experiment_id>",
    target_experiment_id="<destination_experiment_id>",
)

La migration est idempotente — en cas d'interruption (par exemple, en raison d'un délai d'attente du cluster), réexécutez la même commande. Il reprend là où il s'est arrêté et ignore les lignes déjà migrées.

Pour ne migrer que les traces créées après une heure spécifique, veuillez transmettre start_time_ms (en millisecondes d’époque) :

Python
import time
from databricks.migrations.migrate_traces_to_uc import run

one_week_ago_ms = int((time.time() - 7 * 24 * 60 * 60) * 1000)

run(
    source_experiment_id="<source_experiment_id>",
    target_experiment_id="<destination_experiment_id>",
    start_time_ms=one_week_ago_ms,  # Only migrate traces from the last 7 days
)

After the migration completes, the source experiment is not modified and can be retained as a backup. If you use production monitoring, persist a SQL Warehouse ID on the destination Experimentation before registering scorers. See Configure a SQL Warehouse for Unity Catalog traces.

Migrer à partir de l'ancien format Unity Catalog​

Si vous avez configuré le stockage des traces Unity Catalog à l’aide de l’ancien format lié au schéma, vos traces sont stockées dans des tables aux noms fixes telles que mlflow_experiment_trace_otel_spans et mlflow_experiment_trace_otel_logs. Cette migration copie les étendues et les annotations au format de préfixe de table actuel à l'aide de Spark SQL.

Comment déterminer si cette migration est nécessaire : vérifiez si votre schéma Unity Catalog contient des tables nommées mlflow_experiment_trace_otel_spans et mlflow_experiment_trace_otel_logs. Dans ce cas, votre Experimentation utilise l’ancien format lié au schéma et est éligible à la migration.

Les deux formats diffèrent comme suit :

  • 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 résident dans des tables à nom fixe. Les tags, les évaluations et les métadonnées sont stockés sous forme d’événements de log dans la table des logs.
  • Table-prefix (current format): the trace destination is a three-part path (catalog.schema.table_prefix). Trace data lives in prefix-namespaced tables. Annotations have a dedicated table.

Exigences​

Mêmes prérequis partagés que pour le premier chemin de migration (configuration UC, SQL Warehouse, DBR 15.3+ et package databricks-agents). Pour la liste complète, consultez les exigences du premier chemin. De plus :

  • Sur la source : USE_CATALOG, USE_SCHEMA et SELECT sur le catalogue, le schéma et les tables mlflow_experiment_trace_otel_* source.
  • Sur la destination : USE_CATALOG, USE_SCHEMA, MODIFY et SELECT sur le catalogue de destinations, le schéma et les tables <table_prefix>_otel_*. SELECT est requis, car la migration lit les lignes existantes afin d’ignorer les données déjà migrées.
  • CREATE TABLE sur le schéma de destination .

Étape 1 : créer une expérimentation de destination​

Créez une expérimentation liée à un emplacement avec préfixe de table Unity Catalog. Pour plus de détails sur la configuration, consultez Créer une Experimentation 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}")

Enregistrer l'ID d'Experimentation. Utilisez-le pour configurer vos notebooks, vos jobs ou vos modèles déployés afin d'enregistrer des traces vers la nouvelle destination.

Étape 2 : désactiver la journalisation des traces et arrêter les écritures​

Mettez à jour vos notebooks, jobs ou modèles déployés pour Log les traces dans l’expérience de destination créée à l’étape 1.

important

Arrêtez toutes les écritures dans l’Experimentation source avant de lancer la migration. Les traces écrites dans les tables sources pendant la migration risquent de ne pas être copiées. Vérifiez qu’aucun notebook, job ou modèle déployé n’enregistre activement de traces dans l’expérimentation source.

Si vous souhaitez effectuer un test en mode simulation au préalable, vous pouvez ignorer cette étape et exécuter la migration sans basculer vos workloads de production.

Étape 3 : exécuter la migration​

Dans un Notebook Databricks sur le cluster, exécutez :

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 dans lesquels sont stockées vos tables de traces sources.
  • <destination_catalog>.<destination_schema>.<table_prefix>: le catalogue Unity Catalog, le schéma et le préfixe de table pour la destination. Cette valeur doit correspondre à l’emplacement configuré à l’étape 1.

The migration is idempotent — if it fails partway through, re-run it. Already-migrated rows are skipped automatically.

Une fois la migration terminée, les tables sources ne sont pas modifiées et peuvent être conservées comme sauvegarde. Si vous utilisez le monitoring de la production, conservez un ID de SQL Warehouse sur l’Experimentation de destination avant d’enregistrer les évaluateurs. Voir Configurer un SQL Warehouse pour les traces Unity Catalog.

Ressources supplémentaires​

Sur cette page