Gérer les entrées et les sorties du composant et du pipeline

  • Article

Dans cet article, vous apprenez :

  • Vue d’ensemble des entrées et sorties dans le composant et le pipeline
  • Comment promouvoir les entrées et sorties de composant en entrées et sorties de pipeline
  • Comment définir des entrées facultatives
  • Comment personnaliser le chemin d’accès des sorties
  • Comment télécharger des sorties
  • Comment inscrire des sorties en tant que ressource nommée

Vue d’ensemble des entrées et des sorties

Les pipelines Azure Machine Learning prennent en charge les entrées et les sorties au niveau du composant et du pipeline.

Au niveau du composant, les entrées et les sorties définissent l’interface d’un composant. La sortie d’un composant peut être utilisée comme entrée pour un autre composant dans le même pipeline parent, ce qui permet de transférer des données ou des modèles entre les composants. Cette interconnexion forme un graphique illustrant le flux de données au sein du pipeline.

Au niveau du pipeline, les entrées et les sorties sont utiles pour soumettre des travaux de pipeline avec des entrées de données ou des paramètres variables qui contrôlent la logique d’entraînement (par exemple, learning_rate). Elles sont particulièrement utiles lors de l’appel du pipeline via un point de terminaison REST. Ces entrées et sorties vous permettent d’affecter différentes valeurs à l’entrée du pipeline ou d’accéder à la sortie des travaux du pipeline via le point de terminaison REST. Pour plus d’informations, consultez Création de travaux et de données d’entrée pour le point de terminaison par lots.

Types d’entrées et de sorties

Les types de sorties d’un composant ou pipeline suivants sont pris en charge.

L’utilisation de sorties de données ou de modèles sérialise essentiellement les sorties et les enregistre sous forme de fichiers dans un emplacement de stockage. Dans les étapes suivantes, cet emplacement de stockage peut être monté, téléchargé ou chargé dans le système de fichiers cible de calcul, ce qui permet à l’étape suivante d’accéder aux fichiers pendant l’exécution du travail.

Ce processus nécessite que le code source du composant sérialise l’objet de sortie souhaité, généralement stocké dans la mémoire, dans des fichiers. Par exemple, vous pouvez sérialiser un dataframe pandas en tant que fichier CSV. Notez qu’Azure Machine Learning ne définit pas de méthodes standardisées pour la sérialisation d’objets. En tant qu’utilisateur, vous avez la possibilité de choisir votre méthode préférée pour sérialiser des objets dans des fichiers. Après cela, dans le composant en aval, vous pouvez désérialiser et lire ces fichiers indépendamment. Voici quelques exemples pour votre référence :

  • Dans l’exemple nyc_taxi_data_regression, le composant de préparation a une sortie de type uri_folder. Dans le code source du composant, il lit les fichiers csv du dossier d’entrée, traite les fichiers et écrit les fichiers CSV traités dans le dossier de sortie.
  • Dans l’exemple nyc_taxi_data_regression, le composant d’apprentissage a une sortie de type mlflow_model. Dans le code source du composant, il enregistre le modèle entraîné à l’aide de la méthode mlflow.sklearn.save_model.

En plus des types de données ou de modèles ci-dessus, les entrées du pipeline ou du composant peuvent également suivre les types primitifs.

  • string
  • number
  • integer
  • boolean

Dans l’exemple nyc_taxi_data_regression, le composant d’apprentissage a une entrée number nommée test_split_ratio.

Remarque

La sortie des types primitifs n’est pas prise en charge.

Chemin d’accès et mode des entrées et des sorties de données

Pour les ressources de données des entrées et des sorties, vous devez spécifier un paramètre path qui pointe vers l’emplacement des données. Le tableau suivant montre les différents emplacements de données pris en charge par le pipeline Azure Machine Learning, ainsi que des exemples de paramètre des chemins d’accès :

Emplacement Exemples Entrée Sortie
Chemin sur votre ordinateur local ./home/username/data/my_data ✓
Chemin sur un serveur http(s) public https://raw.githubusercontent.com/pandas-dev/pandas/main/doc/data/titanic.csv ✓
Chemin dans Stockage Azure wasbs://<container_name>@<account_name>.blob.core.windows.net/<path>
abfss://<file_system>@<account_name>.dfs.core.windows.net/<path>		 Non suggéré, car il peut avoir besoin d’une configuration d’identité supplémentaire pour lire les données.
Un chemin d’accès sur un magasin de données Azure Machine Learning azureml://datastores/<data_store_name>/paths/<path> ✓ ✓
Chemin d’accès à une ressource de données azureml:<my_data>:<version> ✓ ✓

Remarque

Pour les entrées et sorties sur le stockage, nous vous recommandons vivement d’utiliser le chemin d’accès du magasin de données Azure Machine Learning à la place du chemin d’accès direct de stockage Azure. Le chemin d’accès du magasin de données est pris en charge pour différents types de travaux dans le pipeline.

Pour l’entrée et sortie des données, vous pouvez choisir parmi différents modes (téléchargement, montage ou chargement) pour définir la façon dont les données sont accessibles dans la cible de calcul. Ce tableau présente les modes possibles pour différentes combinaisons de type/mode/entrée/sortie.

Type Entrée/sortie upload download ro_mount rw_mount direct eval_download eval_mount
uri_folder Entrée ✓ ✓ ✓
uri_file Entrée ✓ ✓ ✓
mltable Entrée ✓ ✓ ✓ ✓ ✓
uri_folder Sortie ✓ ✓
uri_file Sortie ✓ ✓
mltable Sortie ✓ ✓ ✓

Remarque

Dans la plupart des cas, nous vous suggérons d’utiliser le mode ro_mount ou rw_mount. Pour plus d’informations sur le mode, consultez les modes de ressources de données.

Représentation visuelle dans Azure Machine Learning studio

Les captures d’écran suivantes fournissent un exemple d’affichage des entrées et des sorties dans un travail de pipeline dans Azure Machine Learning studio. Ce travail particulier, nommé nyc-taxi-data-regression, se trouve dans azureml-example.

Dans la page de travail de pipeline de Studio, les entrées et sorties du type de modèle/données d’un composant s’affichent sous la forme d’un petit cercle dans le composant correspondant, appelé port d’entrée/de sortie. Ces ports représentent le flux de données dans un pipeline.

La sortie au niveau du pipeline s’affiche sous la forme d’une zone violette pour faciliter l’identification.

Screenshot highlighting the pipeline input and output port.

Lorsque vous pointez la souris sur un port d’entrée et sortie, le type s’affiche.

Screenshot highlighting the port type when hovering the mouse.

Les entrées de type primitif ne s’affichent pas sur le graphique. Il se trouve dans l’onglet Paramètres du panneau de vue d’ensemble du travail de pipeline (pour les entrées au niveau du pipeline) ou dans le panneau des composants (pour les entrées au niveau du composant). La capture d’écran suivante montrant l’onglet Paramètres d’un travail de pipeline, il peut être ouvert en sélectionnant le lien Vue d’ensemble du travail.

Si vous souhaitez vérifier les entrées pour un composant, double-cliquez sur le composant pour ouvrir le panneau du composant.

Screenshot highlighting the job overview setting panel.

De même, lors de la modification d’un pipeline dans le concepteur, vous pouvez trouver les entrées et les sorties dans le panneau Interface du pipeline, et les entrées et les sorties du composant dans le panneau du composant (qui s’affiche quand vous double-cliquez sur le composant).

Screenshot highlighting the pipeline interface in designer.

Comment promouvoir les entrées et les sorties d’un composant au niveau du pipeline

La promotion de l’entrée et de la sortie d’un composant au niveau du pipeline vous permet de remplacer l’entrée et la sortie du composant lors de l’envoi d’un travail de pipeline. Elle est également utile si vous souhaitez déclencher le pipeline à l’aide d’un point de terminaison REST.

Voici des exemples pour promouvoir les entrées et les sorties de composant aux entrées et sorties au niveau du pipeline.

$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}}

L’exemple complet se trouve dans le pipeline train-score-eval avec des composants inscrits. Ce pipeline promeut trois entrées et trois sorties au niveau du pipeline. Prenons pipeline_job_training_max_epocs comme exemple. Il est déclaré sous la section inputs au niveau de la racine, ce qui signifie que son entrée se situe au niveau du pipeline. Sous la section jobs -> train_job, l’entrée nommée max_epocs est référencée comme ${{parent.inputs.pipeline_job_training_max_epocs}}, ce qui indique que l’entrée de train_jobmax_epocs fait référence à l’entrée pipeline_job_training_max_epocs au niveau du pipeline. De même, vous pouvez promouvoir la sortie du pipeline à l’aide du même schéma.

Studio

Vous pouvez promouvoir l’entrée d’un composant en entrée au niveau du pipeline dans la page de création du concepteur. Accédez au volet de paramètres du composant en double-cliquant sur le composant -> recherchez l’entrée que vous souhaitez promouvoir -> sélectionnez les trois points à droite -> sélectionnez Ajouter à l’entrée du pipeline.

Screenshot highlighting how to promote to pipeline input in designer.

Entrée facultative

Par défaut, toutes les entrées sont requises et doivent recevoir une valeur (ou une valeur par défaut) chaque fois que vous envoyez un travail de pipeline. Toutefois, il peut arriver que vous ayez besoin d’entrées facultatives. Dans ce cas, vous avez la possibilité de ne pas attribuer de valeur à l’entrée lors de l’envoi d’un travail de pipeline.

L’entrée facultative peut être utile dans deux scénarios ci-dessous :

  • Si vous disposez d’une entrée de type données/modèle facultative et que vous ne lui attribuez pas de valeur lors de l’envoi du travail de pipeline, un composant dans le pipeline n’a pas de dépendance de données précédente. En d’autres termes, le port d’entrée n’est lié à aucun composant ou nœud de données/modèle. Cela oblige le service de pipeline à appeler ce composant directement, au lieu d’attendre que la dépendance précédente soit prête.

  • La capture d’écran ci-dessous fournit un exemple clair du deuxième scénario. Si vous définissez continue_on_step_failure = True pour le pipeline et que vous avez un deuxième nœud (node2) qui utilise la sortie du premier nœud (node1) comme entrée facultative, node2 est toujours exécuté même si node1 échoue. Toutefois, si node2 utilise l’entrée requise de node1, il n’est pas exécuté si node1 échoue.

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

Voici des exemples sur la définition d’une entrée facultative.

$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
version: 9
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}}

Lorsque l’entrée est définie comme optional = true, vous devez utiliser $[[]] pour adapter la ligne de commande avec des entrées. Consultez la ligne mise en surbrillance dans l’exemple ci-dessus.

Remarque

La sortie facultative n’est pas prise en charge.

Dans le graphique de pipeline, les entrées facultatives du type de données/modèle sont représentées par un cercle en pointillés. Les entrées facultatives des types primitifs peuvent se trouver sous l’onglet Paramètres. Contrairement aux entrées requises, les entrées facultatives ne comportent pas d’astérisque, ce qui signifie qu’elles ne sont pas obligatoires.

Screenshot highlighting the optional input.

Comment personnaliser le chemin de sortie

Par défaut, la sortie d’un composant est stockée dans azureml://datastores/${{default_datastore}}/paths/${{name}}/${{output_name}}. {default_datastore} est défini par le client du magasin de données par défaut pour le pipeline. S’il n’est pas défini, il s’agit du stockage d’objets blob de l’espace de travail. {name} est le nom du travail, qui sera résolu au moment de l’exécution du travail. {output_name} est le nom de sortie défini par le client dans le composant YAML.

Toutefois, vous pouvez également personnaliser l’emplacement de stockage de la sortie en définissant le chemin d’accès d’une sortie. Voici quelques exemples :

pipeline.yaml définit un pipeline qui a trois sorties au niveau du pipeline. Le YAML complet se trouve dans l’exemple de pipeline train-score-eval avec des composants inscrits. Vous pouvez utiliser la commande suivante pour définir le chemin d’accès de sortie personnalisé pour la sortie 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

Comment télécharger la sortie

Vous pouvez télécharger la sortie d’un composant ou d’un pipeline en suivant l’exemple ci-dessous.

Télécharger la sortie au niveau du pipeline

# 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>

Télécharger la sortie du travail enfant

Lorsque vous devez télécharger la sortie d’un travail enfant (une sortie de composant qui n’est pas promue au niveau du pipeline), vous devez d’abord répertorier toutes les entités de travail enfant d’un travail de pipeline, puis utiliser du code similaire pour télécharger la sortie.

# 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>

Comment inscrire la sortie en tant que ressource nommée

Vous pouvez inscrire la sortie d’un composant ou d’un pipeline en tant que ressource nommée en affectant name et version à la sortie. La ressource inscrite peut être listée dans votre espace de travail par le biais de l’interface utilisateur/CLI/kit de développement logiciel (SDK) de Studio, et également être référencée dans vos travaux futurs.

Enregistrer la sortie du pipeline

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

Enregistrer la sortie d’un travail enfant

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

Étapes suivantes