Implantar modelos com o REST

Artigo
09/03/2024

Este artigo descreve como usar a API REST do Azure Machine Learning para implantar modelos usando pontos de extremidade online. Os pontos de extremidade online permitem implantar seu modelo sem precisar criar e gerenciar a infraestrutura subjacente e os clusters do Kubernetes. Os procedimentos a seguir demonstram como criar um ponto de extremidade online e implantação e validar o ponto de extremidade invocando-o.

Há muitas maneiras de criar um ponto de extremidade online do Azure Machine Learning. Você pode usar a CLI do Azure, o Estúdio do Azure Machine Learning ou a API REST. A API REST usa verbos HTTP padrão para criar, recuperar, atualizar e excluir recursos. Ele funciona com qualquer linguagem ou ferramenta que possa fazer solicitações HTTP. A estrutura simples da API REST torna-a uma boa opção em ambientes de script e na automação de operações de aprendizado de máquina.

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. Você pode obter o token seguindo as etapas em Recuperar um token de autenticação de entidade de serviço.
O utilitário de curl.
- Todas as instalações do Microsoft Windows 10 e Windows 11 têm o curl instalado por padrão. No PowerShell, curl é um alias para Invoke-WebRequest e curl -d "key=val" -X POST uri torna-se Invoke-WebRequest -Body "key=val" -Method POST -Uri uri.
- Para plataformas UNIX, o programa curl está disponível no Subsistema do Windows para Linux ou em qualquer distribuição UNIX.

Definir nome do ponto de extremidade

Os nomes de ponto de extremidade devem ser exclusivos no nível da região do Azure. Um nome de ponto de extremidade, como meu-ponto-de-extremidade, deve ser o único ponto de extremidade com esse nome dentro de uma região especificada.

Crie um nome de ponto de extremidade exclusivo chamando o utilitário RANDOM, que adiciona um número aleatório como um sufixo ao valor endpt-rest:

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

Criar ativos de machine learning

Para se preparar para a implantação, configure seus ativos do Azure Machine Learning e configure seu trabalho. Registre os ativos necessários para implantação, incluindo o modelo, o código e o ambiente.

Dica

As chamadas à API REST nos procedimentos a seguir usam $SUBSCRIPTION_ID, $RESOURCE_GROUP, $LOCATION (região) e $WORKSPACE do Azure Machine Learning como espaços reservados para alguns argumentos. Ao implementar o código para a sua implantação, substitua os espaços reservados de argumento pelos valores de implantação específicos.

As solicitações REST administrativas usam um token de autenticação da entidade de serviço. Ao implementar o código para a sua implantação, substitua instâncias do espaço reservado $TOKEN pelo token da entidade de serviço da sua implantação. 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 variável API_version para acomodar versões futuras:

API_VERSION="2022-05-01"

Obter detalhes da conta de armazenamento

Para registrar o modelo e o código, primeiro você precisa carregar esses itens em uma conta de Armazenamento do Microsoft Azure. Os detalhes da conta de Armazenamento do Microsoft Azure estão disponíveis no armazenamento de dados. Neste exemplo, você obtém o armazenamento de dados padrão e a conta de Armazenamento do Microsoft 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, pode carregar 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ê pode usar outros métodos para concluir o upload, como o portal do Azure ou o Gerenciador de Armazenamento do Microsoft Azure.

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

Carregue os arquivos de modelo com uma chamada de API REST semelhante:

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

Após a conclusão do upload, 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 Registro de Contêiner da Microsoft. Você pode configurar a imagem do Docker com o comando docker e adicionar dependências do Conda com o comando condaFile.

O código a seguir lê o conteúdo de um ambiente Conda (arquivo YAML) e gera 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 ponto de extremidade para pontuar dados com o modelo

Você precisa do URI de pontuação e do token de acesso para invocar o ponto de extremidade de implantação.

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

Em seguida, 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')

Por fim, invoque o ponto de extremidade usando o utilitário 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 logs de implantação

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 quiser usar ainda mais a implantação, exclua os recursos.

Execute o seguinte comando, que 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

Compartilhar via

Implantar modelos com o REST

Pré-requisitos

Definir nome do ponto de extremidade

Criar ativos de machine learning

Obter detalhes da conta de armazenamento

Carregar e registrar o código

Carregar e registrar o modelo

Criar ambiente

Criar ponto de extremidade

Criar implantação

Invocar ponto de extremidade para pontuar dados com o modelo

Verificar logs de implantação

Excluir o ponto de extremidade

Comentários

Recursos adicionais

Compartilhar via

Implantar modelos com o REST

Pré-requisitos

Definir nome do ponto de extremidade

Criar ativos de machine learning

Obter detalhes da conta de armazenamento

Carregar e registrar o código

Carregar e registrar o modelo

Criar ambiente

Criar ponto de extremidade

Criar implantação

Invocar ponto de extremidade para pontuar dados com o modelo

Verificar logs de implantação

Excluir o ponto de extremidade

Conteúdo relacionado

Comentários

Recursos adicionais