登録済み R モデルをオンライン (リアルタイム) エンドポイントにデプロイする方法

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

この記事では、マネージドエンドポイント (Web API) に R モデルをデプロイして、アプリケーションでほぼリアルタイムにモデルに対して新しいデータをスコア付けできるようにする方法について説明します。

前提条件

Azure Machine Learning ワークスペース。
Azure CLI と ml 拡張機能がインストールされている。または、CLI がプレインストールされているワークスペース内のコンピューティングインスタンスを使用します。
ワークスペースに関連付けられている少なくとも 1 つのカスタム環境。 R 環境、またはその他のカスタム環境を作成します (存在しない場合)。
R plumber パッケージの理解
トレーニングして crate でパッケージ化し、ワークスペースに登録したモデル

この構造でフォルダーを作成する

プロジェクトに次のフォルダー構造を作成します。

📂 r-deploy-azureml
 ├─📂 docker-context
 │  ├─ Dockerfile
 │  └─ start_plumber.R
 ├─📂 src
 │  └─ plumber.R
 ├─ deployment.yml
 ├─ endpoint.yml

これらの各ファイルの内容については、この記事で説明します。

Dockerfile

これは、コンテナー環境を定義するファイルです。また、追加の R パッケージのインストールがあれば、ここで定義します。

サンプルの Dockerfile は次のようになります。

# REQUIRED: Begin with the latest R container with plumber
FROM rstudio/plumber:latest

# REQUIRED: Install carrier package to be able to use the crated model (whether from a training job
# or uploaded)
RUN R -e "install.packages('carrier', dependencies = TRUE, repos = 'https://cloud.r-project.org/')"

# OPTIONAL: Install any additional R packages you may need for your model crate to run
RUN R -e "install.packages('<PACKAGE-NAME>', dependencies = TRUE, repos = 'https://cloud.r-project.org/')"
RUN R -e "install.packages('<PACKAGE-NAME>', dependencies = TRUE, repos = 'https://cloud.r-project.org/')"

# REQUIRED
ENTRYPOINT []

COPY ./start_plumber.R /tmp/start_plumber.R 

CMD ["Rscript", "/tmp/start_plumber.R"]

このファイルを変更して、スコアリングスクリプトに必要なパッケージを追加してください。

plumber.R

重要

このセクションでは、plumber.R スクリプトを構成する方法を示します。 plumber パッケージの詳細については、plumber のドキュメントを参照してください。

ファイル plumber.R は、スコアリング用の関数を定義する R スクリプトです。また、このスクリプトにより、エンドポイントを動作させるために必要なタスクが実行されます。スクリプトは次のようになります。

コンテナー内の AZUREML_MODEL_DIR 環境変数から、モデルがマウントされるパスを取得します。
crate 関数を使用して作成されたモデルオブジェクトを carrierパッケージから読み込みます。これは、パッケージ化されたときに crate.bin として保存されました。
モデルオブジェクトを "非シリアル化" します
スコアリング関数を定義します

ヒント

スコアリング関数で生成するものが何であれ JSON に変換しなおせることを確認します。一部の R オブジェクトは簡単に変換されません。

# plumber.R
# This script will be deployed to a managed endpoint to do the model scoring

# REQUIRED
# When you deploy a model as an online endpoint, Azure Machine Learning mounts your model
# to your endpoint. Model mounting enables you to deploy new versions of the model without
# having to create a new Docker image.

model_dir <- Sys.getenv("AZUREML_MODEL_DIR")

# REQUIRED
# This reads the serialized model with its respecive predict/score method you 
# registered. The loaded load_model object is a raw binary object.
load_model <- readRDS(paste0(model_dir, "/models/crate.bin"))

# REQUIRED
# You have to unserialize the load_model object to make it its function
scoring_function <- unserialize(load_model)

# REQUIRED
# << Readiness route vs. liveness route >>
# An HTTP server defines paths for both liveness and readiness. A liveness route is used to
# check whether the server is running. A readiness route is used to check whether the 
# server's ready to do work. In machine learning inference, a server could respond 200 OK 
# to a liveness request before loading a model. The server could respond 200 OK to a
# readiness request only after the model has been loaded into memory.

#* Liveness check
#* @get /live
function() {
  "alive"
}

#* Readiness check
#* @get /ready
function() {
  "ready"
}

# << The scoring function >>
# This is the function that is deployed as a web API that will score the model
# Make sure that whatever you are producing as a score can be converted 
# to JSON to be sent back as the API response
# in the example here, forecast_horizon (the number of time units to forecast) is the input to scoring_function.  
# the output is a tibble
# we are converting some of the output types so they work in JSON


#* @param forecast_horizon 
#* @post /score
function(forecast_horizon) {
  scoring_function(as.numeric(forecast_horizon)) |> 
    tibble::as_tibble() |> 
    dplyr::transmute(period = as.character(yr_wk),
                     dist = as.character(logmove),
                     forecast = .mean) |> 
    jsonlite::toJSON()
}

start_plumber.R

ファイル start_plumber.R は、コンテナーの起動時に実行され、plumber.R スクリプトを呼び出します。次のスクリプトをそのまま使用してください。

entry_script_path <- paste0(Sys.getenv('AML_APP_ROOT'),'/', Sys.getenv('AZUREML_ENTRY_SCRIPT'))

pr <- plumber::plumb(entry_script_path)

args <- list(host = '0.0.0.0', port = 8000); 

if (packageVersion('plumber') >= '1.0.0') {
  pr$setDocs(TRUE)
} else { 
  args$swagger <- TRUE 
} 

do.call(pr$run, args)

コンテナーをビルドする

これらの手順では、ワークスペースに関連付けられている Azure Container Registry があることを前提としています。これは、最初のカスタム環境を作成するときに作成されます。カスタム環境があるかどうかを確認するには、次のようにします。

Azure Machine Learning Studio にサインインします。
必要に応じてワークスペースを選びます。
左側のナビゲーションで [環境] を選びます。
上部の [カスタム環境] を選びます。
カスタム環境が表示される場合は、それ以上の作業はありません。
カスタム環境が表示されない場合は、R 環境またはその他のカスタム環境を作成します。 (デプロイにはこの環境を使用 "しません"が、同じく自動的に作成されたコンテナーレジストリを使用 "します"。)

少なくとも 1 つのカスタム環境があることを確認したら、次の手順を使用してコンテナーをビルドします。

ターミナルウィンドウを開き、Azure にサインインします。 Azure Machine Learning コンピューティングインスタンスからこれを行う場合は、以下を使用します。
```
az login --identity
```
コンピューティングインスタンスを使用していない場合は、--identity を省略し、プロンプトに従ってブラウザーウィンドウを開いて認証します。
最新バージョンの CLI と ml 拡張機能があることを確認します。
```
az upgrade
```
複数の Azure サブスクリプションがある場合は、アクティブなサブスクリプションを、ワークスペースに使用しているサブスクリプションに設定します (1 つのサブスクリプションにのみアクセスできる場合は、この手順をスキップできます)。<SUBSCRIPTION-NAME> をサブスクリプション名に置き換えます。また、かっこ <> は削除します。
```
az account set --subscription "<SUBSCRIPTION-NAME>"
```
既定のワークスペースを設定します。コンピューティングインスタンスからこれを行う場合は、次のコマンドをそのまま使用できます。他のコンピューターを使用している場合は、代わりにリソースグループとワークスペースの名前を置き換えてください。 (これらの値は Azure Machine Learning スタジオにあります。)
```
az configure --defaults group=$CI_RESOURCE_GROUP workspace=$CI_WORKSPACE
```
確実にプロジェクトディレクトリにいるようにします。
```
cd r-deploy-azureml
```
クラウドでイメージをビルドするには、ターミナルで次の bash コマンドを実行します。 <IMAGE-NAME> は、イメージに付ける名前に置き換えてください。

ワークスペースが仮想ネットワーク内にある場合は、このコードの最終行の az acr build コマンドに --image-build-compute を追加するための追加手順について、「Azure Container Registry (ACR) の有効化」を参照してください。
```
WORKSPACE=$(az config get --query "defaults[?name == 'workspace'].value" -o tsv)
ACR_NAME=$(az ml workspace show -n $WORKSPACE --query container_registry -o tsv | cut -d'/' -f9-)
IMAGE_TAG=${ACR_NAME}.azurecr.io/<IMAGE-NAME>

az acr build ./docker-context -t $IMAGE_TAG -r $ACR_NAME
```

重要

イメージがビルドされるまで数分かかります。ビルドプロセスが完了するまで待ってから、次のセクションに進みます。このターミナルを閉じないでください。これを使用して、次にデプロイを作成します。

az acr コマンドにより、docker-context フォルダー (イメージをビルドするための成果物が入っています) は、イメージがビルドされ、Azure Container Registry でホストされるクラウドに自動的にアップロードされます。

モデルのデプロイ

記事のこのセクションでは、エンドポイントとデプロイを定義および作成し、モデルと前の手順でビルドしたイメージをマネージドオンラインエンドポイントにデプロイします。

"エンドポイント" は、トレーニング済みモデルのスコアリング出力を受信するために、アプリケーションなどのクライアントが呼び出すことができる HTTPS エンドポイントです。次の機能を提供します。

"キーとトークン" ベースの認証を使用する認証
SSL ターミネーション
安定したスコアリング URI (endpoint-name.region.inference.ml.Azure.com)

"デプロイ" は、実際のスコアリングを実行するモデルのホスティングに必要なリソースのセットです。 1 つの "エンドポイント" に複数の "デプロイ" を含めることができます。 Azure Machine Learning マネージドエンドポイントの負荷分散機能を使用すると、各デプロイに任意の割合のトラフィックを送信できます。トラフィック割り当てを使用すると、異なるインスタンス間で要求を分散することによって、ブルーグリーンデプロイの安全なロールアウトを実施できます。

マネージドオンラインエンドポイントを作成する

プロジェクトディレクトリに、次のコードを含む endpoint.yml ファイルを追加します。 <ENDPOINT-NAME> は、マネージドエンドポイントに付ける名前に置き換えてください。
```
$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: <ENDPOINT-NAME>
auth_mode: aml_token
```
イメージをビルドしたのと同じターミナルを使用して、次の CLI コマンドを実行してエンドポイントを作成します。
```
az ml online-endpoint create -f endpoint.yml
```
次のセクションで引き続き使用するために、ターミナルを開いたままにします。

Create deployment

デプロイを作成するには、deployment.yml ファイルに次のコードを追加します。

<ENDPOINT-NAME> は、endpoint.yml ファイルで定義したエンドポイント名に置き換えます
<DEPLOYMENT-NAME> は、デプロイに付ける名前に置き換えます
<MODEL-URI> は、登録済みモデルの URI に置き換えます (azureml:modelname@latest の形式)
<IMAGE-TAG> は、次の結果の値に置き換えます。
```
echo $IMAGE_TAG
```

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: <DEPLOYMENT-NAME>
endpoint_name: <ENDPOINT-NAME>
code_configuration:
  code: ./src
  scoring_script: plumber.R
model: <MODEL-URI>
environment:
  image: <IMAGE-TAG>
  inference_config:
    liveness_route:
      port: 8000
      path: /live
    readiness_route:
      port: 8000
      path: /ready
    scoring_route:
      port: 8000
      path: /score
instance_type: Standard_DS2_v2
instance_count: 1

次に、ターミナルで次の CLI コマンドを実行して、デプロイを作成します (100% のトラフィックをこのモデルに設定していることに注意してください)。
```
az ml online-deployment create -f deployment.yml --all-traffic --skip-script-validation
```

注意

サービスがデプロイされるまでに数分かかる場合があります。デプロイが完了するまで待ってから、次のセクションに進みます。

テスト

デプロイが正常に作成されたら、スタジオまたは CLI を使用してエンドポイントをテストできます。

[スタジオ](#tab/azure-studio)
Azure CLI

Azure Machine Learning スタジオに移動し、左側のメニューから [エンドポイント] を選びます。次に、前に作成した r-endpoint-iris を選びます。

[Input data to test real-time endpoint] (リアルタイムエンドポイントをテストするための入力データ) テキストボックスに次の json を入力します。

{
    "forecast_horizon" : [2]
}

[Test] を選択します。次の出力が表示されます。

サンプル要求を作成する

プロジェクトの親フォルダーに、sample_request.json という名前のファイルを作成し、次のように設定します。

{
    "forecast_horizon" : [2]
}

エンドポイントを呼び出す

要求を呼び出します。この例では、r-endpoint-forecast という名前を使用しています。

az ml online-endpoint invoke --name r-endpoint-forecast --request-file sample_request.json

リソースをクリーンアップする

エンドポイントを使用して正常にスコア付けを行ったので、継続的なコストが発生しないようにそれを削除してかまいません。

az ml online-endpoint delete --name r-endpoint-forecast

次のステップ

Azure Machine Learning での R の使用方法の詳細については、Azure Machine Learning での R 機能の概要に関する記事を参照してください。