如何將已註冊的 R 模型部署到線上 (即時) 端點

發行項
10/16/2024

在本文中，您將了解如何將 R 模型部署至受控端點 (Web API)，以便應用程式近乎即時地針對模型評分新資料。

必要條件

Azure Machine Learning 工作區。
已安裝的 Azure CLI 和 ml 延伸模組。或者，在工作區中使用計算執行個體，此執行個體已預先安裝 CLI。
至少一個與工作區相關聯的自訂環境。建立 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 環境變數掛接模型的路徑。
從 carrier 套件載入使用 crate 函式所建立的模型物件，該函式在封裝時儲存為 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 檔案是在容器啟動時執行的 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 環境或任何其他自訂環境。 (您不會使用此環境進行部署，但您會使用也為您建立的容器登錄。)

確認您至少有一個自訂環境之後，啟動終端機並設定 CLI：

開啟終端機視窗並登入 Azure。如果是使用 Azure Machine Learning 計算執行個體，請使用：
```
az login --identity
```
如果您不在計算執行個體上，請省略 --identity 並遵循提示以開啟瀏覽器視窗進行驗證。
確定您有最新版的 CLI 和 ml 延伸模組：
```
az upgrade
```
如果您有多個 Azure 訂用帳戶，請將作用中的訂用帳戶設定為您用於工作區的訂用帳戶。 (如果您只有單一訂用帳戶的存取權，則可略過此步驟。)以您的訂用帳戶名稱或訂用帳戶識別碼取代 <YOUR_SUBSCRIPTION_NAME_OR_ID>。也請移除方括號 <>。
```
az account set -s "<YOUR_SUBSCRIPTION_NAME_OR_ID>"
```
設定預設工作區。如果是使用計算執行個體，可以依原樣保留下列命令。如果您位於任何其他電腦上，請改用您的資源群組和工作區名稱。 (您可以在 Azure Machine Learning 工作室中找到這些值。)
```
az configure --defaults group=$CI_RESOURCE_GROUP workspace=$CI_WORKSPACE
```

設定 CLI 之後，請使用下列步驟來建置容器。

確定您位於專案目錄中。
```
cd r-deploy-azureml
```
若要在雲端建置映像，請在終端機中執行下列 bash 命令。將 <IMAGE-NAME> 取代為您想要提供映像的名稱。

如果您的工作區位於虛擬網路中，請參閱啟用 Azure Container Registry (ACR) 以取得將 --image-build-compute 新增至此程式碼最後一行 az acr build 命令的其他步驟。
```
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)

部署是託管執行實際評分模型所需的一組資源。單一端點可包含多個部署。 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
```
讓終端機保持開啟，以在下一節繼續使用。

建立部署

若要建立部署，請將下列程式碼新增至 deployment.yml 檔案。

以您在 endpoint.yml 檔案中定義的端點名稱取代 <ENDPOINT-NAME>
將 <DEPLOYMENT-NAME> 取代為您想要提供部署的名稱
以註冊模型的 URI 取代 <MODEL-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
```

注意

部署服務可能需要幾分鐘的時間。等到部署完成，再繼續進行下一節。

Test

成功建立部署後，您可以使用工作室或 CLI 來測試端點：

工作室
Azure CLI

瀏覽至 Azure Machine Learning 工作室，然後從左側功能表選取 [端點]。接下來，選取您稍早建立的 r-endpoint-iris。

在 [待用即時端點的輸入資料] 文字方塊中輸入下列 json：

{
    "forecast_horizon" : [2]
}

選取 [測試]。您應該會看見下列輸出：

建立範例要求

在您的專案父資料夾中，建立名為 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 功能概觀

共用方式為