Implementar e classificar um modelo de machine learning com um ponto final online

  • Artigo
  • 35 minutos para ler

APLICA-SE A:Extensão v2 da CLI do Azure (atual)SDK python azure-ai-ml v2 (atual)

Saiba como utilizar um ponto final online para implementar o seu modelo, para que não tenha de criar e gerir a infraestrutura subjacente. Começará por implementar um modelo no seu computador local para depurar quaisquer erros e, em seguida, irá implementá-lo e testá-lo no Azure.

Também irá aprender a ver os registos e a monitorizar o contrato de nível de serviço (SLA). Começa com um modelo e acaba com um ponto final HTTPS/REST dimensionável que pode utilizar para classificação online e em tempo real.

Os pontos finais online são pontos finais que são utilizados para inferência online (em tempo real). Existem dois tipos de pontos finais online: pontos finais online geridos e pontos finais online do Kubernetes. Para obter mais informações sobre pontos finais e diferenças entre pontos finais online geridos e pontos finais online do Kubernetes, consulte O que são pontos finais do Azure Machine Learning?.

Os pontos finais online geridos ajudam a implementar os modelos de ML de forma chave na mão. Os pontos finais online geridos funcionam com computadores GPU e CPU avançados no Azure de forma dimensionável e totalmente gerida. Os pontos finais online geridos tratam de servir, dimensionar, proteger e monitorizar os modelos, ao libertá-lo da sobrecarga de configuração e gestão da infraestrutura subjacente.

O exemplo principal neste documento utiliza pontos finais online geridos para implementação. Em vez disso, para utilizar o Kubernetes, veja as notas neste documento inline com o debate sobre o ponto final online gerido.

Dica

Para criar pontos finais online geridos no estúdio do Azure Machine Learning, consulte Utilizar pontos finais online geridos no estúdio.

Pré-requisitos

Antes de seguir os passos neste artigo, certifique-se de que tem os seguintes pré-requisitos:

  • Os controlos de acesso baseados em funções do Azure (RBAC do Azure) são utilizados para conceder acesso a operações no Azure Machine Learning. Para efetuar os passos neste artigo, a sua conta de utilizador tem de ter a função de proprietário ou contribuidor da área de trabalho do Azure Machine Learning ou uma função personalizada que permita Microsoft.MachineLearningServices/workspaces/onlineEndpoints/*. Para obter mais informações, veja Gerir o acesso a uma área de trabalho do Azure Machine Learning.

  • Se ainda não tiver definido as predefinições para a CLI do Azure, guarde as predefinições. Para evitar transmitir os valores da sua subscrição, área de trabalho e grupo de recursos várias vezes, execute este código:

    az account set --subscription <subscription ID>
az configure --defaults workspace=<Azure Machine Learning workspace name> group=<resource group>

  • (Opcional) Para implementar localmente, tem de instalar o Motor do Docker no seu computador local. Recomendamos vivamente esta opção, pelo que é mais fácil depurar problemas.

Importante

Os exemplos neste documento partem do princípio de que está a utilizar a shell do Bash. Por exemplo, a partir de um sistema Linux ou Subsistema Windows para Linux.

Preparar o sistema

Clonar o repositório de exemplo

Para acompanhar este artigo, clone primeiro o repositório de exemplos (azureml-examples). Em seguida, execute o seguinte código para aceder ao diretório de exemplos:

git clone --depth 1 https://github.com/Azure/azureml-examples
cd azureml-examples
cd cli

Dica

Utilize --depth 1 para clonar apenas a consolidação mais recente para o repositório, o que reduz o tempo para concluir a operação.

Definir um nome de ponto final

Para definir o nome do ponto final, execute o seguinte comando (substitua YOUR_ENDPOINT_NAME por um nome exclusivo).

Para Unix, execute este comando:

export ENDPOINT_NAME="<YOUR_ENDPOINT_NAME>"

Nota

Os nomes dos pontos finais têm de ser exclusivos numa região do Azure. Por exemplo, na região do Azure westus2 , só pode haver um ponto final com o nome my-endpoint.

Definir o ponto final e a implementação

O fragmento seguinte mostra o ficheiro de pontos finais/online/gerido/sample/endpoint.yml :

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: key

Nota

Para obter uma descrição completa do YAML, consulte Referência do YAML do ponto final online.

A referência para o formato YAML do ponto final está descrita na tabela seguinte. Para saber como especificar estes atributos, veja o exemplo YAML em Preparar o sistema ou a referência do YAML do ponto final online. Para obter informações sobre os limites relacionados com pontos finais geridos, veja Gerir e aumentar quotas de recursos com o Azure Machine Learning.

Chave Descrição
$schema (Opcional) O esquema YAML. Para ver todas as opções disponíveis no ficheiro YAML, pode ver o esquema no exemplo anterior num browser.
name O nome do ponto final. Tem de ser exclusivo na região do Azure.
As regras de nomenclatura são definidas nos limites de pontos finais online geridos.
auth_mode Utilize key para autenticação baseada em chaves. Utilize aml_token para autenticação baseada em tokens do Azure Machine Learning. key não expira, mas aml_token expira. (Obtenha o token mais recente com o az ml online-endpoint get-credentials comando.)

O exemplo contém todos os ficheiros necessários para implementar um modelo num ponto final online. Para implementar um modelo, tem de ter:

  • Ficheiros de modelo (ou o nome e a versão de um modelo que já está registado na área de trabalho). No exemplo, temos um modelo scikit-learn que faz a regressão.
  • O código necessário para classificar o modelo. Neste caso, temos um ficheiro score.py .
  • Um ambiente em que o modelo é executado. Como verá, o ambiente pode ser uma imagem do Docker com dependências do Conda ou pode ser um Dockerfile.
  • Definições para especificar o tipo de instância e a capacidade de dimensionamento.

O fragmento seguinte mostra o ficheiro de pontos finais/online/gerido/sample/blue-deployment.yml , com todas as entradas necessárias:

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: my-endpoint
model:
  path: ../../model-1/model/
code_configuration:
  code: ../../model-1/onlinescoring/
  scoring_script: score.py
environment: 
  conda_file: ../../model-1/environment/conda.yml
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
instance_type: Standard_DS3_v2
instance_count: 1

A tabela descreve os atributos de um deployment:

Chave Descrição
name O nome da implementação.
model Neste exemplo, especificamos as propriedades do modelo inline: path. Os ficheiros de modelo são automaticamente carregados e registados com um nome gerado automaticamente. Para obter as melhores práticas relacionadas, veja a sugestão na secção seguinte.
code_configuration.code.path O diretório no ambiente de desenvolvimento local que contém todo o código fonte do Python para classificar o modelo. Pode utilizar diretórios e pacotes aninhados.
code_configuration.scoring_script O ficheiro Python que está no code_configuration.code.path diretório de classificação no ambiente de desenvolvimento local. Este código Python tem de ter uma init() função e uma run() função. A função init() será chamada depois de o modelo ser criado ou atualizado (pode utilizá-lo para colocar o modelo em cache na memória, por exemplo). A run() função é chamada em todas as invocações do ponto final para fazer a classificação e predição reais.
environment Contém os detalhes do ambiente para alojar o modelo e o código. Neste exemplo, temos definições inline que incluem.path Vamos utilizar environment.docker.image para a imagem. As conda_file dependências serão instaladas na parte superior da imagem. Para obter mais informações, veja a sugestão na secção seguinte.
instance_type O SKU da VM que irá alojar as instâncias de implementação. Para obter mais informações, veja Managed online endpoints supported VM SKUs (SKUs de VM suportados por pontos finais online geridos).
instance_count O número de instâncias na implementação. Baseie o valor na carga de trabalho esperada. Para elevada disponibilidade, recomendamos que defina instance_count como, pelo menos 3, . Reservamos mais 20% para realizar atualizações. Para obter mais informações, veja Quotas de pontos finais online geridos.

Durante a implementação, os ficheiros locais, como a origem do Python para o modelo de classificação, são carregados a partir do ambiente de desenvolvimento.

Para obter mais informações sobre o esquema YAML, veja a referência do YAML do ponto final online.

Nota

Para utilizar o Kubernetes em vez de pontos finais geridos como destino de computação:

  1. Crie e anexe o cluster do Kubernetes como um destino de computação à área de trabalho do Azure Machine Learning com estúdio do Azure Machine Learning.
  2. Utilize o YAML do ponto final para direcionar o Kubernetes em vez do YAML do ponto final gerido. Terá de editar o YAML para alterar o valor de target para o nome do destino de computação registado. Pode utilizar este deployment.yaml que tem propriedades adicionais aplicáveis à implementação do Kubernetes.

Todos os comandos utilizados neste artigo (exceto a monitorização do SLA opcional e a integração do Azure Log Analytics) podem ser utilizados com pontos finais geridos ou com pontos finais do Kubernetes.

Registar o modelo e o ambiente separadamente

Neste exemplo, especificamos o path (de onde carregar ficheiros) inline. A CLI carrega automaticamente os ficheiros e regista o modelo e o ambiente. Como melhor prática para a produção, deve registar o modelo e o ambiente e especificar o nome e a versão registados separadamente no YAML. Utilize o formulário model: azureml:my-model:1 ou environment: azureml:my-env:1.

Para o registo, pode extrair as definições YAML de model e environment para ficheiros YAML separados e utilizar os comandos az ml model create e az ml environment create. Para saber mais sobre estes comandos, execute az ml model create -h e az ml environment create -h.

Utilizar diferentes tipos de instâncias de CPU e GPU

O YAML anterior utiliza um tipo de fins gerais (Standard_DS2_v2) e uma imagem do Docker não GPU (no YAML, veja o image atributo). Para computação de GPU, escolha um SKU de tipo de computação gpu e uma imagem do Docker de GPU.

Para obter os tipos de instâncias de GPU e fins gerais suportados, veja SKUs de VMs suportadas por pontos finais online geridos. Para obter uma lista das imagens base da CPU e da GPU do Azure Machine Learning, veja Imagens base do Azure Machine Learning.

Nota

Para utilizar o Kubernetes em vez de pontos finais geridos como um destino de computação, veja Introdução ao destino de computação do Kubernetes

Utilizar mais do que um modelo

Atualmente, só pode especificar um modelo por implementação no YAML. Se tiver mais do que um modelo, quando registar o modelo, copie todos os modelos como ficheiros ou subdiretórios para uma pasta que utilize para registo. No script de classificação, utilize a variável ambiente AZUREML_MODEL_DIR para obter o caminho para a pasta raiz do modelo. A estrutura de diretórios subjacente é mantida. Para obter um exemplo de implementação de vários modelos numa implementação, veja Implementar vários modelos numa implementação.

Dica

Se tiver mais de 1500 ficheiros para registar, poderá considerar comprimir os ficheiros ou subdiretórios como .tar.gz ao registar o modelo. Para consumir os modelos, pode descomprimir os ficheiros ou subdiretórios na função init() do script de classificação. Em alternativa, quando registar o modelo, defina a propriedade como True, o azureml.unpack que permitirá a descompressão automática. Em ambos os casos, a descompressão ocorre uma vez na fase de inicialização.

Compreender o script de classificação

Dica

O formato do script de classificação para pontos finais online é o mesmo formato utilizado na versão anterior da CLI e no SDK python.

Conforme indicado anteriormente, o script especificado em code_configuration.scoring_script tem de ter uma init() função e uma run() função.

Este exemplo utiliza o ficheiro de score.py: score.py

import os
import logging
import json
import numpy
import joblib


def init():
    """
    This function is called when the container is initialized/started, typically after create/update of the deployment.
    You can write the logic here to perform init operations like caching the model in memory
    """
    global model
    # AZUREML_MODEL_DIR is an environment variable created during deployment.
    # It is the path to the model folder (./azureml-models/$MODEL_NAME/$VERSION)
    # Please provide your model's folder name if there is one
    model_path = os.path.join(
        os.getenv("AZUREML_MODEL_DIR"), "model/sklearn_regression_model.pkl"
    )
    # deserialize the model file back into a sklearn model
    model = joblib.load(model_path)
    logging.info("Init complete")


def run(raw_data):
    """
    This function is called for every invocation of the endpoint to perform the actual scoring/prediction.
    In the example we extract the data from the json input and call the scikit-learn model's predict()
    method and return the result back
    """
    logging.info("model 1: request received")
    data = json.loads(raw_data)["data"]
    data = numpy.array(data)
    result = model.predict(data)
    logging.info("Request processed")
    return result.tolist()

A init() função é chamada quando o contentor é inicializado ou iniciado. Normalmente, a inicialização ocorre pouco depois de a implementação ser criada ou atualizada. Escreva aqui lógica para operações de inicialização globais, como colocar em cache o modelo na memória (como fazemos neste exemplo). A run() função é chamada para cada invocação do ponto final e deve fazer a classificação e predição reais. No exemplo, extraímos os dados da entrada JSON, chamamos o método do predict() modelo scikit-learn e, em seguida, devolvemos o resultado.

Implementar e depurar localmente com pontos finais locais

Para poupar tempo na depuração, recomendamos vivamente que teste o ponto final localmente. Para obter mais informações, veja Depurar pontos finais online localmente no Visual Studio Code.

Nota

Importante

O objetivo de uma implementação de ponto final local é validar e depurar o código e a configuração antes de implementar no Azure. A implementação local tem as seguintes limitações:

  • Os pontos finais locais não suportam regras de tráfego, autenticação ou definições de pesquisa.
  • Os pontos finais locais suportam apenas uma implementação por ponto final.
  • Os pontos finais locais não suportam modelos registados. Para utilizar modelos já registados, pode transferi-los através da CLI ou do SDK e fazer referência aos mesmos na definição de implementação.

Dica

Pode utilizar o pacote Python do servidor HTTP de inferência do Azure Machine Learning para depurar o script de classificação localmente sem o Motor do Docker. A depuração com o servidor de inferência ajuda-o a depurar o script de classificação antes de implementar nos pontos finais locais para que possa depurar sem ser afetado pelas configurações do contentor de implementação.

Implementar o modelo localmente

Primeiro, crie um ponto final. Opcionalmente, para um ponto final local, pode ignorar este passo e criar diretamente a implementação (passo seguinte), que, por sua vez, irá criar os metadados necessários. Implementar modelos localmente é útil para fins de desenvolvimento e teste.

az ml online-endpoint create --local -n $ENDPOINT_NAME -f endpoints/online/managed/sample/endpoint.yml

Agora, crie uma implementação com o nome blue no ponto final.

az ml online-deployment create --local -n blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml

O --local sinalizador direciona a CLI para implementar o ponto final no ambiente do Docker.

Dica

Utilize o Visual Studio Code para testar e depurar os pontos finais localmente. Para obter mais informações, veja Depurar pontos finais online localmente no Visual Studio Code.

Verificar se a implementação local foi bem-sucedida

Verifique o estado para ver se o modelo foi implementado sem erros:

az ml online-endpoint show -n $ENDPOINT_NAME --local

O resultado deve ser semelhante ao seguinte JSON. O provisioning_state é Succeeded.

{
  "auth_mode": "key",
  "location": "local",
  "name": "docs-endpoint",
  "properties": {},
  "provisioning_state": "Succeeded",
  "scoring_uri": "http://localhost:49158/score",
  "tags": {},
  "traffic": {}
}

A tabela seguinte contém os valores possíveis para provisioning_state:

Estado Descrição
Criação O recurso está a ser criado.
Atualização O recurso está a ser atualizado.
Eliminar O recurso está a ser eliminado.
Com êxito A operação de criação/atualização foi efetuada com êxito.
Com falhas A operação de criação/atualização/eliminação falhou.

Invocar o ponto final local para classificar dados com o modelo

Invoque o ponto final para classificar o modelo com o comando invoke de conveniência e transmitir parâmetros de consulta armazenados num ficheiro JSON:

az ml online-endpoint invoke --local --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json

Se quiser utilizar um cliente REST (como curl), tem de ter o URI de classificação. Para obter o URI de classificação, execute az ml online-endpoint show --local -n $ENDPOINT_NAME. Nos dados devolvidos, localize o scoring_uri atributo . Os comandos baseados em curl de exemplo estão disponíveis mais à frente neste documento.

Rever os registos da saída da operação de invocação

No exemplo score.py ficheiro, o run() método regista algum resultado na consola do .

Pode ver este resultado com o get-logs comando :

az ml online-deployment get-logs --local -n blue --endpoint $ENDPOINT_NAME

Implementar o ponto final online no Azure

Em seguida, implemente o ponto final online no Azure.

Implementar no Azure

Para criar o ponto final na cloud, execute o seguinte código:

az ml online-endpoint create --name $ENDPOINT_NAME -f endpoints/online/managed/sample/endpoint.yml

Para criar a implementação com o nome blue no ponto final, execute o seguinte código:

az ml online-deployment create --name blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml --all-traffic

Esta implementação pode demorar até 15 minutos, dependendo se o ambiente ou imagem subjacente está a ser criado pela primeira vez. As implementações subsequentes que utilizam o mesmo ambiente terminarão o processamento mais rapidamente.

Dica

  • Se preferir não bloquear a consola da CLI, pode adicionar o sinalizador --no-wait ao comando . No entanto, esta ação irá parar a apresentação interativa do estado de implementação.

Importante

O --all-traffic sinalizador no acima az ml online-deployment create atribui 100% do tráfego ao ponto final à implementação recentemente criada. Embora isto seja útil para fins de desenvolvimento e teste, para produção, poderá querer abrir tráfego para a nova implementação através de um comando explícito. Por exemplo, az ml online-endpoint update -n $ENDPOINT_NAME --traffic "blue=100"

Dica

Verificar o estado do ponto final

O show comando contém informações sobre provisioning_status o ponto final e a implementação:

az ml online-endpoint show -n $ENDPOINT_NAME

Pode listar todos os pontos finais na área de trabalho num formato de tabela com o list comando:

az ml online-endpoint list --output table

Verificar o estado da implementação online

Verifique os registos para ver se o modelo foi implementado sem erros:

az ml online-deployment get-logs --name blue --endpoint $ENDPOINT_NAME

Por predefinição, os registos são extraídos do servidor de inferência. Para ver os registos do inicializador de armazenamento (monta recursos como o modelo e o código no contentor), adicione o --container storage-initializer sinalizador.

Para obter mais informações sobre os registos de implementação, veja Obter registos de contentores.

Invocar o ponto final para classificar dados com o modelo

Pode utilizar o invoke comando ou um cliente REST à sua escolha para invocar o ponto final e classificar alguns dados:

az ml online-endpoint invoke --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json

O exemplo seguinte mostra como utilizar a chave para autenticar no ponto final:

Dica

Pode controlar quais os principais de segurança do Azure Active Directory que podem obter a chave de autenticação ao atribuí-los a uma função personalizada que permita Microsoft.MachineLearningServices/workspaces/onlineEndpoints/token/action e Microsoft.MachineLearningServices/workspaces/onlineEndpoints/listkeys/action. Para obter mais informações, veja Gerir o acesso a uma área de trabalho do Azure Machine Learning.

ENDPOINT_KEY=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -o tsv --query primaryKey)

Em seguida, utilize curl para classificar dados.

SCORING_URI=$(az ml online-endpoint show -n $ENDPOINT_NAME -o tsv --query scoring_uri)

curl --request POST "$SCORING_URI" --header "Authorization: Bearer $ENDPOINT_KEY" --header 'Content-Type: application/json' --data @endpoints/online/model-1/sample-request.json

Repare que utilizamos show e get-credentials comandos para obter as credenciais de autenticação. Repare também que estamos a utilizar o --query sinalizador para filtrar atributos apenas para o que precisamos. Para saber mais sobre --queryo , veja Consultar a saída do comando da CLI do Azure.

Para ver os registos de invocação, execute get-logs novamente.

Para obter informações sobre a autenticação através de um token, consulte Autenticar em pontos finais online.

(Opcional) Atualizar a implementação

Se quiser atualizar o código, modelo ou ambiente, atualize o ficheiro YAML e, em seguida, execute o az ml online-endpoint update comando.

Nota

Se atualizar a contagem de instâncias e, juntamente com outras definições de modelo (código, modelo ou ambiente) num único update comando: primeiro a operação de dimensionamento será executada, as outras atualizações serão aplicadas. No ambiente de produção, é uma boa prática realizar estas operações separadamente.

Para compreender como update funciona:

  1. Abra o ficheiro online/model-1/onlinescoring/score.py.

  2. Altere a última linha da init() função: Depois de logging.info("Init complete"), adicione logging.info("Updated successfully").

  3. Guarde o ficheiro.

  4. Execute este comando:

    az ml online-deployment update -n blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml

    Nota

    A atualização com o YAML é declarativa. Ou seja, as alterações no YAML refletem-se nos recursos de Resource Manager do Azure subjacentes (pontos finais e implementações). Uma abordagem declarativa facilita o GitOps: todas as alterações aos pontos finais e implementações (mesmo instance_count) passam pelo YAML.

    Dica

    Com o update comando, pode utilizar o --set parâmetro na CLI do Azure para substituir atributos no YAML ou para definir atributos específicos sem transmitir o ficheiro YAML. A utilização --set de atributos individuais é especialmente valiosa em cenários de desenvolvimento e teste. Por exemplo, para aumentar verticalmente o instance_count valor da primeira implementação, pode utilizar o --set instance_count=2 sinalizador. No entanto, como o YAML não é atualizado, esta técnica não facilita o GitOps.

  5. Uma vez que modificou a init() função (init() é executada quando o ponto final é criado ou atualizado), a mensagem Updated successfully estará nos registos. Obtenha os registos ao executar:

    az ml online-deployment get-logs --name blue --endpoint $ENDPOINT_NAME

O update comando também funciona com implementações locais. Utilize o mesmo az ml online-deployment update comando com o sinalizador --local .

Nota

O acima é um exemplo de atualização sem interrupção no local.

  • Para o ponto final online gerido, a mesma implementação é atualizada com a nova configuração, com 20% de nós de cada vez, ou seja, se a implementação tiver 10 nós, 2 nós de cada vez serão atualizados.
  • Para o ponto final online do Kubernetes, o sistema criará iteradamente uma nova instância de implementação com a nova configuração e eliminará a antiga.
  • Para a utilização de produção, pode considerar a implementação azul-verde, que oferece uma alternativa mais segura.

(Opcional) Configurar o dimensionamento automático

O dimensionamento automático executa a quantidade certa de recursos para processar a carga da aplicação. Os pontos finais online geridos suportam o dimensionamento automático através da integração com a funcionalidade de dimensionamento automático do Azure Monitor. Para configurar o dimensionamento automático, veja Como dimensionar automaticamente pontos finais online.

(Opcional) Monitorizar o SLA com o Azure Monitor

Para ver métricas e definir alertas com base no seu SLA, conclua os passos descritos em Monitorizar pontos finais online.

(Opcional) Integrar com o Log Analytics

O get-logs comando para a CLI ou o get_logs método do SDK fornece apenas as últimas centenas de linhas de registos de uma instância selecionada automaticamente. No entanto, o Log Analytics fornece uma forma de armazenar e analisar registos de forma duradoura. Para obter mais informações sobre como utilizar o registo, consulte Monitorizar pontos finais online

Como configurar e-mails no estúdio

Para começar a receber e-mails quando o seu trabalho, ponto final online ou ponto final de lote estiver concluído ou se existir um problema (com falha, cancelado), siga os seguintes passos:

  1. No Azure ML Studio, aceda às definições ao selecionar o ícone de engrenagem.
  2. Selecione o separador Email notificações.
  3. Alterne para ativar ou desativar notificações por e-mail para um evento específico.

Captura de ecrã a mostrar as definições do estúdio do Azure ML no separador notificações por e-mail.

Eliminar o ponto final e a implementação

Se não utilizar a implementação, deve eliminá-la ao executar o seguinte código (elimina o ponto final e todas as implementações subjacentes):

az ml online-endpoint delete --name $ENDPOINT_NAME --yes --no-wait

Passos seguintes

Experimente a implementação segura dos seus modelos como passo seguinte:

Para saber mais, veja estes artigos: