使用 REST 部署模型

發行項
03/06/2024

瞭解如何使用 Azure Machine Learning REST API 來部署模型。

REST API 使用標準 Http 指令動詞來建立、擷取、更新和刪除資源。 REST API 支援任何可發出 HTTP 要求的語言或工具。 REST 的簡單結構讓其成為指令碼環境及 MLOps 自動化的理想選擇。

在本文中，您將了解新的 REST API 有何用途：

建立機器學習資產
建立基本定型作業
建立超參數微調掃掠作業

必要條件

Azure 訂用帳戶 (您具備其系統管理權限)。如果您沒有此類訂用帳戶，請試用免費或付費的個人訂用帳戶。
Azure Machine Learning 工作區。
工作區中有服務主體。管理 REST 規定使用服務主體驗證。
服務主體驗證權杖。請依照擷取服務主體驗證權杖中的步驟來擷取此語彙基元。
curl 公用程式。 Windows 子系統 Linux 版或任何 UNIX 發行版本中都有 curl 程式。在 PowerShell 中，curl 是 Invoke-WebRequest 的別名，而且 curl -d "key=val" -X POST uri 變成 Invoke-WebRequest -Body "key=val" -Method POST -Uri uri。

設定端點名稱

注意

端點名稱在 Azure 區域層級必須是唯一的。例如，westus2 中只能有一個具有名稱為 my-endpoint 的端點。

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 入口網站來尋找相同的資訊：

# 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 儲存體 CLI，將 Blob 上傳至您的預設容器：

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

提示

您也可以使用其他方法來上傳，例如 Azure 入口網站或 Azure 儲存體總管。

上傳程式碼之後，您可以使用 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\"
}")

建立部署

在端點下建立部署：

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