Creación de trabajos y datos de entrada para puntos de conexión por lotes

  • Artículo

Los punto de conexión por lotes se pueden usar para realizar operaciones por lotes largas con grandes cantidades de datos. Estos datos se pueden colocar en diferentes lugares. Algunos tipos de puntos de conexión por lotes también pueden recibir parámetros literales como entradas. En este tutorial veremos cómo puede especificar esas entradas y los distintos tipos o ubicaciones admitidos.

Antes de invocar un punto de conexión

Para invocar correctamente un punto de conexión por lotes y crear trabajos, asegúrese de que tiene lo siguiente:

  • Tiene permisos para ejecutar una implementación de punto de conexión por lotes. Los roles Científico de datos, Colaborador y Propietario de AzureML se pueden usar para ejecutar una implementación. Para las definiciones de roles personalizados, lea Autorización en puntos de conexión por lotes para conocer los permisos específicos necesarios.

  • Tiene un token de Microsoft Entra ID válido que representa una entidad de seguridad para invocar el punto de conexión. Esta entidad de seguridad puede ser una entidad de seguridad de usuario o una entidad de servicio. En cualquier caso, una vez invocado un punto de conexión, se crea un trabajo de implementación por lotes en la identidad asociada al token. Con fines de prueba, puede usar sus propias credenciales para la invocación, como se menciona a continuación.

    Use la CLI de Azure para iniciar sesión mediante la autenticación interactiva o de código de dispositivo:

    az login

    Para más información sobre cómo autenticarse con varios tipos de credenciales, lea Autorización en puntos de conexión por lotes.

  • El clúster de proceso donde se implementa el punto de conexión tiene acceso para leer los datos de entrada.

    Sugerencia

    Si usa un almacén de datos sin credenciales o una cuenta externa de Azure Storage como entrada de datos, asegúrese de configurar clústeres de proceso para el acceso a datos. La identidad administrada del clúster de proceso se usa para montar la cuenta de almacenamiento. La identidad del trabajo (invocador) se sigue usando para leer los datos subyacentes, lo que le permite lograr un control de acceso pormenorizado.

Conceptos básicos de la creación de trabajos

Para crear un trabajo a partir de un punto de conexión por lotes, hay que invocarlo. La invocación se puede realizar mediante la CLI de Azure, el SDK de Azure Machine Learning para Python o una llamada a la API REST. En los ejemplos siguientes se muestran los conceptos básicos de la invocación de un punto de conexión por lotes que recibe una única carpeta de datos de entrada para su procesamiento. Consulte Descripción de las entradas y salidas para obtener ejemplos con distintas entradas y salidas.

Use la operación invoke en puntos de conexión por lotes:

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data

Invocación de una implementación específica

Los puntos de conexión por lotes pueden hospedar varias implementaciones en el mismo punto de conexión. El punto de conexión predeterminado se usa a menos que el usuario especifique lo contrario. Puede cambiar la implementación que se usa de la siguiente manera:

Use el argumento --deployment-name o -d para especificar el nombre de la implementación:

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --deployment-name $DEPLOYMENT_NAME \
                            --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data

Configuración de las propiedades del trabajo

Puede configurar algunas de las propiedades del trabajo creado en el momento de la invocación.

Nota:

La configuración de propiedades de trabajo solo está disponible en puntos de conexión por lotes con implementaciones de componentes de canalización por momento.

Configurar el nombre del experimento

Use el argumento --experiment-name para especificar el nombre del experimento:

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --experiment-name "my-batch-job-experiment" \
                            --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data

Reconocimiento de entradas y salidas

Los puntos de conexión por lotes proporcionan una API duradera que los consumidores pueden usar para crear trabajos por lotes. La misma interfaz se puede usar para especificar las entradas y las salidas que espera la implementación. Use entradas para pasar cualquier información que el punto de conexión necesite para realizar el trabajo.

Diagrama que muestra cómo se utilizan las entradas y salidas en los puntos de conexión de lote.

Los puntos de conexión por lotes admiten dos tipos de entradas:

  • Entradas de datos, que son punteros a una ubicación de almacenamiento específica o a un recurso de Azure Machine Learning.
  • Entradas literales, que son valores literales (como números o cadenas) que desea pasar al trabajo.

El número y el tipo de entradas y salidas dependen del tipo de implementación por lotes. Las implementaciones de modelos siempre requieren una entrada de datos y generan una salida de datos. No se admiten entradas literales. Sin embargo, las implementaciones de componentes de canalización proporcionan una construcción más general para compilar puntos de conexión y permiten especificar cualquier número de entradas (datos y literales) y salidas.

En la tabla siguiente se resumen las entradas y salidas de las implementaciones por lotes:

Tipo de implementación Número de entrada Tipos de entrada admitidos Número de salida Tipos de salida admitidos
Implementación de modelo 1 Entradas de datos 1 Salidas de datos
Implementación de componentes de canalización [0..N] Entradas de datos y entradas literales [0..N] Salidas de datos

Sugerencia

Las entradas y salidas siempre se denominan. Esos nombres sirven como claves para identificarlos y pasar el valor real durante la invocación. En el caso de las implementaciones de modelos, ya que siempre requieren una entrada y salida, el nombre se omitirá durante la invocación. Puede asignar el nombre que mejor describa el caso de uso, como "sales_estimation".

Entradas de datos

Las entradas de datos hacen referencia a entradas que apuntan a una ubicación donde se colocan los datos. Dado que los puntos de conexión por lotes suelen consumir grandes cantidades de datos, no se pueden pasar los datos de entrada como parte de la solicitud de invocación. En su lugar, especifique la ubicación donde debería ir el punto de conexión por lotes para buscar los datos. Los datos de entrada se montan y transmiten en el proceso de destino para mejorar el rendimiento.

Los puntos de conexión por lotes admiten la lectura de archivos ubicados en las siguientes opciones de almacenamiento:

  • Recursos de datos de Azure Machine Learning, incluida la carpeta (uri_folder) y el archivo (uri_file).
  • Almacenes de datos de Azure Machine Learning, incluidos Azure Blob Storage, Azure Data Lake Storage Gen1 y Azure Data Lake Storage Gen2.
  • Cuentas de Azure Storage, incluidos Azure Data Lake Storage Gen1, Azure Data Lake Storage Gen2 y Azure Blob Storage.
  • Carpetas o archivos de datos locales (CLI de Azure Machine Learning o SDK de Azure Machine Learning para Python). Sin embargo, esa operación da lugar a que los datos locales se carguen en el almacén de datos de Azure Machine Learning predeterminado del área de trabajo en la que está trabajando.

Importante

Aviso de desuso: los conjuntos de datos de tipo FileDataset (V1) están en desuso y se retirarán en el futuro. Los puntos de conexión por lotes existentes que dependen de esta funcionalidad seguirán funcionando, pero los puntos de conexión por lotes creados con CLIv2 (2.4.0 y versiones posteriores) de disponibilidad general o la API REST de disponibilidad general (2022-05-01 y versiones posteriores) no admitirán el conjunto de datos V1.

Entradas literales

Las entradas literales hacen referencia a entradas que se pueden representar y resolver en tiempo de invocación, como cadenas, números y valores booleanos. Normalmente, se usan entradas literales para pasar parámetros al punto de conexión como parte de una implementación de componentes de canalización. Los puntos de conexión por lotes admiten los siguientes tipos literales:

  • string
  • boolean
  • float
  • integer

Las entradas literales solo se admiten en implementaciones de componentes de canalización. Consulte Creación de trabajos con entradas literales para obtener información sobre cómo especificarlos.

Salidas de datos

Las salidas de datos hacen referencia a la ubicación donde se deberán colocar los resultados de un trabajo por lotes. Las salidas se identifican por nombre y Azure Machine Learning asignará automáticamente una ruta de acceso única a cada salida con nombre. Sin embargo, puede especificar otra ruta de acceso si es necesario.

Importante

Los puntos de conexión de Batch solo admiten la escritura de salidas en almacenes de datos de Azure Blob Storage. Si necesita escribir en una cuenta de almacenamiento con espacios de nombres jerárquicos habilitados (también conocidos como Azure Datalake Gen2 o ADLS Gen2), observe que este servicio de almacenamiento se puede registrar como un almacén de datos de Azure Blob Storage, ya que los servicios son totalmente compatibles. De este modo, puede escribir salidas de puntos de conexión por lotes en ADLS Gen2.

Creación de trabajos con entradas de datos

En los siguientes ejemplos se muestra cómo crear trabajos que toman entradas de datos de recursos de datos, almacenes de datos y cuentas de Azure Storage.

Entrada de datos desde un recurso de datos

Los recursos de datos de Azure Machine Learning (anteriormente conocidos como conjuntos de datos) se admiten como entradas para trabajos. Siga estos pasos para ejecutar un trabajo de punto de conexión por lotes mediante datos almacenados en un recurso de datos registrado en Azure Machine Learning:

Advertencia

Actualmente no se admiten los recursos de datos de tipo Table (MLTable).

  1. Primero, cree el recurso de datos. Este recurso de datos consta de una carpeta con varios archivos CSV que procesará en paralelo mediante puntos de conexión por lotes. Puede omitir este paso si los datos ya están registrados como un recurso de datos.

    Cree una definición de recurso de datos en 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: heart-classifier-mlflow/data

    A continuación, cree el recurso de datos:

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

  2. Cree la entrada o solicitud:

    DATASET_ID=$(az ml data show -n heart-dataset-unlabeled --label latest | jq -r .id)

    Nota

    El identificador de los recursos de datos tendría el aspecto de /subscriptions/<subscription>/resourcegroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/data/<data-asset>/versions/<version>. También puede usar azureml:/<datasset_name>@latest como una manera de especificar la entrada.

  3. Ejecute el punto de conexión:

    Use el argumento --set para especificar la entrada:

    az ml batch-endpoint invoke --name $ENDPOINT_NAME \
    --set inputs.heart_dataset.type="uri_folder" inputs.heart_dataset.path=$DATASET_ID

    Para un punto de conexión que atiende una implementación de modelo, puede usar el argumento --input para especificar la entrada de datos, ya que una implementación de modelos siempre requiere una entrada de datos.

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --input $DATASET_ID

    El argumento --set tiende a generar comandos largos cuando se especifican varias entradas. En esos casos, coloque las entradas en un archivo YAML y use --file para especificar las entradas que necesita para invocar el punto de conexión.

    inputs.yml

    inputs:
  heart_dataset: azureml:/<datasset_name>@latest

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --file inputs.yml

Entrada de datos desde almacenes de datos

Los trabajos de implementaciones por lotes pueden hacer referencia directamente a los datos de los almacenes de datos registrados de Azure Machine Learning. En este ejemplo, primero va a cargar algunos datos en el almacén de datos predeterminado del área de trabajo de Azure Machine Learning y, a continuación, ejecutar una implementación por lotes en él. Siga estos pasos para ejecutar un trabajo de punto de conexión por lotes mediante los datos almacenados en un almacén de datos.

  1. Acceda al almacén de datos predeterminado del área de trabajo de Azure Machine Learning. Si los datos están en un almacén diferente, puede usar ese almacén en su lugar. No es necesario usar el almacén de datos predeterminado.

    DATASTORE_ID=$(az ml datastore show -n workspaceblobstore | jq -r '.id')

    Nota

    El identificador de los almacenes de datos tendría el aspecto de /subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/datastores/<data-store>.

    Sugerencia

    El almacén de datos de blobs predeterminado en un área de trabajo se denomina workspaceblobstore. Puede omitir este paso si ya conoce el identificador de recurso del almacén de datos predeterminado en el área de trabajo.

  2. Debe cargar algunos datos de ejemplo en el almacén de datos. En este ejemplo se supone que ya ha cargado los datos de ejemplo incluidos en el repositorio de la carpeta sdk/python/endpoints/batch/deploy-models/heart-classifier-mlflow/data en la carpeta heart-disease-uci-unlabeled de la cuenta de almacenamiento de blobs. Asegúrese de que lo ha hecho antes de continuar.

  3. Cree la entrada o solicitud:

    Coloque la ruta de acceso del archivo en la variable siguiente:

    DATA_PATH="heart-disease-uci-unlabeled"
INPUT_PATH="$DATASTORE_ID/paths/$DATA_PATH"

    Nota:

    Vea cómo se anexa la ruta de acceso paths al identificador de recurso del almacén de datos para indicar que lo siguiente es una ruta de acceso dentro del mismo.

    Sugerencia

    También puede usar azureml://datastores/<data-store>/paths/<data-path> como una manera de especificar la entrada.

  4. Ejecute el punto de conexión:

    Use el argumento --set para especificar la entrada:

    az ml batch-endpoint invoke --name $ENDPOINT_NAME \
    --set inputs.heart_dataset.type="uri_folder" inputs.heart_dataset.path=$INPUT_PATH

    Para un punto de conexión que atiende una implementación de modelo, puede usar el argumento --input para especificar la entrada de datos, ya que una implementación de modelos siempre requiere una entrada de datos.

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --input $INPUT_PATH --input-type uri_folder

    El argumento --set tiende a generar comandos largos cuando se especifican varias entradas. En esos casos, coloque las entradas en un archivo YAML y use --file para especificar las entradas que necesita para invocar el punto de conexión.

    inputs.yml

    inputs:
  heart_dataset:
    type: uri_folder
    path: azureml://datastores/<data-store>/paths/<data-path>

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --file inputs.yml

    Si los datos fueran un archivo, use uri_file como tipo en su lugar.

Entrada de datos desde cuentas de Azure Storage

Los puntos de conexión por lotes de Azure Machine Learning pueden leer datos de ubicaciones en la nube en cuentas de Azure Storage, tanto públicas como privadas. Siga estos pasos para ejecutar un trabajo de punto de conexión por lotes mediante los datos almacenados en una cuenta de almacenamiento:

Nota:

Consulte la sección Configurar clústeres de proceso para el acceso a datos para obtener más información sobre la configuración adicional necesaria para leer correctamente los datos de las cuentas de almacenamiento.

  1. Cree la entrada o solicitud:

    INPUT_DATA = "https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data"

    Si los datos son un archivo:

    INPUT_DATA = "https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data/heart.csv"

  2. Ejecute el punto de conexión:

    Use el argumento --set para especificar la entrada:

    az ml batch-endpoint invoke --name $ENDPOINT_NAME \
    --set inputs.heart_dataset.type="uri_folder" inputs.heart_dataset.path=$INPUT_DATA

    Para un punto de conexión que atiende una implementación de modelo, puede usar el argumento --input para especificar la entrada de datos, ya que una implementación de modelos siempre requiere una entrada de datos.

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --input $INPUT_DATA --input-type uri_folder

    El argumento --set tiende a generar comandos largos cuando se especifican varias entradas. En esos casos, coloque las entradas en un archivo YAML y use --file para especificar las entradas que necesita para invocar el punto de conexión.

    inputs.yml

    inputs:
  heart_dataset:
    type: uri_folder
    path: https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --file inputs.yml

    Si los datos fueran un archivo, use uri_file como tipo en su lugar.

Creación de trabajos con entradas literales

Las implementaciones de componentes de canalización pueden tomar entradas literales. En el ejemplo siguiente, se muestra cómo especificar una entrada denominada score_mode, de tipo string, con un valor de append:

Coloque las entradas en un archivo YAML y use --file para especificar las entradas necesarias para invocar el punto de conexión.

inputs.yml

inputs:
  score_mode:
    type: string
    default: append

az ml batch-endpoint invoke --name $ENDPOINT_NAME --file inputs.yml

También puede usar el argumento --set para especificar el valor. Sin embargo, tiende a generar comandos largos cuando se especifican varias entradas:

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
    --set inputs.score_mode.type="string" inputs.score_mode.default="append"

Creación de trabajos con salidas de datos

En el ejemplo siguiente, se muestra cómo cambiar la ubicación en la cual se coloca una salida denominada score. Por motivos de exhaustividad, estos ejemplos también configuran una entrada denominada heart_dataset.

  1. Use el almacén de datos predeterminado en el área de trabajo de Azure Machine Learning para guardar las salidas. Es posible usar cualquier otro almacén de datos del área de trabajo siempre que sea una cuenta de almacenamiento de blobs.

    DATASTORE_ID=$(az ml datastore show -n workspaceblobstore | jq -r '.id')

    Nota

    El identificador de los almacenes de datos tendría el aspecto de /subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/datastores/<data-store>.

  2. Creación de una salida de datos:

    DATA_PATH="batch-jobs/my-unique-path"
OUTPUT_PATH="$DATASTORE_ID/paths/$DATA_PATH"

    Para mayor exhaustividad, cree también una entrada de datos:

    INPUT_PATH="https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data"

    Nota:

    Vea cómo se anexa la ruta de acceso paths al identificador de recurso del almacén de datos para indicar que lo siguiente es una ruta de acceso dentro del mismo.

  3. Ejecute la implementación:

    Use el argumento --set para especificar la entrada:

    az ml batch-endpoint invoke --name $ENDPOINT_NAME \
    --set inputs.heart_dataset.path=$INPUT_PATH \
    --set outputs.score.path=$OUTPUT_PATH

Pasos siguientes