Implantar modelos MLflow em implantações em lote

  • Artigo

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

Neste artigo, saiba como implantar modelos MLflow no Azure Machine Learning para inferência em lote usando pontos de extremidade em lote. Ao implantar modelos MLflow em pontos de extremidade em lote, o Azure Machine Learning:

  • Fornece uma imagem base MLflow/ambiente curado que contém as dependências necessárias para executar um trabalho em lote do Azure Machine Learning.
  • Cria um pipeline de trabalho em lote com um script de pontuação para você que pode ser usado para processar dados usando paralelização.

Nota

Para obter mais informações sobre os tipos de arquivo de entrada suportados e detalhes sobre como o modelo MLflow funciona, consulte Considerações ao implantar na inferência em lote.

Sobre este exemplo

Este exemplo mostra como você pode implantar um modelo MLflow em um ponto de extremidade de lote para executar previsões em lote. Este exemplo usa um modelo MLflow baseado no UCI Heart Disease Data set. O banco de dados contém 76 atributos, mas estamos usando 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/colar YAML e outros arquivos, primeiro clone o repositório e, em seguida, altere os diretórios para a pasta:

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

Os arquivos para este exemplo estão em:

cd endpoints/batch/deploy-models/heart-classifier-mlflow

Acompanhe em Jupyter Notebooks

Pode acompanhar este exemplo nos seguintes blocos de notas. No repositório clonado, abra o bloco de anotações: mlflow-for-batch-tabular.ipynb.

Pré-requisitos

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

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

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

  • Verifique se você tem as seguintes permissões no espaço de trabalho:

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

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

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

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

    az extension add -n ml

    Nota

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

Ligar à sua área de trabalho

A área de trabalho é o recurso de nível superior do Azure Machine Learning que proporciona um local centralizado para trabalhar com todos os artefactos que cria quando utiliza o Azure Machine Learning. Nesta seção, nos conectaremos ao espaço de trabalho no qual você executará tarefas de implantação.

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

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

Passos

Siga estas etapas para implantar um modelo MLflow em um ponto de extremidade de lote para executar inferência em lote sobre novos dados:

  1. O Batch Endpoint só pode implantar modelos registrados. Nesse caso, já temos uma cópia local do modelo no repositório, então só precisamos 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.

    MODEL_NAME='heart-classifier-mlflow'
az ml model create --name $MODEL_NAME --type "mlflow_model" --path "model"

  2. Antes de avançar, precisamos garantir que as implantações em lote que estamos prestes a criar possam ser executadas em alguma infraestrutura (computação). As implantações em lote podem ser executadas em qualquer computação do Azure Machine Learning que já exista no espaço de trabalho. Isso significa que várias implantações em lote podem compartilhar a mesma infraestrutura de computação. Neste exemplo, vamos trabalhar em um cluster de computação do Azure Machine Learning chamado cpu-cluster. Vamos verificar se a computação existe no espaço de trabalho ou criá-la de outra forma.

    Crie um cluster de computação da seguinte maneira:

    az ml compute create -n batch-cluster --type amlcompute --min-instances 0 --max-instances 5

  3. Agora é hora de criar o ponto de extremidade e a implantação em lote. Vamos começar com o ponto de extremidade primeiro. Os pontos de extremidade exigem apenas um nome e uma descrição para serem criados. O nome do ponto de extremidade terminará no URI associado ao seu ponto de extremidade. Por isso, 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.

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

    ENDPOINT_NAME="heart-classifier"

  4. Crie o ponto de extremidade:

    Para criar um novo ponto de extremidade, crie uma YAML configuração como a seguinte:

    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

    Em seguida, crie o ponto de extremidade com o seguinte comando:

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

  5. Agora, vamos criar a implantação. Os modelos MLflow não exigem que você indique um ambiente ou um script de pontuação ao criar as implantações à medida que ele é criado para você. No entanto, você pode especificá-los se quiser personalizar como a implantação faz inferência.

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

    implantação-simples/deployment.yml

    $schema: https://azuremlschemas.azureedge.net/latest/modelBatchDeployment.schema.json
endpoint_name: heart-classifier-batch
name: classifier-xgboost-mlflow
description: A heart condition classifier based on XGBoost
type: model
model: azureml:heart-classifier-mlflow@latest
compute: azureml:batch-cluster
resources:
  instance_count: 2
settings:
  max_concurrency_per_instance: 2
  mini_batch_size: 2
  output_action: append_row
  output_file_name: predictions.csv
  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-simple/deployment.yml --endpoint-name $ENDPOINT_NAME --set-default

    Importante

    Configure timeout em sua implantação com base em quanto tempo leva para seu modelo executar a inferência em um único lote. Quanto maior for o tamanho do lote, mais longo terá de ser este valor. Remeber que mini_batch_size indica o número de arquivos em um lote, não o número de amostras. Ao trabalhar com dados tabulares, cada arquivo pode conter várias linhas, o que aumentará o tempo necessário para o ponto de extremidade em lote processar cada arquivo. Use valores altos nesses casos para evitar erros de tempo limite.

  6. Embora você possa invocar uma implantação específica dentro de um ponto de extremidade, geralmente desejará invocar o próprio ponto de extremidade e permitir que o ponto de extremidade decida qual implantação usar. Essa implantação é chamada de implantação "padrão". Isso lhe dá a possibilidade de alterar a implantação padrão e, portanto, alterar o modelo que serve a implantação sem alterar o contrato com o usuário invocando o ponto de extremidade. Use as seguintes instruções para atualizar a implantação padrão:

    DEPLOYMENT_NAME="classifier-xgboost-mlflow"
az ml batch-endpoint update --name $ENDPOINT_NAME --set defaults.deployment_name=$DEPLOYMENT_NAME

  7. Neste ponto, nosso ponto de extremidade em lote está pronto para ser usado.

Testando a implantação

Para testar nosso endpoint, vamos usar uma amostra de dados não rotulados localizados neste repositório e 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, vamos carregá-lo em um repositório de dados do Azure Machine Learning. Particularmente, vamos 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 locais.

  1. Vamos criar o ativo de dados primeiro. Esse ativo de dados consiste em uma pasta com vários arquivos CSV que queremos processar em paralelo usando pontos de extremidade em lote. Você pode pular esta etapa se seus dados já estiverem registrados como um ativo de dados ou se você quiser usar um tipo de entrada diferente.

    a. Crie uma definição de ativo de dados em YAML:

    heart-dataset-unlabeled.yml

    $schema: https://azuremlschemas.azureedge.net/latest/data.schema.json
name: heart-dataset-unlabeled
description: An unlabeled dataset for heart classification.
type: uri_folder
path: data

    b. Crie o ativo de dados:

    az ml data create -f heart-dataset-unlabeled.yml

  2. Agora que os dados estão carregados e prontos para serem usados, vamos invocar o ponto de extremidade:

    JOB_NAME = $(az ml batch-endpoint invoke --name $ENDPOINT_NAME --input azureml:heart-dataset-unlabeled@latest --query name -o tsv)

    Nota

    O utilitário jq pode não ser instalado em todas as instalações. Você pode obter instruções de instalação neste link.

    Gorjeta

    Observe como não estamos indicando o nome da implantação na operação invoke. Isso ocorre porque o ponto de extremidade roteia automaticamente o trabalho para a implantação padrão. Como nosso endpoint tem apenas uma implantação, essa é a padrão. Você pode direcionar uma implantação específica indicando o argumento/parâmetro deployment_name.

  3. Um trabalho em lote é iniciado assim que o comando retorna. Você pode monitorar o status do trabalho até que ele termine:

    az ml job show -n $JOB_NAME --web

Analisando as saídas

As previsões de saída são geradas no predictions.csv arquivo conforme indicado na configuração de implantação. O trabalho gera uma saída nomeada chamada score onde esse arquivo é colocado. Apenas um arquivo é gerado por trabalho em lote.

O ficheiro está estruturado da seguinte forma:

  • Há uma linha por cada ponto de dados que foi enviado para o modelo. Para dados tabulares, isso significa que o arquivo (predictions.csv) contém uma linha para cada linha presente em cada um dos arquivos processados. Para outros tipos de dados (por exemplo, imagens, áudio, texto), há uma linha por cada arquivo processado.

  • As seguintes colunas estão no arquivo (em ordem):

    • row (opcional), o índice de linha correspondente no arquivo de dados de entrada. Isso só se aplica se os dados de entrada forem tabulares. As previsões são retornadas na mesma ordem em que aparecem no arquivo de entrada para que você possa confiar no número da linha para corresponder à previsão correspondente.
    • prediction, a previsão associada aos dados de entrada. Este valor é retornado "no estado em que se encontra" e foi fornecido pela função do predict(). modelo.
    • file_name, o nome do ficheiro a partir do qual os dados foram lidos. Em dados tabulares, use este campo para saber qual previsão pertence a quais dados de entrada.

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

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

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

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

score = pd.read_csv(
    "named-outputs/score/predictions.csv", names=["row", "prediction", "file"]
)

A saída tem a seguinte aparência:

row previsão ficheiro
0 0 heart-unlabeled-0.csv
1 1 heart-unlabeled-0.csv
2 0 heart-unlabeled-0.csv
... ... ...
307 0 heart-unlabeled-3.csv

Gorjeta

Observe que, neste exemplo, os dados de entrada eram dados tabulares em CSV formato e havia 4 arquivos de entrada diferentes (heart-unlabeled-0.csv, heart-unlabeled-1.csv, heart-unlabeled-2.csv e heart-unlabeled-3.csv).

Considerações ao implantar na inferência em lote

O Azure Machine Learning dá suporte à implantação de modelos MLflow em pontos de extremidade em lote sem indicar um script de pontuação. Isso representa uma maneira conveniente de implantar modelos que exigem o processamento de grandes quantidades de dados em lote. O Azure Machine Learning usa informações na especificação do modelo MLflow para orquestrar o processo de inferência.

Como é distribuído o trabalho dos trabalhadores

Os pontos de extremidade em lote distribuem o trabalho no nível do arquivo, para dados estruturados e não estruturados. Como consequência, apenas arquivos URI e pastas URI são suportados para esse recurso. Cada trabalhador processa lotes de Mini batch size arquivos de cada vez. Para dados tabulares, os pontos de extremidade em lote não levam em conta o número de linhas dentro de cada arquivo ao distribuir o trabalho.

Aviso

As estruturas de pastas aninhadas não são exploradas durante a inferência. Se você estiver particionando seus dados usando pastas, certifique-se de nivelar a estrutura antes.

As implantações em lote chamarão a predict função do modelo MLflow uma vez por arquivo. Para arquivos CSV contendo várias linhas, isso pode impor uma pressão de memória na computação subjacente e pode aumentar o tempo necessário para o modelo marcar um único arquivo (especialmente para modelos caros, como modelos de linguagem grande). Se você encontrar várias exceções de falta de memória ou entradas de tempo limite em logs, considere dividir os dados em arquivos menores com menos linhas ou implementar o processamento em lote no nível da linha dentro do script de modelo/pontuação.

Suporte a tipos de arquivo

Os seguintes tipos de dados são suportados para inferência em lote ao implantar modelos MLflow sem um ambiente e um script de pontuação. Se você gosta de processar um tipo de arquivo diferente ou executar inferência de uma maneira diferente que os pontos de extremidade em lote fazem por padrão, você sempre pode criar a implantação com um script de pontuação, conforme explicado em Usando modelos MLflow com um script de pontuação.

Extensão de nome de ficheiro Tipo retornado como entrada do modelo Requisito de assinatura
.csv, .parquet, .pqt pd.DataFrame ColSpec. Se não for fornecida, a digitação de colunas não será imposta.
.png, .jpg, .jpeg, .tiff, .bmp, .gif np.ndarray TensorSpec. A entrada é remodelada para corresponder à forma dos tensores, se disponível. Se nenhuma assinatura estiver disponível, tensores do tipo np.uint8 são inferidos. Para obter orientações adicionais, leia Considerações sobre modelos MLflow que processam imagens.

Aviso

Esteja ciente de que qualquer arquivo não suportado que possa estar presente nos dados de entrada fará com que o trabalho falhe. Você verá uma entrada de erro da seguinte forma: "ERROR:azureml:Error processing input file: '/mnt/batch/tasks/.../a-given-file.avro'. O tipo de ficheiro 'avro' não é suportado.".

Aplicação de assinatura para modelos MLflow

Os tipos de dados de entrada são impostos por trabalhos de implantação em lote durante a leitura dos dados usando a assinatura de modelo MLflow disponível. Isto significa que a sua introdução de dados deve estar em conformidade com os tipos indicados na assinatura do modelo. Se os dados não puderem ser analisados conforme o esperado, o trabalho falhará com uma mensagem de erro semelhante à seguinte: "ERROR:azureml:Error processing input file: '/mnt/batch/tasks/.../a-given-file.csv'. Exceção: literal inválido para int() com base 10: 'value'".

Gorjeta

As assinaturas em modelos MLflow são opcionais, mas são altamente encorajadas, pois fornecem uma maneira conveniente de detetar problemas de compatibilidade de dados antecipadamente. Para obter mais informações sobre como registrar modelos com assinaturas, leia Registrando modelos com uma assinatura, ambiente ou exemplos personalizados.

Você pode inspecionar a assinatura do modelo abrindo o arquivo associado ao MLmodel modelo MLflow. Para obter mais detalhes sobre como as assinaturas funcionam no MLflow, consulte Assinaturas no MLflow.

Suporte de sabor

As implantações em lote suportam apenas a implantação de modelos MLflow com um pyfunc sabor. Se você precisar implantar um tipo diferente, consulte Usando modelos MLflow com um script de pontuação.

Personalizando implantações de modelos MLflow com um script de pontuação

Os modelos MLflow podem ser implantados em pontos de extremidade em lote sem indicar um script de pontuação na definição de implantação. No entanto, você pode optar por indicar esse arquivo (geralmente chamado de driver em lote) para personalizar como a inferência é executada.

Normalmente, você selecionará esse fluxo de trabalho quando:

  • Você precisa processar um tipo de arquivo não suportado por implantações em lote implantações MLflow.
  • Você precisa personalizar a maneira como o modelo é executado, por exemplo, usar um sabor específico para carregá-lo com mlflow.<flavor>.load().
  • Você precisa fazer o processamento pré/pos em sua rotina de pontuação quando não é feito pelo próprio modelo.
  • A saída do modelo não pode ser bem representada em dados tabulares. Por exemplo, é um tensor que representa uma imagem.
  • O modelo não pode processar cada arquivo de uma só vez devido a restrições de memória e precisa lê-lo em partes.

Importante

Se você optar por indicar um script de pontuação para uma implantação de modelo MLflow, também terá que especificar o ambiente onde a implantação será executada.

Passos

Use as etapas a seguir para implantar um modelo MLflow com um script de pontuação personalizado.

  1. Identifique a pasta onde seu modelo MLflow está colocado.

    a. Vá para o portal do Azure Machine Learning.

    b. Vá para a seção Modelos.

    c. Selecione o modelo que você está tentando implantar e clique na guia Artefatos.

    d. Anote a pasta que é exibida. Esta pasta foi indicada quando o modelo foi registado.

    Captura de tela mostrando a pasta onde os artefatos de modelo são colocados.

  2. Crie um script de pontuação. Observe como o nome model da pasta que você identificou antes foi incluído na init() função.

    deployment-custom/código/batch_driver.py

    # Copyright (c) Microsoft. All rights reserved.
# Licensed under the MIT license.

import os
import glob
import mlflow
import pandas as pd
import logging


def init():
    global model
    global model_input_types
    global model_output_names

    # 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
    model_path = glob.glob(os.environ["AZUREML_MODEL_DIR"] + "/*/")[0]

    # Load the model, it's input types and output names
    model = mlflow.pyfunc.load(model_path)
    if model.metadata and model.metadata.signature:
        if model.metadata.signature.inputs:
            model_input_types = dict(
                zip(
                    model.metadata.signature.inputs.input_names(),
                    model.metadata.signature.inputs.pandas_types(),
                )
            )
        if model.metadata.signature.outputs:
            if model.metadata.signature.outputs.has_input_names():
                model_output_names = model.metadata.signature.outputs.input_names()
            elif len(model.metadata.signature.outputs.input_names()) == 1:
                model_output_names = ["prediction"]
    else:
        logging.warning(
            "Model doesn't contain a signature. Input data types won't be enforced."
        )


def run(mini_batch):
    print(f"run method start: {__file__}, run({len(mini_batch)} files)")

    data = pd.concat(
        map(
            lambda fp: pd.read_csv(fp).assign(filename=os.path.basename(fp)), mini_batch
        )
    )

    if model_input_types:
        data = data.astype(model_input_types)

    # Predict over the input data, minus the column filename which is not part of the model.
    pred = model.predict(data.drop("filename", axis=1))

    if pred is not pd.DataFrame:
        if not model_output_names:
            model_output_names = ["pred_col" + str(i) for i in range(pred.shape[1])]
        pred = pd.DataFrame(pred, columns=model_output_names)

    return pd.concat([data, pred], axis=1)

  3. Vamos criar um ambiente onde o script de pontuação possa ser executado. Como nosso modelo é MLflow, os requisitos de conda também são especificados no pacote de modelo (para obter mais detalhes sobre os modelos MLflow e os arquivos incluídos nele, consulte O formato MLmodel). Vamos então construir o ambiente usando as dependências conda do arquivo. No entanto, também precisamos incluir o pacote azureml-core que é necessário para implantações em lote.

    Gorjeta

    Se o seu modelo já estiver registado no registo do modelo, pode transferir/copiar o ficheiro associado ao conda.yml seu modelo acedendo a Azure Machine Learning studio> Models > Selecione o seu modelo na lista > Artefactos. Abra a pasta raiz na navegação e selecione o conda.yml arquivo listado. Clique em Download ou copie seu conteúdo.

    Importante

    Este exemplo usa um ambiente conda especificado em /heart-classifier-mlflow/environment/conda.yaml. Este arquivo foi criado combinando o arquivo de dependências conda MLflow original e adicionando o pacote azureml-core. Não é possível usar o conda.yml arquivo do modelo diretamente.

    A definição de ambiente será incluída na própria definição de implantação como um ambiente anônimo. Você verá nas seguintes linhas na implantação:

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

  4. Configure a implantação:

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

    Implantação-Custom/deployment.yml

    $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
type: model
model: azureml:heart-classifier-mlflow@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: append_row
  output_file_name: predictions.csv
  retry_settings:
    max_retries: 3
    timeout: 300
  error_threshold: -1
  logging_level: info

  5. Vamos criar a implantação agora:

    az ml batch-deployment create --file deployment-custom/deployment.yml --endpoint-name $ENDPOINT_NAME

  6. Neste ponto, nosso ponto de extremidade em lote está pronto para ser usado.

Clean up resources (Limpar recursos)

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 serão excluídos.

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

Próximos passos