Compartir vía

Personalización de salidas en implementaciones por lotes

  • Artículo

SE APLICA A:Extensión ML de la CLI de Azure v2 (actual)SDK de Python azure-ai-ml v2 (actual)

En esta guía se explica cómo crear implementaciones que generen salidas y archivos personalizados. A veces, se necesita más control sobre lo que se escribe como salida de los trabajos de inferencia por lotes. Entre estos casos, figuran los siguientes situaciones:

  • Necesita controlar cómo se escriben las predicciones en la salida. Por ejemplo, desea anexar la predicción a los datos originales si los datos son tabulares.
  • Debe escribir las predicciones en un formato de archivo diferente del que admiten de forma predefinida las implementaciones por lotes.
  • El modelo es un modelo generativo que no puede escribir la salida en un formato tabular. Por ejemplo, los modelos que generan imágenes como salidas.
  • El modelo genera varios archivos tabulares en lugar de uno único. Por ejemplo, los modelos que realizan la previsión teniendo en cuenta varios escenarios.

Las implementaciones por lotes permiten tomar el control de la salida de los trabajos al permitirle escribir directamente en la salida del trabajo de implementación por lotes. En este tutorial, aprenderá a implementar un modelo para realizar la inferencia por lotes y escribir las salidas en formato parquet anexando las predicciones a los datos de entrada originales.

Acerca de este ejemplo

En este ejemplo se muestra cómo puede implementar un modelo para realizar la inferencia por lotes y personalizar cómo se escriben las predicciones en la salida. El modelo se basa en el conjunto de datos sobre enfermedades cardiacas de la UCI. La base de datos contiene 76 atributos, pero en este ejemplo se usa un subconjunto de 14 de ellos. El modelo intenta predecir la presencia de enfermedades cardíacas en un paciente. Es un entero cuyo valor es 0 (sin presencia) o 1 (presencia).

El modelo se entrenó mediante un clasificador de XGBBoost y todo el preprocesamiento necesario se empaquetó en forma de canalización de scikit-learn, convirtiendo este modelo en una canalización de un extremo a otro que pasa de los datos sin procesar a las predicciones.

El ejemplo de este artículo se basa en ejemplos de código incluidos en el repositorio azureml-examples. Para ejecutar los comandos de forma local sin tener que copiar/pegar YAML y otros archivos, primero clona el repositorio y luego cambia los directorios a la carpeta:

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

Los archivos de este ejemplo están en:

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

Seguimiento en un cuaderno de Jupyter

Hay un cuaderno de Jupyter que se puede usar para seguir este ejemplo. En el repositorio clonado, abra el cuaderno llamado custom-output-batch.ipynb.

Requisitos previos

Antes de seguir los pasos de este artículo, asegúrese de que tiene los siguientes requisitos previos:

  • Suscripción a Azure. Si no tiene una suscripción de Azure, cree una cuenta gratuita antes de empezar. Pruebe la versión gratuita o de pago de Azure Machine Learning.

  • Un área de trabajo de Azure Machine Learning. Si no tiene una, siga los pasos descritos en el artículo Administración de áreas de trabajo de Azure Machine Learning para crear una.

  • Asegúrese de tener los permisos siguientes en el área de trabajo:

    • Crear o administrar implementaciones y puntos de conexión por lotes: use los roles de propietario, colaborador o un rol personalizado que permita Microsoft.MachineLearningServices/workspaces/batchEndpoints/*.

    • Crear implementaciones de ARM en el grupo de recursos del área de trabajo: use los roles de propietario, colaborador o un rol personalizado que permita Microsoft.Resources/deployments/write en el grupo de recursos donde se implemente el área de trabajo.

  • Debe instalar el siguiente software para trabajar con Azure Machine Learning:

    La CLI de Azure y la mlextensión para Azure Machine Learning.

    az extension add -n ml

    Nota

    Las implementaciones de componentes de canalización para puntos de conexión de Batch se introdujeron en la versión 2.7 de la extensión ml para la CLI de Azure. Use az extension update --name ml para obtener la última versión.

Conexión con su área de trabajo

El área de trabajo es el recurso de nivel superior para Azure Machine Learning, que proporciona un lugar centralizado para trabajar con todos los artefactos que crea al usar Azure Machine Learning. En esta sección, nos conectaremos al área de trabajo en la que realizará las tareas de implementación.

Pasa los valores del id. de suscripción, el área de trabajo, la ubicación y el grupo de recursos en el código siguiente:

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

Creación de una implementación por lotes con una salida personalizada

En este ejemplo, creará una implementación que pueda escribir directamente en la carpeta de salida del trabajo de implementación por lotes. La implementación usa esta característica para escribir archivos parquet personalizados.

Registro del modelo

Solo se pueden implementar modelos registrados mediante un punto de conexión por lotes. En este ejemplo, ya tiene una copia local del modelo en el repositorio, por lo que solo necesita publicar el modelo en el registro del área de trabajo. Puede omitir este paso si el modelo que está intentando implementar ya está registrado.

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

Crear un script de puntuación

Es necesario crear un script de puntuación que pueda leer los datos de entrada proporcionados por la implementación por lotes y devolver las puntuaciones del modelo. También escribirá directamente en la carpeta de salida del trabajo. En resumen, el script de puntuación propuesto hace lo siguiente:

  1. Lee los datos de entrada como archivos .csv.
  2. Ejecuta una función de modelo predict de MLflow sobre los datos de entrada.
  3. Anexa las predicciones a pandas.DataFrame junto con los datos de entrada.
  4. Escribe los datos en un archivo denominado como archivo de entrada, pero en 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

Observaciones:

  • Observe cómo se usa la variable de entorno AZUREML_BI_OUTPUT_PATH para obtener acceso a la ruta de acceso de salida del trabajo de implementación.
  • La función init() rellena una variable global denominada output_path que se puede usar más adelante para saber dónde escribir.
  • El método run devuelve una lista de los archivos procesados. Es necesario que la función run devuelva un objeto list o pandas.DataFrame.

Advertencia

Tenga en cuenta que todos los ejecutores por lotes tienen acceso de escritura a esta ruta de acceso al mismo tiempo. Esto significa que debe tener en cuenta la simultaneidad. En este caso, asegúrese de que cada ejecutor escriba su propio archivo usando el nombre del archivo de entrada como nombre de la carpeta de salida.

Creación del punto de conexión

Ahora creará un punto de conexión por lotes denominado heart-classifier-batch donde se implementa el modelo.

  1. Decida el nombre del punto de conexión. El nombre del punto de conexión aparece en el URI asociado al punto de conexión, por lo que los nombres de punto de conexión por lotes deberán ser únicos dentro de una región de Azure. Por ejemplo, solo puede haber un punto de conexión por lotes con el nombre mybatchendpoint en westus2.

    En este caso, coloque el nombre del punto de conexión en una variable para poder hacer referencia a el más adelante.

    ENDPOINT_NAME="heart-classifier-custom"

  2. Configuración del punto de conexión por lotes.

    El siguiente archivo YAML define un punto de conexión por lotes:

    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

  3. Creación del punto de conexión:

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

Creación de la implementación

Siga los pasos siguientes para crear una implementación mediante el script de puntuación anterior:

  1. En primer lugar, cree un entorno donde se pueda ejecutar el script de puntuación:

    No se requiere ningún paso adicional para la CLI de Azure Machine Learning. La definición del entorno se incluye en el archivo de implementación.

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

  2. Cree la implementación. Observe que output_action ahora está establecido en SUMMARY_ONLY.

    Nota:

    En este ejemplo se supone que dispone de un clúster de proceso denominado batch-cluster. Cambie ese nombre como corresponda.

    Para crear una nueva implementación en el punto de conexión creado, cree una configuración de YAML como la siguiente. Puede comprobar el esquema YAML del punto de conexión por lotes completo para obtener propiedades adicionales.

    $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

    Después, cree la implementación con el siguiente comando:

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

  3. En este momento, nuestro punto de conexión por lotes está listo para usarse.

Prueba de la implementación

Para probar el punto de conexión, use un ejemplo de datos sin etiquetar ubicados en este repositorio que se puedan usar con el modelo. Los puntos de conexión por lotes solo pueden procesar los datos que se encuentren en la nube y que sean accesibles desde el área de trabajo de Azure Machine Learning. En este ejemplo, lo cargará en un almacén de datos de Azure Machine Learning. Creará un recurso de datos que se pueda usar para invocar el punto de conexión para la puntuación. Sin embargo, tenga en cuenta que los puntos de conexión por lotes aceptan datos que se pueden colocar en varios tipos de ubicaciones.

  1. Invoque el punto de conexión con los datos de una cuenta de almacenamiento:

    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:

    Es posible que la utilidad jq no esté instalada en todas las instalaciones. Puede obtener instrucciones en GitHub.

  2. Se inicia un trabajo por lotes tan pronto como el comando vuelve. Puede supervisar el estado del trabajo hasta que finalice:

    az ml job show -n $JOB_NAME --web

Analice las salidas

El trabajo genera una salida con nombre denominada score, donde se colocan todos los archivos generados. Como escribió directamente en el directorio, un archivo por cada archivo de entrada, puede esperar tener el mismo número de archivos. En este ejemplo concreto, asigne un nombre a los archivos de salida que sea igual que el de las entradas, pero con una extensión parquet.

Nota:

Observe que un archivo predictions.csv también se incluye en la carpeta de salida. Este archivo contiene el resumen de los archivos procesados.

Puede descargar los resultados del trabajo con el nombre del trabajo:

Use los siguientes comandos para descargar las predicciones:

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

Una vez descargado el archivo, puede abrirlo con su herramienta favorita. En el ejemplo siguiente se cargan las predicciones mediante el dataframe de 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

La salida tiene el siguiente aspecto:

age sex ... thal prediction
63 1 ... fijo 0
67 1 ... normal 1
67 1 ... reversible 0
37 1 ... normal 0

Limpieza de recursos

Ejecute el código siguiente para eliminar el punto de conexión por lotes y todas las implementaciones subyacentes. Los trabajos de puntuación por lotes no se eliminan.

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

Contenido relacionado