REST を使用してモデルをデプロイする

[アーティクル]
04/04/2023

Azure Machine Learning REST API を使用してモデルをデプロイする方法について学習します。

REST API では、標準の HTTP 動詞を使用して、リソースの作成、取得、更新、および削除を行います。 REST API は、HTTP 要求を作成できるすべての言語またはツールで使用できます。 REST は構造がわかりやすいため、スクリプト環境や MLOps オートメーションに適しています。

この記事では、新しい REST API を使用して次のことを行う方法について学習します。

機械学習資産を作成する
基本的なトレーニングジョブを作成する
ハイパーパラメーター調整スイープジョブを作成する

前提条件

管理者権限を持っている Azure サブスクリプション。そのようなサブスクリプションがない場合は、無料または有料の個人用サブスクリプションをお試しください。
Azure Machine Learning ワークスペース。
ワークスペース内のサービスプリンシパル。管理 REST 要求でサービスプリンシパル認証が使用されている。
サービスプリンシパルの認証トークン。「サービスプリンシパルの認証トークンを取得する」の手順に従って、このトークンを取得します。
curl ユーティリティ。 curl プログラムは、Linux 用 Windows サブシステムまたは任意の UNIX ディストリビューションで使用できます。 PowerShell では、curl は Invoke-WebRequest の別名であり、curl -d "key=val" -X POST uri は Invoke-WebRequest -Body "key=val" -Method POST -Uri uri になります。

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

注意

エンドポイントの名前は、Azure リージョンレベルで一意である必要があります。たとえば、westus2 に存在できる my-endpoint という名前のエンドポイントは 1 つだけです。

export ENDPOINT_NAME=endpt-rest-`echo $RANDOM`

Azure Machine Learning オンラインエンドポイント

オンラインエンドポイントを使用すると、基盤となるインフラストラクチャと Kubernetes クラスターを作成および管理することなくモデルをデプロイできます。この記事では、オンラインエンドポイントとデプロイを作成し、それを呼び出して検証します。ただし、まず、モデル、コード、環境など、デプロイに必要な資産を登録する必要があります。

Azure Machine Learning オンラインエンドポイントを作成するには、Azure CLI や、スタジオを使う視覚的なものなど、さまざまな方法があります。次の例は、REST API を使用した、オンラインエンドポイントです。

機械学習資産を作成する

最初に、Azure Machine Learning 資産を設定して、ジョブを構成します。

次の REST API 呼び出しでは、プレースホルダーとして SUBSCRIPTION_ID、RESOURCE_GROUP、LOCATION、および WORKSPACE を使用しています。プレースホルダーを実際の値に置き換えてください。

管理 REST により、サービスプリンシパル認証トークンが要求されます。 TOKEN は、実際の値に置き換えてください。このトークンは、次のコマンドを使用して取得できます。

response=$(curl -H "Content-Length: 0" --location --request POST "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/onlineEndpoints/$ENDPOINT_NAME/token?api-version=$API_VERSION" \
--header "Authorization: Bearer $TOKEN")
accessToken=$(echo $response | jq -r '.accessToken')

サービスプロバイダーは、api-version 引数を使用して互換性を保証します。 api-version 引数はサービスによって異なります。将来のバージョンに対応するために、API バージョンを変数として設定します。

API_VERSION="2022-05-01"

ストレージアカウントの詳細を取得する

モデルとコードを登録するには、まず、それらをストレージアカウントにアップロードする必要があります。ストレージアカウントの詳細は、データストアで使用できます。この例では、自分のワークスペースの既定のデータストアと Azure ストレージアカウントを取得します。 GET 要求を使用して自分のワークスペースに対してクエリを実行し、情報が含まれた JSON ファイルを取得します。

jq ツールを使用して、JSON の結果を解析し、必要な値を取得できます。 Azure portal を使用しても同じ情報を取得することができます。

# Get values for storage account
response=$(curl --location --request GET "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/datastores?api-version=$API_VERSION&isDefault=true" \
--header "Authorization: Bearer $TOKEN")
AZUREML_DEFAULT_DATASTORE=$(echo $response | jq -r '.value[0].name')
AZUREML_DEFAULT_CONTAINER=$(echo $response | jq -r '.value[0].properties.containerName')
export AZURE_STORAGE_ACCOUNT=$(echo $response | jq -r '.value[0].properties.accountName')

コードをアップロードして登録する

データストアを用意できたら、スコアリングスクリプトをアップロードできます。 Azure Storage CLI を使用して、BLOB を既定のコンテナーにアップロードします。

az storage blob upload-batch -d $AZUREML_DEFAULT_CONTAINER/score -s endpoints/online/model-1/onlinescoring

ヒント

また、Azure portal や Azure Storage Explorer など、他の方法でアップロードすることもできます。

コードをアップロードしたら、PUT 要求を使用してコードを指定し、datastoreId を使用してデータストアを参照することができます。

curl --location --request PUT "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/codes/score-sklearn/versions/1?api-version=$API_VERSION" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" \
--data-raw "{
  \"properties\": {
    \"codeUri\": \"https://$AZURE_STORAGE_ACCOUNT.blob.core.windows.net/$AZUREML_DEFAULT_CONTAINER/score\"
  }
}"

モデルをアップロードして登録する

コードと同様に、モデルファイルをアップロードします。

az storage blob upload-batch -d $AZUREML_DEFAULT_CONTAINER/model -s endpoints/online/model-1/model

モデルを登録します。

curl --location --request PUT "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/models/sklearn/versions/1?api-version=$API_VERSION" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" \
--data-raw "{
    \"properties\": {
        \"modelUri\":\"azureml://subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/workspaces/$WORKSPACE/datastores/$AZUREML_DEFAULT_DATASTORE/paths/model\"
    }
}"

環境を作成する

デプロイは、必要な依存関係がある環境で実行する必要があります。 PUT 要求を使用して環境を作成します。 Microsoft Container Registry の Docker イメージを使用します。 Docker を使用して Docker イメージを構成し、condaFile を使用して conda の依存関係を追加できます。

次のスニペットでは、Conda 環境 (YAML ファイル) の内容が環境変数に読み込まれています。

ENV_VERSION=$RANDOM
curl --location --request PUT "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/environments/sklearn-env/versions/$ENV_VERSION?api-version=$API_VERSION" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" \
--data-raw "{
    \"properties\":{
        \"condaFile\": \"$CONDA_FILE\",
        \"image\": \"mcr.microsoft.com/azureml/openmpi3.1.2-ubuntu18.04:20210727.v1\"
    }
}"

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

オンラインエンドポイントを作成します。

response=$(curl --location --request PUT "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/onlineEndpoints/$ENDPOINT_NAME?api-version=$API_VERSION" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $TOKEN" \
--data-raw "{
    \"identity\": {
       \"type\": \"systemAssigned\"
    },
    \"properties\": {
        \"authMode\": \"AMLToken\"
    },
    \"location\": \"$LOCATION\"
}")

Create deployment

エンドポイントでデプロイを作成します。

response=$(curl --location --request PUT "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/onlineEndpoints/$ENDPOINT_NAME/deployments/blue?api-version=$API_VERSION" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $TOKEN" \
--data-raw "{
    \"location\": \"$LOCATION\",
    \"sku\": {
        \"capacity\": 1,
        \"name\": \"Standard_DS2_v2\"
    },
    \"properties\": {
        \"endpointComputeType\": \"Managed\",
        \"scaleSettings\": {
            \"scaleType\": \"Default\"
        },
        \"model\": \"/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/models/sklearn/versions/1\",
        \"codeConfiguration\": {
            \"codeId\": \"/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/codes/score-sklearn/versions/1\",
            \"scoringScript\": \"score.py\"
        },
        \"environmentId\": \"/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/environments/sklearn-env/versions/$ENV_VERSION\"
    }
}")

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

エンドポイントを呼び出すには、スコアリング URI とアクセストークンが必要です。最初にスコアリング URI を取得します。

response=$(curl --location --request GET "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/onlineEndpoints/$ENDPOINT_NAME?api-version=$API_VERSION" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $TOKEN")

scoringUri=$(echo $response | jq -r '.properties.scoringUri')

エンドポイントのアクセストークンを取得します。

response=$(curl -H "Content-Length: 0" --location --request POST "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/onlineEndpoints/$ENDPOINT_NAME/token?api-version=$API_VERSION" \
--header "Authorization: Bearer $TOKEN")
accessToken=$(echo $response | jq -r '.accessToken')

次に、curl を使用してエンドポイントを呼び出します。

curl --location --request POST $scoringUri \
--header "Authorization: Bearer $accessToken" \
--header "Content-Type: application/json" \
--data-raw @endpoints/online/model-1/sample-request.json

ログを確認する

デプロイログを確認します。

curl --location --request POST "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/onlineEndpoints/$ENDPOINT_NAME/deployments/blue/getLogs?api-version=$API_VERSION" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" \
--data-raw "{ \"tail\": 100 }"

エンティティを削除する

今後使用する予定がない場合、以下のコマンドでデプロイを削除してください (エンドポイントとそこにあるすべてのデプロイが削除されます)。

curl --location --request DELETE "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/onlineEndpoints/$ENDPOINT_NAME?api-version=$API_VERSION" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $TOKEN" || true

次の手順

Azure CLI を使用してモデルをデプロイする方法について説明します。
Studio を使用してモデルをデプロイする方法について説明します。
オンラインエンドポイントのデプロイとスコアリングのトラブルシューティングについて説明します。
オンラインエンドポイントとマネージド ID を使用して Azure リソースにアクセスする方法について説明します。
オンラインエンドポイントを監視する方法について説明します。
オンラインエンドポイントの安全なロールアウトについて説明します。
Azure Machine Learning のマネージドオンラインエンドポイントのコストを表示する。
マネージドオンラインエンドポイント SKU の一覧。
オンラインエンドポイントの制限について説明します。