Personalizar saídas em implantações em lote

Artigo
09/03/2024

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
Python

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

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

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. Para criar um workspace, confira Gerenciar workspaces do Azure Machine Learning.
Certifique-se de que você tenha as seguintes permissões no espaço de trabalho do Machine Learning:
- Criar ou gerenciar implantações e pontos de extremidade em lote: use uma função de Proprietário, Colaborador ou Personalizada que permita Microsoft.MachineLearningServices/workspaces/batchEndpoints/*.
- Crie implantações do Azure Resource Manager 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 onde o espaço de trabalho está implantado.
Instale o seguinte software para trabalhar com o Machine Learning:
- CLI do Azure
- Python
Execute o seguinte comando para instalar a CLI do Azure e a extensão do Azure Machine Learning ml:
```
az extension add -n ml
```
As implantações de componente de pipeline para pontos de extremidade do Lote são introduzidas na versão 2.7 da extensão ml da CLI do Azure. Use o comando az extension update --name ml para obter a versão mais recente.
Execute o seguinte comando para instalar o SDK do Azure Machine Learning para Python:
```
pip install azure-ai-ml
```
As classes ModelBatchDeployment e PipelineComponentBatchDeployment são introduzidas na versão 1.7.0 do SDK. Use o comando pip install -U azure-ai-ml para obter a versão mais recente.

Conectar-se ao workspace

O workspace é o recurso de nível superior do Machine Learning. Ele fornece um local centralizado para trabalhar com todos os artefatos criados ao usar o Machine Learning. Nesta seção, você se conecta ao workspace em que executa as suas tarefas de implantação.

CLI do Azure
Python

No comando a seguir, insira os valores para a sua ID de assinatura, workspace, local e grupo de recursos:

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

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

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

No comando a seguir, insira os valores para sua ID de assinatura, espaço de trabalho e grupo de recursos:

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
Python

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

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:

Lê os dados de entrada como arquivos CSV.
Executa uma função predict de modelo MLflow nos dados de entrada.
Acrescenta as previsões a um conjunto pandas.DataFrame com os dados de entrada.
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.

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
- 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"
```
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"
```

Configurar o ponto de extremidade em lote.

CLI do Azure
Python

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

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

Criar o ponto de extremidade:

CLI do Azure
Python

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

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:

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

CLI do Azure
Python

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

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",
)

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
Python

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

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()

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.

Invoque o ponto de extremidade com os dados de uma conta de armazenamento:
- CLI do Azure
- Python
```
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.
Dica

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

Em geral, você pode usar um parâmetro inputs = {} de dicionário 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 o parâmetro input como uma maneira mais curta de especificar o local de dados de entrada para a implantação. Essa abordagem funciona porque uma implantação de modelo sempre aceita apenas 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
)
```
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
- Python
```
az ml job show -n $JOB_NAME --web
```
```
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
Python

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

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

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

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

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()

Compartilhar via

Personalizar saídas em implantações em lote

Sobre este exemplo

Acompanhe em um notebook do Jupyter

Pré-requisitos

Conectar-se ao workspace

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

Registre o modelo

Criar um script de pontuação

Criar o ponto de extremidade

Criar a implantação

Teste a implantação

Analise as saídas

Limpar os recursos

Comentários

Recursos adicionais

Compartilhar via

Personalizar saídas em implantações em lote

Sobre este exemplo

Acompanhe em um notebook do Jupyter

Pré-requisitos

Conectar-se ao workspace

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

Registre o modelo

Criar um script de pontuação

Criar o ponto de extremidade

Criar a implantação

Teste a implantação

Analise as saídas

Limpar os recursos

Conteúdo relacionado

Comentários

Recursos adicionais