Implantar modelos com REST

Artigo
04/04/2023

Saiba como usar a API REST do Azure Machine Learning para implantar modelos.

A API REST usa verbos HTTP padrão para criar, recuperar, atualizar e excluir recursos. A API REST funciona com qualquer linguagem ou ferramenta que pode fazer solicitações HTTP. A estrutura direta do REST a torna uma boa opção nos ambientes de script e na automação de MLOps.

Neste artigo, você aprenderá a usar as novas APIs REST para:

Criar ativos de machine learning
Criar um trabalho de treinamento básico
Criar um trabalho de limpeza de ajuste de hiperparâmetro

Pré-requisitos

Uma assinatura do Azure para a qual você tem direitos administrativos. Caso você não tenha essa assinatura, experimente a assinatura pessoal gratuita ou paga.
Um workspace do Azure Machine Learning.
Uma entidade de serviço no workspace. As solicitações REST administrativas usam a autenticação da entidade de serviço.
Um token de autenticação da entidade de serviço. Siga as etapas descritas em Recuperar um token de autenticação da entidade de serviço para recuperar esse token.
O utilitário de curl. O programa de curl está disponível no Subsistema do Windows para Linux ou em qualquer distribuição do UNIX. No PowerShell, o curl é um alias para Invoke-WebRequest e curl -d "key=val" -X POST uri se torna Invoke-WebRequest -Body "key=val" -Method POST -Uri uri.

Definir nome do ponto de extremidade

Observação

Os nomes de ponto de extremidade precisam ser exclusivos no nível da região do Azure. Por exemplo, só pode haver um ponto de extremidade com o nome my-endpoint em westus2.

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

Pontos de extremidade online do Azure Machine Learning

Os pontos de extremidade online permitem a implantação do modelo sem a necessidade de criar e gerenciar a infraestrutura subjacente, bem como clusters do Kubernetes. Neste artigo, você vai criar um ponto de extremidade online e uma implantação e os validará invocando-os. Mas primeiro você vai precisar registrar os ativos necessários para a implantação, incluindo o modelo, o código e o ambiente.

Existem várias maneiras de criar um ponto de extremidade online do Azure Machine Learning incluindo a CLI do Azure e visualmente com o estúdio. O exemplo a seguir é um ponto de extremidade online com a API REST.

Criar ativos de machine learning

Primeiro, configure seus ativos do Azure Machine Learning para configurar o trabalho.

Nas chamadas à API REST a seguir, usaremos SUBSCRIPTION_ID, RESOURCE_GROUP, LOCATION e WORKSPACE como espaços reservados. Substitua os espaços reservados pelos seus próprios valores.

As solicitações REST administrativas usam um token de autenticação da entidade de serviço. Substitua TOKEN por um valor próprio. Você pode recuperar esse token com o seguinte 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')

O provedor de serviços usa o argumento api-version para garantir a compatibilidade. O argumento api-version varia de serviço para serviço. Defina a versão da API como uma variável para acomodar versões futuras:

API_VERSION="2022-05-01"

Obter detalhes da conta de armazenamento

Para registrar o modelo e o código, eles dever ser carregados em uma conta de armazenamento. Os detalhes da conta de armazenamento estão disponíveis no armazenamento de dados. Neste exemplo, você obterá o armazenamento de dados padrão e a conta do Armazenamento do Azure para seu workspace. Consulte o workspace com uma solicitação GET para obter um arquivo JSON com as informações.

Você pode usar a ferramenta jq para analisar o resultado JSON e obter os valores necessários. Você também pode usar o portal do Azure para obter as mesmas informações:

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

Carregar e registrar o código

Agora que você tem o armazenamento de dados, carregue o script de pontuação. Use a CLI do Armazenamento do Azure para carregar um blob no contêiner padrão:

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

Dica

Você também pode usar outros métodos para fazer o carregamento, como o portal do Azure ou o Gerenciador de Armazenamento do Azure.

Depois de carregar o código, você pode especificar o código com uma solicitação PUT e referenciar o armazenamento de dados com 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\"
  }
}"

Carregar e registrar o modelo

Assim como o código, carregue os arquivos de modelo:

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

Registre o modelo:

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

Criar ambiente

A implantação precisa ser executada em um ambiente com as dependências necessárias. Crie o ambiente com uma solicitação PUT. Use uma imagem do Docker do Microsoft Container Registry. Você pode configurar a imagem do Docker com Docker e adicionar dependências do Conda com condaFile.

No seguinte trecho, o conteúdo do ambiente Conda (arquivo YAML) foi lido em uma variável de 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\"
    }
}"

Criar ponto de extremidade

Crie o ponto de extremidade 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\"
}")

Criar implantação

Crie a implantação no ponto de extremidade:

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

Invocar o ponto de extremidade para pontuar dados com o modelo

Precisamos do URI de pontuação e do token de acesso para invocar o ponto de extremidade. Primeiro, obtenha o URI de pontuação:

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

Obtenha o token de acesso do ponto de extremidade:

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

Agora, invoque o ponto de extremidade 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

Verificar os logs

Verifique os logs implantação:

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

Excluir o ponto de extremidade

Se você não for usar a implantação, deverá excluí-la com o comando abaixo (ele exclui o ponto de extremidade e todas as implantações subjacentes):

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

Próximas etapas

Saiba como implantar o seu modelo usando a CLI do Azure.
Saiba como implantar o seu modelo usando o estúdio.
Saiba como Solucionar problemas de pontuação e de implantação de pontos de extremidade online
Saiba como Acessar os recursos do Azure com um ponto de extremidade online e uma identidade gerenciada
Saiba como monitorar os pontos de extremidade online.
Saiba fazer a Distribuição segura para ponto de extremidade online.
Exibir os custos de um ponto de extremidade online gerenciado do Azure Machine Learning.
Lista de SKUs de pontos de extremidade online gerenciados.
Saiba mais sobre os limites para pontos de extremidade online.