Déployer des modèles avec REST

  • Article

Découvrez comment déployer des modèles avec l’API REST d’Azure Machine Learning.

L’API REST utilise des verbes HTTP standard pour créer, récupérer, mettre à jour et supprimer des ressources. L’API REST fonctionne avec tout langage de programmation ou outil pouvant effectuer des requêtes HTTP. La structure simple de REST en fait un bon choix dans les environnements de script et pour l’automatisation MLOps.

Dans cet article, vous allez apprendre à utiliser les nouvelles API REST pour :

  • Créer des ressources de machine learning
  • Créer un travail d’entraînement de base
  • Créer un travail de balayage de réglage hyperparamétrique

Conditions préalables requises

Définir le nom du point de terminaison

Notes

Les noms des points de terminaison doivent être uniques au niveau de la région Azure. Par exemple, il ne peut y avoir qu’un seul point de terminaison avec le nom my-endpoint dans westus2.

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

Points de terminaison en ligne Azure Machine Learning

Les points de terminaison en ligne vous permettent de déployer votre modèle sans avoir à créer ni à gérer l’infrastructure sous-jacente ainsi que les clusters Kubernetes. Dans cet article, vous allez créer un point de terminaison en ligne et un déploiement, puis le valider en l’appelant. Mais tout d’abord, vous devez inscrire les ressources nécessaires au déploiement, notamment le modèle, le code et l’environnement.

Il existe de nombreuses façons de créer des points de terminaison en ligne Azure Machine Learning, y compris Azure CLI et visuellement avec le studio. L’exemple suivant présente un point de terminaison en ligne avec l’API REST.

Créer des ressources de machine learning

Tout d’abord, définissez vos ressources Azure Machine Learning pour configurer votre travail.

Dans les appels d’API REST suivants, nous utilisons SUBSCRIPTION_ID, RESOURCE_GROUP, LOCATION et WORKSPACE comme espaces réservés. Remplacez les espaces réservés par vos valeurs.

Les requêtes REST administratives utilisent un jeton d’authentification de principal de service. Remplacez TOKEN par votre propre valeur. Vous pouvez récupérer ce jeton à l’aide de la commande suivante :

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')

Le fournisseur de services utilise l’argument api-version pour garantir la compatibilité. L’argument api-version varie d’un service à l’autre. Définissez la version de l’API en tant que variable pour prendre en charge les futures versions :

API_VERSION="2022-05-01"

Obtenir les détails du compte de stockage

Pour inscrire le modèle et le code, vous devez d’abord les charger dans un compte de stockage. Les détails du compte de stockage sont disponibles dans le magasin de données. Dans cet exemple, vous obtenez le magasin de stockage par défaut et le compte Stockage Azure pour votre espace de travail. Interrogez votre espace de travail avec une requête GET pour obtenir ces informations dans un fichier JSON.

Vous pouvez utiliser l’outil jq pour analyser le résultat JSON et obtenir les valeurs nécessaires. Vous pouvez aussi utiliser le portail Azure pour rechercher les mêmes informations :

# 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')

Charger et inscrire le code

Maintenant que vous disposez du magasin de données, vous pouvez charger le script de scoring. Utilisez l’interface CLI Stockage Azure pour charger un objet blob dans votre conteneur par défaut :

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

Conseil

Vous pouvez aussi employer d’autres méthodes de chargement, comme le portail Azure ou l’Explorateur Stockage Azure.

Une fois le code chargé, vous pouvez le spécifier avec une requête PUT et faire référence au magasin de données avec 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\"
  }
}"

Charger et inscrire le modèle

Comme pour le code, chargez les fichiers de modèle :

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

Maintenant, inscrivez le modèle :

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\"
    }
}"

Créer un environnement

Le déploiement doit s’exécuter dans un environnement qui a les dépendances requises. Créez l’environnement avec une demande PUT. Utilisez une image Docker à partir de Microsoft Container Registry. Vous pouvez configurer l’image Docker avec Docker et ajouter des dépendances conda avec condaFile.

Dans l’extrait de code suivant, le contenu d’un environnement Conda (fichier YAML) a été lu dans une variable d’environnement :

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\"
    }
}"

Création d’un point de terminaison

Créez le point de terminaison en ligne :

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\"
}")

Créer un déploiement

Créez un déploiement sous le point de terminaison en ligne :

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\"
    }
}")

Appeler le point de terminaison pour effectuer le scoring des données avec votre modèle

Nous avons besoin de l’URI de scoring et du jeton d’accès pour appeler le point de terminaison. Tout d’abord, récupérez l’URI de scoring :

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')

Récupérez le jeton d’accès du point de terminaison :

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')

À présent, appelez le point de terminaison à l’aide de curl :

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

Consulter les journaux

Vérifiez les journaux du déploiement :

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 }"

Supprimer le point de terminaison

Si vous n’envisagez pas d’utiliser le déploiement, vous devez le supprimer avec la commande ci-dessous (cela supprime le point de terminaison et tous les déploiements sous-jacents) :

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

Étapes suivantes