リアルタイム推論のために新しいデプロイの安全なロールアウトを実行する

  • [アーティクル]

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

このアーティクルでは、中断させることなく、新しいバージョンで運用環境にある機械学習モデルをデプロイする方法について学習します。 ブルーグリーン デプロイ戦略 (安全なロールアウト戦略とも呼ばれます) を使用して、新しいバージョンの Web サービスを運用環境に導入します。 この戦略により、完全にロールアウトする前に、新しいバージョンの Web サービスを少数のユーザーまたは要求にロールアウトできます。

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

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

この記事では、次の内容について説明します。

  • モデルのバージョン 1 を提供するために、オンライン エンドポイントと "blue" という名前のデプロイを定義する
  • より多くの要求を処理できるよう、ブルーのデプロイをスケーリングする
  • モデルのバージョン 2 ("グリーン" デプロイと呼ばれます) をエンドポイントにデプロイしますが、ライブ トラフィックなしでデプロイを送信する
  • グリーン デプロイを別個にテストする
  • ライブ トラフィックの割合をグリーンのデプロイにミラーリングして検証する
  • ライブ トラフィックの割合を小さく抑えてライブ トラフィックのごく一部をグリーン デプロイに送信する
  • すべてのライブ トラフィックをグリーン デプロイに送信する
  • 使用されなくなった v1 ブルー デプロイを削除する

前提条件

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

  • Azure ロールベースのアクセス制御 (Azure RBAC) は、Azure Machine Learning の操作に対するアクセスを許可するために使用されます。 この記事の手順を実行するには、ユーザー アカウントに、Azure Machine Learning ワークスペースの所有者か共同作成者ロール、または Microsoft.MachineLearningServices/workspaces/onlineEndpoints/* を許可するカスタム ロールを割り当てる必要があります。 詳細については、「Azure Machine Learning ワークスペースへのアクセスの管理」を参照してください。

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

システムを準備する

環境変数の設定

まだ 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-safe-rollout-online-endpoints.shファイルに存在します。また、YAML 構成ファイルはendpoints/online/managed/sample/サブディレクトリに存在します。

注意

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

エンドポイントとデプロイを定義する

オンライン エンドポイントは、オンライン (リアルタイム) の推論に使用されます。 オンライン エンドポイントには、クライアントからデータを受信して、リアルタイムで応答を返信できる準備が整ったデプロイが含まれています。

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

次の表は、エンドポイントを定義する際に指定する主な属性を一覧表示しています。

属性 内容
名前 必須。 エンドポイントの名前。 Azure リージョンで一意である必要があります。 名前付け規則の詳細については、「エンドポイントの制限」を参照してください。
認証モード エンドポイントの認証方法。 キーベースの認証 key と Azure Machine Learning トークンベースの認証 aml_token のどちらかを選択します。 キーには有効期限がありませんが、トークンには有効期限があります。 認証の詳細については、オンライン エンドポイントの認証に関する記事を参照してください。
説明 エンドポイントの説明。
タグ エンドポイントのタグのディクショナリ。
トラフィック デプロイ間でトラフィックをルーティングする方法に関するルール。 トラフィックをキーと値のペアのディクショナリとして表します。キーはデプロイ名を表し、値はそのデプロイへのトラフィックの割合を表します。 トラフィックは、エンドポイントにデプロイが作成されている場合にのみ設定できます。 デプロイの作成後は、オンライン エンドポイントのトラフィックを更新することもできます。 ミラーリングされたトラフィックの使用方法の詳細については、「新しいデプロイにライブ トラフィックのごく一部を割り当てる」を参照してください。
トラフィックのミラーリング デプロイにミラーリングするライブ トラフィックの割合。 ミラーリングされたトラフィックの使用方法の詳細については、「ミラーリングされたトラフィックを使ってデプロイをテストする」を参照してください。

エンドポイントの作成時に指定できる属性の完全なリストについては、「CLI (v2) オンライン エンドポイント YAML スキーマ」または SDK (v2) の ManagedOnlineEndpoint クラスに関する記事を参照してください。

デプロイを定義する

デプロイは、実際の推論を実行するモデルをホストするのに必要なリソースのセットです。 次の表は、デプロイを定義する際に指定する主な属性について説明しています。

属性 内容
名前 必須。 デプロイの名前。
エンドポイント名 必須。 デプロイの作成先となるエンドポイントの名前。
モデル デプロイに使用するモデル。 この値は、ワークスペース内の既存のバージョン管理されたモデルへの参照またはインライン モデルの仕様のいずれかです。 この例では、回帰を行う scikit-learn モデルを使用します。
コード パス モデルのスコアリングに使用されるすべての Python ソース コードが格納されている、ローカル開発環境上のディレクトリへのパス。 入れ子になったディレクトリとパッケージを使用できます。
スコアリング スクリプト 指定された入力要求に対してモデルを実行する Python コード。 この値には、ソース コード ディレクトリ内のスコアリング ファイルへの相対パスを指定できます。
スコアリング スクリプトは、デプロイされた Web サービスに送信されたデータを受け取り、それをモデルに渡します。 その後、スクリプトはモデルを実行して、その応答をクライアントに返します。 スコアリング スクリプトはモデルに固有のものであり、モデルが入力として期待し、出力として返すデータを理解する必要があります。
この例では、score.py ファイルがあります。 この Python コードには、init() 関数と run() 関数が含まれている必要があります。 init() 関数は、モデルの作成または更新後に呼び出されます (たとえば、モデルをメモリにキャッシュするために使用できます)。 run() 関数は、実際のスコアリングおよび予測を実行するために、エンドポイントが呼び出されるたびに呼び出されます。
環境 必須。 モデルとコードをホスティングする環境。 この値は、ワークスペース内の既存のバージョン管理された環境への参照、またはインライン環境仕様のいずれかになります。 この環境には、Conda の依存関係を持つ Docker イメージ、Dockerfile、または登録済みの環境を使用できます。
インスタンスの種類 必須。 デプロイに使用する VM サイズ。 サポートされているサイズの一覧については、マネージド オンライン エンドポイント SKU の一覧に関するページを参照してください。
インスタンス数 必須です。 デプロイに使用するインスタンスの数。 想定されるワークロードに基づく値を指定します。 高可用性を実現するために、この値を少なくとも 3 に設定することをお勧めします。 アップグレードを実行するために 20% 余分に予約されています。 詳細については、「オンライン エンドポイントの制限」をご覧ください。

デプロイの作成時に指定できる属性の完全なリストについては、「CLI (v2) マネージド オンライン デプロイ YAML スキーマ」または SDK (v2) の ManagedOnlineDeployment クラスに関する記事を参照してください。

オンライン エンドポイントを作成する

最初にエンドポイントの名前を設定してから、構成します。 この記事では、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 コマンドを使用します。

オンライン エンドポイントを作成するには。

  1. エンドポイント名を設定します。

    Unix の場合は、次のコマンドを実行します (YOUR_ENDPOINT_NAMEを、一意の名前に置き換えます)。

    export ENDPOINT_NAME="<YOUR_ENDPOINT_NAME>"

    重要

    エンドポイント名は Azure リージョン内で一意である必要があります。 たとえば、Azure westus2 リージョンでは、my-endpoint という名前のエンドポイントは 1 つしか使用できません。

  2. クラウドにエンドポイントを作成します。

    次のコードを実行して、endpoint.yml ファイルを使用してエンドポイントを構成します。

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

'ブルー' デプロイを作成する

この記事では、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 という名前のデプロイを作成するには、次のコマンドを実行して、blue-deployment.yml ファイルを使用して構成します。

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

重要

az ml online-deployment create で --all-traffic フラグを指定すると、エンドポイント トラフィックの 100% が、新しく作成されたブルー デプロイに割り当てられます。

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

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

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

既存のデプロイを確認する

既存のデプロイを確認する方法の 1 つは、特定の入力要求に対してモデルをスコア付けできるようにエンドポイントを呼び出すことです。 CLI または Python SDK を使用してエンドポイントを呼び出すときに、受信トラフィックを受信するデプロイの名前を任意で指定できます。

Note

CLI や Python SDK とは異なり、Azure Machine Learning スタジオではエンドポイントを呼び出すときにデプロイを指定する必要があります。

デプロイ名を使用してエンドポイントを呼び出す

トラフィックを受信するデプロイの名前を使用してエンドポイントを呼び出すと、Azure Machine Learning によってエンドポイントのトラフィックが指定のデプロイに直接ルーティングされ、その出力が返されます。 CLI v2 の場合は --deployment-name オプション、SDK v2 の場合は deployment_name オプションを使用して、デプロイを指定できます。

デプロイを指定せずにエンドポイントを呼び出す

トラフィックを受信するデプロイを指定せずにエンドポイントを呼び出すと、Azure Machine Learning では、トラフィック制御設定に基づいてエンドポイントの受信トラフィックがエンドポイント内のデプロイにルーティングされます。

トラフィック制御設定では、受信トラフィックの指定された割合がエンドポイント内の各デプロイに割り当てられます。 たとえばトラフィック ルールで、エンドポイント内の特定のデプロイで受信トラフィックを 40% 受信するように指定している場合、Azure Machine Learning ではエンドポイントのトラフィックの 40% がそのデプロイにルーティングされます。

既存のエンドポイントとデプロイの状態は、次を実行して確認できます。

az ml online-endpoint show --name $ENDPOINT_NAME 

az ml online-deployment show --name blue --endpoint $ENDPOINT_NAME

$ENDPOINT_NAME によって識別されるエンドポイントと、blue というデプロイが確認できます。

サンプル データを使用してエンドポイントをテストする

エンドポイントは、invoke コマンドを使用して呼び出すことができます。 json ファイルを使用してサンプル要求を送信します。

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

より多くのトラフィックを処理できるように既存のデプロイをスケーリングする

オンライン エンドポイントを使用して機械学習モデルをデプロイおよびスコアリングするに関するページで説明されているデプロイでは、デプロイの yaml ファイルで instance_count の値を 1 に設定しました。 update コマンドを使用してスケール アウトできます。

az ml online-deployment update --name blue --endpoint-name $ENDPOINT_NAME --set instance_count=2

Note

上記のコマンドでは、--set を使用してデプロイ構成をオーバーライドします。 または、yaml ファイルを更新し、--file 入力を使用して update コマンドに入力 として渡します。

新しいモデルをデプロイする (ただし、まだトラフィックは送らない)

green という名前の新しいデプロイを作成します。

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

green には、まだ明示的にトラフィックを割り当てていないので、割り当てられたトラフィックはありません。 次のコマンドを使用して確認できます。

az ml online-endpoint show -n $ENDPOINT_NAME --query traffic

新しいデプロイをテストする

green に割り当てられたトラフィックは 0% ですが、--deployment の名前を指定して直接呼び出すことができます。

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

トラフィック ルールを介さずに、REST クライアントを使用して直接デプロイを呼び出したい場合、azureml-model-deployment: <deployment-name> という HTTP ヘッダーを設定します。 次のコード スニペットでは、curl を使用してデプロイを直接呼び出します。 コード スニペットは、Unix/WSL 環境で動作する必要があります。

# get the scoring uri
SCORING_URI=$(az ml online-endpoint show -n $ENDPOINT_NAME -o tsv --query scoring_uri)
# use curl to invoke the endpoint
curl --request POST "$SCORING_URI" --header "Authorization: Bearer $ENDPOINT_KEY" --header 'Content-Type: application/json' --header "azureml-model-deployment: green" --data @endpoints/online/model-2/sample-request.json

ミラーリングされたトラフィックを使ってデプロイをテストする

green デプロイをテストしたら、一定割合のライブ トラフィックをそれに "ミラーリング" (またはコピー) できます。 トラフィック ミラーリング (シャドウとも呼ばれます) を行っても、クライアントに返される結果は変わりません。要求は引き続き、100% が blue デプロイに送られます。 ミラーリングされた一定割合のトラフィックがコピーされ、green デプロイに送信されるため、クライアントに影響を与えずにメトリックとログを収集できます。 ミラーリングは、クライアントに影響を与えずに新しいデプロイを検証する場合に便利です。 たとえば、ミラーリングを使用して、待ち時間が許容範囲内かどうかを確認したり、HTTP エラーが発生していないかどうかを確認したりできます。 トラフィック ミラーリング/シャドウを使用した新しいデプロイのテストは、シャドウ テストとも呼ばれます。 ミラーリングされたトラフィックを受信するデプロイ (この場合は green デプロイ) は、"シャドウ デプロイ" と呼ばれることもあります。

ミラーリングには次の制限事項があります。

  • ミラーリングは、CLI (v2) (バージョン 2.4.0 以降) と Python SDK (v2) (バージョン 1.0.0 以降) でサポートされています。 以前のバージョンの CLI/SDK を使用してエンドポイントを更新すると、トラフィックのミラーリング設定が失われます。
  • 現在、ミラーリングは、Kubernetes オンライン エンドポイントではサポートされていません。
  • トラフィックは、エンドポイント内の 1 つのデプロイにのみミラーリングできます。
  • ミラーリングできるトラフィックの最大割合は 50% です。 この制限は、エンドポイント帯域幅クォータ (既定では 5 Mbps) への影響を軽減するためのものです。割り当てられたクォータを超えると、エンドポイント帯域幅が抑えられます。 帯域幅調整の監視については、「マネージド オンライン エンドポイントを監視する」を参照してください。

以下の動作にも注意してください。

  • デプロイは、ライブ トラフィックまたはミラーリングされたトラフィックのどちらかのみ (両方ではない) を受信するように構成できます。
  • エンドポイントを呼び出すときに、そのデプロイの名前 (シャドウ デプロイも含む) を指定して予測を返すことができます。
  • 受信トラフィックを受信するデプロイの名前を使用してエンドポイントを呼び出すと、Azure Machine Learning によってトラフィックがシャドウ デプロイにミラーリングされません。 デプロイを指定しない場合、Azure Machine Learning は、エンドポイントに送信されたトラフィックからシャドウ デプロイにトラフィックをミラーリングします。

次は、ミラーリングされたトラフィックの 10% を受信するようにグリーン デプロイを設定します。 クライアントは、引き続きブルー デプロイからのみ予測を受け取ります。

Diagram showing 10% traffic mirrored to one deployment.

次のコマンドは、トラフィックの 10% を green デプロイにミラーリングします。

az ml online-endpoint update --name $ENDPOINT_NAME --mirror-traffic "green=10"

受信トラフィックを受信するデプロイを指定せずにエンドポイントを複数回呼び出すと、トラフィックのミラーリングをテストできます。

for i in {1..20} ; do
    az ml online-endpoint invoke --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json
done

デプロイからのログを確認することで、トラフィックの特定の割合が green のデプロイに送信されたことを確認できます。

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

テスト後、ミラー トラフィックを 0 に設定して、ミラーリングを無効にすることができます。

az ml online-endpoint update --name $ENDPOINT_NAME --mirror-traffic "green=0"

ライブ トラフィックの小さい割合を新しいデプロイに割り当てる

green デプロイをテストしたら、それにトラフィックのごく一部を割り当てます。

az ml online-endpoint update --name $ENDPOINT_NAME --traffic "blue=90 green=10"

ヒント

トラフィックの割合の合計が、0% (トラフィックを無効にする場合) または 100% (トラフィックを有効にする場合) のいずれかになる必要があります。

これで、green デプロイが全ライブ トラフィックの 10% を受け取ります。 クライアントは、blue と green の両方のデプロイから予測を受け取ります。

Diagram showing traffic split between deployments.

すべてのトラフィックを新しいデプロイに送る

green デプロイに問題がなければ、すべてのトラフィックをそのデプロイに切り替えます。

az ml online-endpoint update --name $ENDPOINT_NAME --traffic "blue=0 green=100"

以前のデプロイを削除する

次の手順に従って、マネージド オンライン エンドポイントから個々のデプロイを削除します。 個々のデプロイを削除すると、マネージド オンライン エンドポイント内の他のデプロイに影響します。

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

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

エンドポイントとデプロイを使用する予定がない場合は、削除してください。 エンドポイントを削除すると、その基礎になっているデプロイもすべて削除されます。

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

関連するコンテンツ