オンライン エンドポイントを使用して機械学習モデルをデプロイおよびスコア付けする

適用対象:Azure CLI ml extension v2 (現行)Python SDK azure-ai-ml v2 (現行)

この記事では、リアルタイム推論で使用するために、モデルをオンライン エンドポイントにデプロイする方法について説明します。 まずローカル コンピューターにモデルをデプロイして、発生するエラーをデバッグします。 次に、Azure にモデルをデプロイしてテストします。 デプロイ ログを確認して、サービス レベル アグリーメント (SLA) を監視する方法についても説明します。 この記事の終わりまでに、リアルタイム推論に使用できるスケーラブルな HTTPS/REST エンドポイントが用意されています。

オンライン エンドポイントは、リアルタイムの推論に使用されるエンドポイントです。 オンライン エンドポイントには、2 つの種類があります。マネージド オンライン エンドポイントKubernetes オンライン エンドポイントです。 エンドポイントの詳細、およびマネージド オンライン エンドポイントと Kubernetes オンライン エンドポイントの違いについては、「Azure Machine Learning エンドポイントとは」を参照してください。

マネージド オンライン エンドポイントは、ターンキー MLモデルをデプロイするのに役立ちます。 マネージド オンライン エンドポイントは、スケーラブルでフル マネージドの方法で Azure の強力な CPU および GPU マシンと動作します。 マネージド オンライン エンドポイントは、モデルの提供、スケーリング、セキュリティ保護、監視を行います。基になるインフラストラクチャの設定と管理のオーバーヘッドがなくなります。

このドキュメントの主な例では、デプロイにマネージド オンライン エンドポイントを使用します。 代わりに Kubernetes を使用する場合は、マネージド オンライン エンドポイントに関する説明に沿って本ドキュメント内に記載されている注記を参照してください。

前提条件

適用対象: Azure CLI ML 拡張機能 v2 (現行)

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

  • Azure ロールベースのアクセス制御 (Azure RBAC) は、Azure Machine Learning の操作に対するアクセスを許可するために使用されます。 この記事の手順を実行するには、ユーザー アカウントに、Azure Machine Learning ワークスペースの所有者共同作成者ロール、または Microsoft.MachineLearningServices/workspaces/onlineEndpoints/* を許可するカスタム ロールを割り当てる必要があります。 スタジオを使用してオンライン エンドポイントやデプロイを作成または管理する場合は、リソース グループ所有者から追加のアクセス許可 "Microsoft.Resources/deployments/write" が必要です。 詳細については、「Azure Machine Learning ワークスペースへのアクセスの管理」を参照してください。

  • (省略可能) ロ―カルでデプロイするには、ローカル コンピューターに Docker エンジンをインストールする必要があります。 問題のデバッグを容易にするため、このオプションを "強くお勧めします"。

デプロイのための仮想マシン クォータの割り当て

マネージド オンライン エンドポイントの場合、Azure Machine Learning では、一部の VM SKU でアップグレードを実行するためにコンピューティング リソースの 20% が予約されます。 デプロイで特定の数のインスタンスを要求する場合は、使用可能な ceil(1.2 * number of instances requested for deployment) * number of cores for the VM SKU のクォータを確保して、エラーが発生しないようにする必要があります。 たとえば、デプロイで Standard_DS3_v2 VM (4 コアを搭載) の 10 個のインスタンスを要求する場合は、使用可能な 48 コア (12 instances * 4 cores) のクォータが必要です。 使用状況を確認してクォータの増加を要求するには、「Azure portal で使用状況とクォータを表示する」を参照してください。

追加のクォータ予約から除外される特定の VM SKU があります。 完全な一覧を表示するには、マネージド オンライン エンドポイント SKU の一覧を参照してください。

Azure Machine Learning には、すべてのユーザーがクォータにアクセスして限られた時間のテストを実行できる、共有クォータ プールが用意されています。 スタジオを使ってモデル カタログから Llama-2、Phi、Nemotron、Mistral、Dolly、Deci-DeciLM の各モデルをマネージド オンライン エンドポイントにデプロイする場合、Azure Machine Learning では、この共有クォータに短時間アクセスできます。

オンライン エンドポイントのデプロイに共有クォータを使用する方法の詳細については、「スタジオを使用して基礎モデルをデプロイする方法」を参照してください。

システムを準備する

環境変数の設定

まだ Azure CLI の既定値を設定していない場合は、既定の設定を保存する必要があります。 サブスクリプション、ワークスペース、およびリソース グループの値を複数回渡さないようにするには、次のコードを実行します。

az account set --subscription <subscription ID>
az configure --defaults workspace=<Azure Machine Learning workspace name> group=<resource group>

examples リポジトリをクローンします

このアーティクルに従って、まずサンプル リポジトリ (azureml-examples) を複製します。 その後、次のコードを実行してリポジトリの cli/ ディレクトリに移動します。

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

ヒント

--depth 1 を使用すると、リポジトリに対する最新のコミットだけが複製されるので、操作の完了にかかる時間を短縮できます。

このチュートリアルのコマンドは、cli ディレクトリ内のファイル deploy-local-endpoint.shdeploy-managed-online-endpoint.sh に入っています。また、YAML 構成ファイルは endpoints/online/managed/sample/ サブディレクトリ内にあります。

注意

Kubernetes オンライン エンドポイントの YAML 構成ファイルは、endpoints/online/kubernetes/サブディレクトリにあります。

エンドポイントを定義する

エンドポイントを定義するには、以下を指定する必要があります。

  • [エンドポイント名] : エンドポイントの名前。 Azure リージョンで一意である必要があります。 名前付け規則の詳細については、「エンドポイントの制限」を参照してください。
  • 認証モード: エンドポイントの認証方法。 キーベースの認証と Azure Machine Learning トークンベースの認証のどちらかを選択します。 キーには有効期限がありませんが、トークンには有効期限があります。 認証の詳細については、オンライン エンドポイントの認証に関する記事を参照してください。
  • 必要に応じて、エンドポイントに説明やタグを追加できます。

エンドポイント名を設定する

エンドポイント名を設定するには、次のコマンドを実行します (YOUR_ENDPOINT_NAME を一意の名前に置き換えます)。

Linux の場合は、次のコマンドを実行します。

export ENDPOINT_NAME="<YOUR_ENDPOINT_NAME>"

エンドポイントを構成する

次のスニペットは、endpoints/online/managed/sample/endpoint.yml ファイルを示しています。

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: key

エンドポイント YAML 形式のリファレンスを次の表で説明します。 これらの属性の指定方法については、オンライン エンドポイント YAML リファレンスに関する記事を参照してください。 マネージド エンドポイントに関する制限については、オンライン エンドポイントの制限に関する記事を参照してください。

Key 説明
$schema (省略可能) YAML スキーマ。 上記のコード スニペットをブラウザーで表示すると、YAML ファイルで使用可能なすべてのオプションを確認できます。
name エンドポイントの名前。
auth_mode キーベースの認証に key を使用します。 Azure Machine Learning のトークン ベースの認証に aml_token を使用します。 最新のトークンを取得するには、az ml online-endpoint get-credentials コマンドを使用します。

デプロイを定義する

デプロイは、実際の推論を実行するモデルをホストするのに必要なリソースのセットです。 モデルをデプロイするには、次が必要です。

  • モデル ファイル (または、ワークスペースに既に登録されているモデルの名前とバージョン)。 この例では、回帰を行う scikit-learn モデルを使用します。
  • スコアリング スクリプト、つまり、特定の入力要求でモデルを実行するコード。 スコアリング スクリプトは、デプロイされた Web サービスに送信されたデータを受け取り、それをモデルに渡します。 その後、スクリプトはモデルを実行して、その応答をクライアントに返します。 スコアリング スクリプトはモデルに固有のものであり、モデルが入力として期待し、出力として返すデータを理解する必要があります。 この例では、score.py ファイルがあります。
  • モデルが実行される環境。 この環境には、Conda 依存関係がある Docker イメージか、または Dockerfile のいずれかを使用できます。
  • インスタンスの種類とスケーリング キャパシティを指定するための設定。

次の表は、デプロイの主な属性について説明しています。

属性 内容
名前 デプロイの名前。
エンドポイント名 デプロイを作成するエンドポイントの名前。
モデル デプロイに使用するモデル。 この値は、ワークスペース内の既存のバージョン管理されたモデルへの参照またはインライン モデルの仕様のいずれかです。
コード パス モデルのスコアリングに使用されるすべての Python ソース コードが格納されている、ローカル開発環境上のディレクトリへのパス。 入れ子になったディレクトリとパッケージを使用できます。
スコアリング スクリプト ソース コード ディレクトリ内のスコアリング ファイルへの相対パス。 この Python コードには、init() 関数と run() 関数が含まれている必要があります。 init() 関数は、モデルの作成または更新後に呼び出されます (たとえば、モデルをメモリにキャッシュするために使用できます)。 run() 関数は、実際のスコアリングおよび予測を実行するために、エンドポイントが呼び出されるたびに呼び出されます。
環境 モデルとコードをホスティングする環境。 この値は、ワークスペース内の既存のバージョン管理された環境への参照、またはインライン環境仕様のいずれかになります。
インスタンスの種類 デプロイに使用する VM サイズ。 サポートされているサイズの一覧については、マネージド オンライン エンドポイント SKU の一覧に関するページを参照してください。
インスタンス数 デプロイに使用するインスタンスの数。 想定されるワークロードに基づく値を指定します。 高可用性を実現するために、この値を少なくとも 3 に設定することをお勧めします。 アップグレードを実行するために 20% 余分に予約されています。 詳細については、デプロイのための仮想マシン クォータの割り当てに関連する記事を参照してください。

Note

  • デプロイの背後にあるインスタンスがセキュリティ パッチやその他の回復操作を実行すると、(環境で定義されている) モデルとコンテナー イメージは、デプロイによりいつでも再び参照できます。 Azure Container Registry で登録済みのモデルまたはコンテナー イメージをデプロイに使用し、モデルまたはコンテナー イメージを削除した場合、再イメージ化が行われると、これらの資産に依存するデプロイが失敗する可能性があります。 モデルまたはコンテナー イメージを削除した場合は、依存するデプロイが、代替モデルまたはコンテナー イメージで再作成または更新されていることを確認します。
  • 環境で参照されるコンテナー レジストリは、エンドポイント ID に Microsoft Entra 認証と Azure RBAC を介してアクセスする権限がある場合にのみ、プライベートにすることができます。 同じ理由から、Azure Container Registry 以外のプライベート Docker レジストリはサポートされていません。

デプロイを構成する

次のスニペットは、デプロイを構成するのに必要なすべての入力が指定された endpoints/online/managed/sample/blue-deployment.yml ファイルを示しています。

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: my-endpoint
model:
  path: ../../model-1/model/
code_configuration:
  code: ../../model-1/onlinescoring/
  scoring_script: score.py
environment: 
  conda_file: ../../model-1/environment/conda.yaml
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
instance_type: Standard_DS3_v2
instance_count: 1

注意

blue-deployment.yml ファイルで、次のデプロイ属性が指定されています。

  • model - この例では、path を使用してインラインでモデルのプロパティを指定しています。 モデル ファイルは自動的にアップロードされ、自動生成された名前で登録されます。
  • environment - この例では、path を含むインライン定義を使用しています。 イメージには environment.docker.image を使用します。 イメージ上に conda_file 依存関係がインストールされます。

デプロイ中に、スコアリング モデル用の Python ソースなどのローカル ファイルが開発環境からアップロードされます。

YAML スキーマの詳細については、オンライン エンドポイント YAML リファレンスに関するドキュメントを参照してください。

注意

コンピューティング先として、マネージド エンドポイントの代わりに Kubernetes を使用するには:

  1. Azure Machine Learning スタジオを使用して、Kubernetes クラスターを作成し、Azure Machine Learning ワークスペースにコンピューティング先としてアタッチします。
  2. Kubernetes をターゲットにするには、マネージド エンドポイント YAML の代わりに、エンドポイント YAML を使用します。 target の値を、登録済みのコンピューティング先の名前に変更するには、YAML を編集する必要があります。 Kubernetes デプロイに適用できる追加のプロパティを持つこの deployment.yaml を使用できます。

この記事で使用されているコマンド (オプションの SLA 監視と Azure Log Analytics 統合を除く) はすべて、マネージド エンドポイントまたは Kubernetes エンドポイントで使用できます。

モデルと環境を別々に登録する

この例では、インラインで path (ファイルのアップロード先) を指定します。 CLI によってファイルが自動的にアップロードされ、モデルと環境が登録されます。 運用環境ではベスト プラクティスとして、モデルと環境を登録し、登録する名前とバージョンを YAML で個別に指定することをお勧めします。 model: azureml:my-model:1 または environment: azureml:my-env:1.の形式を使用します。

登録するためには、modelenvironment の YAML 定義を別々の YAML ファイルに抽出し、az ml model create コマンドと az ml environment create コマンドを使用します。 これらのコマンドの詳細については、az ml model create -haz ml environment create -h を実行してください。

モデルを資産として登録する方法の詳細については、「CLI を使用して、Machine Learning でモデルを資産として登録する」を参照してください。 環境を作成する方法の詳細については、「CLI & SDK (v2) を使用して Azure Machine Learning 環境を管理する」を参照してください。

CPU と GPU の異なるインスタンス タイプおよびイメージを使用する

上記の blue-deployment.yml ファイルでの定義では、汎用型の Standard_DS3_v2 インスタンスと非 GPU Docker イメージ mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest が使用されています。 GPU コンピューティングの場合は、GPU コンピューティング タイプの SKU と GPU の Docker イメージを選択します。

サポートされる汎用タイプと GPU インスタンス タイプについては、マネージド オンライン エンドポイントでサポートされる VM SKU に関するページを参照してください。 Azure Machine Learning CPU と GPU の基本イメージの一覧については、「Azure Machine Learning 基本イメージ」を参照してください。

注意

コンピューティング先として、マネージド エンドポイントの代わりに Kubernetes を使用する場合は、Kubernetes コンピューティング先の概要に関するページを参照してください。

AZUREML_MODEL_DIR に関するモデル パスを特定する

Azure Machine Learning にモデルをデプロイする場合、デプロイ構成の一部として、デプロイするモデルの場所を指定する必要があります。 Azure Machine Learning では、モデルへのパスは AZUREML_MODEL_DIR 環境変数で追跡されます。 AZUREML_MODEL_DIR に関してモデル パスを特定することで、マシンにローカルに保存されている 1 つ以上のモデルをデプロイしたり、Azure Machine Learning ワークスペースに登録されているモデルをデプロイしたりできます。

説明のために、単一のモデルをデプロイする場合と、ローカルに保存された複数のモデルをデプロイする場合の最初の 2 つのケースについて、次のローカル フォルダー構造を参照します。

A screenshot showing a folder structure containing multiple models.

デプロイで単一のローカル モデルを使用する

ローカル マシンにある単一のモデルをデプロイで使用するには、デプロイ YAML で path から model を指定します。 パス /Downloads/multi-models-sample/models/model_1/v1/sample_m1.pkl を持つデプロイ YAML の例を次に示します。

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json 
name: blue 
endpoint_name: my-endpoint 
model: 
  path: /Downloads/multi-models-sample/models/model_1/v1/sample_m1.pkl 
code_configuration: 
  code: ../../model-1/onlinescoring/ 
  scoring_script: score.py 
environment:  
  conda_file: ../../model-1/environment/conda.yml 
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest 
instance_type: Standard_DS3_v2 
instance_count: 1 

デプロイを作成すると、環境変数 AZUREML_MODEL_DIR は、モデルが格納されている Azure 内の格納場所 (storage location) をポイントするようになります。 たとえば、/var/azureml-app/azureml-models/81b3c48bbf62360c7edbbe9b280b9025/1 にはモデル sample_m1.pkl が含まれます。

スコアリング スクリプト (score.py) 内で、init() 関数でモデル (この例では sample_m1.pkl) を読み込むことができます。

def init(): 
    model_path = os.path.join(str(os.getenv("AZUREML_MODEL_DIR")), "sample_m1.pkl") 
    model = joblib.load(model_path) 

デプロイで複数のローカル モデルを使用する

Azure CLI、Python SDK、その他のクライアント ツールでは、配置定義で 1 回のデプロイあたり 1 つのモデルのみを指定できますが、すべてのモデルをファイルまたはサブディレクトリとして含むモデル フォルダーを登録することで、1 回のデプロイで複数のモデルを引き続き使用できます。

先ほどのフォルダー構造の例では、models フォルダーに複数のモデルがあることがわかります。 デプロイ YAML では、models フォルダーへのパスを次のように指定できます。

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json 
name: blue 
endpoint_name: my-endpoint 
model: 
  path: /Downloads/multi-models-sample/models/ 
code_configuration: 
  code: ../../model-1/onlinescoring/ 
  scoring_script: score.py 
environment:  
  conda_file: ../../model-1/environment/conda.yml 
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest 
instance_type: Standard_DS3_v2 
instance_count: 1 

デプロイを作成すると、環境変数 AZUREML_MODEL_DIR は、モデルが格納されている Azure 内の格納場所 (storage location) をポイントするようになります。 たとえば、/var/azureml-app/azureml-models/81b3c48bbf62360c7edbbe9b280b9025/1 にはモデルとファイル構造が含まれます。

この例では、AZUREML_MODEL_DIR フォルダーの内容は次のようになります。

A screenshot of the folder structure of the storage location for multiple models.

スコアリング スクリプト (score.py) 内で、init() 関数でモデルを読み込むことができます。 sample_m1.pkl モデルを読み込むコードを次に示します。

def init(): 
    model_path = os.path.join(str(os.getenv("AZUREML_MODEL_DIR")), "models","model_1","v1", "sample_m1.pkl ") 
    model = joblib.load(model_path) 

1 つのデプロイに複数のモデルをデプロイする方法の例については、1 つのデプロイへの複数のモデルのデプロイ (CLI の例)1 つのデプロイへの複数のモデルのデプロイ (SDK の例) に関する記事を参照してください。

ヒント

登録するファイルが 1500 を超える場合は、モデルの登録時にファイルまたはサブディレクトリを .tar.gz として圧縮することを検討してください。 モデルを使用するには、スコアリング スクリプトから init() 関数のファイルまたはサブディレクトリを圧縮解除します。 または、モデルを登録するときに、azureml.unpack プロパティを True に設定すると、ファイルやサブディレクトリが自動圧縮解除されます。 この場合、圧縮解除は初期化ステージで 1 回行われます。

Azure Machine Learning ワークスペースに登録されたモデルをデプロイで使用する

Azure Machine Learning ワークスペースに登録されている 1 つ以上のモデルをデプロイで使用するには、デプロイ YAML に登録されているモデルの名前を指定します。 たとえば、次のデプロイ YAML 構成で登録された model の名前を azureml:local-multimodel:3 と指定します。

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json 
name: blue 
endpoint_name: my-endpoint 
model: azureml:local-multimodel:3 
code_configuration: 
  code: ../../model-1/onlinescoring/ 
  scoring_script: score.py 
environment:  
  conda_file: ../../model-1/environment/conda.yml 
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest 
instance_type: Standard_DS3_v2 
instance_count: 1 

この例では、local-multimodel:3 に Azure Machine Learning スタジオの [モデル] タブから表示できる次のモデルの成果物が含まれることを考慮してください。

A screenshot of the folder structure showing the model artifacts of the registered model.

デプロイを作成すると、環境変数 AZUREML_MODEL_DIR は、モデルが格納されている Azure 内の格納場所 (storage location) をポイントするようになります。 たとえば、/var/azureml-app/azureml-models/local-multimodel/3 にはモデルとファイル構造が含まれます。 AZUREML_MODEL_DIR は、モデル成果物のルートを含むフォルダーを指します。 この例に基づき、AZUREML_MODEL_DIR フォルダーの内容は次のようになります。

A screenshot of the folder structure showing multiple models.

スコアリング スクリプト (score.py) 内で、init() 関数でモデルを読み込むことができます。 たとえば、次の diabetes.sav モデルを読み込みます。

def init(): 
    model_path = os.path.join(str(os.getenv("AZUREML_MODEL_DIR"), "models", "diabetes", "1", "diabetes.sav") 
    model = joblib.load(model_path) 

スコアリング スクリプトを理解する

ヒント

オンライン エンドポイントのスコアリング スクリプトの形式は、前のバージョンの CLI や Python SDK で使用されている形式と同じです。

前述のように、code_configuration.scoring_script で指定されているスコアリング スクリプトには、init() 関数と run() 関数が含まれている必要があります。

この例では、score.py ファイル: score.py を使用します

import os
import logging
import json
import numpy
import joblib


def init():
    """
    This function is called when the container is initialized/started, typically after create/update of the deployment.
    You can write the logic here to perform init operations like caching the model in memory
    """
    global model
    # AZUREML_MODEL_DIR is an environment variable created during deployment.
    # It is the path to the model folder (./azureml-models/$MODEL_NAME/$VERSION)
    # Please provide your model's folder name if there is one
    model_path = os.path.join(
        os.getenv("AZUREML_MODEL_DIR"), "model/sklearn_regression_model.pkl"
    )
    # deserialize the model file back into a sklearn model
    model = joblib.load(model_path)
    logging.info("Init complete")


def run(raw_data):
    """
    This function is called for every invocation of the endpoint to perform the actual scoring/prediction.
    In the example we extract the data from the json input and call the scikit-learn model's predict()
    method and return the result back
    """
    logging.info("model 1: request received")
    data = json.loads(raw_data)["data"]
    data = numpy.array(data)
    result = model.predict(data)
    logging.info("Request processed")
    return result.tolist()

init() 関数は、コンテナーが初期化または起動された時に呼び出されます。 初期化は、通常、デプロイが作成または更新された直後に実行されます。 init 関数は、(この例で行っているように) モデルをメモリにキャッシュするなど、グローバルな初期化操作のロジックを記述する場所です。

run() 関数は、エンドポイントが呼び出されるたびに呼び出され、実際のスコアリングと予測を実行します。 この例では、JSON 入力からデータを抽出し、scikit-learn モデルの predict() メソッドを呼び出し、結果を返します。

ローカル エンドポイントを使用してデプロイとデバッグをローカルで行う

Azure にデプロイする前に、コードと構成を検証およびデバッグして、エンドポイントをローカルでテスト実行することを "強くお勧めします"。 Azure CLI と Python SDK ではローカルのエンドポイントとデプロイがサポートされていますが、Azure Machine Learning スタジオと ARM テンプレートではサポートされていません。

ローカルにデプロイするには、Docker エンジンをインストールして実行する必要があります。 通常、Docker エンジンは、コンピューターの起動時に起動します。 起動しない場合は、Docker エンジンをトラブルシューティングします。

ヒント

Azure Machine Learning 推論 HTTP サーバー Python パッケージを使用して、Docker エンジンなしでスコアリング スクリプトをローカルでデバッグできます。 推論サーバーを使用したデバッグは、ローカル エンドポイントにデプロイする前にスコアリング スクリプトをデバッグするのに役立ちます。これにより、デプロイ コンテナーの構成の影響を受けることなくデバッグできます。

Note

ローカル エンドポイントには、次の制限があります。

  • トラフィック ルール、認証、プローブ設定はサポート "されません"。
  • エンドポイントごとにサポートされるデプロイは 1 つのみです。
  • ローカル モデル ファイル、およびローカルの conda ファイルのみの環境をサポートします。 登録済みのモデルをテストする場合は、最初にそれらを CLI または SDK を使用してダウンロードしてから、デプロイ定義で path を使用して親フォルダーを参照します。 登録された環境をテストする場合は、Azure Machine Learning スタジオで環境のコンテキストを確認し、使用するローカル conda ファイルを準備します。 この記事の例では、ローカル デプロイをサポートする、ローカル モデル、およびローカル conda ファイルの環境を使用する方法を示しています。

Azure にデプロイする前にオンライン エンドポイントをローカルでデバッグする方法の詳細については、「Visual Studio Code を使用してオンライン エンドポイントをローカルでデバッグする」を参照してください。

モデルをローカルにデプロイする

最初にエンドポイントを作成します。 必要に応じて、ローカル エンドポイントの場合は、この手順をスキップして直接デプロイを作成し (次の手順)、これにより必要なメタデータを作成します。 モデルをローカル環境にデプロイすると、開発とテストに役立ちます。

az ml online-endpoint create --local -n $ENDPOINT_NAME -f endpoints/online/managed/sample/endpoint.yml

ここで、エンドポイントの下に blue という名前のデプロイを作成します。

az ml online-deployment create --local -n blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml

--local フラグは、エンドポイントを Docker 環境にデプロイするよう CLI に命令するものです。

ヒント

お使いのエンドポイントをローカルでテストおよびデバッグするには、Visual Studio Code を使用します。 詳細については、Visual Studio Code でオンライン エンドポイントをローカルでデバッグする方法に関する記事を参照してください。

ローカル デプロイが成功したかどうかを確認する

状態を確認し、エラーなしでモデルがデプロイされたかどうかを確認します。

az ml online-endpoint show -n $ENDPOINT_NAME --local

出力は次の JSON のようになります。 provisioning_stateSucceeded です。

{
  "auth_mode": "key",
  "location": "local",
  "name": "docs-endpoint",
  "properties": {},
  "provisioning_state": "Succeeded",
  "scoring_uri": "http://localhost:49158/score",
  "tags": {},
  "traffic": {}
}

次の表は、provisioning_state に指定できる値です。

状態 説明
作成 リソースを作成しています。
更新中 リソースを更新しています。
削除中 リソースは削除中です。
Succeeded 作成/更新操作が成功しました。
失敗 作成/更新/削除操作が失敗しました。

ローカル エンドポイントを呼び出し、モデルを使用してデータをスコアリングする

エンドポイントを呼び出してモデルをスコアリングするには、便利な invoke コマンドを使用して、JSON ファイルに格納されているクエリ パラメーターを渡します。

az ml online-endpoint invoke --local --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json

REST クライアント (curl など) を使用する場合は、スコアリング URI が必要です。 スコアリング URI を取得するには、az ml online-endpoint show --local -n $ENDPOINT_NAME を実行します。 返された値で、scoring_uri 属性を探します。 curl ベースのサンプル コマンドは、このドキュメントの後の方にあります。

呼び出し操作からの出力をログで確認する

例の score.py ファイルでは、run() メソッドがいくつかの出力をコンソールにログしています。

この出力は、get-logs コマンドを使って確認できます。

az ml online-deployment get-logs --local -n blue --endpoint $ENDPOINT_NAME

オンライン エンドポイントを Azure にデプロイする

次に、オンライン エンドポイントを Azure にデプロイする

Deploy to Azure (Azure へのデプロイ)

クラウドにエンドポイントを作成するには、次のコードを実行します。

az ml online-endpoint create --name $ENDPOINT_NAME -f endpoints/online/managed/sample/endpoint.yml

エンドポイントの下に blue という名前のデプロイを作成するには、次のコードを実行します。

az ml online-deployment create --name blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml --all-traffic

基になる環境またはイメージが初めて構築されるものであるかどうかに応じて、このデプロイには最大で 15 分かかる場合があります。 同じ環境を使用する後続のデプロイでは、処理がより迅速に完了します。

ヒント

  • CLI コンソールをブロックしたくない場合は、コマンドに --no-wait フラグを追加してください。 ただし、この場合、デプロイ状態が対話的に表示されなくなります。

重要

上記の az ml online-deployment create--all-traffic フラグを指定すると、エンドポイント トラフィックの 100% が、新しく作成されたブルー デプロイに割り当てられます。 これは開発とテストのために役立ちますが、運用環境では、明示的なコマンドを使用して、新しいデプロイへのトラフィックを開くことができます。 たとえば、az ml online-endpoint update -n $ENDPOINT_NAME --traffic "blue=100" のようにします。

ヒント

エンドポイントの状態を確認する

show コマンドには、provisioning_state にエンドポイントとデプロイの情報が含まれます。

az ml online-endpoint show -n $ENDPOINT_NAME

list コマンドを使用すると、ワークスペースのすべてのエンドポイントを表形式で一覧表示できます。

az ml online-endpoint list --output table

オンライン デプロイの状態を確認する

ログを調べて、モデルがエラーなしでデプロイされたかどうかを確認します。

コンテナーからのログ出力を表示するには、次の CLI コマンドを使用します。

az ml online-deployment get-logs --name blue --endpoint $ENDPOINT_NAME

既定では、ログは推論サーバー コンテナーからプルされます。 ストレージ初期化子コンテナーのログを表示するには、--container storage-initializer フラグを追加します。 デプロイのログについて詳しくは、「コンテナー ログを取得する」をご覧ください。

エンドポイントを呼び出し、モデルを使用してデータをスコアリングする

invoke コマンドまたは任意の REST クライアントを使用してエンドポイントを呼び出し、データをスコアリングすることができます。

az ml online-endpoint invoke --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json

次の例は、エンドポイントに対する認証に使用されるキーを取得する方法を示しています。

ヒント

認証キーを取得できる Microsoft Entra セキュリティ プリンシパルは、Microsoft.MachineLearningServices/workspaces/onlineEndpoints/token/actionMicrosoft.MachineLearningServices/workspaces/onlineEndpoints/listkeys/action を許可するカスタム ロールにそれを割り当てることで制御できます。 詳細については、「Azure Machine Learning ワークスペースへのアクセスの管理」を参照してください。

ENDPOINT_KEY=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -o tsv --query primaryKey)

次に、curl を使用してデータをスコアリングします。

SCORING_URI=$(az ml online-endpoint show -n $ENDPOINT_NAME -o tsv --query scoring_uri)

curl --request POST "$SCORING_URI" --header "Authorization: Bearer $ENDPOINT_KEY" --header 'Content-Type: application/json' --data @endpoints/online/model-1/sample-request.json

認証資格情報を取得するには、show コマンドと get-credentials コマンドを使用します。 --query フラグを使用して、必要な属性だけをフィルターしています。 --query の詳細については、Azure CLI コマンドの出力のクエリに関するページを参照してください。

起動ログを表示するには、再度 get-logs を実行します。

トークンを使った認証については、オンライン エンドポイントへの認証に関するページを参照してください。

(省略可能) デプロイを更新する

コード、モデル、または環境を更新する場合は、YAML ファイルを更新し、次に az ml online-endpoint update コマンドを実行します。

注意

単一の update コマンドでインスタンス数 (デプロイをスケーリングするため) と他のモデル設定 (コード、モデル、環境など) を更新する場合、最初にスケーリング操作が実行され、その後に他の更新が適用されます。 運用環境では、これらの操作を個別に実行することをお勧めします。

update の動作を理解するには:

  1. ファイル online/model-1/onlinescoring/score.py を開きます。

  2. init() 関数の最後の行を変更します。logging.info("Init complete") の後に、logging.info("Updated successfully") を追加してください。

  3. ファイルを保存します。

  4. 次のコマンドを実行します。

    az ml online-deployment update -n blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml
    

    注意

    YAML を使用した更新は宣言型です。 つまり YAML の変更は、基になる Azure Resource Manager リソース (エンドポイントとデプロイ) に反映されます。 この宣言型アプローチによって GitOps が促進されます。つまり、エンドポイントとデプロイに対する "すべて" の変更は YAML を経由することになります (instance_count も含む)。

    ヒント

    • --set パラメーターなどの汎用更新パラメーターを CLI の update コマンドで使用すると、YAML 内の属性をオーバーライドしたり、"あるいは" 特定の属性を YAML ファイルに渡さずに設定したりできます。 個別の属性に対する --set の使用は、特に開発およびテストのシナリオで利便性を発揮します。 たとえば、最初のデプロイの instance_count 値をスケールアップするのであれば、--set instance_count=2 フラグを使用できます。 ただし、YAML が更新されないため、この手法に GitOps を促進する効果はありません。
    • YAML ファイルの指定は必須ではありません。 たとえば、特定のデプロイに対して異なるコンカレンシー設定をテストする場合は、az ml online-deployment update -n blue -e my-endpoint --set request_settings.max_concurrent_requests_per_instance=4 environment_variables.WORKER_COUNT=4 などを試すことができます。 これにより、既存のすべての構成は保持され、指定されたパラメーターのみが更新されます。
  5. エンドポイントの作成時または更新時に実行される init() 関数に変更を加えたため、Updated successfully というメッセージがログに記録されます。 次を実行してログを取得します。

    az ml online-deployment get-logs --name blue --endpoint $ENDPOINT_NAME
    

update コマンドは、ローカル デプロイでも動作します。 同じ az ml online-deployment update コマンドを --local フラグと共に使用します。

注意

上記のデプロイの更新は、インプレース ローリング更新の例です。

  • マネージド オンライン エンドポイントの場合、デプロイは一度に 20% のノードずつ新しい構成に更新されます。 つまり、デプロイに 10 個のノードがある場合、一度に 2 つのノードが更新されます。
  • Kubernetes オンライン エンドポイントの場合、システムは新しい構成で新しいデプロイ インスタンスを作成し、古いものを削除するということを繰り返します。
  • 運用環境で使用する場合は、ブルーグリーン デプロイを検討することをお勧めします。これは、Web サービスを更新するためのより安全な代替手段を提供します。

(省略可能) 自動スケーリングを構成する

自動スケールでは、アプリケーションの負荷を処理するために適切な量のリソースが自動的に実行されます。 マネージド オンライン エンドポイントでは、Azure Monitor 自動スケーリング機能との統合によって、自動スケーリングをサポートします。 自動スケールを構成するには、「オンライン エンドポイントを自動スケーリングする方法」をご覧ください。

(省略可能) Azure Monitor を使用して SLA を監視する

メトリックを表示し、SLA に基づいてアラートを設定するには、オンライン エンドポイントの監視に関するページの手順を実行します。

(省略可能) Log Analytics と統合する

CLI の get-logs コマンドまたは SDK の get_logs メソッドで取得できるのは、自動的に選ばれたインスタンスからのログの最後の数百行だけです。 一方、Log Analytics は、ログを永続的に保存して分析する手段となります。 ログの使用の詳細については、「オンライン エンドポイントを監視する」を参照してください。

エンドポイントとデプロイを削除する

デプロイを今後使用する予定がない場合、次のコードを実行してデプロイを削除してください (エンドポイントと基になるすべてのデプロイが削除されます)。

az ml online-endpoint delete --name $ENDPOINT_NAME --yes --no-wait