Personalizar saídas em implantações em lote

APLICA-SE A:Azure CLI ml extension v2 (current)Python SDK azure-ai-ml v2 (current)

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

• Você precisa controlar como as previsões são escritas 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 daquele suportado pronto para uso por implantações em lote.
• Seu modelo é um modelo generativo que não pode escrever 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 que você assuma o controle da saída dos trabalhos, permitindo que você escreva diretamente na saída do trabalho de implantação em lote. Neste tutorial, você aprenderá a implantar um modelo para executar inferência em lote e gravar as saídas no formato parquet anexando as previsões aos dados de entrada originais.

Sobre este exemplo

Este exemplo mostra como você pode implantar um modelo para executar inferência em lote e personalizar como suas previsões são escritas na saída. O modelo é baseado no conjunto de dados de Doença Cardíaca 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ça cardíaca em um paciente. É inteiro valorizado de 0 (sem presença) a 1 (presença).

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

O exemplo neste artigo é baseado em exemplos de código contidos no repositório azureml-examples . Para executar os comandos localmente sem ter que copiar ou colar YAML e outros arquivos, use os seguintes comandos para clonar o repositório e vá para a pasta para sua linguagem de codificação:

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 para este exemplo estão em:

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

Acompanhe em um caderno Jupyter

Há um bloco de anotações Jupyter que você pode usar para seguir este exemplo. No repositório clonado, abra o bloco de anotações chamado custom-output-batch.ipynb.

Pré-requisitos

• Uma subscrição do Azure. Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

• Uma área de trabalho do Azure Machine Learning. Para criar um espaço de trabalho, consulte Gerenciar espaços de trabalho do Azure Machine Learning.

• As seguintes permissões no espaço de trabalho do Azure Machine Learning:

  • Para criar ou gerenciar pontos de extremidade e implantações em lote: use um Proprietário, Colaborador ou função personalizada que tenha recebido as Microsoft.MachineLearningServices/workspaces/batchEndpoints/* permissões.
  • Para criar implantações do Azure Resource Manager no grupo de recursos do espaço de trabalho: use um Proprietário, Colaborador ou função personalizada à qual tenha sido atribuída a Microsoft.Resources/deployments/write permissão no grupo de recursos em que o espaço de trabalho está implantado.

• A CLI do Azure Machine Learning ou o SDK do Azure Machine Learning para Python:

  CLI do Azure

  Execute o seguinte comando para instalar a CLI do Azure e a extensão para o ml Azure Machine Learning:

  az extension add -n ml
  

  As implantações de componentes de pipeline para pontos de extremidade em lote são introduzidas na versão 2.7 da ml extensão para a CLI do Azure. Use o az extension update --name ml comando para obter a versão mais recente.

  Python

  Execute o seguinte comando para instalar o SDK do Azure Machine Learning para Python:

  pip install azure-ai-ml
  

  As ModelBatchDeployment classes e PipelineComponentBatchDeployment são introduzidas na versão 1.7.0 do SDK. Use o pip install -U azure-ai-ml comando para obter a versão mais recente.

---

Ligar à sua área de trabalho

O espaço de trabalho é 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 quando usa o Azure Machine Learning. Nesta seção, você se conecta ao espaço de trabalho onde executa suas tarefas de implantação.

CLI do Azure

No comando a seguir, insira sua ID de assinatura, nome do espaço de trabalho, nome do grupo de recursos e local:

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 obtenha um identificador para o espaço de trabalho:

   No comando a seguir, insira a ID da assinatura, o nome do grupo de recursos e o nome do espaço de trabalho:

   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 gravar diretamente na pasta de saída do trabalho de implantação em lote. A implantação usa esse recurso para escrever arquivos de parquet personalizados.

Registar o modelo

Você só pode implantar 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 no espaço de trabalho. Você pode pular esta 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

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

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

código/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

Observações:

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

Aviso

Leve em consideração que todos os executores em lote têm acesso de gravação a esse caminho ao mesmo tempo. Isso significa que você precisa levar em conta a simultaneidade. Nesse caso, certifique-se de que cada executor escreva 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 seu ponto de extremidade, portanto , os nomes de ponto de extremidade em lote precisam ser exclusivos dentro de 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, coloque o nome do ponto de extremidade em uma variável para que você possa facilmente consultá-lo mais tarde.

   ENDPOINT_NAME="heart-classifier-custom"
   

   Python

   Nesse caso, coloque o nome do ponto de extremidade em uma variável para que você possa facilmente consultá-lo mais tarde.

   endpoint_name = "heart-classifier-custom"

2. Configure seu ponto de extremidade em lote.

   CLI do Azure

   O seguinte arquivo YAML 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. Crie 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 onde o script de pontuação possa ser executado:

   CLI do Azure

   Nenhuma etapa extra é necessária para a CLI do Azure Machine Learning. A definição de 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 ao 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.

   Nota

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

   CLI do Azure

   Para criar uma nova implantação sob o ponto de extremidade criado, crie uma configuração YAML como a seguinte. Você pode verificar o esquema YAML do ponto de extremidade de 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 sob o 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 ponto, nosso ponto de extremidade em lote está pronto para ser usado.

Testar a implementação

Para testar seu endpoint, use uma amostra de dados não rotulados localizados neste repositório, que podem ser usados com o modelo. Os pontos de extremidade em 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ê o carrega em um repositório de dados do Azure Machine Learning. Você vai 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 em lote aceitam dados que podem ser colocados em vários tipos de locais.

1. Invoque o ponto de extremidade com 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)
   

   Nota

   O utilitário jq pode não estar instalado em todas as instalações. Você pode obter instruções no GitHub.

   Python

   Gorjeta

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

   Em geral, você pode usar um parâmetro de dicionário inputs = {} com o invoke método 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 o input parâmetro como uma maneira mais curta de especificar o local dos dados de entrada para a implantação. Essa abordagem funciona porque uma implantação de modelo sempre usa apenas uma entrada de dados.

   Configure as entradas:

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

   Criar um emprego:

   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 termine:

   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ê escreveu no diretório diretamente, um arquivo por cada arquivo de entrada, então você pode esperar ter o mesmo número de arquivos. Neste exemplo em particular, nomeie os arquivos de saída da mesma forma que as entradas, mas eles têm uma extensão parquet.

Nota

Observe que um predictions.csv de arquivo também está incluído na pasta de saída. Este ficheiro contém o resumo dos ficheiros 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")

Uma vez que o arquivo é baixado, você pode abri-lo usando sua ferramenta favorita. O exemplo a seguir carrega as previsões usando Pandas dataframe.

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:

idade	sexo	...	Thal	previsão
63	1	...	fixo	0
67	1	...	normal	1
67	1	...	reversível	0
37	1	...	normal	0

Clean up resources (Limpar recursos)

CLI do Azure

Execute o código a seguir para excluir o ponto de extremidade em lote e todas as implantações subjacentes. Os 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. Os trabalhos de pontuação em lote não são excluídos.

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

Conteúdos relacionados

• Processamento de imagem com implantações de modelo em lote
• Implantar modelos de linguagem em pontos de extremidade em lote