Implantar modelos com REST

Este artigo descreve como usar a API REST do Azure Machine Learning para implantar modelos usando pontos de extremidade online. Os endpoints online permitem que você implante seu modelo sem ter que criar e gerenciar a infraestrutura subjacente e os clusters do Kubernetes. Os procedimentos a seguir demonstram como criar um ponto de extremidade online e implantar 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 a torna uma boa escolha em ambientes de script e para automação de operações de aprendizado de máquina.

Pré-requisitos

• Uma assinatura do Azure para a qual você tem direitos administrativos. Se você não tiver essa assinatura, experimente a assinatura pessoal gratuita ou paga.

• Um espaço de trabalho do Azure Machine Learning.

• Uma entidade de serviço em seu espaço de trabalho. 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 da entidade de serviço.

• O utilitário curl .

  • Todas as instalações do Microsoft Windows 10 e Windows 11 têm 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 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 de região do Azure. Um nome de ponto de extremidade como my-endpoint 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 RANDOM utilitário, que adiciona um número aleatório como sufixo ao valor endpt-rest:

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

Criar ativos de aprendizado de máquina

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

Gorjeta

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

O REST administrativo solicita um token de autenticação da entidade de serviço. Ao implementar o código para sua implantação, substitua instâncias do espaço reservado $TOKEN pelo token da entidade de serviço para 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 para garantir a api-version compatibilidade. O api-version argumento varia de serviço para serviço.

Defina a API_version 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, você precisa primeiro carregar esses itens em uma conta de Armazenamento do Azure. Os detalhes da conta de Armazenamento do 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 Azure para seu espaço de trabalho. Consulte seu espaço de trabalho 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 localizar 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 registar código

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

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

Gorjeta

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

Depois de carregar seu código, você pode especificar seu código com uma solicitação PUT e consultar o armazenamento de dados com o datastoreId identificador:

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

Modelo de upload e registo

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 que tenha 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 o docker comando e adicionar dependências conda com o condaFile comando.

O código a seguir lê o conteúdo de um ambiente Conda (arquivo YAML) 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 implementação

Crie uma implantação sob o 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\"
    }
}")

Invoque o 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 ao 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')

Finalmente, 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 de 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 ponto de extremidade

Se você não for usar 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

Conteúdos relacionados

• Implantar e pontuar um modelo usando um ponto de extremidade online
• Solucionar problemas de implantação e pontuação de endpoints online
• Monitorizar pontos finais online