モデル提供でカスタム Python ライブラリを使用する

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

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

必要条件

• MLflow 1.29 以上

• ネットワーク ポリシーを構成して、モデル サービス エンドポイントからの送信ネットワーク アクセスを制限します。 モデル サービスを使用した検証を参照してください。

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

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

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

構成したら、モデルを提供するに進みます。

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

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

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

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

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

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

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

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

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

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

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

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 パラメーターを使用してその場所を指定し、"code/<wheel-file-name>.whl" パラメーターにextra_pip_requirementsを渡すことができます。

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 ホイールを使用して MLflow モデルを更新する

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

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

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

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

モデルを提供する

パッケージを含む新しいモデル バージョンがモデル レジストリで使用可能な場合は、モデル提供を使用してこのモデル バージョンをエンドポイントに追加できます。

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

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

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

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

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

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