Personalizar saídas em implantações em lote

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

Este guia explica como criar implantações que geram saídas e arquivos personalizados. Às vezes, é necessário mais controle sobre o que é escrito como saída de trabalhos de inferência em lote. Estes casos incluem as seguintes situações:

• É necessário controlar como as previsões são gravadas na saída. Por exemplo, você deseja acrescentar a previsão aos dados originais, se os dados forem tabulares.
• Você precisa escrever suas previsões em um formato de arquivo diferente daquela com suporte pronto para uso por implantações em lote.
• Seu modelo é um modelo generativo que não pode gravar a saída em um formato tabular. Por exemplo, modelos que produzem imagens como saídas.
• Seu modelo produz vários arquivos tabulares em vez de um único. Por exemplo, modelos que executam a previsão considerando vários cenários.

As Implantações em lote permitem assumir o controle da saída dos trabalhos, permitindo gravar diretamente na saída do trabalho de implantação em lote. Neste tutorial, você aprenderá como implantar um modelo para executar a inferência do lote e gravar as saídas em formato parquet, acrescentando as previsões aos dados de entrada originais.

Sobre este exemplo

Este exemplo mostra como você pode implantar um modelo para executar a inferência em lote e personalizar como suas previsões são gravadas na saída. O modelo é baseado no conjunto de dados de Doenças Cardíacas da UCI. O banco de dados contém 76 atributos, mas este exemplo usa um subconjunto de 14 deles. O modelo tenta prever a presença de doenças cardíacas em um paciente. Ele é inteiro com valor 0 (sem presença) a 1 (presença).

O modelo foi treinado usando um classificador XGBBoost e todo o pré-processamento necessário foi empacotado como um pipeline scikit-learn, tornando esse modelo um pipeline de ponta a ponta que vai de dados brutos a previsões.

O exemplo neste artigo é baseado em exemplos de códigos contidos no repositório azureml-examples . Para executar os comandos localmente sem precisar copiar/colar o YAML e outros arquivos, primeiro clone o repositório e altere os diretórios para a pasta:

CLI do Azure

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

Python

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

Os arquivos desse exemplo estão em:

cd endpoints/batch/deploy-models/custom-outputs-parquet

Acompanhe em um notebook do Jupyter

Há um notebook do Jupyter que é possível usar para seguir este exemplo. No repositório clonado, abra o notebook chamadocustom-output-batch.ipynb.

Pré-requisitos

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

• Uma assinatura do Azure. Caso não tenha uma assinatura do Azure, crie uma conta gratuita antes de começar. Experimente a versão gratuita ou paga do Azure Machine Learning.

• Um workspace do Azure Machine Learning. Se você não tiver um, use as etapas do artigo Gerenciar espaços de trabalho do Azure Machine Learning para criar um.

• Certifique-se de ter as seguintes permissões no espaço de trabalho:

  • Criar ou gerenciar pontos de extremidade e implantações em lotes: use uma função de Proprietário, Colaborador ou Personalizada que permita Microsoft.MachineLearningServices/workspaces/batchEndpoints/*.

  • Criar implantações do ARM no grupo de recursos do espaço de trabalho: use uma função de Proprietário, Colaborador ou Personalizada que permita Microsoft.Resources/deployments/write no grupo de recursos em que o espaço de trabalho está implantado.

• Você precisa instalar o software a seguir para trabalhar com o Azure Machine Learning:

  CLI do Azure

  A CLI do Azure e a mlextensão do Azure Machine Learning.

  az extension add -n ml
  

  Observação

  Implantações de componente de pipeline para Pontos de Extremidade em Lote foram introduzidas na versão 2.7 da extensão ml para a CLI do Azure. Use az extension update --name ml para obter a última versão.

  Python

  O SDK do Azure Machine Learning para Python.

  pip install azure-ai-ml
  

  Observação

  As classes ModelBatchDeployment e PipelineComponentBatchDeployment foram introduzidas na versão 1.7.0 do SDK. Use pip install -U azure-ai-ml para obter a última versão.

Conectar-se ao workspace

O workspace é o recurso de nível superior para o Azure Machine Learning. Ele fornece um local centralizado para trabalhar com todos os artefatos que você cria ao usar o Azure Machine Learning. Nesta seção, nos conectaremos ao workspace no qual você executará tarefas de implantação.

CLI do Azure

Passe os valores para sua ID de assinatura, espaço de trabalho, localização e grupo de recursos no código a seguir:

az account set --subscription <subscription>
az configure --defaults workspace=<workspace> group=<resource-group> location=<location>

Python

1. Importe as bibliotecas necessárias:

   from azure.ai.ml import MLClient, Input, load_component
   from azure.ai.ml.entities import BatchEndpoint, ModelBatchDeployment, ModelBatchDeploymentSettings, PipelineComponentBatchDeployment, Model, AmlCompute, Data, BatchRetrySettings, CodeConfiguration, Environment, Data
   from azure.ai.ml.constants import AssetTypes, BatchDeploymentOutputAction
   from azure.ai.ml.dsl import pipeline
   from azure.identity import DefaultAzureCredential
   

2. Configure os detalhes do espaço de trabalho e gerencie o espaço de trabalho:

   Passe os valores para sua ID de assinatura, espaço de trabalho e grupo de recursos no seguinte código:

   subscription_id = "<subscription>"
   resource_group = "<resource-group>"
   workspace = "<workspace>"
   
   ml_client = MLClient(DefaultAzureCredential(), subscription_id, resource_group, workspace)
   

Criar uma implantação em lote com uma saída personalizada

Neste exemplo, você cria uma implantação que pode ser gravada diretamente na pasta de saída do trabalho de implantação em lote. A implantação usa esse recurso para gravar arquivos parquet personalizados.

Registre o modelo

Implante modelos registrados usando um ponto de extremidade em lote. Nesse caso, você já tem uma cópia local do modelo no repositório, portanto, só precisa publicar o modelo no registro do workspace. Você poderá pular essa etapa se o modelo que está tentando implantar já estiver registrado.

CLI do Azure

MODEL_NAME='heart-classifier-sklpipe'
az ml model create --name $MODEL_NAME --type "custom_model" --path "model"

Python

model_name = "heart-classifier-sklpipe"
model_description = "A heart condition classifier trained with XGBoosts and Scikit-Learn for feature processing."
model_local_path = "model"

model = ml_client.models.create_or_update(
    Model(
        name=model_name,
        path=model_local_path,
        type=AssetTypes.CUSTOM_MODEL,
        tags={"framework": "scikit-learn", "estimator": "xgboost"},
    )
)

Criar um script de pontuação

É necessário criar um script de pontuação que possa ler os dados de entrada fornecidos pela implantação em lotes e retornar as pontuações do modelo. Você também escreverá diretamente na pasta de saída do trabalho. Em resumo, o script de pontuação proposto faz o seguinte:

1. Lê os dados de entrada como arquivos CSV.
2. Executa uma função predict de modelo MLflow nos dados de entrada.
3. Acrescenta as previsões a um conjunto pandas.DataFrame com os dados de entrada.
4. Grava os dados em um arquivo nomeado como o arquivo de entrada, mas em formato parquet.

code/batch_driver.py

import os
import pickle
import glob
import pandas as pd
from pathlib import Path
from typing import List


def init():
    global model
    global output_path

    # AZUREML_MODEL_DIR is an environment variable created during deployment
    # It is the path to the model folder
    # Please provide your model's folder name if there's one:
    output_path = os.environ["AZUREML_BI_OUTPUT_PATH"]
    model_path = os.environ["AZUREML_MODEL_DIR"]
    model_file = glob.glob(f"{model_path}/*/*.pkl")[-1]

    with open(model_file, "rb") as file:
        model = pickle.load(file)


def run(mini_batch: List[str]):
    for file_path in mini_batch:
        data = pd.read_csv(file_path)
        pred = model.predict(data)

        data["prediction"] = pred

        output_file_name = Path(file_path).stem
        output_file_path = os.path.join(output_path, output_file_name + ".parquet")
        data.to_parquet(output_file_path)

    return mini_batch

Comentários:

• Observe como a variável de ambiente AZUREML_BI_OUTPUT_PATH é usada para obter acesso ao caminho de saída do trabalho de implantação.
• A função init() preenche uma variável global chamada output_path, que pode ser usada posteriormente para saber onde gravar.
• O método run retorna uma lista dos arquivos processados. É necessário que a função run retorne um list ou um objeto pandas.DataFrame.

Aviso

Leve em conta que todos os executores de lote têm acesso de gravação a esse caminho ao mesmo tempo. Isso significa que você precisa considerar a simultaneidade. Nesse caso, garanta que cada executor grave seu próprio arquivo, usando o nome do arquivo de entrada como o nome da pasta de saída.

Criar o ponto de extremidade

Agora você cria um ponto de extremidade em lote chamado heart-classifier-batch, onde o modelo é implantado.

1. Decida o nome do ponto de extremidade. O nome do ponto de extremidade aparece no URI associado ao ponto de extremidade, assim, os nomes de ponto de extremidade em lote precisam ser exclusivos em uma região do Azure. Por exemplo, pode haver apenas um ponto de extremidade em lote com o nome mybatchendpoint em westus2.

   CLI do Azure

   Nesse caso, vamos colocar o nome do ponto de extremidade em uma variável para que possamos referenciá-lo facilmente mais tarde.

   ENDPOINT_NAME="heart-classifier-custom"
   

   Python

   Nesse caso, vamos colocar o nome do ponto de extremidade em uma variável para que possamos referenciá-lo facilmente mais tarde.

   endpoint_name = "heart-classifier-custom"

2. Configurar o ponto de extremidade em lote.

   CLI do Azure

   O arquivo YAML a seguir define um ponto de extremidade em lote:

   endpoint.yml

   $schema: https://azuremlschemas.azureedge.net/latest/batchEndpoint.schema.json
   name: heart-classifier-batch
   description: A heart condition classifier for batch inference
   auth_mode: aad_token
   

   Python

   endpoint = BatchEndpoint(
       name=endpoint_name,
       description="A heart condition classifier for batch inference",
   )

3. Criar o ponto de extremidade:

   CLI do Azure

   az ml batch-endpoint create -n $ENDPOINT_NAME -f endpoint.yml
   

   Python

   ml_client.batch_endpoints.begin_create_or_update(endpoint).result()

Criar a implantação

Siga as próximas etapas para criar uma implantação usando o script de pontuação anterior:

1. Primeiro, crie um ambiente em que o script de pontuação possa ser executado:

   CLI do Azure

   Nenhuma etapa adicional é necessária para a CLI do Azure Machine Learning. A definição do ambiente está incluída no arquivo de implantação.

   environment:
     name: batch-mlflow-xgboost
     image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
     conda_file: environment/conda.yaml
   

   Python

   Obtenha uma referência para o ambiente:

   environment = Environment(
       name="batch-mlflow-xgboost",
       conda_file="environment/conda.yaml",
       image="mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest",
   )

2. Crie a implantação. Observe que output_action agora está definido como SUMMARY_ONLY.

   Observação

   Este exemplo pressupõe que você tenha um cluster de computação com o nome batch-cluster. Altere esse nome adequadamente.

   CLI do Azure

   Para criar uma nova implantação no ponto de extremidade criado, crie uma configuração YAML semelhante à seguinte. Você pode verificar o esquema YAML do ponto de extremidade do lote completo para obter propriedades extras.

   $schema: https://azuremlschemas.azureedge.net/latest/modelBatchDeployment.schema.json
   endpoint_name: heart-classifier-batch
   name: classifier-xgboost-custom
   description: A heart condition classifier based on XGBoost and Scikit-Learn pipelines that append predictions on parquet files.
   type: model
   model: azureml:heart-classifier-sklpipe@latest
   environment:
     name: batch-mlflow-xgboost
     image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
     conda_file: environment/conda.yaml
   code_configuration:
     code: code
     scoring_script: batch_driver.py
   compute: azureml:batch-cluster
   resources:
     instance_count: 2
   settings:
     max_concurrency_per_instance: 2
     mini_batch_size: 2
     output_action: summary_only
     retry_settings:
       max_retries: 3
       timeout: 300
     error_threshold: -1
     logging_level: info
   

   Em seguida, crie a implantação com o seguinte comando:

   az ml batch-deployment create --file deployment.yml --endpoint-name $ENDPOINT_NAME --set-default
   

   Python

   Para criar uma nova implantação no ponto de extremidade criado, use o seguinte script:

   deployment = ModelBatchDeployment(
       name="classifier-xgboost-custom",
       description="A heart condition classifier based on XGBoost which writes outputs in parquet format.",
       endpoint_name=endpoint.name,
       model=model,
       environment=environment,
       code_configuration=CodeConfiguration(
           code="code",
           scoring_script="batch_driver.py",
       ),
       compute=compute_name,
       settings=ModelBatchDeploymentSettings(
           mini_batch_size=2,
           instance_count=2,
           max_concurrency_per_instance=2,
           output_action=BatchDeploymentOutputAction.SUMMARY_ONLY,
           retry_settings=BatchRetrySettings(max_retries=3, timeout=300),
           logging_level="info",
       ),
   )

   Em seguida, crie a implantação com o seguinte comando:

   ml_client.batch_deployments.begin_create_or_update(deployment).result()

3. Neste estágio, nosso ponto de extremidade em lotes está pronto para ser usado.

Teste a implantação

Para testar o ponto de extremidade, use um exemplo de dados não rotulados localizados neste repositório, que pode ser usado com o modelo. Os pontos de extremidade do lote só podem processar dados localizados na nuvem e acessíveis a partir do espaço de trabalho do Azure Machine Learning. Neste exemplo, você carrega-o em um armazenamento de dados do Azure Machine Learning. Você criará um ativo de dados que pode ser usado para invocar o ponto de extremidade para pontuação. No entanto, observe que os pontos de extremidade do lote aceitam dados que podem ser colocados em vários tipos de locais.

1. Invoque o ponto de extremidade com os dados de uma conta de armazenamento:

   CLI do Azure

   JOB_NAME = $(az ml batch-endpoint invoke --name $ENDPOINT_NAME --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data --query name -o tsv)
   

   Observação

   O utilitário jq pode não ser instalado em todas as instalações. É possível obter instruções no GitHub.

   Python

   Dica

   Qual é a diferença entre inputs e input quando você invoca um ponto de extremidade?

   Em geral, você pode usar um dicionário inputs = {} com o método invoke para fornecer um número arbitrário de entradas necessárias para um ponto de extremidade em lote que contém uma implantação de modelo ou uma implantação de pipeline.

   Para uma implantação de modelo, você pode usar input como uma maneira mais curta de especificar o local dos dados de entrada para a implantação, já que uma implantação de modelo sempre usa somente uma entrada de dados.

   Configurar as entradas:

   input = Input(
       type=AssetTypes.URI_FOLDER,
       path="https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data",
   )

   Criar um trabalho:

   job = ml_client.batch_endpoints.invoke(
       endpoint_name=endpoint.name, deployment_name=deployment.name, input=input
   )

2. Um trabalho em lote é iniciado assim que o comando retorna. Você pode monitorar o status do trabalho até que ele seja concluído:

   CLI do Azure

   az ml job show -n $JOB_NAME --web
   

   Python

   ml_client.jobs.get(job.name)

Analise as saídas

O trabalho gera uma saída nomeada chamada score onde todos os arquivos gerados são colocados. Como você gravou diretamente no diretório, um arquivo por cada arquivo de entrada, então é possível esperar ter o mesmo número de arquivos. Neste exemplo específico, nomeie os arquivos de saída da mesma forma que as entradas, mas eles têm uma extensão parquet.

Observação

Observe que um arquivo predictions.csv também está incluído na pasta de saída. Esse arquivo contém o resumo dos arquivos processados.

Você pode baixar os resultados do trabalho usando o nome do trabalho:

CLI do Azure

Para baixar as previsões, use o seguinte comando:

az ml job download --name $JOB_NAME --output-name score --download-path ./

Python

ml_client.jobs.download(name=scoring_job.name, download_path=".", output_name="score")

Depois que o arquivo for baixado, você poderá abri-lo usando sua ferramenta favorita. O exemplo a seguir carrega as previsões usando dataframe Pandas.

import pandas as pd
import glob

output_files = glob.glob("named-outputs/score/*.parquet")
score = pd.concat((pd.read_parquet(f) for f in output_files))
score

A saída tem a seguinte aparência:

age	sexo	...	thal	prediction
63	1	...	fixo	0
67	1	...	normal	1
67	1	...	reversible	0
37	1	...	normal	0

Limpar os recursos

CLI do Azure

Execute o código a seguir para excluir o ponto de extremidade em lote e todas as implantações subjacentes. Trabalhos de pontuação em lote não são excluídos.

az ml batch-endpoint delete --name $ENDPOINT_NAME --yes

Python

Execute o código a seguir para excluir o ponto de extremidade em lote e todas as implantações subjacentes. Trabalhos de pontuação em lote não são excluídos.

ml_client.batch_endpoints.begin_delete(endpoint_name).result()

Conteúdo relacionado

• Processamento de imagens com implantações de modelos em lote
• Implantar modelos de idioma em pontos de extremidade em lotes