既存のトレースをUnity Catalogに移行する

Unity Catalog は、MLflow トレースの推奨されるストレージの場所です。このページでは、次の 2 つの移行パスについて説明します。

• Experiment storage → Unity Catalog ：トレースがMLflowエクスペリメント（レガシーのdefault）に保存されている場合は、ガバナンスされたアクセス、SQLによるクエリー機能、ストレージ制限なしを利用するためにUnity Catalogに移行します。
• 従来の Unity Catalog 形式 → 現在の Unity Catalog 形式 ：以前のスキーマ連携形式（catalog.schema）を使用して Unity Catalog のトレースストレージを構成している場合は、期間クエリーの高速化、より豊富な属性タイプ、専用のアノテーションテーブル、およびスキーマごとの複数のトレース先のサポートを利用するために、現在のテーブルプレフィックス形式（catalog.schema.table_prefix）に移行してください。

移行する既存のトレースがなく、最初から始める場合は、Unity Catalogでのトレースの保存を参照して、新しいエクスペリメントを直接構成してください。

実験ストレージから Unity Catalog への移行

この移行では、ソース MLflow エクスペリメントからトレース、スパン、評価、タグ、メタデータを Unity Catalog Delta テーブルにコピーします。ソース エクスペリメントは変更されません。

注記

この移行では、アーカイブまたは削除されたトレース、データセット レコード、ラベリング セッション、ラン、またはトレース以外のエンティティはコピーされません。

要件

• Unity Catalogでのトレースの保存に関する前提条件（必要なワークスペースプレビューを含む）。要件を参照してください。

• CAN USE 権限を持つ Databricks SQL warehouse。移行コマンドはクラスター上でランし、warehouseは使用しません。migrationされたトレースをUIで表示するにはwarehouseが必要です。

• Databricks Runtime 15.3以降を実行しているDatabricksクラスター。

• databricks-agents Python パッケージ:

  Bash

  pip install "databricks-agents>=1.10.1"

• 次の権限:

  • ソースエクスペリメントへの読み取りアクセス。
  • USE_CATALOG および宛先カタログとスキーマの USE_SCHEMA。
  • CREATE TABLE 宛先スキーマ上で。また、トレースがスキップされた場合、移行によって同じスキーマに _migration_skipped テーブルが作成されます。
  • MODIFY および宛先 <prefix>_otel_* テーブルの SELECT。移行によって既存の行を読み取り、すでに移行されたトレースをスキップするため、 SELECT が必要です。ALL_PRIVILEGES では不十分です。 MODIFY と SELECT を明示的に付与してください。権限の付与を参照してください。

ステップ 1: 送信先のエクスペリメントを作成する

Unity Catalogのトレース保存場所にバインドされたMLflowエクスペリメントを作成します。トレースの保存場所は3パートのパス（catalog.schema.table_prefix）であり、移行によって<prefix>_otel_spans、<prefix>_otel_annotations、<prefix>_otel_logs、<prefix>_otel_metricsの4つのDeltaテーブルに書き込まれます。

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

エクスペリメント ID を保存します。これは、ステップ 2 および 3 で使用します。進める前に、テストトレースをいくつか取り込んで、Unity Catalog のトレースが機能することを確認できます。Unity Catalog テーブルへのトレースの Logs を参照してください。

ステップ 2：トレースログの切り替えと書き込みの停止

移行を実行する前に、トレースのログ記録を新しい送信先にリダイレクトし、ソース エクスペリメントへの書き込みを停止します。これにより、移行中にトレースが失われないようになります。

1. ソースのエクスペリメントへのすべての書き込みを停止します。ノートブック、ジョブ、またはデプロイされたモデルがそれにアクティブにログを記録していないことを確認します。

2. ソース エクスペリメントを指す set_experiment 呼び出しを置き換えます:

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

注記

トレースの保存場所は、MLFLOW_EXPERIMENT_NAME および MLFLOW_EXPERIMENT_ID 環境変数を使用して構成することもできます。これらは、デプロイされたエージェント、コンテナ化されたサービス、モデルサービングEndpointの構成、および IDE またはローカル開発環境で使用されます。詳細については、Tracingの概要 および OpenTelemetry への MLflow トレースのエクスポートを参照してください。

ステップ3：移行を実行する

クラスター上の Databricks ノートブックで次を実行します。

Python

from databricks.migrations.migrate_traces_to_uc import run

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

移行はべき等です — 中断された場合（クラスターのタイムアウトなどにより）、同じコマンドを再実行してください。中断したところから再開され、すでに移行された行はスキップされます。

特定の花時間以降に作成されたトレースのみを移行するには、 start_time_ms （エポックミリ秒）を渡します。

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
)

移行の完了後、ソース エクスペリメントは変更されず、バックアップとして保持できます。本番運用モニタリングを使用する場合は、スコアラーを登録する前に、宛先エクスペリメントに SQL Warehouse ID を永続化します。「Unity Catalog トレース用の SQL ウェアハウスの構成」を参照してください。

レガシーの Unity Catalog 形式からの移行

古いスキーマリンク形式を使用して Unity Catalog トレースストレージを構成した場合、トレースは mlflow_experiment_trace_otel_spans や mlflow_experiment_trace_otel_logs などの固定名テーブルに保存されます。このマイグレーションは、Spark SQLを使用してスパンとアノテーションを現在のテーブルプレフィックス形式にコピーします。

この移行が必要かどうかの確認方法 ：Unity Catalogのスキーマに mlflow_experiment_trace_otel_spans および mlflow_experiment_trace_otel_logs という名前のテーブルが含まれているかどうかを確認します。該当する場合、エクスペリメントでは古いスキーマリンク形式が使用されており、移行の対象となります。

2つのフォーマットは次のように異なります：

• スキーマリンク （古い形式）：エクスペリメントのトレースの宛先は2パートのパス（catalog.schema）です。トレースデータは固定名のテーブルに保存されます。タグ、評価、およびメタデータは、logsテーブルにログイベントとして保存されます。
• Table-prefix (現在の形式): トレース送信先は 3 つの部分で構成されるパス (catalog.schema.table_prefix) です。トレースデータは、プレフィックスを名前空間とするテーブルに格納されます。注釈には専用のテーブルがあります。

要件

最初のエクステンションパスと同じ共有前提条件（UC のセットアップ、SQLウェアハウス、DBR 15.3 以降、および databricks-agents パッケージ）。完全な一覧については、最初のパスの要件を参照してください。さらに、以下の点に注意してください：

• ソース 上: ソースカタログ、スキーマ、およびmlflow_experiment_trace_otel_*テーブル上のUSE_CATALOG、USE_SCHEMA、SELECT。
• 宛先 ：宛先カタログ、スキーマ、および <table_prefix>_otel_* テーブルにおける USE_CATALOG、USE_SCHEMA、MODIFY、および SELECT。SELECT は、移行済みデータをスキップするために移行処理が既存の行を読み取る必要があるため、必須です。
• CREATE TABLE on the 宛先 スキーマ上で。

ステップ 1: 送信先のエクスペリメントを作成する

Unity Catalog のテーブルプレフィックス・ロケーションにリンクされたエクスペリメントを作成する。完全な設定の詳細については、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}")

エクスペリメント ID を保存します。これを使用して、ノートブック、ジョブ、またはデプロイされたモデルを設定し、新しい配信先にトレースをログに記録します。

ステップ 2：トレースログの切り替えと書き込みの停止

ステップ 1 で作成した宛先のエクスペリメントにトレースをLogするように、ノートブック、ジョブ、またはデプロイされたモデルを更新します。

重要

移行を実行する前に、ソースエクスペリメントへのすべての書き込みを停止します。移行中にソーステーブルに書き込まれたトレースはコピーされない場合があります。ノートブック、ジョブ、またはデプロイされたモデルが、ソースエクスペリメントにアクティブにトレースを記録していないことを確認します。

最初にドライランを行う場合は、このステップをスキップして、本番運用ワークロードを切り替えずに移行をランできます。

ステップ3：移行を実行する

クラスター上の Databricks ノートブックで次を実行します。

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

プレースホルダーを置き換えます。

• <source_catalog>.<source_schema>：ソース・トレース・テーブルが保存されている Unity Catalog のカタログとスキーマ。
• <destination_catalog>.<destination_schema>.<table_prefix>: 宛先の Unity Catalog カタログ、スキーマ、およびテーブルプレフィックス。これは、ステップ1で設定したロケーションと一致している必要があります。

移行はべき等です — 途中で失敗した場合は、もう一度実行してください。移行済みの行は自動的にスキップされます。

移行完了後も、ソーステーブルは変更されず、バックアップとして保持できます。本番運用モニタリングを使用する場合は、スコアラーを登録する前に、送信先のエクスペリメントにSQL Warehouse IDを永続化してください。「Unity Catalog トレース用のSQLウェアハウスの構成」を参照してください。

その他のリソース

• OpenTelemetryトレースをUnity Catalogに保存する — Unity Catalogのトレースロケーションを使用して、新しいエクスペリメントを設定します。
• 自動トレーシングと統合 — 本番運用において、エージェントをインストルメントし、トレースを Unity Catalog にルーティングします。
• 本番運用のモニタリングを設定する — Unity Catalog に保存されたトレースに対してスコアラーを実行します。