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

MLflowトレースをUnity Catalogに保存する

備考

ベータ版

この機能はベータ版です。ワークスペース管理者は、 プレビュー ページからこの機能へのアクセスを制御できます。「Databricks プレビューの管理」を参照してください。

Databricks 、OpenTelemetry 互換形式 (OTEL) を使用してMLflowトレースをUnity Catalogテーブルに保存することをサポートしています。 安心により、 MLflow経験ごとに整理されたトレースをMLflowコントロール プレーン サービスに保存します。 ただし、OTEL 形式を使用してUnity Catalogにトレースを保存すると、次の利点があります。

  • アクセス制御は、エクスペリメント レベルの ACL ではなく、 Unity Catalogスキーマとテーブル権限を通じて管理されます。 Unity Catalogテーブルにアクセスできるユーザーは、トレースがどの expperiment に属しているかに関係なく、それらのテーブルに保存されているすべてのトレースを表示できます。

  • トレース ID はtr-<UUID>形式ではなく URI 形式を使用するため、外部システムとの互換性が向上します。

  • Delta テーブルに無制限のトレースを保存し、トレース データの長期保持と分析を可能にします。パフォーマンスに関する考慮事項を参照してください。

  • Databricks SQLウェアハウスを通じてSQLを使用してトレース データを直接クエリし、高度なアナリティクスとカスタム レポートを可能にします。

  • OTEL形式は他のOpenTelemetryクライアントおよびツールとの互換性を保証します

前提条件​

  • Unity カタログ対応のワークスペース。

  • Unity Catalog でカタログとスキーマを作成する権限。

  • 「OpenTelemetry on Databricks」プレビューが有効になっていることを確認します。「Databricks プレビューの管理」を参照してください。

  • Databricks SQL ウェアハウス。後で参照できるようにウェアハウス ID を保存します。

  • この機能がベータ版である間は、ワークスペースは次のいずれかのリージョンにある必要があります。

    • us-east-1
    • us-west-2

  • お使いの環境に MLflow Python ライブラリ バージョン 3.8.0 以降がインストールされている:

    Bash
    pip install mlflow[databricks]>=3.8.0 --upgrade --force-reinstall

セットアップ: UC テーブルを作成し、エクスペリメントをリンクする​

トレースを保存するためのUnity Catalogテーブルを作成します。 次に、テーブルを含むUnity CatalogスキーマをMLflowエクスペリメントにリンクし、そのトレースを確実にテーブルに書き込みます。

Python
# Example values for the placeholders below:
# MLFLOW_TRACING_SQL_WAREHOUSE_ID: "abc123def456" (found in SQL Warehouse URL)
# experiment_name: "/Users/user@company.com/traces"
# catalog_name: "main" or "my_catalog"
# schema_name: "mlflow_traces" or "production_traces"

import os
import mlflow
from mlflow.exceptions import MlflowException
from mlflow.entities import UCSchemaLocation
from mlflow.tracing.enablement import set_experiment_trace_location

mlflow.set_tracking_uri("databricks")

# Specify the ID of a SQL warehouse you have access to.
os.environ["MLFLOW_TRACING_SQL_WAREHOUSE_ID"] = "<SQL_WAREHOUSE_ID>"
# Specify the name of the MLflow Experiment to use for viewing traces in the UI.
experiment_name = "<MLFLOW_EXPERIMENT_NAME>"
# Specify the name of the Catalog to use for storing traces.
catalog_name = "<UC_CATALOG_NAME>"
# Specify the name of the Schema to use for storing traces.
schema_name = "<UC_SCHEMA_NAME>"

if experiment := mlflow.get_experiment_by_name(experiment_name):
    experiment_id = experiment.experiment_id
else:
    experiment_id = mlflow.create_experiment(name=experiment_name)
print(f"Experiment ID: {experiment_id}")

# To link an experiment to a trace location
result = set_experiment_trace_location(
    location=UCSchemaLocation(catalog_name=catalog_name, schema_name=schema_name),
    experiment_id=experiment_id,
)
print(result.full_otel_spans_table_name)

テーブルを検証する​

セットアップ コードを実行すると、カタログ エクスプローラー UI のスキーマに 3 つの新しいUnity Catalogテーブルが表示されます。

  • mlflow_experiment_trace_otel_logs
  • mlflow_experiment_trace_otel_metrics
  • mlflow_experiment_trace_otel_spans

権限を付与する​

DatabricksユーザーまたはサービスプリンシパルがUnity CatalogテーブルからMLflowトレースを読み書きするには、次の権限が必要です。

  1. カタログに対する USE_CATALOG 権限。
  2. スキーマに対する USE_SCHEMA 権限。
  3. 各mlflow_experiment_trace_<type>テーブルに対する MODIFY および SELECT 権限。
注記

ALL_PRIVILEGES Unity Catalogトレース テーブルにアクセスするには不十分です。 MODIFY 権限 と SELECT 権限を明示的に付与する必要があります。

Unity Catalogテーブルへのトレースのログ​

テーブルを作成した後、トレースの保存先を指定して、さまざまなソースからテーブルにトレースを書き込むことができます。これをどのように行うかは、トレースのソースによって異なります。

カタログとスキーマは、 mlflow.tracing.set_destination Python API を使用するか、 MLFLOW_TRACING_DESTINATION環境変数を設定することによって指定できます。

Python
import mlflow

mlflow.set_tracking_uri("databricks")

# Specify the name of the catalog and schema to use for storing Traces
catalog_name = "<UC_CATALOG_NAME>"
schema_name = "<UC_SCHEMA_NAME>"

# Option 1: Use the `set_destination` API to configure the catalog and schema for
# storing MLflow Traces
from mlflow.entities import UCSchemaLocation
mlflow.tracing.set_destination(
    destination=UCSchemaLocation(
        catalog_name=catalog_name,
        schema_name=schema_name,
    )
)

# Option 2: Use the `MLFLOW_TRACING_DESTINATION` environment variable to configure the
# catalog and schema for storing MLflow Traces
import os
os.environ["MLFLOW_TRACING_DESTINATION"] = f"{catalog_name}.{schema_name}"

# Create and ingest an example trace using the `@mlflow.trace` decorator
@mlflow.trace
def test(x):
    return x + 1

test(100)

UIでトレースを表示する​

他のトレースを表示するのと同じ方法で、OTEL 形式で保存されたトレースを表示します。

  1. ワークスペースで、 「体験」 に移動します。

  2. トレースが記録されているエクスペリメントを見つけます。 たとえば、 mlflow.set_experiment("/Shared/my-genai-app-traces")によって設定されたエクスペリメント。

  3. 「Traces」 タブをクリックすると、そのエクスペリメントに記録されたすべてのトレースのリストが表示されます。

    トレースリストビュー

  4. トレースをUnity Catalogテーブルに保存した場合、 Databricks SQLウェアハウスを使用してトレースを取得します。 ドロップダウン メニューからSQLウェアハウスを選択します。

  5. 別のスキーマを選択することもできます。代替スキーマを選択するときは、そのスキーマに OpenTelemetry テーブルがすでに含まれていることを確認してください。ドロップダウン メニューではテーブルは作成されません。 MLflow UI でのSQL選択

UI を使用してトレースを検索する方法の詳細については、 「 Databricks MLflow UI でトレースを表示する」を参照してください。

Unity Catalogスキーマのリンクを解除する​

MLflowエクスペリメントからUnity Catalogスキーマのリンクを解除するには、 MLflowエクスペリメント UI から [Storage UC Schema] ドロップダウンをクリックし、 [Unlink schema] を選択します。

トレースはUnity Catalogスキーマに引き続き存在し、スキーマはいつでもMLflowエクスペリメントに再リンクできます。

スキーマのリンク解除オプション

制限事項​

  • トレースの取り込みは、ワークスペースごとに 1 秒あたり 100 トレース、テーブルごとに 1 秒あたり 100 MB に制限されます。

  • 2TB を超えるトレース データがテーブルに保存されると、UI パフォーマンスが低下する可能性があります。パフォーマンスに関する考慮事項を参照してください。

  • Unity Catalogに保存されているトレースの個々のトレースの削除はサポートされていません。 トレースを削除するには、 SQLを使用して、基礎となるUnity Catalogテーブルから行を直接削除する必要があります。 これは、 MLflow UI またはAPIを使用して削除できるエクスペリメント トレースと異なります。

  • MLflowエクスペリメントをUnity Catalogスキーマに接続する場合、エクスペリメントにリンクされているUnity Catalogスキーマに保存されているトレースのみにアクセスできます。 エクスペリメント内の既存のトレースは、 MLflowクライアントPython >= 3.5.0 からの検索では アクセスでき なくなります。 MLflow UI からも行えます。これらのトレースはエクスペリメントに保存されたままですが、エクスペリメントがUnity Catalogにリンクされている間は表示したり検索したりすることはできません。

    MLflowエクスペリメントからスキーマのリンクを解除すると、既存のトレースにアクセスできるようになります。

  • 取り込みスループットの制限は 1 秒あたり 200 クエリ (QPS) です

次のステップ​