Implantar modelos com REST

Artigo
11/22/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 possa fazer solicitações HTTP. A estrutura direta do REST o torna uma boa escolha em ambientes de script e para automação de MLOps.

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

Criar ativos de aprendizado de máquina
Criar um emprego de formação básica
Criar um trabalho de varredura de ajuste de hiperparâmetro

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. Siga as etapas em Recuperar um token de autenticação da entidade de serviço para recuperar esse token .
O utilitário curl . O programa curl está disponível no Subsistema Windows para Linux ou qualquer distribuição UNIX. 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.

Definir nome do ponto de extremidade

Nota

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

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

Pontos de extremidade online do Azure Machine Learning

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

Há muitas 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 aprendizado de máquina

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

Nas seguintes chamadas à API REST, usamos SUBSCRIPTION_ID, , RESOURCE_GROUPLOCATIONe WORKSPACE como espaços reservados. Substitua os marcadores de posição pelos seus próprios valores.

O REST administrativo solicita um token de autenticação da entidade de serviço. Substitua TOKEN pelo seu próprio valor. 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 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, primeiro eles precisam ser carregados para uma conta de armazenamento. Os detalhes da conta de armazenamento 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 código de registo &

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ê também pode usar outros métodos para carregar, 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 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\"
  }
}"

Modelo de upload e registo

Semelhante ao código, Carregue os arquivos de modelo:

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

Agora, 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 docker do Microsoft Container Registry. Você pode configurar a imagem docker com e adicionar dependências conda com DockercondaFile.

No trecho a seguir, o conteúdo de um 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 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 seu 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 ao ponto final:

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 registos

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

Se você não for usar a implantação, exclua-a 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óximos passos

Saiba como implantar seu modelo usando a CLI do Azure.
Saiba como implantar seu modelo usando o Studio.
Saiba como solucionar problemas de implantação e pontuação de endpoints online
Saiba como aceder aos recursos do Azure com um ponto de extremidade online e uma identidade gerida
Saiba como monitorar endpoints online.
Aprenda a implementação segura para endpoints online.
Exiba os custos de um ponto de extremidade online gerenciado pelo Azure Machine Learning.
Lista de SKU de endpoints online gerenciados.
Saiba mais sobre os limites para endpoints online.