モデルパッケージを作成する (プレビュー)

[アーティクル]
09/03/2024

モデルパッケージは Azure Machine Learning の機能であり、機械学習モデルをサービスプラットフォームにデプロイするために必要なすべての依存関係を収集できます。モデルをデプロイする前にパッケージを作成すると、堅牢で信頼性の高いデプロイと、より効率的な MLOps ワークフローが提供されます。パッケージは、ワークスペース間だけでなく、Azure Machine Learning の外部にも移動できます。

重要

現在、この機能はパブリックプレビュー段階にあります。このプレビューバージョンはサービスレベルアグリーメントなしで提供されており、運用環境のワークロードに使用することは推奨されません。特定の機能はサポート対象ではなく、機能が制限されることがあります。

詳しくは、Microsoft Azure プレビューの追加使用条件に関するページをご覧ください。

この記事では、デプロイのためにモデルをパッケージ化する方法について説明します。

前提条件

この記事の手順に従う前に、次の前提条件が満たされていることをご確認ください。

Azure サブスクリプション。 Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。無料版または有料版の Azure Machine Learning をお試しください。
Azure Machine Learning ワークスペース。準備できていない場合は、「ワークスペースの管理方法」に関する記事の手順を使用して作成します。
Azure ロールベースのアクセス制御 (Azure RBAC) は、Azure Machine Learning の操作に対するアクセスを許可するために使用されます。この記事の手順を実行するには、ユーザーアカウントに、Azure Machine Learning ワークスペースの所有者か共同作成者ロール、またはカスタムロールを割り当てる必要があります。詳細については、「Azure Machine Learning ワークスペースへのアクセスの管理」を参照してください。
パッケージ化するモデル。この例では、ワークスペースに登録されている MLflow モデルを使用します。

注意事項

モデルパッケージは、大規模言語モデルを含め、Azure AI モデルカタログ内のモデルではサポートされていません。 Azure AI モデルカタログ内のモデルは、Azure AI デプロイターゲットの推論用に最適化されており、パッケージ化には適していません。

この例の概要

この例では、Azure Machine Learning でモデルをパッケージ化する方法について説明します。

リポジトリの複製

この記事の例は、azureml-examples リポジトリに含まれているコードサンプルを基にしています。 YAML などのファイルをコピーして貼り付けることなくコマンドをローカルで実行するには、最初にリポジトリを複製してから、ディレクトリをそのフォルダーに変更します。

Azure CLI
Python

git clone https://github.com/Azure/azureml-examples --depth 1
cd azureml-examples/cli

!git clone https://github.com/Azure/azureml-examples --depth 1
!cd azureml-examples/sdk/python

このセクションでは、endpoints/online/deploy-packages/custom-model フォルダーの例を使用します。

ワークスペースに接続する

作業を行う Azure Machine Learning ワークスペースに接続します。

Azure CLI
Python

az account set --subscription <subscription>
az configure --defaults workspace=<workspace> group=<resource-group> location=<location>

ワークスペースは、Azure Machine Learning の最上位のリソースで、Azure Machine Learning を使用するときに作成するすべての成果物を操作するための一元的な場所を提供します。このセクションでは、展開タスクを実行するワークスペースに接続します。

必要なライブラリをインポートします。

from azure.identity import DefaultAzureCredential
from azure.ai.ml import MLClient
from azure.ai.ml.entities import (
    AzureMLOnlineInferencingServer,
    ModelPackage,
    CodeConfiguration,
    BaseEnvironment,
    ModelConfiguration,
)
from azure.ai.ml.entities import (
    ManagedOnlineEndpoint,
    ManagedOnlineDeployment,
    Environment,
    Model,
)

Azure Machine Learning のコンピューティングインスタンスで実行している場合は、次のように MLClient を作成します。
```
ml_client = MLClient.from_config(DefaultAzureCredential())
```
それ以外の場合は、ワークスペースの詳細を構成し、ワークスペースへのハンドルを取得します。
```
subscription_id = "<subscription>"
resource_group = "<resource-group>"
workspace = "<workspace>"

ml_client = MLClient(DefaultAzureCredential(), subscription_id, resource_group, workspace)
```

モデルをパッケージ化する

モデルパッケージを明示的に作成して、パッケージ化操作の実行方法を制御できます。このワークフローは、次の場合に使います。

モデルパッケージの作成方法をカスタマイズする必要がある。
モデルパッケージを Azure Machine Learning の外部にデプロイする必要がある。
MLOps ワークフローでモデルパッケージを使う必要がある。

モデルパッケージを作成するには、次を指定します。

パッケージ化するモデル: 各モデルパッケージに含めることができるモデルは 1 つだけです。 Azure Machine Learning では、同じモデルパッケージに複数のモデルをパッケージ化することはできません。
基本環境: 環境は基本イメージを示すために使用され、Python パッケージではモデルに必要な依存関係があります。 MLflow モデルの場合、Azure Machine Learning によって基本環境が自動的に生成されます。カスタムモデルの場合は、それを指定する必要があります。
サービステクノロジー: モデルの実行に使用される推論スタック。

モデルを登録する

モデルパッケージでは、モデルをワークスペースまたは Azure Machine Learning レジストリに登録する必要があります。この例では、リポジトリにモデルのローカルコピーが既に存在するため、ワークスペース内のレジストリにモデルを発行するだけで済みます。デプロイしようとしているモデルが既に登録されている場合は、このセクションをスキップできます。

Azure CLI
Python

MODEL_NAME='sklearn-regression'
MODEL_PATH='model'
az ml model create --name $MODEL_NAME --path $MODEL_PATH --type custom_model

model_name = "sklearn-regression"
model_path = "model"

model = ml_client.models.create_or_update(Model(name=model_name, path=model_path))

基本環境を作成する

基本環境は、基本イメージとモデルの Python パッケージの依存関係を示すために使われます。このモデルでは、conda ファイルに示されているように、次のパッケージを使う必要があります。

conda.yaml

name: model-env
channels:
  - conda-forge
dependencies:
  - python=3.9
  - numpy=1.23.5
  - pip=23.0.1
  - scikit-learn=1.2.2
  - scipy=1.10.1
  - xgboost==1.3.3

Note

基本環境は、オンラインエンドポイントやバッチエンドポイントへのモデルのデプロイに使う環境とどのように違うでしょうか? モデルをエンドポイントにデプロイする場合、マネージドオンラインエンドポイントが機能するために必要なモデルの依存関係と Python パッケージを環境に含める必要があります。このため、デプロイには手作業が必要であり、モデルの要件とサービス提供プラットフォームの要件を組み合わせる必要があります。一方、モデルパッケージを使うと、推論サーバーに必要なパッケージがパッケージ化時に自動的にモデルパッケージに挿入されるため、このような作業がありません。

次のように環境を作成します。

Azure CLI
Python

環境定義を作成します。

sklearn-regression-env.yml

$schema: https://azuremlschemas.azureedge.net/latest/environment.schema.json
name: sklearn-regression-env
image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu22.04
conda_file: conda.yaml
description: An environment for models built with XGBoost and Scikit-learn.

次に環境を作成します。

az ml environment create -f environment/sklearn-regression-env.yml

base_environment = ml_client.environments.create_or_update(
    Environment(
        name=f"{model_name}-env",
        image="mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu22.04",
        conda_file="environment/conda.yml",
    )
)

パッケージ仕様を作成する

Azure Machine Learning では、Azure CLI または Azure Machine Learning SDK for Python を使ってモデルパッケージを作成できます。カスタムパッケージ仕様では、次の属性がサポートされています。

Azure CLI
Python

属性	Type	内容	必須
`target_environment`	`str`	作成するパッケージの名前。パッケージ操作の結果は、Azure Machine Learning の環境です。	はい
`base_environment_source`	`object`	モデルの依存関係を指定したパッケージの作成に使う基本イメージ。	はい (モデルが MLflow ではない場合)。
`base_environment_source.type`	`str`	基本イメージの種類。基本イメージとして別の環境を使うこと (`type: environment_asset`) のみがサポートされています。
`base_environment_source.resource_id`	`str`	使う基本環境のリソース ID。形式 `azureml:<name>:<version>` または長いリソース ID を使います。
`inferencing_server`	`object`	使う推論サーバー。	はい
`inferencing_server.type`	`azureml_online` `custom`	Azure Machine Learning 推論サーバーの場合は `azureml_online`、TensorFlow Serving や Torch Serve などのカスタムオンラインサーバーの場合は `custom` を使います。	はい
`inferencing_server.code_configuration`	`object`	推論ルーチンを使用したコード構成。メソッド `init` と `run` を含む Python ファイルを少なくとも 1 つ含める必要があります。	はい (モデルが MLflow ではない場合)。
`model_configuration`	`object`	モデルの構成。この属性を使って、結果のイメージでモデルがどのようにパッケージ化されるかを制御します。	いいえ
`model_configuration.mode`	`download` `copy`	モデルがどのようにパッケージ内に配置されるかを示します。指定できる値は `download` (既定値) と `copy` です。デプロイ時にモデルレジストリからモデルをダウンロードする場合は、`download` を使います。このオプションを使うと、モデルは含まれていないため、小さい Docker イメージが作成されます。 Azure Machine Learning からイメージを切断する場合は、`copy` を使います。パッケージ時にモデルは Docker イメージ内にコピーされます。プライベートリンクが有効なワークスペースでは、`copy` はサポートされません。	いいえ

属性	Type	内容	必須
`target_environment`	`str`	作成するパッケージの名前。パッケージ操作の結果は、Azure Machine Learning の環境です。	はい
`base_environment_source`	`BaseEnvironment`	モデルの依存関係を指定したパッケージの作成に使う基本イメージ。	はい (モデルの種類が MLflow でない場合)。
`base_environment_source.type`	`BaseEnvironmentType`	基本イメージの種類。基本イメージとして別の環境を使うこと (`EnvironmentAsset`) のみがサポートされています。
`base_environment_source.resource_id`	`str`	使う基本環境のリソース ID。形式 `azureml:<name>:<version>` または長い形式のリソース ID を使います。
`inferencing_server`	`AzureMLOnlineInferencingServer` `CustomOnlineInferenceServer`	使う推論サーバー。 Azure Machine Learning 推論サーバーに対しては `AzureMLOnlineInferencingServer`、TensorFlow Serving や Torch Serve などのカスタムオンラインサーバーの場合は `CustomOnlineInferenceServer` を使います。 `AzureMLInferencingServer` に設定し、モデルの種類が Mlflow でない場合は、コードの構成セクションを指定し、メソッド `init` と `run` を含む Python ファイルを少なくとも 1 つ含める必要があります。 `CustomOnlineInferenceServer` に設定した場合、オンラインサーバーの構成セクションを指定する必要があります。	はい
`model_configuration`	`ModelConfiguration`	モデルの構成。この属性を使って、結果のイメージでモデルがどのようにパッケージ化されるかを制御します。	いいえ
`model_configuration.mode`	`ModelInputMode`	モデルがどのようにパッケージ内に配置されるかを指定します。指定できる値は `ModelInputMode.DOWNLOAD` (既定値) と `ModelInputMode.COPY` です。デプロイ時にモデルレジストリからモデルをダウンロードする場合は、`ModelInputMode.DOWNLOAD` を使います。このオプションを使うと、モデルは含まれていないため、小さい Docker イメージが作成されます。 Azure Machine Learning からイメージを切断する場合は、`ModelInputMode.COPY` を使います。パッケージ時にモデルは Docker イメージ内にコピーされます。プライベートリンクが有効なワークスペースでは、`ModelInputMode.COPY` はサポートされません。	いいえ

次のようにパッケージ仕様を作成します。

Azure CLI
Python

package-moe.yml

$schema: http://azureml/sdk-2-0/ModelVersionPackage.json
base_environment_source:
    type: environment_asset
    resource_id: azureml:sklearn-regression-env:1
target_environment: sklearn-regression-online-pkg
inferencing_server: 
    type: azureml_online
    code_configuration:
      code: src
      scoring_script: score.py

モデルパッケージを作成するには、次のようにパッケージ仕様を作成します。

pakage_config = ModelPackage(
    target_environment="sklearn-regression-online-pkg",
    base_environment_source=BaseEnvironment(
        type="asset",
        resource_id=f"azureml:{base_environment.name}:{base_environment.version}",
    ),
    inferencing_server=AzureMLOnlineInferencingServer(
        code_configuration=CodeConfiguration(code="src", scoring_script="score.py")
    ),
)

モデルパッケージ操作を開始します。

Azure CLI
Python

az ml model package -n $MODEL_NAME -v $MODEL_VERSION --file package-moe.yml

model_package = ml_client.models.package(model_name, model.version, pakage_config)

パッケージ操作の結果は環境です。

プライベート Python フィードに依存関係があるモデルをパッケージ化する

モデルパッケージは、プライベートフィードで使用できる Python の依存関係を解決できます。この機能を使用するには、ワークスペースからフィードへの接続を作成し、PAT トークン構成を指定する必要があります。次の Python コードは、パッケージ操作を実行するワークスペースを構成する方法を示しています。

from azure.ai.ml.entities import WorkspaceConnection
from azure.ai.ml.entities import PatTokenConfiguration

# fetching secrets from env var to secure access, these secrets can be set outside or source code
git_pat = os.environ["GIT_PAT"]

credentials = PatTokenConfiguration(pat=git_pat)

ws_connection = WorkspaceConnection(
    name="<workspace_connection_name>",
    target="<git_url>",
    type="git",
    credentials=credentials,
)

ml_client.connections.create_or_update(ws_connection)

接続を作成したら、「モデルをパッケージ化する」のセクションで説明したようにモデルパッケージをビルドします。次の例で、パッケージの基本環境は、次の conda ファイルで指定されているように、Python 依存関係 bar のプライベートフィードを使います。

conda.yml

name: foo
channels:
  - defaults
dependencies:
  - python
  - pip
  - pip:
    - --extra-index-url <python_feed_url>
    - bar

MLflow モデルを使っている場合、モデルの依存関係はモデル自体の内部で示されるため、基本環境は必要ありません。代わりに、「カスタムのシグネチャ、環境、またはサンプルを使用したモデルのログ記録」で説明されているように、モデルをログするときにプライベートフィードの依存関係を指定します。

レジストリでホストされているモデルをパッケージ化する

モデルパッケージを使うと、デプロイ前に依存関係を簡単にまとめることができます。ただし、モデルがレジストリでホストされている場合、通常、デプロイのターゲットは別のワークスペースになります。このセットアップでパッケージを作成する場合、target_environment プロパティを使って、モデルパッケージの名前だけでなく、作成する完全な場所を指定します。

次のコードを使うと、レジストリから t5-base モデルのパッケージが作成されます。

モデルが配置されているレジストリと、モデルパッケージを作成する必要があるワークスペースに接続します。

Azure CLI
Python

az login

registry_client = MLClient(
    credential=DefaultAzureCredential(),
    subscription_id=ml_client.subscription_id,
    resource_group_name=ml_client.resource_group_name,
    workspace_reference=ml_client.workspace_name,
    registry_name=registry_name,
)

パッケージ化するモデルへの参照を取得します。この例では、azureml レジストリからモデル t5-base をパッケージ化します。

Azure CLI
Python

MODEL_NAME="t5-base"
MODEL_VERSION=$(az ml model show --name $MODEL_NAME --label latest --registry-name azureml | jq .version -r)

model_name = "t5-base"
model = registry_client.models.get(name=model_name, label="latest")

パッケージ仕様を構成します。パッケージ化するモデルは MLflow なので、基本環境とスコアリングスクリプトは省略可能です。

Azure CLI
Python

package.yml

$schema: http://azureml/sdk-2-0/ModelVersionPackage.json
target_environment: pkg-t5-base-online
inferencing_server: 
    type: azureml_online

import time

model_package_name = f"pkg-{model.name}-{model.version}"
model_package_version = str(int(time.time()))

package_config = ModelPackage(
    target_environment=model_package_name,
    target_environment_version=model_package_version,
    inferencing_server=AzureMLOnlineInferencingServer(),
)

モデルパッケージを作成する操作を開始します。

Azure CLI
Python

az ml model package --name $MODEL_NAME \
                    --version $MODEL_VERSION \
                    --registry-name azureml \
                    --file package.yml

model_package = registry_client.models.package(
    model.name, model.version, package_config
)

これで、ターゲットワークスペースにパッケージが作成され、デプロイする準備ができました。

Azure Machine Learning の外部にデプロイするモデルをパッケージ化する

必要に応じて、モデルパッケージを Azure Machine Learning の外部にデプロイできます。移植性を保証するに必要なことは、Azure Machine Learning のモデルレジストリから参照するのではなく、生成された docker イメージ内にモデル自体がコピーされるように、パッケージ内のモデル構成のモードを copy に設定することだけです。

次のコードは、モデルパッケージで copy を構成する方法を示しています。

Azure CLI
Python

package-external.yml

$schema: http://azureml/sdk-2-0/ModelVersionPackage.json
base_environment_source:
    type: environment_asset
    resource_id: azureml:sklearn-regression-env:1
target_environment: sklearn-regression-docker-pkg
inferencing_server: 
    type: azureml_online
    code_configuration:
      code: src
      scoring_script: score.py
model_configuration:
  mode: copy

pakage_config = ModelPackage(
    target_environment="sklearn-regression-online-pkg",
    base_environment_source=BaseEnvironment(
        type="asset",
        resource_id=f"azureml:{base_environment.name}:{base_environment.version}",
    ),
    inferencing_server=AzureMLOnlineInferencingServer(
        code_configuration=CodeConfiguration(code="src", scoring_script="score.py")
    ),
    model_configuration=ModelConfiguration(mode="copy"),
)

次の方法で共有

モデルパッケージを作成する (プレビュー)

前提条件

この例の概要

リポジトリの複製

ワークスペースに接続する

モデルをパッケージ化する

モデルを登録する

基本環境を作成する

パッケージ仕様を作成する

プライベート Python フィードに依存関係があるモデルをパッケージ化する

レジストリでホストされているモデルをパッケージ化する

Azure Machine Learning の外部にデプロイするモデルをパッケージ化する

次のステップ

フィードバック

その他のリソース

次の方法で共有

モデル パッケージを作成する (プレビュー)

前提条件

この例の概要

リポジトリの複製

ワークスペースに接続する

モデルをパッケージ化する

モデルを登録する

基本環境を作成する

パッケージ仕様を作成する

プライベート Python フィードに依存関係があるモデルをパッケージ化する

レジストリでホストされているモデルをパッケージ化する

Azure Machine Learning の外部にデプロイするモデルをパッケージ化する

次のステップ

フィードバック

その他のリソース

モデルパッケージを作成する (プレビュー)