Créer et exécuter des pipelines Machine Learning à l’aide de composants avec l’interface CLI d’Azure Machine Learning

Article
02/05/2024

S’APPLIQUE À :Extension Azure ML CLI v2 (actuelle)

Dans cet article, vous allez apprendre à créer et exécuter un pipeline Machine Learning à l’aide d'Azure CLI et les composants. Vous pouvez créer des pipelines sans utiliser de composants, mais les composants offrent le plus de flexibilité et de possibilités de réutilisation. Vous pouvez définir des pipelines Azure Machine Learning en YAML et les exécuter à partir de l’interface CLI, les créer dans Python ou les composer dans le concepteur Azure Machine Learning studio avec une interface utilisateur par glisser-déplacer. Ce document porte sur l’interface CLI.

Prérequis

Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer. Essayez la version gratuite ou payante d’Azure Machine Learning.
Un espace de travail Azure Machine Learning. Créer des ressources d’espace de travail.
Installer et configurer l’extension Azure CLI pour Machine Learning.

Clonez le référentiel d’exemples :

git clone https://github.com/Azure/azureml-examples --depth 1
cd azureml-examples/cli/jobs/pipelines-with-components/basics

Lecture préalable suggérée

Créer votre premier pipeline avec un composant

Créons votre premier pipeline avec des composants à l’aide d’un exemple. Cette section vise à vous donner une impression initiale de ce à quoi ressemblent un pipeline et le composant dans Azure Machine Learning avec un exemple concret.

À partir du répertoire cli/jobs/pipelines-with-components/basics du référentiel azureml-examples, accédez au sous-répertoire 3b_pipeline_with_data. Il existe trois types de fichiers dans ce répertoire. Il s’agit des fichiers que vous devez créer lors de la création de votre propre pipeline.

pipeline.yml : ce fichier YAML définit le pipeline d’apprentissage automatique. Ce fichier YAML décrit comment interrompre une tâche d’apprentissage automatique complète dans un flux de travail de plusieurs étapes. Par exemple, si vous envisagez une tâche de Machine Learning simple de l’utilisation de données historiques pour effectuer l’apprentissage d’un modèle de prévision des ventes, vous pouvez créer un workflow séquentiel avec le traitement des données, la formation du modèle et les étapes d’évaluation du modèle. Chaque étape est un composant disposant d’une interface bien définie, qui peut être développé, testé et optimisé indépendamment. Le pipeline YAML définit également la façon dont les étapes enfants se connectent à d’autres étapes du pipeline. Par exemple, l’étape de formation du modèle génère un fichier de modèle et celui-ci passe à une étape d’évaluation de modèle.
component.yml : ce fichier YAML définit le composant. Il empaquette les informations suivantes :
- Métadonnées : nom, com complet, version, description, type etc. Les métadonnées permettent de décrire et de gérer le composant.
- Interface : entrées et sorties. Par exemple, un composant d’apprentissage de modèle prend des données d’apprentissage et un nombre d’époques en tant qu’entrée, et génère un fichier de modèle formé en tant que sortie. Une fois l’interface définie, différentes équipes peuvent développer et tester le composant de manière indépendante.
- Commande, code et environnement : commande, code et environnement pour exécuter le composant. La commande est la commande shell pour exécuter le composant. Le code fait généralement référence à un répertoire de code source. L’environnement peut être un environnement Azure Machine Learning (organisé ou créé par le client), une image docker ou un environnement conda.
component_src : il s’agit du répertoire de code source d’un composant spécifique. Il contient le code source qui est exécuté dans le composant. Vous pouvez utiliser votre langage préféré (Python, R...). Le code doit être exécuté par une commande d’interpréteur de commandes. Le code source peut prendre quelques entrées de la ligne de commande shell pour contrôler l’exécution de cette étape. Par exemple, une étape de formation peut prendre des données de formation, un taux d’apprentissage, un nombre d’époques pour contrôler le processus de formation. L’argument d’une commande shell permet de transmettre des entrées et des sorties au code.

Créons à présent un pipeline à l’aide de l’exemple 3b_pipeline_with_data. Nous expliquons la signification détaillée de chaque fichier dans les sections suivantes.

Commencez par répertorier vos ressources de calcul disponibles à l’aide de la commande suivante :

az ml compute list

Si vous n’en avez pas, créez un cluster appelé cpu-cluster en exécutant :

Remarque

Ignorez cette étape pour utiliser le calcul serverless.

az ml compute create -n cpu-cluster --type amlcompute --min-instances 0 --max-instances 10

À présent, créez un travail de pipeline défini dans le fichier pipeline.yml avec la commande suivante. La cible de calcul est référencée dans le fichier pipeline.yml en tant que azureml:cpu-cluster. Si votre cible de calcul utilise un autre nom, n’oubliez pas de le mettre à jour dans le fichier pipeline.yml.

az ml job create --file pipeline.yml

Vous devriez recevoir un dictionnaire JSON contenant des informations sur le travail de pipeline notamment :

Clé	Description
`name`	Le nom du travail basé sur le GUID.
`experiment_name`	Le nom sous lequel les travaux seront organisés dans studio.
`services.Studio.endpoint`	L’URL pour la surveillance et l’examen du travail de pipeline.
`status`	État du travail. Il s’agira probablement de `Preparing` à ce stade.

Ouvrez l’URL services.Studio.endpoint pour voir une visualisation graphique du pipeline.

Screenshot of a graph visualization of the pipeline.

Comprendre le YAML de définition de pipeline

Examinons la définition de pipeline dans le fichier 3b_pipeline_with_data/pipeline.yml.

Remarque

Pour utiliser le calcul serverless, remplacez default_compute: azureml:cpu-cluster par default_compute: azureml:serverless dans ce fichier.

$schema: https://azuremlschemas.azureedge.net/latest/pipelineJob.schema.json
type: pipeline

display_name: 3b_pipeline_with_data
description: Pipeline with 3 component jobs with data dependencies

settings:
  default_compute: azureml:cpu-cluster

outputs:
  final_pipeline_output:
    mode: rw_mount

jobs:
  component_a:
    type: command
    component: ./componentA.yml
    inputs:
      component_a_input: 
        type: uri_folder
        path: ./data

    outputs:
      component_a_output: 
        mode: rw_mount
  component_b:
    type: command
    component: ./componentB.yml
    inputs:
      component_b_input: ${{parent.jobs.component_a.outputs.component_a_output}}
    outputs:
      component_b_output: 
        mode: rw_mount
  component_c:
    type: command
    component: ./componentC.yml
    inputs:
      component_c_input: ${{parent.jobs.component_b.outputs.component_b_output}}
    outputs:
      component_c_output: ${{parent.outputs.final_pipeline_output}}
      #  mode: upload

Le tableau décrit les champs les plus utilisés du schéma YAML de pipeline. Pour plus d’informations, consultez le schéma YAML de pipeline complet.

key	description
type	Obligatoire. Le type de travail doit être `pipeline` pour des travaux de pipeline.
display_name	Nom complet du travail de pipeline dans l’interface utilisateur de studio. Modifiable dans l’interface utilisateur de studio. Ne doit pas être unique pour tous les travaux dans l’espace de travail.
jobs	Requis. Dictionnaire de l’ensemble des tâches individuelles à exécuter en tant qu’étapes dans le pipeline. Ces tâches sont considérées comme des tâches enfants du travail de pipeline parent. Dans cette version, les types de travaux pris en charge dans le pipeline sont `command` et `sweep`
inputs	Dictionnaire d’entrées du travail de pipeline. La clé est un nom pour l’entrée dans le contexte du travail et la valeur est la valeur d’entrée. Ces entrées de pipeline peuvent être référencées par les entrées d’un travail d’étape individuelle dans le pipeline à l’aide de l’expression ${{ parent.inputs.<input_name> }}.
outputs	Dictionnaire des configurations de sortie du travail de pipeline. La clé est un nom pour l’entrée dans le contexte du travail et la valeur est la configuration de sortie. Ces sorties de pipeline peuvent être référencées par les sorties d’un travail d’étape individuelle dans le pipeline à l’aide de l’expression ${{ parents.outputs.<output_name> }}.

Dans l’exemple 3b_pipeline_with_data, nous avons créé un pipeline en trois étapes.

Les trois étapes sont définies sous jobs. Le type des trois étapes est un travail de commande. La définition de chaque étape figure dans un fichier component.yml correspondant. Vous pouvez voir les fichiers YAML du composant dans le répertoire 3b_pipeline_with_data. Nous allons expliquer le componentA.yml dans la section suivante.
Ce pipeline a une dépendance de données, qui est courante dans la plupart des pipelines réels. Component_a prend l’entrée de données du dossier local sous ./data (lignes 17 à 20) et transmet sa sortie à componentB (ligne 29). La sortie de Component_a peut être référencée en tant que ${{parent.jobs.component_a.outputs.component_a_output}}.
Le compute définit le calcul par défaut pour ce pipeline. Si un composant sous jobs définit un calcul différent pour ce composant, le système respecte le paramètre spécifique du composant.

Lire et écrire des données dans un pipeline

Un scénario courant consiste à lire et écrire des données dans votre pipeline. Dans Azure Machine Learning, nous utilisons le même schéma pour lire et écrire des données pour tous les types de travaux (travail de pipeline, travail de commande et travail de balayage). Les exemples suivants sont des exemples de travail de pipeline utilisant des données pour des scénarios courants.

Comprendre le YAML de définition de composant

Examinons maintenant le componentA.yml comme exemple pour comprendre le YAML de définition de composant.

$schema: https://azuremlschemas.azureedge.net/latest/commandComponent.schema.json
type: command

name: component_a
display_name: componentA
version: 1

inputs:
  component_a_input:
    type: uri_folder

outputs:
  component_a_output:
    type: uri_folder

code: ./componentA_src

environment: 
  image: python

command: >-
  python hello.py --componentA_input ${{inputs.component_a_input}} --componentA_output ${{outputs.component_a_output}}

Le schéma le plus couramment utilisé du composant YAML est décrit dans le tableau. Pour plus d’informations, consultez le schéma YAML de composant complet.

key	description
name	Requis. Nom du composant. Doit être unique dans l’espace de travail Azure Machine Learning. Doit commencer par une lettre minuscule. Autoriser les lettres minuscules, les chiffres et les traits de soulignement (_). La longueur maximale est de 255 caractères.
display_name	Nom complet du composant dans l’interface utilisateur de Studio. Peut ne pas être unique dans l’espace de travail.
commande	Requis : commande à exécuter
code	Chemin d’accès local au répertoire du code source à télécharger et à utiliser pour le composant.
Environnement	Obligatoire. Environnement utilisé pour exécuter le composant.
inputs	Dictionnaire d’entrées du composant. La clé est un nom pour l’entrée dans le contexte du composant, et la valeur est la définition de l’entrée du composant. Les entrées peuvent être référencées dans la commande à l’aide de l’expression ${{ inputs.<input_name> }}.
outputs	Dictionnaire de sorties du composant. La clé est un nom pour la sortie dans le contexte du composant, et la valeur est la définition de sortie du composant. Les sorties peuvent être référencées dans la commande à l’aide de l’expression ${{ outputs.<output_name> }}.
is_deterministic	Indique s’il faut réutiliser le résultat du travail précédent si les entrées du composant n’ont pas changé. La valeur par défaut est `true`, également appelée réutilisation par défaut. Le scénario courant pour la définir sur `false` consiste à forcer le rechargement de données à partir d’un stockage cloud ou d’une URL.

Pour l’exemple dans 3b_pipeline_with_data/componentA.yml, componentA a une entrée de données et une sortie de données, qui peuvent être connectées à d’autres étapes dans le pipeline parent. Tous les fichiers figurant dans la section code du YAML de composant seront chargés dans Azure Machine Learning, lors de la soumission du travail de pipeline. Dans cet exemple, les fichiers sous ./componentA_src seront chargés (ligne 16 dans componentA.yml). Vous pouvez voir le code source chargé dans l’interface utilisateur de Studio : double-cliquez sur l’étape ComponentA et accédez à l’onglet Instantané, comme illustré dans la capture d’écran suivante. Nous pouvons voir qu’il s’agit d’un script hello-world qui effectue simplement une impression simple, et écrit la DateHeure actuelle dans le chemin componentA_output. Le composant prend l’entrée et la sortie via l’argument de ligne de commande, et il est géré dans le hello.py à l’aide de argparse.

Entrée et sortie

L’entrée et la sortie définissent l’interface d’un composant. L’entrée et la sortie pourraient être une valeur littérale (de type string, number, integer ou boolean) ou un objet contenant un schéma d’entrée.

L’entrée d’objet (de type uri_file, uri_folder, mltable, mlflow_model, custom_model) peut se connecter à d’autres étapes du travail de pipeline parent, et donc passer des données ou un modèle à d’autres étapes. Dans le graphique de pipeline, l’entrée du type d’objet s’affiche en tant que point de connexion.

Les entrées de valeur littérale (string, number, integer, boolean) sont les paramètres que vous pouvez passer au composant au moment de l’exécution. Vous pouvez ajouter une valeur par défaut d’entrées de valeurs littérales dans le champ default. Pour les types number et integer, vous pouvez également ajouter des valeurs minimale et maximale acceptées à l’aide des champs min et max. Si la valeur d’entrée dépasse les valeurs min et max, le pipeline échoue lors de la validation. La validation se produit avant que vous soumettiez un travail de pipeline pour gagner du temps. La validation fonctionne pour l’interface CLI, le Kit de développement logiciel (SDK) Python et l’interface utilisateur du concepteur. La capture d’écran suivante montre un exemple de validation dans l’interface utilisateur du concepteur. Vous pouvez également définir des valeurs autorisées dans le champ enum.

Si vous souhaitez ajouter une entrée à un composant, n’oubliez pas de modifier trois emplacements :

Champ inputs dans le YAML du composant
Champ command dans le YAML du composant.
Code source du composant pour gérer l’entrée de ligne de commande. Il est marqué dans la zone verte dans la capture d’écran précédente.

Pour en savoir plus sur les entrées et les sorties, consultez Gérer les entrées et les sorties du composant et du pipeline.

Environnement

L’environnement définit l’environnement pour exécuter le composant. Ce pourrait être un environnement Azure Machine Learning (organisé ou inscrit par le client), une image docker ou un environnement conda. Regardez les exemples suivants.

Ressource d’environnement inscrite à Azure Machine Learning. Référencée dans la syntaxe azureml:<environment-name>:<environment-version> suivante du composant.
image docker publique
fichier conda à utiliser avec une image de base.

Si certains composants sont spécifiques à un pipeline particulier, le véritable avantage des composants réside dans la réutilisation et le partage. Inscrivez un composant dans votre espace de travail Machine Learning pour le rendre disponible à la réutilisation. Les composants inscrits prennent en charge le contrôle automatique de version, ce qui vous permet de mettre à jour le composant tout en garantissant que les pipelines qui nécessitent une version antérieure continueront de fonctionner.

Dans le référentiel azureml-examples, accédez au répertoire cli/jobs/pipelines-with-components/basics/1b_e2e_registered_components.

Pour inscrire un composant, utilisez la commande az ml component create :

az ml component create --file train.yml
az ml component create --file score.yml
az ml component create --file eval.yml

Une fois l’exécution de ces commandes terminée, vous pouvez voir les composants dans Studio, sous Ressource -> Composants :

Sélectionnez un composant. Vous voyez des informations détaillées pour chaque version du composant.

Sous l’onglet Détails, vous voyez les informations de base du composant, telles que le nom, créé par, la version, etc. Vous voyez des champs modifiables pour les balises et la description. Les balises peuvent être utilisées pour ajouter des mots clés permettant une recherche rapide. Le champ de description prend en charge le formatage Markdown et doit être utilisé pour décrire la fonctionnalité et l’utilisation de base de votre composant.

Sous l’onglet Travaux, vous voyez l’historique de tous les travaux qui utilisent ce composant.

Utiliser des composants inscrits dans un fichier YAML de travail de pipeline

Utilisons 1b_e2e_registered_components pour montrer l’utilisation d’un composant inscrit dans un YAML de pipeline. Accédez au répertoire 1b_e2e_registered_components et ouvrez le fichier pipeline.yml. Les clés et les valeurs des champs inputs et outputs sont similaires à celles déjà traitées. La seule différence significative réside dans les valeurs du champ component dans les entrées jobs.<JOB_NAME>.component. La valeur component se présente sous la forme azureml:<COMPONENT_NAME>:<COMPONENT_VERSION>. La définition train-job, par exemple, spécifie que la dernière version du composant inscrit my_train doit être utilisée :

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:

Gérer les composants

Vous pouvez vérifier les détails du composant et gérer le composant à l’aide de l’interface CLI (v2). Utilisez az ml component -h pour obtenir des instructions détaillées sur la commande de composant. Le tableau suivant répertorie toutes les commandes disponibles. Pour plus d’exemples, consultez Référence Azure CLI.

commandes	description
`az ml component create`	Créer un composant
`az ml component list`	Répertorier les composants d’un espace de travail
`az ml component show`	Afficher les détails d’un composant
`az ml component update`	Mettre à jour un composant Seuls quelques champs (description, display_name) prennent en charge la mise à jour
`az ml component archive`	Archiver un conteneur de composant
`az ml component restore`	Restaurer un composant archivé

Étapes suivantes

Essayez l’exemple de composant CLI v2