Unity Catalog 内でモデル ライフサイクルを管理する

重要

この記事では、ML モデルのライフサイクル全体を管理する機械学習ワークフローの一部として Unity Catalog のモデルを使用する方法について説明します。 Databricks は、Unity Catalog 内でホステッド バージョンの MLflow モデル レジストリを提供しています。 Unity Catalog のモデルは、Unity Catalog の利点を ML モデルに拡張します。これには、ワークスペース全体の一元的なアクセス制御、監査、系列、モデル検出が含まれます。 Unity Catalog のモデルは、オープンソースの MLflow Python クライアントと互換性があります。

Unity Catalog のモデルの主な特徴は次のとおりです。

  • モデルの名前空間とガバナンスにより、環境、プロジェクト、またはチーム レベルでモデルをグループ化および管理できます (“データ サイエンティストに運用モデルへの読み取り専用アクセスを付与します”)。
  • 時系列モデル系列 (特定の時点でモデルを生成した MLflow 実験と実行)。
  • モデル サービング
  • モデルのバージョン管理。
  • エイリアスを使用したモデル デプロイ。 たとえば、prod カタログ内のモデルの “Champion” バージョンをマークします。

ワークスペースの既定のカタログが Unity Catalog 内のカタログに構成されている場合、mlflow.<model-type>.log_model(..., registered_model_name)mlflow.register_model(model_uri, name) などの MLflow API を使用して登録されたモデルは既定で Unity Catalog に登録されます。

この記事には、Unity Catalog のモデルの UI と API 両方の手順が含まれています。

モデル レジストリの概念の概要については、「MLflow を使用した ML ライフサイクル管理」を参照してください。

要件

  1. Unity Catalog はワークスペースで有効になっている必要があります。 「Unity Catalog の使用の開始」を参照して、Unity Catalog メタストアを作成し、それをワークスペースで有効にし、カタログを作成します。 Unity Catalog が有効になっていない場合でも、従来のワークスペース モデル レジストリを使用できます。

  2. ワークスペースは、権限継承をサポートする Unity Catalog メタストアにアタッチされている必要があります。 これは、2022 年 8 月 25 日より後に作成されたすべてのメタストアに当てはまります。 古いメタストアで実行している場合は、ドキュメントに従ってアップグレードしてください。

  3. Unity Catalog へのアクセス権があるクラスターでコマンドを実行するためのアクセス権が必要です。

  4. 新しい登録済みモデルを作成するには、スキーマに対する CREATE_MODEL 権限に加えて、スキーマとその外側のカタログに対する USE SCHEMA および USE CATALOG 権限が必要です。 次に示すように、CREATE_MODEL はカタログ エクスプローラー UI または SQL GRANT コマンドを使用して付与できる新しいスキーマ レベルの権限です。

    GRANT CREATE_MODEL ON SCHEMA <schema-name> TO <principal>
    

トレーニング ワークロードを Unity Catalog にアップグレードする

このセクションには、既存のトレーニング ワークロードを Unity Catalog にアップグレードする手順が含まれています。

MLflow Python クライアントをインストールする

以下のコードを使用して、最新バージョンの MLflow Python クライアントをノートブックにインストールすることで、Databricks Runtime 11.3 LTS 以降の Unity Catalog のモデルを使用することもできます。

%pip install --upgrade "mlflow-skinny[databricks]"
dbutils.library.restartPython()

Unity Catalog のモデルにアクセスするように MLflow クライアントを構成する

既定では、MLflow Python クライアントは Databricks のワークスペース モデル レジストリにモデルを作成します。 Unity Catalog のモデルにアップグレードするには、次のように MLflow クライアントを構成します。

import mlflow
mlflow.set_registry_uri("databricks-uc")

Note

ワークスペースの既定のカタログが (hive_metastore ではなく) Unity Catalog 内にあり、Databricks Runtime 13.3 LTS 以降 (Azure China リージョンでは Databricks Runtime 15.0 以降) を使ってクラスターを実行している場合、モデルは自動的に既定のカタログ内に作成され、既定のカタログから読み込まれます。構成は必要ありません。 他の Databricks Runtime バージョンに関しては動作に変更はありません。 既定のカタログが 2024 年 1 月より前に Unity Catalog 内のカタログに構成され、2024 年 1 月より前にワークスペース モデル レジストリが使われていた少数のワークスペースは、この動作から除外されます。

Unity Catalog 互換モデルのトレーニングと登録

必要な権限: 新しい登録済みモデルを作成するには、外側のスキーマに対する CREATE_MODEL および USE SCHEMA 権限、そして外側のカタログに対する USE CATALOG 権限が必要です。 登録済みモデルの下に新しいモデル バージョンを作成するには、登録済みモデルの所有者であり、モデルを含むスキーマとカタログに対する USE SCHEMA および USE CATALOG 権限を持っている必要があります。

UC の ML モデル バージョンには、モデル シグネチャが必要です。 モデル トレーニング ワークロードでまだシグネチャを使用して MLflow モデルのログ記録を行っていない場合は、次のいずれかを実行できます。

  • Databricks の自動ログを使用します。これは、多くの一般的な ML フレームワーク向けのシグネチャを使用してモデルのログ記録を自動的に行います。 MLflow ドキュメントでサポートされているフレームワークを確認してください。
  • MLflow 2.5.0 以降では、mlflow.<flavor>.log_model 呼び出しで入力例を指定でき、モデル署名が自動的に推論されます。 詳細については、「MLflow ドキュメント」を参照してください。

次に、モデルの 3 レベルの名前を MLflow API に <catalog>.<schema>.<model> という形式で渡します。

このセクションの例では、prod カタログの下の ml_team スキーマにモデルを作成し、アクセスします。

このセクションのモデル トレーニングの例では、新しいモデル バージョンを作成し、それを prod カタログに登録します。 prod カタログを使用しても、そのモデル バージョンが運用トラフィックに対応するとは限りません。 モデル バージョンを囲むカタログ、スキーマ、および登録モデルは、その環境 (prod) および関連するガバナンス ルール (たとえば、管理者のみが prod カタログから削除できるように権限を設定できます) を反映しますが、デプロイの状態は反映しません。 デプロイの状態を管理するには、モデル エイリアスを使用します。

自動ログを使用して Unity Catalog にモデルを登録する

from sklearn import datasets
from sklearn.ensemble import RandomForestClassifier

# Train a sklearn model on the iris dataset
X, y = datasets.load_iris(return_X_y=True, as_frame=True)
clf = RandomForestClassifier(max_depth=7)
clf.fit(X, y)

# Note that the UC model name follows the pattern
# <catalog_name>.<schema_name>.<model_name>, corresponding to
# the catalog, schema, and registered model name
# in Unity Catalog under which to create the version
# The registered model will be created if it doesn't already exist
autolog_run = mlflow.last_active_run()
model_uri = "runs:/{}/model".format(autolog_run.info.run_id)
mlflow.register_model(model_uri, "prod.ml_team.iris_model")

自動的に推測された署名を使用してモデルを Unity Catalog に登録する

自動的に推論される署名のサポートは、MLflow バージョン 2.5.0 以降で利用でき、Databricks Runtime 11.3 LTS ML 以降でサポートされます。 自動的に推論された署名を使用するには、次のコードを使用して最新の MLflow Python クライアントをノートブックにインストールします。

%pip install --upgrade "mlflow-skinny[databricks]"
dbutils.library.restartPython()

次のコードは、自動的に推論された署名の例を示しています。

from sklearn import datasets
from sklearn.ensemble import RandomForestClassifier

with mlflow.start_run():
    # Train a sklearn model on the iris dataset
    X, y = datasets.load_iris(return_X_y=True, as_frame=True)
    clf = RandomForestClassifier(max_depth=7)
    clf.fit(X, y)
    # Take the first row of the training dataset as the model input example.
    input_example = X.iloc[[0]]
    # Log the model and register it as a new version in UC.
    mlflow.sklearn.log_model(
        sk_model=clf,
        artifact_path="model",
        # The signature is automatically inferred from the input example and its predicted output.
        input_example=input_example,
        registered_model_name="prod.ml_team.iris_model",
    )

Unity Catalog でモデルのデータ系列を追跡する

Note

Unity Catalog でのテーブルからモデルへの系列のサポートは、MLflow 2.11.0 以降で利用できます。

Unity Catalog のテーブルでモデルをトレーニングする場合、モデルのトレーニングおよび評価の元になったアップストリーム データセットに対してモデルの系列を追跡できます。 これを行うには、mlflow.log_input を使用します。 これにより、モデルを生成した MLflow 実行で入力テーブル情報が保存されます。 データ系列は、機能ストア API を使用してログに記録されたモデルに対しても自動的にキャプチャされます。 「特徴量ストアの系列を表示する」を参照してください。

モデルを Unity Catalog に登録すると、系列情報が自動的に保存され、カタログ エクスプローラーのモデル バージョン UI[系列] タブに表示されます。

次のコードは例を示します。

import mlflow
import pandas as pd
import pyspark.pandas as ps
from sklearn.datasets import load_iris
from sklearn.ensemble import RandomForestRegressor

# Write a table to Unity Catalog
iris = load_iris()
iris_df = pd.DataFrame(iris.data, columns=iris.feature_names)
iris_df.rename(
  columns = {
    'sepal length (cm)':'sepal_length',
    'sepal width (cm)':'sepal_width',
    'petal length (cm)':'petal_length',
    'petal width (cm)':'petal_width'},
  inplace = True
)
iris_df['species'] = iris.target
ps.from_pandas(iris_df).to_table("prod.ml_team.iris", mode="overwrite")

# Load a Unity Catalog table, train a model, and log the input table
dataset = mlflow.data.load_delta(table_name="prod.ml_team.iris", version="0")
pd_df = dataset.df.toPandas()
X = pd_df.drop("species", axis=1)
y = pd_df["species"]
with mlflow.start_run():
    clf = RandomForestRegressor(n_estimators=100)
    clf.fit(X, y)
    mlflow.log_input(dataset, "training")

UI でモデルを表示する

必要な権限: 登録済みモデルとそのモデル バージョンを UI で表示するには、登録済みモデルに対する EXECUTE 権限と、モデルを含むスキーマとカタログに対する USE SCHEMA および USE CATALOG 権限が必要です

Catalog Explorer を使用して、Unity Catalog の登録済みモデルとモデル バージョンを表示および管理できます。

モデルへのアクセスの制御

Unity Catalog に登録されているモデルへのアクセスの制御の情報については、「Unity Catalog の権限とセキュリティ保護可能なオブジェクト」を参照してください。 カタログおよびスキーマ全体でモデルを整理するためのベスト ベスト プラクティスについては、「データの整理」を参照してください。

Grants REST API を使用して、モデルのアクセス許可をプログラムで構成できます。 モデルのアクセス許可を構成する場合は、REST API 要求で securable_type"FUNCTION" に設定します。 たとえば、登録されたモデルのアクセス許可を更新するには、PATCH /api/2.1/unity-catalog/permissions/function/{full_name} を使用します。

エイリアスとタグを使用してモデルをデプロイおよび整理する

モデルのエイリアスとタグは、Unity Catalog 内のモデルを整理および管理するのに役立ちます。

モデル エイリアスを使用すると、登録済みモデルの特定のバージョンに変更可能な名前付き参照を割り当てることができます。 エイリアスを使用して、モデル バージョンのデプロイの状態を示すことができます。 たとえば、現在運用中のモデル バージョン “Champion” エイリアスを割り当て、運用モデルを使用するワークロードでこのエイリアスをターゲットにすることができます。 その後、“Champion” エイリアスを別のモデル バージョンに再割り当てすることで、運用モデルを更新できます。

タグは、登録されたモデルおよびモデルのバージョンに関連付けるキーと値のペアであり、機能またはステータスごとにラベルを付けて分類することができます。 たとえば、キー "task" と値 "question-answering" (UI では task:question-answering として表示される) を持つタグを、質問応答タスクを目的とした登録済みモデルに適用できます。 モデルのバージョン レベルでは、デプロイ前検証中のバージョンに validation_status:pending をタグ付けし、デプロイのためにクリアされたバージョンには validation_status:approved をタグ付けできます。

エイリアスとタグの使用方法については、次のセクションを参照してください。

モデルのエイリアスの設定と削除

必要な権限: 登録済みモデルの所有者、およびモデルを含むスキーマとカタログに対する USE SCHEMA および USE CATALOG 権限。

カタログ エクスプローラーを使用して、Unity Catalog 内のモデルの別名を設定、更新、および削除できます。 モデルの詳細ページで登録済みモデル全体のエイリアスを管理したり、モデル バージョンの詳細ページで特定のモデル バージョンのエイリアスを構成したりできます。

MLflow Client API を使用してエイリアスを設定、更新、削除するには、以下の例を参照してください。

from mlflow import MlflowClient
client = MlflowClient()

# create "Champion" alias for version 1 of model "prod.ml_team.iris_model"
client.set_registered_model_alias("prod.ml_team.iris_model", "Champion", 1)

# reassign the "Champion" alias to version 2
client.set_registered_model_alias("prod.ml_team.iris_model", "Champion", 2)

# get a model version by alias
client.get_model_version_by_alias("prod.ml_team.iris_model", "Champion")

# delete the alias
client.delete_registered_model_alias("prod.ml_team.iris_model", "Champion")

モデルのタグの設定と削除

必要な権限: 登録されたモデルに対する APPLY_TAG 権限に加えて、モデルを含むスキーマおよびカタログに対する USE SCHEMA および USE CATALOG 権限を持つ所有者またはユーザー。

UI を使用してタグを設定および削除する方法については、カタログ エクスプローラーでのタグの管理に関するページを参照してください。

MLflow Client API を使用してタグを設定および削除するには、以下の例を参照してください。

from mlflow import MlflowClient
client = MlflowClient()

# Set registered model tag
client.set_registered_model_tag("prod.ml_team.iris_model", "task", "classification")

# Delete registered model tag
client.delete_registered_model_tag("prod.ml_team.iris_model", "task")

# Set model version tag
client.set_model_version_tag("prod.ml_team.iris_model", "1", "validation_status", "approved")

# Delete model version tag
client.delete_model_version_tag("prod.ml_team.iris_model", "1", "validation_status")

登録されたモデル タグとモデル バージョン タグは両方とも、プラットフォーム全体の制約を満たす必要があります。

エイリアスおよびタグ クライアント API の詳細については、MLflow API ドキュメントを参照してください。

推論用のモデルを読み込む

推論ワークロードでエイリアスでモデル バージョンを使用する

必要な権限: 登録済みモデルに対する EXECUTE 権限、そしてモデルを含むスキーマとカタログに対する USE SCHEMA および USE CATALOG 権限。

モデル バージョンをエイリアスで参照するバッチ推論ワークロードを記述できます。 たとえば、次のスニペットは、バッチ推論に “Champion” モデル バージョンを読み込んで適用します。 “Champion” バージョンが新しいモデル バージョンを参照するように更新されると、バッチ推論ワークロードは次の実行でそれを自動的に取得します。 これにより、モデル デプロイをバッチ推論ワークロードから切り離すことができます。

import mlflow.pyfunc
model_version_uri = "models:/prod.ml_team.iris_model@Champion"
champion_version = mlflow.pyfunc.load_model(model_version_uri)
champion_version.predict(test_x)

デプロイ ワークフローを記述して、エイリアスでモデル バージョンを取得し、次のようにモデル提供 REST API を使用して、そのバージョンを提供するようにモデル提供エンドポイントを更新することもできます。

import mlflow
import requests
client = mlflow.tracking.MlflowClient()
champion_version = client.get_model_version_by_alias("prod.ml_team.iris_model", "Champion")
# Invoke the model serving REST API to update endpoint to serve the current "Champion" version
model_name = champion_version.name
model_version = champion_version.version
requests.request(...)

推論ワークロードでバージョン番号でモデル バージョンを使用する

次のようにバージョン番号でモデル バージョンを読み込むこともできます。

import mlflow.pyfunc
# Load version 1 of the model "prod.ml_team.iris_model"
model_version_uri = "models:/prod.ml_team.iris_model/1"
first_version = mlflow.pyfunc.load_model(model_version_uri)
first_version.predict(test_x)

ワークスペース間でモデルを共有する

同じリージョンのユーザーとモデルを共有する

適切な権限を持っている限り、モデルを含むメタストアにアタッチされている任意のワークスペースから Unity カタログ内のモデルにアクセスできます。 たとえば、開発ワークスペース内の prod カタログからモデルにアクセスして、新しく開発されたモデルを運用ベースラインと比較することを支援することができます。

作成した登録済みモデルで他のユーザーと共同作業 (書き込み権限を共有) するには、自分自身および共同作業したいユーザーを含むグループにモデルの所有権を付与する必要があります。 共同作業者には、モデルを含むカタログとスキーマに対する USE CATALOG および USE SCHEMA 権限も必要です。 詳細については、「Unity Catalog の権限とセキュリティ保護可能なオブジェクト」を参照してください。

別のリージョンまたはアカウントのユーザーとモデルを共有する

他のリージョンまたはアカウントのユーザーとモデルを共有するには、Delta Sharing の Databricks 間共有フローを使用します。 「共有にモデルを追加する」 (プロバイダーの場合) と「Databricks-to-Databricks モデルでアクセスする」 (受信者の場合) を参照してください。 受信者は、共有からカタログを作成した後、その共有カタログ内のモデルに Unity カタログ内の他のモデルと同じ方法でアクセスします。

モデルまたはモデル バージョンに注釈を付ける

必要な権限: 登録済みモデルの所有者、およびモデルを含むスキーマとカタログに対する USE SCHEMA および USE CATALOG 権限。

注釈を付けて、モデルまたはモデル バージョンに関する情報を提供できます。 たとえば、問題の概要や、使用される手法とアルゴリズムに関する情報を含めることができます。

UI を使用してモデルまたはモデル バージョンに注釈を付ける

マークダウン コメントを使用したカタログ エクスプローラーのドキュメント データ」を参照してください。

API を使用してモデルまたはモデル バージョンに注釈を付ける

登録済みモデルの説明を更新するには、次のように MLflow Client API の update_registered_model() メソッドを使用します。

client = MlflowClient()
client.update_registered_model(
  name="<model-name>",
  description="<description>"
)

モデル バージョンの説明を更新するには、MLflow Client API update_model_version() メソッドを使用します。

client = MlflowClient()
client.update_model_version(
  name="<model-name>",
  version=<model-version>,
  description="<description>"
)

モデル名を変更する (API のみ)

必要な権限: 登録済みモデルの所有者、登録済みモデルを含むスキーマに対する CREATE_MODEL 権限、そしてモデルを含むスキーマとカタログに対する USE SCHEMA および USE CATALOG 権限。

登録されているモデルの名前を変更するには、MLflow Client API rename_registered_model() メソッドを使用します。

client=MlflowClient()
client.rename_registered_model("<model-name>", "<new-model-name>")

モデルまたはモデル バージョンを削除する

必要な権限: 登録済みモデルの所有者、およびモデルを含むスキーマとカタログに対する USE SCHEMA および USE CATALOG 権限。

カタログ エクスプローラー UI または API を使用して、登録済みモデルまたは登録済みモデル内のモデル バージョンを削除できます。

API を使用してモデル バージョンまたはモデルを削除する

警告

この操作を元に戻すことはできません。 モデルを削除すると、Unity Catalog によって保存されているすべてのモデル成果物と、登録済みモデルに関連付けられているすべてのメタデータが削除されます。

モデル バージョンを削除する

モデル バージョンを削除するには、MLflow Client API delete_model_version() メソッドを使用します。

# Delete versions 1,2, and 3 of the model
client = MlflowClient()
versions=[1, 2, 3]
for version in versions:
  client.delete_model_version(name="<model-name>", version=version)

モデルを削除する

モデルを削除するには、MLflow Client API delete_registered_model() メソッドを使用します。

client = MlflowClient()
client.delete_registered_model(name="<model-name>")

モデルの一覧表示と検索

次のように MLflow の search_registered_models() Python API を使用して、Unity Catalog 内の登録済みモデルを一覧表示できます。

client=MlflowClient()
client.search_registered_models()

また、次のように search_model_versions() メソッドを使用して、特定のモデル名を検索し、そのバージョンの詳細を一覧表示することもできます。

from pprint import pprint

client=MlflowClient()
[pprint(mv) for mv in client.search_model_versions("name='<model-name>'")]

この例は、Unity Catalog 内のモデルを使用して機械学習アプリケーションを構築する方法を示しています。

Unity Catalog のモデルの例

ワークフローとモデルを Unity Catalog に移行する

Databricks では、ガバナンスの向上、ワークスペースと環境の間の簡単な共有、柔軟性の高い MLOps ワークフローのために、Unity Catalog のモデルを使用することをお勧めします。 次の表は、ワークスペース モデル レジストリと Unity Catalog の機能を比較したものです。

機能 ワークスペース モデル レジストリ (レガシ) Unity Catalog のモデル (推奨)
名前付きエイリアスによるモデル バージョンの参照 モデル レジストリ ステージ: モデル バージョンを 4 つの固定ステージのいずれかに移動し、そのステージで参照します。 ステージの名前変更や追加はできません。 モデル レジストリ エイリアス: 登録されている各モデルのモデル バージョンへのカスタムおよび再割り当て可能な名前付き参照を最大 10 個作成します。
モデルのアクセス制御環境を作成する モデル レジストリ ステージ: 1 つの登録済みモデル内のステージを使用して、モデル バージョンの環境を示し、4 つの固定ステージのうちの 2 つのみ (Staging および Production) でアクセス制御を行います。 登録済みモデル: 3 レベルの名前空間と Unity Catalog のアクセス許可を利用してガバナンスを表現し、MLOps ワークフロー内の各環境に登録されたモデルを作成します。
環境間でのモデルの昇格 (モデルのデプロイ) transition_model_version_stage() MLflow クライアント API を使用してモデル バージョンを別のステージに移動すると、前のステージを参照するワークフローが中断する可能性があります。 copy_model_version() MLflow クライアント API を使用して、登録済みモデル間でモデル バージョンをコピーします。
ワークスペース間でモデルにアクセスして共有する ワークスペース間でモデルを手動でエクスポートおよびインポートするか、個人用アクセス トークンとワークスペース シークレット スコープを使用してリモート モデル レジストリへの接続を構成します。 同じアカウント内のワークスペース間でモデルにすぐにアクセスできます。 コンフィギュレーションは必要ありません。
権限の構成 ワークスペース レベルでアクセス許可を設定します。 アカウント レベルでアクセス許可を設定します。これは、ワークスペース間で一貫したガバナンスを適用します。
Databricks マーケットプレースのモデルにアクセスする 使用不可。 Databricks マーケットプレースから Unity Catalog メタストアにモデルを読み込み、ワークスペース間でアクセスします。

以下のリンク先の記事では、ワークフロー (モデル トレーニングとバッチ推論ジョブ) とモデルをワークスペース モデル レジストリから Unity Catalog に移行する方法について説明します。

Unity Catalog のサポートに関する制限事項

  • ステージは Unity Catalog のモデルではサポートされていません。 Databricks では、Unity Catalog の 3 レベルの名前空間を使用してモデルが置かれている環境を表現し、エイリアスを使用してモデルをデプロイ用に昇格することをお勧めします。 詳細については、アップグレード ガイドを参照してください。
  • Webhook は Unity Catalog のモデルではサポートされていません。 アップグレード ガイドで提案されている代替案を参照してください。
  • 一部の検索 API フィールドと演算子は、Unity Catalog のモデルではサポートされていません。 これは、サポートされているフィルターを使用して検索 API を呼び出し、結果をスキャンすることで軽減できます。 次は一部の例です。
    • order_by パラメーターは、search_model_versions または search_registered_models クライアント API ではサポートされていません。
    • タグベースのフィルター (tags.mykey = 'myvalue') は、search_model_versions または search_registered_models ではサポートされていません。
    • 完全等価以外の演算子 (たとえば、LIKEILIKE!=) は、search_model_versions または search_registered_models ではサポートされません。
    • 登録されているモデルを名前で検索する(たとえば、MlflowClient().search_registered_models(filter_string="name='main.default.mymodel'") はサポートされていません。 特定の登録済みモデルを名前で取得するには、get_registered_model を使用します。
  • Unity Catalog では、登録されたモデルおよびモデル バージョンに関するメール通知とコメント ディスカッション スレッドはサポートされていません。
  • アクティビティ ログは、Unity Catalog のモデルではサポートされていません。 ただし、監査ログを使用して、Unity Catalog 内のモデルのアクティビティを追跡できます。
  • search_registered_models は、Delta Sharing を通じて共有されるモデルに対して古い結果を返す可能性があります。 最新の結果を確認するには、Databricks CLI または SDK を使用してスキーマ内のモデルを一覧表示します。