Compartilhar via

Implantar modelos de machine learning para o Azure

  • Artigo

APLICA-SE A:Extensão de ML da CLI do Azurev1SDK do Python do Azure ML v1

Saiba como implantar o modelo de machine learning ou de aprendizado profundo como um serviço Web na nuvem do Azure.

Observação

Os Pontos de Extremidade do Azure Machine Learning (v2) fornecem uma experiência de implantação aprimorada e mais simples. Os pontos de extremidade dão suporte a cenários de inferência em tempo real e em lote. Os pontos de extremidade oferecem uma interface unificada para invocar e gerenciar implantações de modelo dentre os tipos de computação. Confira O que são os pontos de extremidade do Azure Machine Learning?.

Fluxo de trabalho para implantar um modelo

O fluxo de trabalho é semelhante, independentemente do local de implantação do seu modelo:

  1. Registre o modelo.
  2. Preparar um script de entrada.
  3. Preparar uma configuração de inferência.
  4. Implantar o modelo localmente para garantir que tudo funcione.
  5. Escolha um destino de computação.
  6. Implantar o modelo na nuvem.
  7. Teste o serviço Web resultante.

Para obter mais informações sobre os conceitos envolvidos no fluxo de trabalho de implantação de aprendizado de máquina, confira Gerenciar, implantar e monitorar modelos com o Azure Machine Learning.

Pré-requisitos

APLICA-SE A:Extensão de ML da CLI do Azure v1

Importante

Alguns comandos da CLI do Azure neste artigo usam a extensão azure-cli-ml ou v1 do Azure Machine Learning. O suporte à extensão v1 terminará em 30 de setembro de 2025. Você poderá instalar e usar a extensão v1 até essa data.

Recomendamos que você faça a transição para a extensão ml ou v2, antes de 30 de setembro de 2025. Para obter mais informações sobre a extensão v2, confira Extensão da CLI do Azure ML e SDK do Python v2.

Conectar-se ao workspace

APLICA-SE A: Extensão de ML da CLI do Azure v1

Para ver os workspaces aos quais você tem acesso, use os seguintes comandos:

az login
az account set -s <subscription>
az ml workspace list --resource-group=<resource-group>

Registre o modelo

Uma situação comum de um serviço implantado de machine learning é quando você precisa dos seguintes componentes:

  • Recursos que representem o modelo específico que você deseja implantar (por exemplo, um arquivo de modelo pytorch).
  • Código que você executará no serviço, que executa o modelo em determinada entrada.

O Azure Machine Learnings permite que você separe a implantação em dois componentes separados e, assim, possa manter o código, mas apenas atualizar o modelo. Nós definimos o mecanismo pelo qual você carrega um modelo separadamente do código como "registro do modelo".

Quando você registra um modelo, nós carregamos o modelo na nuvem (na conta de armazenamento padrão do seu workspace) e o montamos na mesma computação em que o serviço Web está em execução.

Os exemplos a seguir demonstram como registrar um modelo.

Importante

Você deve usar apenas os modelos que criar ou que obtiver de uma fonte confiável. Você deve tratar os modelos serializados como código, pois foram descobertas vulnerabilidades de segurança em vários formatos populares. Além disso, os modelos podem ter sido propositalmente treinados com intenção mal-intencionada a fim de fornecer saídas com desvio ou imprecisas.

APLICA-SE A: Extensão de ML da CLI do Azure v1

Os comandos a seguir baixam um modelo e, em seguida, o registram no workspace do Azure Machine Learning:

wget https://aka.ms/bidaf-9-model -O model.onnx --show-progress
az ml model register -n bidaf_onnx \
    -p ./model.onnx \
    -g <resource-group> \
    -w <workspace-name>

Defina -p como o caminho de uma pasta ou de um arquivo que você deseja registrar.

Para saber mais sobre az ml model register, consulte a documentação de referência.

Registrar um modelo de um trabalho de treinamento do Azure Machine Learning

Se você precisar registrar um modelo criado anteriormente através de um trabalho de treinamento do Azure Machine Learning, especifique o experimento, a execução e o caminho para o modelo:

az ml model register -n bidaf_onnx --asset-path outputs/model.onnx --experiment-name myexperiment --run-id myrunid --tag area=qna

O parâmetro --asset-path se refere ao local da nuvem do modelo. Neste exemplo, o caminho de um único arquivo é usado. Para incluir vários arquivos no registro do modelo, defina --asset-path para o caminho de uma pasta que contém os arquivos.

Para saber mais sobre az ml model register, consulte a documentação de referência.

Observação

Você também pode registrar um modelo de um arquivo local por meio do portal da interface do usuário do workspace.

Atualmente, há duas opções para carregar um arquivo de modelo local na interface do usuário:

  • De arquivos locais, que registrarão um modelo v2.
  • De arquivos locais (com base na estrutura), que registrarão um modelo v1.

Observe que somente modelos registrados por meio da entrada De arquivos locais (com base na estrutura) (que são conhecidos como modelos v1) podem ser implantados como serviços Web usando SDKv1/CLIv1.

Definir um script de entrada fictício

O script de entrada recebe os dados enviados para um serviço Web implantado e os transmite ao modelo. Em seguida, ele retorna a resposta do modelo ao cliente. O script é específico para seu modelo. O script de entrada precisa entender os dados esperados e retornados pelo modelo.

As duas coisas que você precisa realizar no seu script de entrada são:

  1. Carregar seu modelo (usando uma função chamada init())
  2. Executar o modelo em dados de entrada (usando uma função chamada run())

Para a implantação inicial, use um script de entrada fictício que imprime os dados recebidos.

import json


def init():
    print("This is init")


def run(data):
    test = json.loads(data)
    print(f"received data {test}")
    return f"test is {test}"

Salve esse arquivo como echo_score.py dentro de um diretório chamado source_dir. Esse script fictício retorna os dados enviados para ele, portanto, ele não usa o modelo. Mas é útil para testar se o script de pontuação está em execução.

Definir uma configuração de inferência

Uma configuração de inferência descreve o contêiner e os arquivos do Docker que serão usados ao inicializar o seu serviço Web. Todos os arquivos do seu diretório de origem, incluindo subdiretórios, serão compactados e carregados na nuvem quando você implantar o seu serviço Web.

A configuração de inferência abaixo especifica que a implantação do machine learning usará o arquivo echo_score.py no diretório ./source_dir para processar solicitações recebidas e que ela usará a imagem do Docker com os pacotes do Python especificados no ambiente project_environment.

Você pode usar qualquer ambiente coletado de inferência do Azure Machine Learning como a imagem base do Docker ao criar o ambiente do seu projeto. Nós instalaremos as dependências necessárias com base nele e armazenaremos a imagem do Docker resultante no repositório associado ao seu workspace.

Observação

O upload do diretório de origem de inferência do aprendizado de máquina do Azure não respeita .gitignore ou .amlignore

APLICA-SE A: Extensão de ML da CLI do Azure v1

Uma configuração de inferência mínima pode ser escrita como:

{
    "entryScript": "echo_score.py",
    "sourceDirectory": "./source_dir",
    "environment": {
        "docker": {
            "arguments": [],
            "baseDockerfile": null,
            "baseImage": "mcr.microsoft.com/azureml/openmpi3.1.2-ubuntu18.04",
            "enabled": false,
            "sharedVolumes": true,
            "shmSize": null
        },
        "environmentVariables": {
            "EXAMPLE_ENV_VAR": "EXAMPLE_VALUE"
        },
        "name": "my-deploy-env",
        "python": {
            "baseCondaEnvironment": null,
            "condaDependencies": {
                "channels": [],
                "dependencies": [
                    "python=3.6.2",
                    {
                        "pip": [
                            "azureml-defaults"
                        ]
                    }
                ],
                "name": "project_environment"
            },
            "condaDependenciesFile": null,
            "interpreterPath": "python",
            "userManagedDependencies": false
        },
        "version": "1"
    }
}

Salve esse arquivo com o nome dummyinferenceconfig.json.

Consulte este artigo para uma visão mais completa sobre as configurações de inferência.

Definir uma configuração de implantação

Uma configuração de implantação especifica a quantidade de memória e os núcleos de que seu WebService precisa para ser executado. Ela também fornece detalhes da configuração do WebService subjacente. Por exemplo, uma configuração de implantação permite que você especifique que o serviço precisa de dois gigabytes de memória, dois núcleos de CPU, um núcleo de GPU e que você deseja habilitar o dimensionamento automático.

As opções disponíveis para uma configuração de implantação diferem de acordo com o destino de computação escolhido. Em uma implantação local, você só pode especificar em que porta o seu serviço Web será oferecido.

APLICA-SE A: Extensão de ML da CLI do Azure v1

As entradas no documento deploymentconfig.json são mapeadas para os parâmetros de LocalWebservice.deploy_configuration. A seguinte tabela descreve o mapeamento entre as entidades no documento JSON e os parâmetros do método:

Entidade JSON Parâmetro de método Descrição
computeType NA O destino de computação. Para destinos locais, o valor precisa ser local.
port port A porta local na qual expor o ponto de extremidade HTTP do serviço.

O seguinte JSON é um exemplo de configuração de implantação a ser usada com a CLI:

{
    "computeType": "local",
    "port": 32267
}

Salve esse JSON como um arquivo chamado deploymentconfig.json.

Para obter mais informações, confira o Esquema de implantação.

Implantar seu modelo de machine learning

Agora, você está pronto para implantar seu modelo.

APLICA-SE A: Extensão de ML da CLI do Azure v1

Substitua bidaf_onnx:1 pelo nome do seu modelo e do número de versão dele.

az ml model deploy -n myservice \
    -m bidaf_onnx:1 \
    --overwrite \
    --ic dummyinferenceconfig.json \
    --dc deploymentconfig.json \
    -g <resource-group> \
    -w <workspace-name>

Chamar o seu modelo

Vamos verificar se o modelo de eco foi implantado com sucesso. Você deve conseguir executar uma simples solicitação de atividade, bem como uma solicitação de pontuação:

APLICA-SE A: Extensão de ML da CLI do Azure v1

curl -v http://localhost:32267
curl -v -X POST -H "content-type:application/json" \
    -d '{"query": "What color is the fox", "context": "The quick brown fox jumped over the lazy dog."}' \
    http://localhost:32267/score

Definir um script de entrada

Agora, é hora de carregar o seu modelo de fato. Primeiro, mude o script de entrada:

import json
import numpy as np
import os
import onnxruntime
from nltk import word_tokenize
import nltk


def init():
    nltk.download("punkt")
    global sess
    sess = onnxruntime.InferenceSession(
        os.path.join(os.getenv("AZUREML_MODEL_DIR"), "model.onnx")
    )


def run(request):
    print(request)
    text = json.loads(request)
    qw, qc = preprocess(text["query"])
    cw, cc = preprocess(text["context"])

    # Run inference
    test = sess.run(
        None,
        {"query_word": qw, "query_char": qc, "context_word": cw, "context_char": cc},
    )
    start = np.asscalar(test[0])
    end = np.asscalar(test[1])
    ans = [w for w in cw[start : end + 1].reshape(-1)]
    print(ans)
    return ans


def preprocess(word):
    tokens = word_tokenize(word)

    # split into lower-case word tokens, in numpy array with shape of (seq, 1)
    words = np.asarray([w.lower() for w in tokens]).reshape(-1, 1)

    # split words into chars, in numpy array with shape of (seq, 1, 1, 16)
    chars = [[c for c in t][:16] for t in tokens]
    chars = [cs + [""] * (16 - len(cs)) for cs in chars]
    chars = np.asarray(chars).reshape(-1, 1, 1, 16)
    return words, chars

Salve esse arquivo como score.py dentro de source_dir.

Observe o uso da variável de ambiente AZUREML_MODEL_DIR para localizar o seu modelo registrado. Agora, você adicionou alguns pacotes de PIP.

APLICA-SE A: Extensão de ML da CLI do Azure v1

{
    "entryScript": "score.py",
    "sourceDirectory": "./source_dir",
    "environment": {
        "docker": {
            "arguments": [],
            "baseDockerfile": null,
            "baseImage": "mcr.microsoft.com/azureml/openmpi3.1.2-ubuntu18.04",
            "enabled": false,
            "sharedVolumes": true,
            "shmSize": null
        },
        "environmentVariables": {
            "EXAMPLE_ENV_VAR": "EXAMPLE_VALUE"
        },
        "name": "my-deploy-env",
        "python": {
            "baseCondaEnvironment": null,
            "condaDependencies": {
                "channels": [],
                "dependencies": [
                    "python=3.6.2",
                    {
                        "pip": [
                            "azureml-defaults",
                            "nltk",
                            "numpy",
                            "onnxruntime"
                        ]
                    }
                ],
                "name": "project_environment"
            },
            "condaDependenciesFile": null,
            "interpreterPath": "python",
            "userManagedDependencies": false
        },
        "version": "2"
    }
}

Salve esse arquivo como inferenceconfig.json

Implante novamente e chame seu serviço

Implante o serviço novamente:

APLICA-SE A: Extensão de ML da CLI do Azure v1

Substitua bidaf_onnx:1 pelo nome do seu modelo e do número de versão dele.

az ml model deploy -n myservice \
    -m bidaf_onnx:1 \
    --overwrite \
    --ic inferenceconfig.json \
    --dc deploymentconfig.json \
    -g <resource-group> \
    -w <workspace-name>

Em seguida, verifique se você pode enviar uma solicitação de post ao serviço:

APLICA-SE A: Extensão de ML da CLI do Azure v1

curl -v -X POST -H "content-type:application/json" \
    -d '{"query": "What color is the fox", "context": "The quick brown fox jumped over the lazy dog."}' \
    http://localhost:32267/score

Escolher um destino de computação

O destino de computação que você usa para hospedar seu modelo afetará o custo e a disponibilidade do ponto de extremidade implantado. Use esta tabela para escolher um destino de computação apropriado.

Destino de computação Usado para Suporte de GPU Descrição
Serviço Web local Teste/depuração   Use para teste e solução de problemas limitados. A aceleração de hardware depende do uso de bibliotecas no sistema local.
Kubernetes do Azure Machine Learning Inferência em tempo real Sim Execute cargas de trabalho de inferência na nuvem.
Instâncias de Contêiner do Azure Inferência em tempo real

Recomendado apenas para fins de desenvolvimento/teste.		   Use para cargas de trabalho baseadas em CPU de baixa escala que exigem menos de 48 GB de RAM. Não exige que você gerencie um cluster.

Adequado apenas para modelos com menos de 1 GB.

Com suporte no designer.

Observação

Ao escolher uma SKU de cluster, primeiro escale verticalmente e, em seguida, escale horizontalmente. Comece com um computador que tenha 150% da RAM de que seu modelo requer, perfile o resultado e localize um computador que tenha o desempenho de que você precisa. Depois de aprender isso, aumente o número de computadores para atender à sua necessidade de inferência simultânea.

Observação

Os Pontos de Extremidade do Azure Machine Learning (v2) fornecem uma experiência de implantação aprimorada e mais simples. Os pontos de extremidade dão suporte a cenários de inferência em tempo real e em lote. Os pontos de extremidade oferecem uma interface unificada para invocar e gerenciar implantações de modelo dentre os tipos de computação. Veja O que são os pontos de extremidade do Azure Machine Learning?.

Implantar na nuvem

Depois de confirmar que o serviço funciona localmente e escolher um destino de computação remoto, você está pronto para implantar na nuvem.

Mude a configuração de implantação para corresponder ao destino de computação que você escolheu, nesse caso, as Instâncias de Contêiner do Azure:

APLICA-SE A: Extensão de ML da CLI do Azure v1

As opções disponíveis para uma configuração de implantação diferem de acordo com o destino de computação escolhido.

{
    "computeType": "aci",
    "containerResourceRequirements":
    {
        "cpu": 0.5,
        "memoryInGB": 1.0
    },
    "authEnabled": true,
    "sslEnabled": false,
    "appInsightsEnabled": false
}

Salve este arquivo como re-deploymentconfig.json.

Para obter mais informações, confira esta referência.

Implante o serviço novamente:

APLICA-SE A: Extensão de ML da CLI do Azure v1

Substitua bidaf_onnx:1 pelo nome do seu modelo e do número de versão dele.

az ml model deploy -n myservice \
    -m bidaf_onnx:1 \
    --overwrite \
    --ic inferenceconfig.json \
    --dc re-deploymentconfig.json \
    -g <resource-group> \
    -w <workspace-name>

Para exibir os logs de serviço, use o seguinte comando:

az ml service get-logs -n myservice \
    -g <resource-group> \
    -w <workspace-name>

Chamar o seu serviço Web remoto

Ao implantar remotamente, você pode habilitar a autenticação de chaves. O exemplo a seguir mostra como obter a sua chave de serviço com o Python para fazer uma solicitação de inferência.

import requests
import json
from azureml.core import Webservice

service = Webservice(workspace=ws, name="myservice")
scoring_uri = service.scoring_uri

# If the service is authenticated, set the key or token
key, _ = service.get_keys()

# Set the appropriate headers
headers = {"Content-Type": "application/json"}
headers["Authorization"] = f"Bearer {key}"

# Make the request and display the response and logs
data = {
    "query": "What color is the fox",
    "context": "The quick brown fox jumped over the lazy dog.",
}
data = json.dumps(data)
resp = requests.post(scoring_uri, data=data, headers=headers)
print(resp.text)
print(service.get_logs())

Confira o artigo sobre aplicativos cliente para consumir serviços Web para obter mais exemplos de clientes em outros idiomas.

Como configurar e-mails no estúdio

Para começar a receber e-mails quando seu trabalho, ponto de extremidade online ou ponto de extremidade de lote estiver concluído ou se houver um problema (falhou, cancelado), use as seguintes etapas:

  1. No Azure ML studio, vá para configurações selecionando o ícone de engrenagem.
  2. Selecione a guia Notificações por email.
  3. Alterne para habilitar ou desabilitar notificações por email para um evento específico.

Screenshot of Azure ML studio's settings on the email notifications tab.

Compreendendo estado do serviço

Durante a implantação do modelo, você pode ver a alteração do estado do serviço durante a implantação completa.

A seguinte tabela descreve os diferentes tipos de estado de serviço:

Estado WebService Descrição Estado final?
Transição O serviço está em processo de implantação. Não
Unhealthy O serviço foi implantado, mas está inacessível no momento. Não
Não agendável O serviço não pode ser implantado no momento devido à falta de recursos. Não
Com falha O serviço falhou ao ser implantado devido a erro ou falha. Yes
Íntegros O serviço está íntegro e o ponto de extremidade está disponível. Yes

Dica

Durante a implantação, as imagens do Docker para destinos de computação são criadas e carregadas do ACR (Registro de Contêiner do Azure). Por padrão, o Azure Machine Learning cria um ACR que usa a camada de serviço básica. Alterar o ACR do seu espaço de trabalho para a camada Standard ou Premium pode reduzir o tempo necessário para criar e implantar imagens em seus destinos de computação. Para obter mais informações, confira Níveis de serviço do Registro de Contêiner do Azure.

Observação

Se você estiver implantando um modelo no AKS, aconselharemos a habilitar o Azure Monitor para esse cluster. Isso ajudará a entender a integridade geral do cluster e o uso de recursos. Os recursos a seguir poderão ser úteis:

Se estiver tentando implantar um modelo em um cluster não íntegro ou com sobrecarga, espera-se que haja problemas. Se precisar de ajuda para solucionar problemas de cluster do AKS, entre em contato com o suporte do AKS.

Excluir recursos

APLICA-SE A: Extensão de ML da CLI do Azure v1

# Get the current model id
import os

stream = os.popen(
    'az ml model list --model-name=bidaf_onnx --latest --query "[0].id" -o tsv'
)
MODEL_ID = stream.read()[0:-1]
MODEL_ID
az ml service delete -n myservice
az ml service delete -n myaciservice
az ml model delete --model-id=<MODEL_ID>

Para excluir um serviço Web implantado, use az ml service delete <name of webservice>.

Para excluir um modelo registrado do seu espaço de trabalho, use az ml model delete <model id>.

Leia mais sobre como excluir um serviço Web e excluir um modelo.

Próximas etapas