Distribuire modelli con REST

Articolo
03/25/2024

Informazioni su come usare l'API REST di Azure Machine Learning per distribuire modelli.

L'API REST usa verbi HTTP standard per creare, recuperare, aggiornare ed eliminare risorse. L'API REST funziona con qualsiasi linguaggio o strumento in grado di effettuare richieste HTTP. La struttura semplice di REST lo rende un'ottima scelta negli ambienti di scripting e per l'automazione MLOps.

Questo articolo illustra come usare le nuove API REST per:

Creare asset di apprendimento automatico
Creare un processo di training di base
Creare un processo di ottimizzazione degli iperparametri

Prerequisiti

Una sottoscrizione di Azure della quale si dispone dei diritti amministrativi. Se non si dispone di una sottoscrizione di questo tipo, provare la sottoscrizione personale gratuita o a pagamento.
Un'area di lavoro di Azure Machine Learning.
Un'entità servizio nell'area di lavoro. Le richieste amministrative REST usano l'autenticazione dell'entità servizio.
Token di autenticazione dell'entità servizio. Per recuperare questo token, seguire la procedura descritta in Recuperare un token di autenticazione dell'entità segui.
L'utilità curl. Il programma curl è disponibile nel sottosistema Windows per Linux o in qualsiasi distribuzione UNIX. In PowerShell curl è un alias per Invoke-WebRequest e curl -d "key=val" -X POST uri diventa Invoke-WebRequest -Body "key=val" -Method POST -Uri uri.

Impostare il nome dell'endpoint

Nota

I nomi degli endpoint devono essere univoci a livello di area di Azure. Ad esempio, può essere presente un solo endpoint con il nome my-endpoint in westus2.

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

Endpoint online di Azure Machine Learning

Gli endpoint online consentono di distribuire il modello senza la necessità di creare e gestire l'infrastruttura sottostante e i cluster Kubernetes. In questo articolo verrà creato un endpoint e una distribuzione online e verrà convalidato eseguendo il richiamo. Prima di tutto bisogna registrare gli asset necessari per la distribuzione, tra cui modello, codice e ambiente.

Esistono molti modi per creare un endpoint online di Azure Machine Learning , tra cui l'interfaccia della riga di comando di Azuree visivamente con lo Studio. L'esempio seguente è un endpoint online con l'API REST.

Creare asset di apprendimento automatico

Prima di tutto, configurare gli asset di Azure Machine Learning per configurare il processo.

Nelle chiamate API REST seguenti viene usato SUBSCRIPTION_ID, RESOURCE_GROUP, LOCATIONe WORKSPACE come segnaposto. Sostituire i segnaposto con i valori personalizzati.

REST amministrativo richiede un token di autenticazione dell'entità servizio. Sostituire TOKEN con il proprio valore. È possibile recuperare questo token con il seguente comando:

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

Il provider di servizi usa l'argomento api-version per garantire la compatibilità. L'argomento api-version varia da servizio a servizio. Impostare la versione dell'API come variabile per adattarla a versioni future:

API_VERSION="2022-05-01"

Ottenere i dettagli dell'account di archiviazione

Per registrare il modello e il codice, è prima necessario caricarli in un account di archiviazione. I dettagli dell'account di archiviazione sono disponibili nell'archivio dati. In questo esempio, si ottengono l'archivio dati predefinito e l'account di Archiviazione di Azure per l'area di lavoro. Eseguire una query sull'area di lavoro con una richiesta GET per ottenere un file JSON con le informazioni.

È possibile utilizzare lo strumento jq per analizzare il risultato JSON e ottenere i valori richiesti. È anche possibile usare il portale di Azure per trovare le stesse informazioni:

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

Caricare e registrare il codice

Ora che si dispone dell'archivio dati, è possibile caricare lo script di assegnazione dei punteggi. Usare l'interfaccia della riga di comando di Archiviazione di Azure per caricare un BLOB nel contenitore predefinito:

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

Suggerimento

È possibile usare anche altri metodi per il caricamento, come il portale di Azure o Azure Storage Explorer.

Dopo aver caricato il codice, è possibile specificarlo con una richiesta PUT e fare riferimento all’archivio dati con 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\"
  }
}"

Caricare e registrare un modello

Analogamente al codice, caricare i file del modello:

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

Ora, registrare il modello:

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

Creare un ambiente

La distribuzione deve essere eseguita in un ambiente che abbia le dipendenze necessarie. Creare l'ambiente con una richiesta PUT. Usare un'immagine Docker da Registro Container Microsoft. È possibile configurare l'immagine di Docker con Docker e aggiungere le dipendenze conda con condaFile.

Nel frammento seguente il contenuto di un ambiente Conda (file YAML) è stato letto in una variabile di ambiente:

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

Creare un endpoint

Creare l'endpoint online:

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

Creare la distribuzione

Creare una distribuzione nell'endpoint:

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

Richiamare l'endpoint per assegnare un punteggio ai dati con il modello

Per richiamare l'endpoint, sono necessari l'URI di assegnazione dei punteggi e il token di accesso. Per prima cosa ottenere l'URI del punteggio:

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

Ottenere il token di accesso dell'endpoint:

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

Richiamare ora l'endpoint usando curl:

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

Controllare i log

Controllare i log di distribuzione:

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

Eliminare l'endpoint

Se non si usa la distribuzione, è necessario eliminarlo con il comando seguente (elimina l'endpoint e tutte le distribuzioni sottostanti):

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

Passaggi successivi

Leggere le informazioni su come distribuire immagini condivise usando l'interfaccia della riga di comando di Azure.
Per informazioni su come distribuire il modello usando Studio.
Informazioni su come Risolvere i problemi di distribuzione e assegnazione dei punteggi agli endpoint online
Informazioni su come Accedere alle risorse di Azure con un endpoint online e un'identità gestita
Informazioni su come monitorare gli endpoint online.
Informazioni sull’Implementazione sicura per gli endpoint online.
Visualizzare i costi per un endpoint online gestito di Azure Machine Learning.
Elenco degli SKU degli endpoint online gestiti.
Informazioni sui limiti degli endpoint online.