Compartir a través de

Administrar las entradas y salidas de componentes y canalización

  • Artículo

En este artículo, aprenderá lo siguiente:

  • Información general de las entradas y salidas en el componente y la canalización
  • Cómo promover entradas/salidas de componentes a entradas/salidas de canalizaciones
  • Cómo definir entradas opcionales
  • Cómo personalizar la ruta de salida
  • Cómo descargar los resultados
  • Cómo registrar las salidas como activos nominales

Resumen de entradas y salidas

Las canalizaciones de Azure Machine Learning admiten entradas y salidas tanto a nivel de componente como de canalización.

A nivel de componente, las entradas y salidas definen la interfaz de un componente. La salida de un componente puede utilizarse como entrada para otro componente de la misma canalización principal, lo que permite pasar datos o modelos de un componente a otro. Esta interconectividad forma un gráfico que ilustra el flujo de datos dentro de la canalización.

A nivel de canalización, las entradas y salidas son útiles para enviar trabajos de canalización con entradas de datos variables o parámetros que controlan la lógica de entrenamiento (por ejemplo learning_rate). Son especialmente útiles cuando se invoca la canalización a través de un punto de conexión REST. Estas entradas y salidas le permiten asignar diferentes valores a la entrada de la canalización o acceder a la salida de los trabajos de canalización a través del punto de conexión REST. Para obtener más información, consulte Creación de trabajos y datos de entrada para puntos de conexión por lotes.

Tipos de entradas y salidas

Los siguientes tipos se admiten como salidas de un componente o una canalización.

Utilizar los datos o la salida del modelo esencialmente serializar las salidas y guardarlas como archivos en una ubicación de almacenamiento. En los pasos posteriores, esta ubicación de almacenamiento se puede montar, descargar o cargar en el sistema de archivos de destino de proceso, lo que permite que el paso siguiente acceda a los archivos durante la ejecución del trabajo.

Este proceso requiere que el código fuente del componente serialice el objeto de salida deseado (normalmente almacenado en memoria) en archivos. Por ejemplo, podría serializar un marcos de datos de Pandas como un archivo CSV. Tenga en cuenta que Azure Machine Learning no define ningún método estandarizado para la serialización de objetos. Como usuario, tiene la flexibilidad de elegir el método preferido para serializar objetos en archivos. A continuación, en el componente posterior, puede deserializar y leer estos archivos de forma independiente. Estos son algunos ejemplos de su referencia:

  • En el ejemplo de nyc_taxi_data_regression, el componente de preparación tiene una salida de tipo uri_folder. En el código fuente del componente, lee los archivos CSV de la carpeta de entrada, procesa los archivos y escribe archivos CSV procesados en la carpeta de salida.
  • En el ejemplo de nyc_taxi_data_regression, el componente de entrenamiento tiene una salida de tipo mlflow_model. En el código fuente del componente, guarda el modelo entrenado mediante el método mlflow.sklearn.save_model.

Además de los tipos de datos o modelos anteriores, las entradas de canalización o componente también pueden seguir los tipos primitivos.

  • string
  • number
  • integer
  • boolean

En el ejemplo nyc_taxi_data_regression, el componente de entrenamiento tiene una entrada de number denominada test_split_ratio.

Nota:

No se admite la salida de tipos primitivos.

Ruta de acceso y modo de las entradas o salidas de datos

Para la entrada o salida de activos de datos, debe especificar un parámetro path que apunte a la ubicación de los datos. Esta tabla muestra las diferentes ubicaciones de datos que admite la canalización de Azure Machine Learning y también muestra ejemplos de parámetros de ruta:

Location Ejemplos Entrada Salida
Ruta de acceso en la máquina local ./home/username/data/my_data ✓
Ruta de acceso en un servidor http(s) público https://raw.githubusercontent.com/pandas-dev/pandas/main/doc/data/titanic.csv ✓
Ruta de acceso en Azure Storage wasbs://<container_name>@<account_name>.blob.core.windows.net/<path>
abfss://<file_system>@<account_name>.dfs.core.windows.net/<path>		 No se recomienda porque puede necesitar una configuración de identidad adicional para leer los datos.
Una ruta de acceso en un almacén de datos de Azure Machine Learning azureml://datastores/<data_store_name>/paths/<path> ✓ ✓
Ruta de acceso a un recurso de datos azureml:<my_data>:<version> ✓ ✓

Nota:

Para la entrada o salida en el almacenamiento, sugerimos encarecidamente utilizar la ruta del almacén de datos de Azure Machine Learning en lugar de la ruta directa de Azure Storage. La ruta del almacén de datos es compatible con varios tipos de trabajo en canalización.

Para la entrada o salida de datos, puede elegir entre varios modos (descarga, montaje o carga) para definir cómo se accede a los datos en el destino de proceso. Esta tabla muestra los modos posibles para diferentes combinaciones de tipo, modo, entrada, o salida.

Tipo Entrada/salida upload download ro_mount rw_mount direct eval_download eval_mount
uri_folder Entrada ✓ ✓ ✓
uri_file Entrada ✓ ✓ ✓
mltable Entrada ✓ ✓ ✓ ✓ ✓
uri_folder Output ✓ ✓
uri_file Output ✓ ✓
mltable Output ✓ ✓ ✓

Nota:

En la mayoría de los casos, se recomienda usar el modo ro_mount o rw_mount. Para obtener más información sobre el modo, consulte modos de activos de datos.

Representación visual en Estudio de Azure Machine Learning

Las siguientes capturas de pantalla proporcionan un ejemplo de cómo se muestran las entradas y salidas en un trabajo de canalización en el Estudio de Azure Machine Learning. Este trabajo en particular, llamado nyc-taxi-data-regression, se puede encontrar en azureml-example.

En la página de trabajo de canalización de Studio, las entradas o salidas del tipo de datos o modelo de un componente se muestran como un círculo pequeño en el componente correspondiente, conocido como puerto de entrada o salida. Estos puertos representan el flujo de datos en una canalización.

La salida de nivel de canalización se muestra como un recuadro morado para facilitar su identificación.

Screenshot highlighting the pipeline input and output port.

Al pasar el ratón sobre un puerto de entrada o salida, se muestra el tipo.

Screenshot highlighting the port type when hovering the mouse.

Las entradas de tipo primitivo no se mostrarán en el gráfico. Se encuentra en la pestaña Configuración del panel de información general de trabajos de canalización (para entradas a nivel de canalización) o del panel de componentes (para entradas a nivel de componentes). La siguiente captura de pantalla muestra la pestaña Configuración de un trabajo de canalización, que puede abrirse seleccionando el enlace Información general de trabajos.

Si desea comprobar las entradas de un componente, haga doble clic en él para abrir el panel de componentes.

Screenshot highlighting the job overview setting panel.

Del mismo modo, al editar una canalización en el diseñador, puede encontrar las entradas y salidas de la canalización en el panel de la interfaz de la canalización, y las entradas y salidas de los componentes en el panel del componente (se activa haciendo doble clic en el componente).

Screenshot highlighting the pipeline interface in designer.

Cómo promover las entradas y salidas de componentes al nivel de canalización

Promover la entrada o salida de un componente al nivel de canalización permite sobrescribir la entrada o salida del componente al enviar un trabajo de canalización. También es útil si desea activar la canalización mediante el punto de conexión REST.

A continuación se muestran ejemplos para promover entradas o salidas de componentes a entradas o salidas de nivel de canalización.

$schema: https://azuremlschemas.azureedge.net/latest/pipelineJob.schema.json
type: pipeline
display_name: 1b_e2e_registered_components
description: E2E dummy train-score-eval pipeline with registered components

inputs:
  pipeline_job_training_max_epocs: 20
  pipeline_job_training_learning_rate: 1.8
  pipeline_job_learning_rate_schedule: 'time-based'

outputs: 
  pipeline_job_trained_model:
    mode: upload
  pipeline_job_scored_data:
    mode: upload
  pipeline_job_evaluation_report:
    mode: upload

settings:
 default_compute: azureml:cpu-cluster

jobs:
  train_job:
    type: command
    component: azureml:my_train@latest
    inputs:
      training_data: 
        type: uri_folder 
        path: ./data      
      max_epocs: ${{parent.inputs.pipeline_job_training_max_epocs}}
      learning_rate: ${{parent.inputs.pipeline_job_training_learning_rate}}
      learning_rate_schedule: ${{parent.inputs.pipeline_job_learning_rate_schedule}}
    outputs:
      model_output: ${{parent.outputs.pipeline_job_trained_model}}
    services:
      my_vscode:
        type: vs_code
      my_jupyter_lab:
        type: jupyter_lab
      my_tensorboard:
        type: tensor_board
        log_dir: "outputs/tblogs"
    #  my_ssh:
    #    type: tensor_board
    #    ssh_public_keys: <paste the entire pub key content>
    #    nodes: all # Use the `nodes` property to pick which node you want to enable interactive services on. If `nodes` are not selected, by default, interactive applications are only enabled on the head node.

  score_job:
    type: command
    component: azureml:my_score@latest
    inputs:
      model_input: ${{parent.jobs.train_job.outputs.model_output}}
      test_data: 
        type: uri_folder 
        path: ./data
    outputs:
      score_output: ${{parent.outputs.pipeline_job_scored_data}}

  evaluate_job:
    type: command
    component: azureml:my_eval@latest
    inputs:
      scoring_result: ${{parent.jobs.score_job.outputs.score_output}}
    outputs:
      eval_output: ${{parent.outputs.pipeline_job_evaluation_report}}

El ejemplo completo se encuentra en canalización train-score-eval con componentes registrados. Esta canalización promueve tres entradas y tres salidas a nivel de canalización. Tomemos pipeline_job_training_max_epocs como ejemplo. Se declara bajo la sección inputs en el nivel raíz, lo que significa que es su entrada a nivel de canalización. En la sección jobs -> train_job, la entrada denominada max_epocs se menciona como ${{parent.inputs.pipeline_job_training_max_epocs}}, lo que indica que la entrada de train_job hace referencia max_epocs a la entrada de nivel de la canalización pipeline_job_training_max_epocs. Del mismo modo, puede promover la salida de canalizaciones utilizando el mismo esquema.

Estudio

Puede promover la entrada de un componente a entrada de nivel de canalización en la página de creación del diseñador. Vaya al panel de configuración del componente haciendo doble clic en el componente -> busque la entrada que desea promover -> Seleccione los tres puntos de la derecha -> Seleccione Agregar a entrada de canalización.

Screenshot highlighting how to promote to pipeline input in designer.

Entrada opcional

Por defecto, todas las entradas son obligatorias y se les debe asignar un valor (o un valor por defecto) cada vez que envíe un trabajo de canalización. Sin embargo, puede haber casos en los que necesite entradas opcionales. En estos casos, tiene la posibilidad de no asignar un valor a la entrada al enviar un trabajo de canalización.

La entrada opcional puede ser útil en los siguientes dos escenarios:

  • Si tiene una entrada opcional de tipo de datos o modelo y no le asigna un valor al enviar el trabajo de canalización, habrá un componente en la canalización que carecerá de una dependencia de datos anterior. En otras palabras, el puerto de entrada no está vinculado a ningún componente o nodo de modelo o datos. Esto hace que el servicio de canalización invoque este componente directamente, en lugar de esperar a que la dependencia anterior esté lista.

  • En la captura de pantalla siguiente se proporciona un ejemplo claro del segundo escenario. Si establece continue_on_step_failure = True para la canalización y tiene un segundo nodo (node2) que usa la salida del primer nodo (node1) como entrada opcional, node2 seguirá ejecutándose aunque no se produzca un error en node1. Sin embargo, si node2 usa la entrada necesaria de node1, no se ejecutará si se produce un error en node1.

    Screenshot to show the orchestration logic of optional input and continue on failure.

A continuación se ofrecen ejemplos sobre cómo definir entradas opcionales.

$schema: https://azuremlschemas.azureedge.net/latest/commandComponent.schema.json
name: train_data_component_cli
display_name: train_data
description: A example train component
tags:
  author: azureml-sdk-team
type: command
inputs:
  training_data: 
    type: uri_folder
  max_epocs:
    type: integer
    optional: true
  learning_rate: 
    type: number
    default: 0.01
    optional: true
  learning_rate_schedule: 
    type: string
    default: time-based
    optional: true
outputs:
  model_output:
    type: uri_folder
code: ./train_src
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest
command: >-
  python train.py 
  --training_data ${{inputs.training_data}} 
  $[[--max_epocs ${{inputs.max_epocs}}]]
  $[[--learning_rate ${{inputs.learning_rate}}]]
  $[[--learning_rate_schedule ${{inputs.learning_rate_schedule}}]]
  --model_output ${{outputs.model_output}}

Cuando la entrada se establece como optional = true, debe usar $[[]] para adoptar la línea de comandos con entradas. Consulte la línea resaltada en el ejemplo anterior.

Nota:

La salida opcional no es compatible.

En el gráfico de canalización, las entradas opcionales del tipo Datos o Modelo se representan mediante un círculo de puntos. Las entradas opcionales de tipos primitivos se encuentran en la pestaña Configuración. A diferencia de las entradas obligatorias, las opcionales no tienen un asterisco al lado, lo que significa que no son obligatorias.

Screenshot highlighting the optional input.

Cómo personalizar la ruta de salida

Por defecto, la salida de un componente se almacenará en azureml://datastores/${{default_datastore}}/paths/${{name}}/${{output_name}}. {default_datastore} es el cliente de almacén de datos predeterminado para la canalización. Si no se establece es el área de trabajo de almacenamiento blob. {name} es el nombre del trabajo, que se resolverá en el momento de la ejecución del trabajo. {output_name} es el nombre de salida definido por el cliente en el componente YAML.

Pero también puede personalizar dónde almacenar la salida definiendo la ruta de una salida. Estos son algunos ejemplos:

pipeline.yaml define una canalización que tiene tres salidas a nivel de canalización. El YAML completo se encuentra en el ejemplo de canalización train-score-eval con componentes registrados. Puede utilizar el siguiente comando para establecer una ruta de salida personalizada para la salida pipeline_job_trained_model.

# define the custom output path using datastore uri
# add relative path to your blob container after "azureml://datastores/<datastore_name>/paths"
output_path="azureml://datastores/{datastore_name}/paths/{relative_path_of_container}"  

# create job and define path using --outputs.<outputname>
az ml job create -f ./pipeline.yml --set outputs.pipeline_job_trained_model.path=$output_path

Cómo descargar el resultado

Puede descargar la salida de un componente o la salida de una canalización siguiendo el siguiente ejemplo.

Descarga del nivel de salida de canalización

# Download all the outputs of the job
az ml job download --all -n <JOB_NAME> -g <RESOURCE_GROUP_NAME> -w <WORKSPACE_NAME> --subscription <SUBSCRIPTION_ID>

# Download specific output
az ml job download --output-name <OUTPUT_PORT_NAME> -n <JOB_NAME> -g <RESOURCE_GROUP_NAME> -w <WORKSPACE_NAME> --subscription <SUBSCRIPTION_ID>

Descargar el resultado de la tarea secundaria

Cuando necesite descargar la salida de un trabajo secundario (una salida de componente que no asciende al nivel de canalización), primero debe listar todas las entidades de trabajo secundario de un trabajo de canalización y luego utilizar un código similar para descargar la salida.

# List all child jobs in the job and print job details in table format
az ml job list --parent-job-name <JOB_NAME> -g <RESOURCE_GROUP_NAME> -w <WORKSPACE_NAME> --subscription <SUBSCRIPTION_ID> -o table

# Select needed child job name to download output
az ml job download --all -n <JOB_NAME> -g <RESOURCE_GROUP_NAME> -w <WORKSPACE_NAME> --subscription <SUBSCRIPTION_ID>

Cómo registrar la salida como activo con nombre

Puede registrar la salida de un componente o canalización como activo con nombre asignando name y version a la salida. El activo registrado se puede listar en su área de trabajo a través del estudio UI/CLI/SDK y también ser referenciado en sus futuros trabajos.

Salida de la canalización de registro

display_name: register_pipeline_output
type: pipeline
jobs:
  node:
    type: command
    inputs:
      component_in_path:
        type: uri_file
        path: https://dprepdata.blob.core.windows.net/demo/Titanic.csv
    component: ../components/helloworld_component.yml
    outputs:
      component_out_path: ${{parent.outputs.component_out_path}}
outputs:
  component_out_path:
    type: mltable
    name: pipeline_output  # Define name and version to register pipeline output
    version: '1'
settings:
  default_compute: azureml:cpu-cluster

Registrar la salida de un trabajo secundario

display_name: register_node_output
type: pipeline
jobs:
  node:
    type: command
    component: ../components/helloworld_component.yml
    inputs:
      component_in_path:
        type: uri_file
        path: 'https://dprepdata.blob.core.windows.net/demo/Titanic.csv'
    outputs:
      component_out_path:
        type: uri_folder
        name: 'node_output'  # Define name and version to register a child job's output
        version: '1'
settings:
  default_compute: azureml:cpu-cluster

Pasos siguientes