モデルサービングでカスタム Python ライブラリを使用する

この記事では、モデルをログに記録するときにカスタムライブラリまたはプライベートミラーサーバーからのライブラリを含めて、 それらをMosaic AI Model Servingでのモデルのデプロイで使用できるようにする方法を学びます。 このガイドで詳しく説明されている手順は、トレーニング済みの ML モデルをデプロイする準備ができた後、Databricksモデルサービングエンドポイントを作成する前に完了する必要があります。

モデル開発では、多くの場合、前処理または後処理の関数、カスタム モデル定義、およびその他の共有ユーティリティを含むカスタム Python ライブラリを使用する必要があります。 さらに、多くのエンタープライズセキュリティチームは、 サプライチェーン攻撃のリスクを減らすために、NexusやArtifactoryなどのプライベートPyPiミラーの使用を推奨しています。 Databricks は、カスタム ライブラリと Databricks ワークスペースのプライベート ミラーからのライブラリのインストールを ネイティブにサポート しています。

必要条件

• MLflow 1.29 以降

• モデルサービングエンドポイントからの送信ネットワークアクセスを制限するには、ネットワークポリシーを設定します。 モデルサービングによる検証を参照してください。

オプション1: プライベートパッケージリポジトリを使用する

組織でプライベート PyPI ミラー (Nexus や Artifactory など) を使用している場合は、オプション 1 を使用します。ワークスペース管理者は、ワークスペース用の安心パッケージリポジトリとして設定できます。 モデルサービングは、モデル環境を構築するときに、このワークスペースレベルの構成を自動的に使用します。

プライベート パッケージ リポジトリをセットアップするには、 「もうPythonパッケージ リポジトリを構成する」を参照してください。

設定が完了したら、モデルの提供に進みます。

オプション 2: カスタム ライブラリをホイール ファイルとしてパッケージ化する

プライベート PyPI ミラーにアクセスできない場合、またはどのパッケージ リポジトリでも使用できないカスタム ライブラリがある場合は、オプション 2 を使用します。これらをPython wheelファイルとしてパッケージ化し、モデルをログに記録するときに含めることができます。

ステップ 1: 依存関係ファイルをアップロードする

Databricks では、依存関係ファイルを Unity Catalog ボリュームにアップロードすることをお勧めします。 または、Databricks UI を使用して Databricks File System (DBFS) にアップロードすることもできます。

ライブラリをノートブックで使用できるようにするには、 %pipを使用してライブラリをインストールする必要があります。 %pip を使用すると、ライブラリが現在のノートブックにインストールされ、依存関係がクラスターにダウンロードされます。

ステップ 2: カスタム ライブラリを使用してモデルをログに記録する

ライブラリをインストールし、Python wheel ファイルを Unity Catalog ボリュームまたは DBFS にアップロードしたら、スクリプトに次のコードを含めます。 extra_pip_requirementsで、依存関係ファイルのパスを指定します。

Python

mlflow.sklearn.log_model(model, "sklearn-model", extra_pip_requirements=["/volume/path/to/dependency.whl"])

DBFS の場合は、次を使用します。

Python

mlflow.sklearn.log_model(model, "sklearn-model", extra_pip_requirements=["/dbfs/path/to/dependency.whl"])

カスタム ライブラリがある場合は、ログを構成するときに、モデルに関連付けられているすべてのカスタム Python ライブラリを指定する必要があります。 これは、log_model() の extra_pip_requirements または conda_env パラメーターを使用して行うことができます。

重要

DBFS を使用する場合は、extra_pip_requirementsをログに記録するときに、dbfs パスの前にスラッシュ (/) を必ず含めてください。DBFS パスの詳細については、「 Databricks でファイルを操作する」を参照してください。

Python

from mlflow.utils.environment import _mlflow_conda_env

mlflow.pyfunc.log_model(
    name="model",
    python_model=MyModel(),
    extra_pip_requirements=["/volumes/path/to/dependency"],
)

カスタム ライブラリがボリュームまたはDBFS以外の場所に格納されている場合は、code_paths パラメーターを使用してその場所を指定し、extra_pip_requirements パラメーターに"code/<wheel-file-name>.whl"渡すことができます。

Python

mlflow.pyfunc.log_model(
    name="model",
    python_model=MyModel(),
    code_paths=["/path/to/dependency.whl"], # This will be logged as `code/dependency.whl`
    extra_pip_requirements=["code/dependency.whl"],
)

ステップ 3: Python wheel ファイルを使用してMLflowモデルを更新する

MLflowには、 ファイルとして事前にパッケージ化されたすべての依存関係とともにモデルをログに記録するためのadd_libraries_to_model() ユーティリティが用意されています。Python wheelこれにより、モデルの依存関係として指定されている 他のすべての ライブラリに加えて、カスタムライブラリがモデルと共にパッケージ化されます。 これにより、モデルで使用されるライブラリが、トレーニング環境からアクセス可能なライブラリとまったく同じであることが保証されます。

次の例では、model_uri は構文 models:/<uc-model>/<model-version> を使用して Unity Catalog モデルレジストリを参照します。 ワークスペース モデルレジストリ (レガシ) を参照するには models:/<model-name>/<model-version>、.

モデルレジストリ URI を使用すると、このユーティリティは既存の登録済みモデルの下に新しいバージョンを生成します。

Python

import mlflow.models.utils
mlflow.models.utils.add_libraries_to_model(<model-uri>)

モデルをサービングする

パッケージが含まれている新しいモデルバージョンがモデルレジストリで利用可能になったら、 モデルサービングを使用してこのモデルバージョンをエンドポイントに追加できます。

パッケージのインストールのトラブルシューティング

ビルド フェーズ中にモデルのデプロイが失敗した場合は、ビルド ログを確認してパッケージのインストールの問題を特定できます。

1. Databricks ワークスペースの [サービング] ページに移動します。
2. エンドポイント名をクリックすると、エンドポイントの詳細が開きます。
3. [ログ] タブをクリックします。
4. ドロップダウン メニューから失敗したバージョンを選択します。
5. [ビルド ログ] をクリックします。

エラー メッセージを確認して問題を特定します。

問題を解決したら、新しいデプロイメントを作成するか、エンドポイントを更新して新しいビルドをトリガーします。

プライベートパッケージリポジトリのトラブルシューティング

プライベート パッケージ リポジトリを使用している場合、一般的な問題は次のとおりです。

• 不足しているパッケージ : 構成されたリポジトリでパッケージが利用できません。必要なパッケージをプライベート リポジトリに追加します。
• 接続の問題 : モデルサービングがパッケージリポジトリにアクセスできません。ネットワーク接続とファイアウォール ルールを確認します。
• 認証失敗 : リポジトリに設定された資格情報が有効ではないか、期限が切れています。ワークスペース構成内のシークレットを更新します。

サーバレスノートブックは、ワークスペース用に設定されたものと同じリポジトリパッケージを使用します。 ノートブックを使用して、モデルサービングにデプロイする前にモデルのrequirements.txtファイルから要件をインストールすることで、接続、認証、およびパッケージの可用性をテストできます。

Python

import mlflow
import subprocess
import sys

# Step 1: Set your model details
catalog = "<your_catalog>"
schema = "<your_schema>"
model_name = "<your_model>"
version = <your_version>

# Step 2: Download the model's requirements.txt
full_model_name = f"{catalog}.{schema}.{model_name}"
requirements_uri = f"models:/{full_model_name}/{version}/requirements.txt"

print(f"Downloading artifacts from: {requirements_uri}")
local_path = mlflow.artifacts.download_artifacts(requirements_uri)

# Step 3: Print the requirements
with open(local_path, "r") as f:
    print(f.read())

# Step 4: Install the requirements using the workspace's default package repository
print(f"Installing requirements from {local_path}...")
subprocess.check_call([sys.executable, "-m", "pip", "install", "-r", local_path])
print("Installation complete!")