Uso de puntos de conexión por lotes (versión preliminar) para la puntuación por lotes

Aprenda a usar puntos de conexión por lotes (versión preliminar) para realizar la puntuación por lotes. Los puntos de conexión por lotes simplifican el proceso de hospedar los modelos para la puntuación por lotes, por lo que puede centrarse en el aprendizaje automático y dejar a un lado la infraestructura. Para más información, consulte ¿Qué son los puntos de conexión de Azure Machine Learning (versión preliminar)?.

En este artículo, aprenderá a realizar las siguientes tareas:

Prerrequisitos

• Debe tener una suscripción a Azure para usar Azure Machine Learning. Si no tiene una suscripción de Azure, cree una cuenta gratuita antes de empezar. Pruebe hoy mismo la versión gratuita o de pago de Azure Machine Learning.

• Instale la CLI de Azure y la extensión ml. Siga los pasos de instalación de Instalación, configuración y uso de la CLI (v2) (versión preliminar).

• Cree un grupo de recursos de Azure si no tiene uno. Deberá tener el permiso Contributor, usted o la entidad de servicio que use. Para la creación del grupo de recursos, consulte Instalación, configuración y uso de la CLI (v2) (versión preliminar).

• Cree un área de trabajo de Azure Machine Learning si aún no tiene una. Para la creación del área de trabajo, consulte Instalación, configuración y uso de la CLI (v2) (versión preliminar).

• Configure el área de trabajo y el grupo de recursos predeterminados para la CLI de Azure. Los comandos de la CLI de Machine Learning requieren los parámetros --workspace/-w y --resource-group/-g. Configurar los valores predeterminados puede evitar pasar los valores varias veces. Puede invalidar estos valores en la línea de comandos. Ejecute el código siguiente para configurar los valores predeterminados. Para más información, consulte Instalación, configuración y uso de la CLI v2 (versión preliminar).

az account set -s "<subscription ID>"
az configure --defaults group="<resource group>" workspace="<workspace name>" location="<location>"

Clonación del repositorio de ejemplos

Ejecute los siguientes comandos para clonar el repositorio de ejemplo de AzureML y vaya al directorio cli. En este artículo se usan los recursos de /cli/endpoints/batch y el ejemplo de trabajo completo es /cli/batch-score.sh.

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

Establezca el nombre del punto de conexión. Reemplace YOUR_ENDPOINT_NAME por un nombre único dentro de una región de Azure.

Para Unix, ejecute este comando:

export ENDPOINT_NAME="<YOUR_ENDPOINT_NAME>"

Para Windows, ejecute este comando:

set ENDPOINT_NAME="<YOUR_ENDPOINT_NAME>"

Creación del proceso

El punto de conexión por lotes solo se ejecuta en recursos de informática en la nube, no de forma local. El recurso de informática en la nube es un clúster de proceso virtual reutilizable. Ejecute el código siguiente para crear un clúster de proceso de Azure Machine Learning. En los ejemplos siguientes de este artículo se usa el proceso creado aquí denominado batch-cluster. Realice los ajustes necesarios y haga referencia al proceso mediante azureml:<your-compute-name>.

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

Información sobre los puntos de conexión por lotes y las implementaciones por lotes

Un punto de conexión por lotes es un punto de conexión HTTPS al que los clientes pueden llamar para desencadenar un trabajo de puntuación por lotes. Un trabajo de puntuación por lotes es un trabajo que puntúa varias entradas (para más información, consulte ¿Qué son los puntos de conexión por lotes?). Una implementación por lotes es un conjunto de recursos de proceso que hospedan el modelo que realiza la puntuación por lotes real. Un punto de conexión por lotes puede tener varias implementaciones.

En el siguiente archivo YAML se define un punto de conexión por lotes, que puede incluir en el comando de la CLI para la creación del punto de conexión por lotes. En el repositorio, este archivo se encuentra en /cli/endpoints/batch/batch-endpoint.yml.

$schema: https://azuremlschemas.azureedge.net/latest/batchEndpoint.schema.json
name: mybatchedp
description: my sample batch endpoint
auth_mode: aad_token

En la tabla siguiente se describen las propiedades clave del YAML de punto de conexión. Para el esquema de YAML de punto de conexión por lotes completo, consulte Esquema de YAML de punto de conexión por lotes de la CLI (v2).

Para crear una implementación por lotes, necesita todos los elementos siguientes:

• Archivos de modelo o un modelo registrado en el área de trabajo al que se haga referencia mediante azureml:<model-name>:<model-version>.
• El código para puntuar el modelo.
• El entorno en el que se ejecuta el modelo. Puede ser una imagen de Docker con dependencias de Conda o un entorno ya registrado en el área de trabajo al que se hace referencia mediante azureml:<environment-name>:<environment-version>.
• El proceso creado previamente al que se hace referencia mediante azureml:<compute-name> y la configuración de los recursos.

Para más información sobre cómo hacer referencia a una entidad de Azure ML, consulte Referencia a una entidad de Azure ML.

El repositorio de ejemplo contiene todos los archivos necesarios. El siguiente archivo YAML define una implementación por lotes con todas las entradas necesarias y la configuración opcional. Puede incluir este archivo en el comando de la CLI para crear la implementación por lotes. En el repositorio, este archivo se encuentra en /cli/endpoints/batch/nonmlflow-deployment.yml.

$schema: https://azuremlschemas.azureedge.net/latest/batchDeployment.schema.json
name: nonmlflowdp
endpoint_name: mybatchedp
model: 
  local_path: ./mnist/model/
code_configuration:
  code:
    local_path: ./mnist/code/
  scoring_script: digit_identification.py
environment:
  conda_file: ./mnist/environment/conda.yml
  image: mcr.microsoft.com/azureml/openmpi3.1.2-ubuntu18.04:latest
compute: azureml:batch-cluster
resources:
  instance_count: 1
max_concurrency_per_instance: 2
mini_batch_size: 10
output_action: append_row
output_file_name: predictions.csv
retry_settings:
  max_retries: 3
  timeout: 30
error_threshold: -1
logging_level: info

En la tabla siguiente se describen las propiedades clave del YAML de implementación. Para el esquema de YAML de implementación por lotes completo, consulte Esquema de YAML de implementación por lotes de la CLI (v2).

Descripción del script de puntuación

Como se mencionó anteriormente, code_configuration.scoring_script debe contener dos funciones:

• init(): use esta función en el caso de cualquier preparación costosa o común. Por ejemplo, para cargar el modelo en un objeto global. Se llamará a esta función una vez al principio del proceso.
• run(mini_batch): se llamará a esta función para cada mini_batch y se realizará la puntuación real.
  • mini_batch: El valor de mini_batch es una lista de rutas de acceso de archivo.
  • response: el método run() debe devolver un dataframe de Pandas o una matriz. Cada elemento de salida devuelto indica una ejecución correcta del elemento de entrada en el mini_batch de entrada. Asegúrese de que se incluyen suficientes datos (por ejemplo, un identificador de cada elemento de entrada) en la respuesta de run() para correlacionar una entrada con un resultado de salida.

En el ejemplo se utiliza /cli/endpoints/batch/mnist/code/digit_identification.py. El modelo se carga en init() desde AZUREML_MODEL_DIR, que es la ruta de acceso a la carpeta del modelo creada durante la implementación. run(mini_batch) itera cada archivo en mini_batch, realiza la puntuación del modelo real y, a continuación, devuelve los resultados de salida.

Implementación con puntos de conexión por lotes y ejecución de la puntuación por lotes

Ahora, vamos a implementar el modelo con puntos de conexión por lotes y a ejecutar la puntuación por lotes.

Creación de un punto de conexión por lotes

La manera más sencilla de crear un punto de conexión por lotes es ejecutar el código siguiente proporcionando solo un elemento --name.

az ml batch-endpoint create --name $ENDPOINT_NAME

También puede crear un punto de conexión por lotes mediante un archivo YAML. Agregue el parámetro --file en el comando anterior y especifique la ruta de acceso del archivo YAML.

Creación de una implementación por lotes

Ejecute el código siguiente para crear una implementación por lotes denominada nonmlflowdp en el punto de conexión por lotes y establézcala como la implementación predeterminada.

az ml batch-deployment create --name nonmlflowdp --endpoint-name $ENDPOINT_NAME --file endpoints/batch/nonmlflow-deployment.yml --set-default

Comprobación de los detalles de implementación y punto de conexión por lotes

Use show para comprobar los detalles de implementación y punto de conexión por lotes.

Para comprobar una implementación por lotes, ejecute el código siguiente:

az ml batch-deployment show --name nonmlflowdp --endpoint-name $ENDPOINT_NAME

Para comprobar un punto de conexión por lotes, ejecute el código siguiente. Como la implementación recién creada se establece como la implementación predeterminada, debe ver nonmlflowdp en defaults.deployment_name en la respuesta.

az ml batch-endpoint show --name $ENDPOINT_NAME

Invocación del punto de conexión por lotes para iniciar un trabajo de puntuación por lotes

La invocación de un punto de conexión por lotes desencadena un trabajo de puntuación por lotes. Se devolverá un elemento name de trabajo de la respuesta de invocación y se puede usar para realizar un seguimiento del progreso de la puntuación por lotes. El trabajo de puntuación por lotes se ejecuta durante un período de tiempo. Divide todas las entradas en varios mini_batch y procesa en paralelo en el clúster de proceso. Un scoring_scrip run() toma un mini_batch y lo procesa mediante un proceso en una instancia. Las salidas del trabajo de puntuación por lotes se almacenarán en el almacenamiento en la nube, ya sea en el almacenamiento de blobs predeterminado del área de trabajo o en el almacenamiento que especifique.

Invocación del punto de conexión por lotes con diferentes opciones de entrada

Puede usar la CLI o REST a fin de ejecutar invoke para el punto de conexión. Para una experiencia REST, consulte Uso de puntos de conexión por lotes (versión preliminar) con REST.

Hay tres opciones para especificar las entradas de datos en la CLI invoke.

• Opción 1: Datos en la nube

  Use --input-path para especificar una carpeta (use el prefijo folder:) o un archivo (use el prefijo file:) en un almacén de datos registrado de Azure Machine Learning. La sintaxis del URI de datos es folder:azureml://datastores/<datastore-name>/paths/<data-path>/ para una carpeta y file:azureml://datastores/<datastore-name>/paths/<data-path>/<file-name> para un archivo específico. Para más información sobre el URI de datos, vea URI de referencia de datos de Azure Machine Learning.

  En el ejemplo se usan datos disponibles públicamente en una carpeta de https://pipelinedata.blob.core.windows.net/sampledata/mnist, que contiene miles de dígitos escritos a mano. El nombre del trabajo de puntuación por lotes se devolverá en la respuesta de la invocación. Ejecute el código siguiente para invocar el punto de conexión por lotes con estos datos. --query name se agrega para devolver solo el nombre del trabajo de la respuesta de invocación y se usará más adelante para supervisar el progreso de la ejecución del trabajo de puntuación por lotes y comprobar los resultados de puntuación por lotes. Quite --query name -o tsv si desea ver la respuesta de invocación completa. Para más información sobre el parámetro --query, vea Consulta de la salida de los comandos de la CLI de Azure.

  JOB_NAME=$(az ml batch-endpoint invoke --name $ENDPOINT_NAME --input-path folder:https://pipelinedata.blob.core.windows.net/sampledata/mnist --query name -o tsv)
  

• Opción 2: Datos registrados

  Utilice --input-dataset para pasar un conjunto datos registrado de Azure Machine Learning. Para crear un conjunto de datos, compruebe az ml dataset create -h para las instrucciones y siga el Esquema de conjunto de datos.

  Nota

  También se puede usar el objeto FileDataset que se crea con la versión anterior de la CLI y el SDK de Python. No se admite TabularDataset.

  az ml batch-endpoint invoke --name $ENDPOINT_NAME --input-dataset azureml:<dataset-name>:<dataset-version>
  

• Opción 3: Datos almacenados localmente

  Use --input-local-path para pasar archivos de datos almacenados localmente. Los archivos de datos se cargarán y registrarán de manera automática con un nombre y una versión generados automáticamente.

  az ml batch-endpoint invoke --name $ENDPOINT_NAME --input-local-path <local-path>
  

Configuración de la ubicación de salida y sobrescritura

Los resultados de la puntuación por lotes se almacenan de forma predeterminada en el almacén de blobs predeterminado del área de trabajo, dentro de una carpeta designada por el nombre del trabajo (un GUID generado por el sistema). Puede configurar dónde almacenar las salidas de puntuación al invocar el punto de conexión por lotes. Use --output-path para configurar cualquier objeto folder: en un almacén de datos registrado de Azure Machine Learning. La sintaxis de --output-path folder: es la misma que la de --input-path folder:. Use --set output_file_name=<your-file-name> para configurar un nuevo nombre de archivo de salida si prefiere tener un archivo de salida que contenga todos los resultados de puntuación (output_action=append_row especificado en el YAML de implementación).

Algunas opciones de configuración se pueden sobrescribir en la invocación para hacer un uso mejor de los recursos de proceso y mejorar el rendimiento:

• Use --instance-count para sobrescribir instance_count. Por ejemplo, para un mayor volumen de entradas de datos, puede que quiera usar más instancias para acelerar la puntuación por lotes de un extremo a otro.
• Use --mini-batch-size para sobrescribir mini_batch_size. El número de mini lotes se decide por los recuentos totales de archivos de entrada y mini_batch_size. Los mini_batch_size más pequeños generan más mini lotes. Los mini lotes se pueden ejecutar en paralelo, pero puede haber una sobrecarga adicional de programación e invocación.
• Use --set para sobrescribir otros valores, entre los que se incluyen max_retries, timeout y error_threshold. Esta configuración puede afectar al tiempo de la puntuación por lotes de un extremo a otro para distintas cargas de trabajo.

Para especificar la ubicación de salida y sobrescribir la configuración en la invocación, ejecute el código siguiente. En el ejemplo se almacenan las salidas en una carpeta con el mismo nombre que el punto de conexión en el almacenamiento de blobs predeterminado del área de trabajo y también se usa un nombre de archivo aleatorio para garantizar la exclusividad de la ubicación de salida. El código debe funcionar en Unix. Reemplácelos por sus propios nombres únicos de archivo y carpeta.

export OUTPUT_FILE_NAME=predictions_`echo $RANDOM`.csv
JOB_NAME=$(az ml batch-endpoint invoke --name $ENDPOINT_NAME --input-path folder:https://pipelinedata.blob.core.windows.net/sampledata/mnist --output-path folder:azureml://datastores/workspaceblobstore/paths/$ENDPOINT_NAME --set output_file_name=$OUTPUT_FILE_NAME --mini-batch-size 20 --instance-count 5 --query name -o tsv)

Supervisión del progreso de la ejecución del trabajo de puntuación por lotes

Los trabajos de puntuación por lotes suelen tardar algún tiempo en procesar todo el conjunto de entradas.

Puede usar la CLI job show para ver el trabajo. Ejecute el código siguiente para comprobar el estado del trabajo de la invocación de punto de conexión anterior. Para más información sobre los comandos de trabajo, ejecute az ml job -h.

STATUS=$(az ml job show -n $JOB_NAME --query status -o tsv)
echo $STATUS
if [[ $STATUS == "Completed" ]]
then
  echo "Job completed"
elif [[ $STATUS ==  "Failed" ]]
then
  echo "Job failed"
  exit 1
else 
  echo "Job status not failed or completed"
  exit 2
fi

Comprobación de los resultados de la puntuación por lotes

Siga los pasos siguientes para ver los resultados de puntuación en Explorador de Azure Storage cuando se complete el trabajo:

1. Ejecute el código siguiente para abrir el trabajo de puntuación por lotes en Estudio de Azure Machine Learning. El vínculo del estudio de trabajo se incluye también en la respuesta de invoke, como el valor de interactionEndpoints.Studio.endpoint.

   az ml job show -n $JOB_NAME --web
   

2. En el grafo de la ejecución, seleccione el paso batchscoring.

3. Seleccione la pestaña Resultados y registros y, después, Show data outputs (Mostrar salidas de datos).

4. En Data outputs (Salidas de datos), seleccione el icono para abrir el Explorador de Storage.

Los resultados de puntuación del Explorador de Storage son similares a la página de ejemplo siguiente:

Implementación de un nuevo modelo

Una vez que tenga un punto de conexión por lotes, puede seguir refinando el modelo y agregar nuevas implementaciones.

Creación de una nueva implementación por lotes que hospeda un modelo de MLflow

Para crear una nueva implementación por lotes en el punto de conexión por lotes existente, pero no establecerla como implementación predeterminada, ejecute el código siguiente:

az ml batch-deployment create --name mlflowdp --endpoint-name $ENDPOINT_NAME --file endpoints/batch/mlflow-deployment.yml

Tenga en cuenta que no se utiliza --set-default. Si vuelve a ejecutar show para el punto de conexión por lotes, no debería ver ningún cambio en defaults.deployment_name.

En el ejemplo se usa un modelo (/cli/endpoints/batch/autolog_nyc_taxi) entrenado y del que se ha hecho un seguimiento con MLflow. scoring_script y environment se pueden generar automáticamente mediante los metadatos del modelo, sin necesidad de especificar en el archivo YAML. Para más información sobre MLflow, consulte Entrenamiento y seguimiento de modelos de Machine Learning con MLflow y Azure Machine Learning (versión preliminar).

A continuación, se muestra el archivo YAML que el ejemplo usa para implementar un modelo de MLflow, que solo contiene las propiedades mínimas necesarias. El archivo de origen del repositorio es /cli/endpoints/batch/mlflow-deployment.yml.

$schema: https://azuremlschemas.azureedge.net/latest/batchDeployment.schema.json
name: mlflowdp
endpoint_name: mybatchedp
model: 
  local_path: ./autolog_nyc_taxi
compute: azureml:batch-cluster

Prueba de una implementación por lotes no predeterminada

Para probar la nueva implementación no predeterminada, ejecute el código siguiente. En el ejemplo se usa un modelo diferente que acepta un archivo csv disponible públicamente desde https://pipelinedata.blob.core.windows.net/sampledata/nytaxi/taxi-tip-data.csv.

JOB_NAME=$(az ml batch-endpoint invoke --name $ENDPOINT_NAME --deployment-name mlflowdp --input-path file:https://pipelinedata.blob.core.windows.net/sampledata/nytaxi/taxi-tip-data.csv --query name -o tsv)

az ml job show -n $JOB_NAME --web

az ml job stream -n $JOB_NAME

STATUS=$(az ml job show -n $JOB_NAME --query status -o tsv)
echo $STATUS
if [[ $STATUS == "Completed" ]]
then
  echo "Job completed"
elif [[ $STATUS ==  "Failed" ]]
then
  echo "Job failed"
  exit 1
else 
  echo "Job status not failed or completed"
  exit 2
fi

Observe que --deployment-name se usa para especificar el nuevo nombre de implementación. Este parámetro le permite ejecutar invoke para una implementación no predeterminada y no actualizará la implementación predeterminada del punto de conexión por lotes.

Actualización de la implementación por lotes predeterminada

Para actualizar la implementación por lotes predeterminada del punto de conexión, ejecute el código siguiente:

az ml batch-endpoint update --name $ENDPOINT_NAME --defaults deployment_name=mlflowdp

Ahora, si vuelve a ejecutar show para el punto de conexión por lotes, debería ver que defaults.deployment_name está establecido en mlflowdp. Puede ejecutar invoke para el punto de conexión por lotes directamente sin el parámetro --deployment-name.

(Opcional) Actualización de la implementación

Si quiere actualizar la implementación (por ejemplo, el código, el modelo, el entorno o la configuración), actualice el archivo YAML y ejecute az ml batch-deployment update. También puede realizar la actualización sin el archivo YAML mediante --set. Consulte az ml batch-deployment update -h para más información.

Eliminación del punto de conexión y la implementación por lotes

Si no va a usar la implementación por lotes anterior, debe eliminarla ejecutando el código siguiente. --yes se usa para confirmar la eliminación.

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

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 eliminarán.

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

Pasos siguientes

• Puntos de conexión de Batch en Studio
• Implementación de modelos con REST (versión preliminar) para la puntuación por lotes
• Solución de problemas de puntos de conexión por lotes