メインコンテンツまでスキップ
に最終更新

レガシーUnity Catalogトレーステーブルをテーブルプレフィックス形式に移行します。

古いスキーマリンク形式 (catalog.schema) を使用してMLflow エクスペリメントを構成してトレースをUnity Catalogに保存した場合は、それらのトレースを現在のテーブルプレフィックス形式 (catalog.schema.table_prefix) に移行してください。

Databricksは、新規および既存のすべてのUCトレースワークロードに対して、テーブルプレフィックス形式の使用を推奨します。これにより、より高速な時間範囲クエリ、より豊富な属性タイプ、専用のアノテーションテーブル、およびスキーマごとに複数のトレース先をサポートする機能が提供されます。

移行処理では、Spark SQLを使用してスパンと注釈（タグ、評価、メタデータ）をコピーします。

古い形式を使用したエクスペリメントを特定する​

トレースをUnity Catalogに保存するエクスペリメントでは、次の 2 つの形式のいずれかを使用します。

  • スキーマリンク （以前の形式）：エクスペリメントのトレースの宛先は、2部構成のパス（catalog.schema）です。トレースデータは、mlflow_experiment_trace_otel_spansやmlflow_experiment_trace_otel_logsなどの固定名のテーブルに保存されます。タグ、評価、およびメタデータは、Logsテーブルにログイベントとして保存されます。
  • テーブルプレフィックス （現在の形式）：エクスペリメントのトレース保存先は、3つの部分からなるパス（catalog.schema.table_prefix）です。トレースデータは <table_prefix>_otel_spans のようなプレフィックス付き名前空間テーブルに保存され、アノテーションには専用のテーブルがあります。

Unity Catalogスキーマにmlflow_experiment_trace_otel_spansとmlflow_experiment_trace_otel_logsという名前のテーブルが含まれている場合、エクスパーメントは古いスキーマリンク形式を使用しており、移行の対象となります。

要件​

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

  • UI で移行されたトレースを表示するために使用される、CAN USE 権限を持つ Databricks SQL warehouse。移行はクラスター上で Spark SQL を実行し、warehouse は使用しません。

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

  • databricks-agents Pythonパッケージ:

    Bash
    pip install "databricks-agents>=1.10.0"

  • 以下の権限：

    • USE_CATALOG および ソース カタログとスキーマ上の USE_SCHEMA、さらにソース mlflow_experiment_trace_otel_* テーブル上の SELECT。移行では、Spark SQL を使用してこれらのテーブルを読み取ります。
    • USE_CATALOG および 宛先 カタログとスキーマに対する USE_SCHEMA、さらに宛先 <table_prefix>_otel_* テーブルに対する MODIFY および SELECT が必要です。移行プロセスでは、すでに移行済みのデータをスキップするために既存の宛先行を読み取るため、SELECT が必要です。
    • CREATE TABLE 宛先 スキーマ上で実行します。これにより、ステップ1で4つのトレーステーブルを作成できるようになります。
注記

ALL_PRIVILEGES は、Unity Catalog トレーステーブルには不十分です。MODIFY および SELECT を明示的に付与します。

ステップ 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 で作成された新しいエクスペリメントへのトレースをログに記録します。 これにより、新しいトレースが宛先テーブルに直接送信されることが保証されます。

重要

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

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

ステップ 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を保持してください。本番運用モニタリングの有効化を参照してください。

このページの見出し