Condividi tramite

Distribuire modelli con REST

  • Articolo

Questo articolo descrive come usare l'API REST di Azure Machine Learning per distribuire i modelli usando endpoint online. Gli endpoint online consentono di distribuire il modello senza la necessità di creare e gestire i cluster Kubernetes e l'infrastruttura sottostante. Le procedure seguenti illustrano come creare un endpoint online e come eseguire la distribuzione e convalidare l'endpoint richiamandolo.

Sono disponibili diversi metodi per creare un endpoint online con Azure Machine Learning. È possibile usare l'interfaccia della riga di comando di Azure, Azure Machine Learning Studioo l'API REST. L'API REST usa verbi HTTP standard per creare, recuperare, aggiornare ed eliminare risorse. Funziona con qualsiasi linguaggio o strumento in grado di effettuare richieste HTTP. La struttura semplice dell'API REST la rende una buona scelta negli ambienti di scripting e per l'automazione delle operazioni di apprendimento automatico.

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.

  • un token di autenticazione dell'entità servizio. È possibile ottenere il token seguendo la procedura descritta in Recuperare un token di autenticazione dell'entità servizio.

  • L'utilità curl.

    • Tutte le installazioni di Microsoft Windows 10 e Windows 11 hanno curl installato per impostazione predefinita. 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.

    • Per le piattaforme UNIX, il programma curl è disponibile nel sottosistema Windows per Linux o in qualsiasi distribuzione UNIX.

Impostare il nome dell'endpoint

I nomi degli endpoint devono essere univoci a livello di area di Azure. Un nome di endpoint, ad esempio my-endpoint, deve essere l'unico endpoint con tale nome all'interno di un'area specificata.

Creare un nome di endpoint univoco chiamando l'utilità RANDOM, che aggiunge un numero casuale come suffisso al valore endpt-rest:

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

Creare asset di apprendimento automatico

Per prepararsi per la distribuzione, configurare gli asset di Azure Machine Learning e configurare il processo. Registrare gli asset necessari per la distribuzione, inclusi il modello, il codice e l'ambiente.

Suggerimento

Le chiamate dell'API REST nelle procedure seguenti usano $SUBSCRIPTION_ID, $RESOURCE_GROUP$LOCATION (area) e Azure Machine Learning $WORKSPACE come segnaposto per alcuni argomenti. Quando si implementa il codice per la distribuzione, sostituire i segnaposto dell'argomento con i valori di distribuzione specifici.

REST amministrativo richiede un token di autenticazione dell'entità servizio. Quando si implementa il codice per la distribuzione, sostituire le istanze del segnaposto $TOKEN con il token dell'entità servizio per la distribuzione. È 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 variabile API_version in modo che supporti le versioni future:

API_VERSION="2022-05-01"

Ottenere i dettagli dell'account di archiviazione

Per registrare il modello e il codice, è prima necessario caricare questi elementi in un account di archiviazione di Azure. I dettagli dell'account di archiviazione di Azure 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 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 l'identificatore 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

Caricare i file del modello con una chiamata API REST simile:

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

Al termine del caricamento, 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 Docker con il comando docker e aggiungere dipendenze conda con il comando condaFile.

Il codice seguente legge il contenuto di un ambiente Conda (file YAML) 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 punteggi ai dati con il modello

Per richiamare l'endpoint di distribuzione, sono necessari l'URI di assegnazione del punteggio e il token di accesso.

Per prima cosa ottenere l'URI di 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')

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

Infine, richiamare l'endpoint usando l'utilità 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 di distribuzione

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 un endpoint

Se non si intende usare ulteriormente la distribuzione, eliminare le risorse.

Eseguire il comando seguente, che 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

Contenuto correlato