Implantar e pontuar um modelo de aprendizado de máquina usando um ponto de extremidade online

  • Artigo

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

Neste artigo, você aprenderá a implantar seu modelo em um ponto de extremidade online para uso em inferências em tempo real. Você começará implantando um modelo em seu computador local para depurar qualquer erro. Em seguida, você implantará e testará o modelo no Azure. Você também aprenderá a exibir os logs de implantação e a monitorar o SLA (Contrato de Nível de Serviço). Ao final deste artigo, você terá um ponto de extremidade HTTPS/REST escalonável que poderá ser usado para inferência em tempo real.

Os pontos de extremidade online são pontos de extremidade usados para inferência em tempo real. Há dois tipos de pontos de extremidade online: pontos de extremidade online gerenciados e pontos de extremidade online do Kubernetes. Para obter mais informações sobre pontos de extremidade e diferenças entre pontos de extremidade online gerenciados e pontos de extremidade online do Kubernetes, confira O que são pontos de extremidade do Azure Machine Learning?.

Os pontos de extremidade online gerenciados ajudam a implantar seus modelos de ML de maneira completa. Os pontos de extremidade online gerenciados funcionam com computadores com CPU e GPU poderosas no Azure, de maneira escalonável e totalmente gerenciada. Os pontos de extremidade online gerenciados cuidam do serviço, do da colocação em escala, da segurança e do monitoramento de seus modelos, liberando você da sobrecarga de configurar e gerenciar a infraestrutura subjacente.

O exemplo principal neste documento usa pontos de extremidade online gerenciados para implantação. Para usar o Kubernetes, confira as observações neste documento que estão alinhadas à discussão sobre os pontos de extremidade online gerenciados.

Pré-requisitos

APLICA-SE A:Extensão de ML da CLI do Azure v2 (atual)

Antes de seguir as etapas neste artigo, verifique se você tem os seguintes pré-requisitos:

  • O RBAC do Azure (controle de acesso baseado em função) do Azure é usado para permitir acesso a operações no Azure Machine Learning. Para executar as etapas neste artigo, sua conta de usuário deve receber a função de proprietário ou colaborador para o espaço de trabalho do Azure Machine Learning ou uma função personalizada que permita Microsoft.MachineLearningServices/workspaces/onlineEndpoints/*. Se você usar o estúdio para criar/gerenciar pontos de extremidade/implantações online, precisará de uma permissão adicional "Microsoft.Resources/deployments/write" do proprietário do grupo de recursos. Para obter mais informações, consulte Gerenciar acesso a um workspace do Azure Machine Learning.

  • (Opcional) Para implantar localmente, você deve instalar o Mecanismo do Docker em seu computador local. Recomendamos enfaticamente esta opção, pois assim é mais fácil depurar problemas.

Alocação de cota de máquina virtual para implantação

Para pontos de extremidade online gerenciados, o Azure Machine Learning reserva 20% dos recursos de computação para executar atualizações em alguns SKUs de VM. Se você solicitar um determinado número de instâncias para essas SKUs de VM em uma implantação, deverá ter uma cota para ceil(1.2 * number of instances requested for deployment) * number of cores for the VM SKU disponível para evitar receber um erro. Por exemplo, se você solicitar 10 instâncias de uma VM Standard_DS3_v2 (que vem com 4 núcleos) em uma implantação, você precisa ter uma cota para 48 núcleos (12 instances * 4 cores) disponíveis. Essa cota extra é reservada para operações internadas pelo sistema, como atualização do sistema operacional, recuperação de VM etc, e não incorrerá em custo, a menos que essa operação seja executada. Para exibir o uso e solicitar aumentos de cota, confira Exibir seu uso e cotas no portal do Azure. Para exibir o custo de execução de pontos de extremidade online gerenciados, consulte Exibir o custo do ponto de extremidade online gerenciado. Há determinados SKUs de VM que são isentos da reserva de cota extra. Para exibir a lista completa, consulte a Lista de SKU de pontos de extremidade online gerenciados.

O Azure Machine Learning fornece um pool de cota compartilhada do qual todos os usuários podem acessar a cota para executar testes por um tempo limitado. Quando você usa o estúdio para implantar modelos Llama-2, Phi, Nemotron, Mistral, Dolly e Deci-DeciLM do catálogo de modelos em um ponto de extremidade online gerenciado, o Azure Machine Learning permite que você acesse essa cota compartilhada por um curto período.

Para obter mais informações sobre como usar a cota compartilhada para implantação de ponto de extremidade online, consulte Como implantar modelos de base usando o estúdio.

Preparar seu sistema

Definir variáveis de ambiente

Se você ainda não definiu os padrões da CLI do Azure, salve as configurações padrão. Para evitar passar os valores para sua assinatura, espaço 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>

Clone o repositório de exemplos

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

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

Dica

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

Os comandos neste tutorial estão nos arquivos deploy-local-endpoint.sh e deploy-managed-online-endpoint.sh no diretório endpoints/online/managed/sample/, e os arquivos de configuração YAML estão no subdiretório cli.

Observação

Os arquivos de configuração YAML para pontos de extremidade online do Kubernetes estão no subdiretório endpoints/online/kubernetes/.

Definir o ponto de extremidade

Para definir um ponto de extremidade, especifique:

  • Nome do ponto de extremidade: o nome do ponto de extremidade. O valor precisa ser exclusivo na região do Azure. Para obter mais informações sobre as regras de nomenclatura, confira Limites de pontos de extremidade.
  • Modo de autenticação: o método de autenticação para o ponto de extremidade. Escolha entre a autenticação baseada em chave e a autenticação baseada em token do Azure Machine Learning. Uma chave não expira, mas um token sim. Para obter mais informações sobre autenticação, confira Autenticação em um ponto de extremidade online.
  • Opcionalmente, você pode adicionar uma descrição e marcas para o ponto de extremidade.

Definir um nome de ponto de extremidade

Para definir o nome do ponto de extremidade, execute o comando a seguir (substitua YOUR_ENDPOINT_NAME por um nome exclusivo).

Para o Linux, execute este comando:

export ENDPOINT_NAME="<YOUR_ENDPOINT_NAME>"

Configurar o ponto de extremidade

O snippet a seguir mostra o arquivo endpoints/online/managed/sample/endpoint.yml:

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

A referência para o formato de ponto de extremidade YAML é descrita na tabela a seguir. Para saber como especificar esses atributos, consulte areferência do YAML para ponto de extremidade online . Para obter informações sobre os limites relacionados aos pontos de extremidade gerenciados, confira Limites de pontos de extremidade online.

Key Descrição
$schema (Opcional) O esquema YAML. Para ver todas as opções disponíveis no arquivo YAML, você pode visualizar o esquema no exemplo anterior em um navegador.
name O nome do ponto de extremidade.
auth_mode Use key para autenticação baseada em chave. Use aml_token para autenticação baseada em chave do Azure Machine Learning. Para obter um token mais recente, use o comando az ml online-endpoint get-credentials.

Definir a implantação

Uma implantação é um conjunto de recursos necessários para hospedar o modelo que executa a inferência real. Para implantar um modelo, você deve ter:

  • Arquivos de modelo (ou o nome e a versão de um modelo já está registrado no espaço de trabalho). No exemplo, temos um modelo scikit-learn que faz regressão.
  • Um script de pontuação, ou seja, um código que executa o modelo em uma determinada solicitação de entrada. Este script de pontuação recebe os dados enviados para um serviço Web implantado e os transmite ao modelo. Em seguida, o script executa o modelo e retorna sua resposta ao cliente. O script de pontuação é específico para seu modelo e deve compreender os dados que o modelo espera como entrada e retorna como saída. Nesse caso, temos um arquivo score.py.
  • Um ambiente no qual seu modelo é executado. O ambiente pode ser um imagem do Docker com dependências do Conda ou um Dockerfile.
  • Configurações para especificar o tipo de instância e a capacidade de dimensionamento.

A tabela a seguir descreve os atributos de chave de uma implantação:

Atributo Descrição
Nome O nome da implantação.
Nome do ponto de extremidade O nome do ponto de extremidade no qual criar a implantação.
Modelar O modelo a ser usado para a implantação. Esse valor pode ser uma referência a um modelo com versão existente no workspace ou uma especificação de modelo embutida.
Caminho do código O diretório no ambiente de desenvolvimento local que contém todo o código-fonte do Python para pontuar o modelo. Você pode usar diretórios e pacotes aninhados.
Script de pontuação O caminho relativo para o arquivo de pontuação no diretório do código-fonte. Esse código Python precisa ter uma função init() e uma função run(). A função init() será chamada depois que o modelo for criado ou atualizado (você pode usá-la para armazenar o modelo em cache na memória, por exemplo). A função run() é chamada em cada invocação do ponto de extremidade para fazer a pontuação e previsão real.
Ambiente Contém os detalhes do ambiente para hospedar o modelo e o código. Esse valor pode ser uma referência para um ambiente com versão existente no espaço de trabalho ou uma especificação de ambiente embutido.
Tipo de instância O tamanho da VM a ser usado para a implantação. Para obter a lista de tamanhos com suporte, confira Lista de SKU de pontos de extremidade online gerenciados.
Contagem de instâncias O número de instâncias a serem usadas para a implantação. Baseie o valor na carga de trabalho esperada. Para alta disponibilidade, recomendamos que você defina o valor mínimo de 3 Reservamos mais 20% para executar atualizações. Para obter mais informações, confira Alocação de cota de máquina virtual para implantações.

Aviso

  • O modelo e a imagem de contêiner (conforme definido em Ambiente) podem ser referenciados novamente a qualquer momento pela implantação quando as instâncias por trás da implantação passam por atualizações de segurança e/ou outras operações de recuperação. Se você usou um modelo registrado ou uma imagem de contêiner em Registro de Contêiner do Azure para implantação e removeu o modelo ou a imagem de contêiner, as implantações que dependem desses ativos podem falhar quando a reimaginação ocorrer. Se você removeu o modelo ou a imagem de contêiner, verifique se as implantações dependentes foram recriadas ou atualizadas com modelo alternativo ou imagem de contêiner.
  • O registro de contêiner ao qual o ambiente se refere só poderá ser privado se a identidade do ponto de extremidade tiver permissão para acessá-lo por meio da autenticação do Microsoft Entra e do RBAC do Azure. Pelo mesmo motivo, não há suporte para registros privados do Docker que não sejam do Registro de Contêiner do Azure.

Configurar uma implantação

O snippet a seguir mostra o arquivo endpoints/online/managed/sample/blue-deployment.yml, com todas as entradas necessárias para configurar uma implantação:

$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.yaml
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
instance_type: Standard_DS3_v2
instance_count: 1

Observação

No arquivo blue-deployment.yml, especificamos os seguintes atributos de implantação:

  • model: nesse exemplo, especificamos as propriedades de modelo embutidas usando o path. Os arquivos de modelo serão carregados e registrados automaticamente com um nome gerado automaticamente.
  • environment: nesse exemplo, temos as definições embutidas que incluem o path. Usaremos environment.docker.image para a imagem. As dependências de conda_file serão instaladas na parte superior da imagem.

Durante a implantação, os arquivos locais, como a origem do Python para o modelo de pontuação, são carregados do ambiente de desenvolvimento.

Para saber mais sobre o esquema YAML, confira a referência YAML do ponto de extremidade online.

Observação

Para usar o Kubernetes em vez de pontos de extremidade gerenciados como um destino de computação:

  1. Crie o cluster do Kubernetes e anexe-o como um destino de computação ao espaço de trabalho do Azure Machine Learning usando o Estúdio do Azure Machine Learning.
  2. Use o YAML de ponto de extremidade para fazer o direcionamento para o Kubernetes, em vez do YAML de ponto de extremidade gerenciado. Você precisará editar o YAML para alterar o valor de target para o nome do destino de computação registrado. Você pode usar esse deployment.yaml que tem propriedades adicionais aplicáveis à implantação do Kubernetes.

Todos os comandos usados neste artigo (exceto o monitoramento opcional de SLA e a integração da Análise de Logs do Azure) podem ser usados com pontos de extremidade gerenciados ou com pontos de extremidade do Kubernetes.

Registrar o modelo e o ambiente separadamente

Neste exemplo, especificamos path (local de onde carregar os arquivos) em linha. A CLI carrega automaticamente os arquivos e registra o modelo e o ambiente. Como melhor prática para produção, você deve registrar o modelo e o ambiente e especificar o nome e a versão registrados separadamente no YAML. Use a forma model: azureml:my-model:1 ou environment: azureml:my-env:1.

Para fazer o registro, você pode extrair as definições do YAML de model e environment em arquivos YAML separados e usar os comandos az ml model create e az ml environment create. Para saber mais sobre esses comandos, execute az ml model create -h e az ml environment create -h.

Para obter mais informações sobre como registrar seu modelo como um ativo, consulte Registrar seu modelo como um ativo no Machine Learning usando o CLI. Para obter mais informações sobre como criar um ambiente, consulte Gerenciar ambientes do Azure Machine Learning com o CLI e SDK (v2).

Usar diferentes imagens e tipos de instância de GPU e CPU

A definição anterior no arquivo blue-deployment.yml usa uma instância Standard_DS3_v2 de tipo de uso geral e uma imagem Docker sem GPU mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest. Para a computação de GPU, escolha um SKU de tipo de computação de GPU e uma imagem do Docker de GPU.

Para os tipos de instância de uso geral e de GPU com suporte, confira SKUs de VM com suporte para pontos de extremidade online gerenciados. Para obter uma lista de imagens de base de GPU e CPU do Azure Machine Learning, confira Imagens de base do Azure Machine Learning.

Observação

Para usar o Kubernetes em vez de pontos de extremidade gerenciados como destino de computação, confira Introdução ao destino de computação Kubernetes.

Identificar o caminho do modelo em relação a AZUREML_MODEL_DIR

Ao implantar seu modelo no Azure Machine Learning, você precisa especificar o local do modelo que deseja implantar como parte da configuração de implantação. No Azure Machine Learning, o caminho para o modelo é acompanhado com a variável de ambiente AZUREML_MODEL_DIR. Ao identificar o caminho do modelo em relação a AZUREML_MODEL_DIR, você pode implantar um ou mais modelos armazenados localmente no computador ou implantar um modelo registrado no workspace do Azure Machine Learning.

Para ilustrar isso, referenciamos a seguinte estrutura de pasta local para os dois primeiros casos, em que você implanta um só modelo ou vários modelos armazenados localmente:

Uma captura de tela mostrando uma estrutura de pastas que contém vários modelos.

Usar um só modelo local em uma implantação

Para usar um só modelo que você tem no computador local em uma implantação, especifique o path para o model no YAML de implantação. Veja um exemplo do YAML de implantação com o caminho /Downloads/multi-models-sample/models/model_1/v1/sample_m1.pkl:

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json 
name: blue 
endpoint_name: my-endpoint 
model: 
  path: /Downloads/multi-models-sample/models/model_1/v1/sample_m1.pkl 
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

Depois que você criar a implantação, a variável de ambiente AZUREML_MODEL_DIR apontará para o local de armazenamento no Azure em que o modelo foi armazenado. Por exemplo, /var/azureml-app/azureml-models/81b3c48bbf62360c7edbbe9b280b9025/1 conterá o modelo sample_m1.pkl.

No script de pontuação (score.py), você pode carregar seu modelo (neste exemplo, sample_m1.pkl) na função init():

def init(): 
    model_path = os.path.join(str(os.getenv("AZUREML_MODEL_DIR")), "sample_m1.pkl") 
    model = joblib.load(model_path)

Usar vários modelos locais em uma implantação

Embora a CLI do Azure, o SDK do Python e outras ferramentas de cliente permitam que você especifique apenas um modelo por implantação na definição de implantação, você ainda pode usar vários modelos em uma implantação registrando uma pasta de modelos que contém todos os modelos como arquivos ou subdiretórios.

No exemplo anterior de estrutura de pastas, observe que há vários modelos na pasta models. No YAML de implantação, você pode especificar o caminho para a pasta models da seguinte maneira:

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json 
name: blue 
endpoint_name: my-endpoint 
model: 
  path: /Downloads/multi-models-sample/models/ 
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

Depois que você criar a implantação, a variável de ambiente AZUREML_MODEL_DIR apontará para o local de armazenamento no Azure em que os modelos foram armazenados. Por exemplo, /var/azureml-app/azureml-models/81b3c48bbf62360c7edbbe9b280b9025/1 conterá os modelos e a estrutura de arquivos.

Neste exemplo, o conteúdo da pasta AZUREML_MODEL_DIR terá esta aparência:

Uma captura de tela da estrutura de pastas do local de armazenamento para vários modelos.

No script de pontuação (score.py), você pode carregar seus modelos na função init(). O código a seguir carrega o modelo sample_m1.pkl:

def init(): 
    model_path = os.path.join(str(os.getenv("AZUREML_MODEL_DIR")), "models","model_1","v1", "sample_m1.pkl ") 
    model = joblib.load(model_path)

Para ver um exemplo de como implantar vários modelos em uma só implantação, confira Implantar vários modelos em uma só implantação (exemplo da CLI) e Implantar vários modelos em uma só implantação (exemplo do SDK).

Dica

Se você tiver mais de 1.500 arquivos para registrar, considere a possibilidade de compactar os arquivos ou subdiretórios como .tar.gz ao registrar o modelo. Para consumir os modelos, você pode descompactar os arquivos ou subdiretórios na função init() do script de pontuação. Como alternativa, ao registrar os modelos, defina a propriedade azureml.unpack como True para descompactar os arquivos ou os subdiretórios automaticamente. Em ambos os casos, a descompressão acontece uma vez no estágio de inicialização.

Usar modelos registrados no workspace do Azure Machine Learning em uma implantação

Para usar um ou mais modelos, que são registrados no workspace do Azure Machine Learning, na implantação, especifique o nome dos modelos registrados no YAML de implantação. Por exemplo, a seguinte configuração de YAML de implantação especifica o nome model registrado como azureml:local-multimodel:3:

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json 
name: blue 
endpoint_name: my-endpoint 
model: azureml:local-multimodel:3 
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

Neste exemplo, considere que local-multimodel:3 contém os seguintes artefatos de modelo, que podem ser exibidos na guia Modelos no Estúdio do Azure Machine Learning:

Uma captura de tela da estrutura de pastas mostrando os artefatos do modelo registrado.

Depois que você criar a implantação, a variável de ambiente AZUREML_MODEL_DIR apontará para o local de armazenamento no Azure em que os modelos foram armazenados. Por exemplo, /var/azureml-app/azureml-models/local-multimodel/3 conterá os modelos e a estrutura de arquivos. AZUREML_MODEL_DIR apontará para a pasta que contém a raiz dos artefatos do modelo. Com base neste exemplo, o conteúdo da pasta AZUREML_MODEL_DIR terá esta aparência:

Uma captura de tela da estrutura de pastas mostrando vários modelos.

No script de pontuação (score.py), você pode carregar seus modelos na função init(). Por exemplo, carregue o modelo diabetes.sav:

def init(): 
    model_path = os.path.join(str(os.getenv("AZUREML_MODEL_DIR"), "models", "diabetes", "1", "diabetes.sav") 
    model = joblib.load(model_path)

Como funciona o script de pontuação

Dica

O formato do script de pontuação para pontos de extremidade online é o mesmo formato usado na versão anterior da CLI e no SDK do Python.

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

Este exemplo usa o arquivo 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 função init() é chamada quando o contêiner é inicializado ou iniciado. Normalmente, essa inicialização ocorre logo depois que a implantação é criada ou atualizada. A função init é o local para escrever a lógica para operações de inicialização global, como o cache do modelo na memória (como fazemos neste exemplo).

A função run() é chamada em cada invocação do ponto de extremidade para fazer a pontuação e previsão real. Nesse exemplo, extrairemos os dados de uma entrada JSON, chamaremos o método predict() do modelo scikit-learn e retornaremos o resultado.

Implantar e depurar localmente usando pontos de extremidade locais

É altamente recomendável que você execute testes no ponto de extremidade localmente validando e depurando seu código e a configuração antes de implantar no Azure. A CLI do Azure e o SDK do Python dão suporte a pontos de extremidade e implantações locais, enquanto estúdio do Azure Machine Learning e modelo do ARM não.

Para implantar localmente, o Mecanismo do Docker deve estar instalado e em execução. O Mecanismo do Docker normalmente é iniciado quando o computador é iniciado. Caso ele não seja, solucione o problema do Mecanismo do Docker.

Dica

Você pode usar o pacote Python do servidor HTTP de inferência do Azure Machine Learning para depurar seu script de pontuação localmente sem o Mecanismo do Docker. A depuração com o servidor de inferência ajuda você a depurar o script de pontuação antes de implantar em pontos de extremidade locais para que você possa depurar sem ser afetado pelas configurações do contêiner de implantação.

Observação

Os pontos de extremidade locais têm as seguintes limitações:

  • Eles não dão suporte a regras de tráfego, autenticação ou configurações de investigação.
  • Eles dão suporte apenas a uma implantação por ponto de extremidade.
  • Eles dão suporte somente a arquivos de modelo local e ambiente com arquivo Conda local. Se você quiser testar modelos registrados, primeiro baixe-os usando a CLI ou o SDK e, em seguida, use path na definição de implantação para fazer referência à pasta pai. Se quiser testar ambientes registrados, verifique o contexto do ambiente no Estúdio do Azure Machine Learning e prepare o arquivo Conda local para usar. O exemplo neste artigo demonstra como usar o modelo local e o ambiente com o arquivo Conda local, que dá suporte à implantação local.

Para obter mais informações sobre como depurar pontos de extremidade online localmente antes de implantar no Azure, confira Depurar pontos de extremidade online localmente no Visual Studio Code.

Implantar o modelo localmente

Primeiro crie um ponto de extremidade. Opcionalmente, para um ponto de extremidade local, você pode ignorar esta etapa e criar diretamente a implantação (próxima etapa), que, por sua vez, criará os metadados necessários. A implantação de 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 a implantação chamada blue no ponto de extremidade.

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

O sinalizador --local direciona a CLI para implantar o ponto de extremidade no ambiente do Docker.

Dica

Use o Visual Studio Code para testar e depurar os pontos de extremidade localmente. Para obter mais informações, confira depurar pontos de extremidade online localmente no Visual Studio Code.

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

Verifique os status para ver se o modelo foi implantado sem erro:

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

A saída deve ter aparência similar 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 a seguir contém os possíveis valores para provisioning_state:

Estado Descrição
Criando O recurso está sendo criado.
Atualizar O recurso está sendo atualizado.
Excluir O recurso está sendo excluído.
Êxito A operação de criação/atualização foi bem-sucedida.
Com falha Falha na operação de criação/atualização/exclusão.

Invocar o ponto de extremidade local para pontuar os dados usando o modelo

Invoque o ponto de extremidade para pontuar o modelo usando o comando fácil invoke e passando os parâmetros de consulta que são armazenados em um arquivo JSON:

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

Se você quiser usar um cliente REST (como a ondulação), deverá ter o URI de pontuação. Para obter o URI de pontuação, execute az ml online-endpoint show --local -n $ENDPOINT_NAME. Nos dados retornados, encontre o atributo scoring_uri. Os comandos baseados em curl de exemplo estão disponíveis mais adiante neste documento.

Examinar os logs em busca da saída da operação de invocação

No exemplo o arquivo score.py, o método run() registra uma saída no console.

Você pode visualizar essa saída usando o comando get-logs:

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

Implantar o ponto de extremidade online no Azure

Depois, implante o ponto de extremidade online no Azure.

Implantar no Azure

Para criar o ponto de extremidade na nuvem, execute o seguinte código:

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

Para criar a implantação chamada blue no ponto de extremidade, 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

Essa implantação pode levar cerca de 15 minutos, dependendo se o ambiente ou a imagem subjacente está sendo criada pela primeira vez. As implantações subsequentes que usam o mesmo ambiente concluirão o processamento mais rápido.

Dica

  • Se você preferir não bloquear o console da CLI, adicione o sinalizador --no-wait ao comando. No entanto, a exibição interativa do status da implantação será interrompida.

Importante

O sinalizador --all-traffic no az ml online-deployment create acima aloca 100% do tráfego do ponto de extremidade para a implantação azul recém-criada. Embora isso seja útil para fins de desenvolvimento e teste, para produção, talvez você queira abrir o tráfego para a nova implantação por meio de um comando explícito. Por exemplo, az ml online-endpoint update -n $ENDPOINT_NAME --traffic "blue=100".

Dica

Verifique o status do endpoint

O comando show contém informações em provisioning_state do ponto de extremidade e da implantação:

az ml online-endpoint show -n $ENDPOINT_NAME

Você pode listar todos os pontos de extremidade do espaço de trabalho no formato de tabela usando o comando list:

az ml online-endpoint list --output table

Verifique o status da implantação online

Verifique os logs para ver se o modelo foi implantado sem erro.

Para ver a saída de log do contêiner, use o seguinte comando da CLI:

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

Por padrão, os logs são extraídos do contêiner do servidor de inferência. Para ver os logs do contêiner do inicializador de armazenamento, adicione o sinalizador --container storage-initializer. Para obter mais informações sobre logs de implantação, consulte Obter logs de contêiner.

Invocar o ponto de extremidade para pontuar os dados usando o modelo

Você pode usar o comando invoke ou um cliente REST da sua escolha para invocar o ponto de extremidade e pontuar alguns dados:

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

O exemplo a seguir mostra como obter a chave usada para autenticar para o ponto de extremidade:

Dica

Você pode controlar quais entidades de segurança do Microsoft Entra podem obter a chave de autenticação atribuindo-as a uma função personalizada que permite Microsoft.MachineLearningServices/workspaces/onlineEndpoints/token/action e Microsoft.MachineLearningServices/workspaces/onlineEndpoints/listkeys/action. Para obter mais informações, consulte Gerenciar acesso a um workspace do Azure Machine Learning.

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

Em seguida, use curl para pontuar os 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

Observe que usamos os comandos show e get-credentials para obter as credenciais de autenticação. Também observamos que estamos usando o sinalizador --query para filtrar somente os atributos necessários. Saiba mais sobre --query, veja Consultar a saída de comando da CLI do Azure.

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

Para obter informações sobre como autenticar usando um token, consulte Autenticar em pontos de extremidade online.

(Opcional) Atualizar a implantação

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

Observação

Se você atualizar a contagem de instâncias (para escalar sua implantação) e junto com outras configurações de modelo (como código, modelo ou ambiente) em um único comando update, a operação de dimensionamento será executada e, em seguida, as outras atualizações serão aplicadas. É uma boa prática executar essas operações separadamente em um ambiente de produção.

Para entender como update funciona:

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

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

  3. Salve o arquivo.

  4. Execute este comando:

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

    Observação

    A atualização usando YAML é declarativa. Ou seja, as alterações no YAML são refletidas nos recursos subjacentes do Azure Resource Manager (pontos de extremidade e implantações). Uma abordagem declarativa facilita o GitOps:Todas as alterações em pontos de extremidade e implantações (até mesmo instance_count) passam pelo YAML.

    Dica

    • Você pode usar parâmetros de atualização genéricos, como o parâmetro --set, com o comando update da CLI para substituir atributos em seu YAML ou para definir atributos específicos sem passá-los no arquivo YAML. Use --set para atributos individuais é útil principalmente em cenários de desenvolvimento e teste. Por exemplo, para escalar verticalmente o valor instance_count da primeira implantação, você pode usar o sinalizador --set instance_count=2. No entanto, como o YAML não está atualizado, essa técnica não facilita o GitOps.
    • Especificar o arquivo YAML NÃO é obrigatório. Por exemplo, se você quiser testar uma configuração de simultaneidade diferente para uma determinada implantação, poderá tentar algo como az ml online-deployment update -n blue -e my-endpoint --set request_settings.max_concurrent_requests_per_instance=4 environment_variables.WORKER_COUNT=4. Isso manterá todas as configurações existentes, mas atualizará apenas os parâmetros especificados.

  5. Como você modificou a função init(), que é executada quando o ponto de extremidade é criado ou atualizado, a mensagem Updated successfully estará nos logs. Recupere os logs executando:

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

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

Observação

A atualização anterior para a implantação é um exemplo de uma atualização sem interrupção no local.

  • Para um ponto de extremidade online gerenciado, a implantação é atualizada para a nova configuração com 20% de nós por vez. Se a implantação tiver 10 nós, serão atualizados 2 nós por vez.
  • Para o ponto de extremidade online do Kubernetes, o sistema criará iteradamente uma nova instância de implantação com a nova configuração e excluirá a antiga.
  • Para uso em produção, considere a implantação azul-verde, que oferece uma alternativa mais segura para atualizar um serviço Web.

(Opcional) Configurar o dimensionamento automático

O dimensionamento automático executa automaticamente a quantidade certa de recursos para lidar com a carga em seu aplicativo. Os pontos de extremidade gerenciados dão suporte ao dimensionamento automático por meio da integração com o recurso de dimensionamento automático do Azure Monitor. Para configurar o dimensionamento automático, consulte Como fazer o dimensionamento automático de pontos de extremidade online.

(Opcional) Monitorar o SLA usando o Azure Monitor

Para exibir as métricas e definir alertas com base em seu SLA, conclua as etapas descritas em Monitorar pontos de extremidade online.

(Opcional) Fazer a integração com o Log Analytics

O comando get-logs para CLI ou o método get_logs para SDK fornece apenas as últimas centenas de linhas de logs de uma instância selecionada automaticamente. No entanto, o Log Analytics oferece uma forma de armazenar e analisar logs de modo durável. Para obter mais informações sobre como usar o registro em log, confira Monitorar pontos de extremidade online.

Excluir o ponto de extremidade e a implantação

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

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

Conteúdo relacionado