Syntaxe YAML fondamentale de CLI (v2)

  • Article

S’APPLIQUE À :Extension Azure CLI ml v2 (actuel)

Chaque entité Azure Machine Learning a une représentation YAML schématisée. Vous pouvez créer une entité à partir d’un fichier de configuration YAML avec une extension .yml ou .yaml.

Cet article fournit une vue d’ensemble des concepts de la syntaxe fondamentale que vous rencontrerez lors de la configuration de ces fichiers YAML.

Référencement d’une entité Azure Machine Learning

Azure Machine Learning fournit une syntaxe de référence (en formats abrégé et long) pour référencer une entité Azure Machine Learning existante lors de la configuration d’un fichier YAML. Par exemple, vous pouvez référencer un environnement enregistré existant dans votre espace de travail afin de l’utiliser comme environnement pour un travail.

Référencement d’une ressource Azure Machine Learning

Il existe deux options pour référencer une ressource Azure Machine Learning (environnements, modèles, données et composants) :

  • Référencer une version explicite d’une ressource :

    • Syntaxe raccourcie : azureml:<asset_name>:<asset_version>
    • la syntaxe Longhand, qui comprend l’ID de ressource Azure Resource Manager (ARM) de la ressource :
    azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/environments/<environment-name>/versions/<environment-version>

  • Référencez la version la plus récente d’une ressource :

    Dans certains scénarios, vous souhaiterez peut-être référencer la dernière version d’une ressource sans devoir rechercher explicitement et spécifier la chaîne de version proprement dite. La dernière version est définie comme la version la plus récente (également connue sous le nom de dernière) d’une ressource sous un nom donné.

    Vous pouvez référencer la version la plus récente à l’aide de la syntaxe suivante : azureml:<asset_name>@latest. Azure Machine Learning permet de résoudre la référence à une version de ressource explicite dans l’espace de travail.

Référencer une ressource Azure Machine Learning

Pour référencer une ressource Azure Machine Learning (par exemple, calcul), vous pouvez utiliser l’une des syntaxes suivantes :

  • Syntaxe raccourcie : azureml:<resource_name>
  • La syntaxe longhand, qui comprend l’ID de ressource ARM de la ressource :
azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/computes/<compute-name>

Informations de référence URI Azure Machine Learning

Azure Machine Learning offre un format d’URI de référence de données pratique pour pointer vers des données dans un service de stockage Azure. Celui-ci peut être utilisé dans des scénarios où vous devez spécifier un emplacement de stockage cloud dans votre fichier YAML, par exemple, lorsque vous créez un modèle Azure Machine Learning à partir de fichiers dans le stockage, ou pointez vers des données à transmettre en tant qu’entrée à un travail.

Pour utiliser ce format d’URI de données, le service de stockage que vous souhaitez référencer doit être préalablement enregistré en tant que magasin de données dans votre espace de travail. Azure Machine Learning gère l’accès aux données à l’aide des informations d’identification que vous avez fournies lors de la création du magasin de données.

Le format se compose d’un magasin de données dans l’espace de travail actuel, et du chemin d’accès dans ce magasin de données au fichier ou dossier vers lesquels vous souhaitez pointer :

azureml://datastores/<datastore-name>/paths/<path-on-datastore>/

Par exemple :

  • azureml://datastores/workspaceblobstore/paths/example-data/
  • azureml://datastores/workspaceblobstore/paths/example-data/iris.csv

En plus de l’URI de référence de données Azure Machine Learning, Azure Machine Learning prend en charge les protocoles d’URI de stockage direct https , wasbs , abfss et adl, ainsi que les URI http et https publics.

Syntaxe d’expression pour la configuration des travaux et composants Azure Machine Learning

Les fichiers YAML v2 de travail et de composant permettent d’utiliser des expressions pour la liaison à des contextes dans différents scénarios. Le cas d’usage essentiel consiste à utiliser une expression pour une valeur qui peut ne pas être connue au moment de la création de la configuration, mais qui doit être résolue au moment de l’exécution.

Utilisez la syntaxe suivante pour indiquer à Azure Machine Learning d’évaluer une expression au lieu de la traiter comme une chaîne :

${{ <expression> }}

Les scénarios pris en charge sont décrits ci-dessous.

Paramétrage de la command avec les contextes inputs et outputs d’un travail

Vous pouvez spécifier des valeurs littérales, des chemins d’accès d’URI et des ressources de données Azure Machine Learning enregistrées comme entrées d’un travail. La command peut ensuite être paramétrée avec des références à ces entrées à l’aide de la syntaxe ${{inputs.<input_name>}}. Les références aux entrées littérales seront résolues en la valeur littérale lors du runtime, tandis que les références à des entrées de données seront résolues en chemin de téléchargement ou chemin de montage (selon le mode spécifié).

De même, les sorties vers le travail peuvent également être référencées dans la command. Pour chaque sortie nommée spécifiée dans le dictionnaire outputs, Azure Machine Learning génère automatiquement un emplacement de sortie sur le magasin de données par défaut dans lequel vous pouvez écrire des fichiers. L’emplacement de sortie de chaque sortie nommée est basé sur le chemin d’accès modélisé suivant : <default-datastore>/azureml/<job-name>/<output_name>/. Le paramétrage de la command avec la syntaxe ${{outputs.<output_name>}} permet de résoudre cette référence en chemin d’accès généré automatiquement, afin que votre script puisse écrire des fichiers dans cet emplacement à partir du travail.

Dans l’exemple ci-dessous, pour un fichier YAML de travail de commande, la command est paramétrée avec deux entrées, une entrée littérale et une entrée de données, ainsi qu’une sortie. Lors du runtime, l’expression ${{inputs.learning_rate}} est résolue en 0.01, et l’expression ${{inputs.iris}} en chemin de téléchargement du fichier iris.csv. ${{outputs.model_dir}} sera résolu en chemin d’accès de montage de l’emplacement de sortie généré par le système correspondant à la sortie model_dir.

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: ./src
command: python train.py --lr ${{inputs.learning_rate}} --training-data ${{inputs.iris}} --model-dir ${{outputs.model_dir}}
environment: azureml:AzureML-Minimal@latest
compute: azureml:cpu-cluster
inputs:
  learning_rate: 0.01
  iris:
    type: uri_file
    path: https://azuremlexamples.blob.core.windows.net/datasets/iris.csv
    mode: download
outputs:
  model_dir:

Paramétrage de la command avec le contexte search_space d’un travail de balayage

Vous utiliserez également cette syntaxe d’expression lorsque vous effectuerez un réglage d’hyperparamètre via un travail de balayage, car les valeurs réelles des hyperparamètres ne sont pas connues au moment de la création du travail. Quand vous exécutez un travail de balayage, Azure Machine Learning sélectionne des valeurs d’hyperparamètres pour chaque évaluation basée sur le search_space. Pour accéder à ces valeurs dans votre script d’apprentissage, vous devez les passer via les arguments de ligne de commande du script. À cette fin, utilisez la syntaxe ${{search_space.<hyperparameter>}} dans la trial.command.

Dans l’exemple ci-dessous pour un fichier YAML de travail de balayage, les références ${{search_space.learning_rate}} et ${{search_space.boosting}} dans trial.command seront résolues en valeurs d’hyperparamètres réelles sélectionnées pour chaque évaluation lors de la soumission du travail d’évaluation pour exécution.

$schema: https://azuremlschemas.azureedge.net/latest/sweepJob.schema.json
type: sweep
sampling_algorithm:
  type: random
search_space:
  learning_rate:
    type: uniform
    min_value: 0.01
    max_value: 0.9
  boosting:
    type: choice
    values: ["gbdt", "dart"]
objective:
  goal: minimize
  primary_metric: test-multi_logloss
trial:
  code: ./src
  command: >-
    python train.py 
    --training-data ${{inputs.iris}}
    --lr ${{search_space.learning_rate}}
    --boosting ${{search_space.boosting}}
  environment: azureml:AzureML-Minimal@latest
inputs:
  iris:
    type: uri_file
    path: https://azuremlexamples.blob.core.windows.net/datasets/iris.csv
    mode: download
compute: azureml:cpu-cluster

Liaison d’entrées et de sorties entre les étapes d’un travail de pipeline

Des expressions sont également utilisées pour lier des entrées et sorties entre les étapes d’un travail de pipeline. Par exemple, vous pouvez lier l’entrée d’un travail (travail B) dans un pipeline à la sortie d’un autre travail (travail A). Cette utilisation signale à Azure Machine Learning le flux de dépendance du graphique de pipeline, et le travail B est exécuté après le travail A parce que la sortie du travail A est requise comme entrée pour le travail B.

Pour un fichier YAML de travail de pipeline, les sections inputs et outputs de chaque travail enfant sont évaluées dans le contexte parent (travail de pipeline de niveau supérieur). En revanche, la command est résolue en contexte actuel (travail enfant).

Il existe deux façons de lier des entrées et des sorties dans un travail de pipeline :

Lier aux entrées et sorties de niveau supérieur du travail de pipeline

Vous pouvez lier les entrées ou sorties d’un travail enfant (étape de pipeline) aux entrées/sorties du travail de pipeline parent de niveau supérieur à l’aide de la syntaxe suivante : ${{parent.inputs.<input_name>}} ou ${{parent.outputs.<output_name>}}. Cette référence est résolue en contexte parent, donc les entrées et sorties de niveau supérieur.

Dans l’exemple ci-dessous, l’entrée (raw_data) de la première étape prep est liée à l’entrée du pipeline de niveau supérieur via ${{parent.inputs.input_data}}. La sortie (model_dir) de l’étape train finale est liée à la sortie du travail de pipeline de niveau supérieur via ${{parent.outputs.trained_model}}.

Lier aux entrées et sorties d’un autre travail enfant (étape)

Pour lier les entrées et sorties d’une étape aux entrées et sorties d’une autre étape, utilisez la syntaxe suivante : ${{parent.jobs.<step_name>.inputs.<input_name>}} ou ${{parent.jobs.<step_name>.outputs.<outputs_name>}}. Là encore, cette référence est résolue en contexte parent, de sorte que l’expression commence par parent.jobs.<step_name>.

Dans l’exemple ci-dessous, l’entrée (training_data) de l’étape train est liée à la sortie (clean_data) de l’étape prep via ${{parent.jobs.prep.outputs.clean_data}}. Les données préparées à l’étape prep seront utilisées comme données d’apprentissage pour l’étape train.

En revanche, les références de contexte dans les propriétés command seront résolues en contexte actuel. Par exemple, la référence ${{inputs.raw_data}} dans la command de l’étape prep sera résolue en entrées du contexte actuel qui est le travail enfant prep. La recherche sera effectuée sur prep.inputs. Une entrée nommée raw_data doit y être définie.

$schema: https://azuremlschemas.azureedge.net/latest/pipelineJob.schema.json
type: pipeline
inputs:
  input_data: 
    type: uri_folder
    path: https://azuremlexamples.blob.core.windows.net/datasets/cifar10/
outputs:
  trained_model:
jobs:
  prep:
    type: command
    inputs:
      raw_data: ${{parent.inputs.input_data}}
    outputs:
      clean_data:
    code: src/prep
    environment: azureml:AzureML-Minimal@latest
    command: >-
      python prep.py 
      --raw-data ${{inputs.raw_data}} 
      --prep-data ${{outputs.clean_data}}
    compute: azureml:cpu-cluster
  train:
    type: command
    inputs: 
      training_data: ${{parent.jobs.prep.outputs.clean_data}}
      num_epochs: 1000
    outputs:
      model_dir: ${{parent.outputs.trained_model}}
    code: src/train
    environment: azureml:AzureML-Minimal@latest
    command: >-
      python train.py 
      --epochs ${{inputs.num_epochs}}
      --training-data ${{inputs.training_data}} 
      --model-output ${{outputs.model_dir}}
    compute: azureml:gpu-cluster

Paramétrage de la command avec les contextes inputs et outputs d’un composant

Comme la command pour un travail, la command pour un composant peut être paramétrée avec des références aux contextes inputs et outputs. Dans ce cas, la référence a trait aux entrées et sorties du composant. Quand le composant est exécuté dans un travail, Azure Machine Learning résout ces références en valeurs d’entrée et de sortie du runtime de travail spécifiées pour les entrées et sorties de composant correspondantes. Voici un exemple d’utilisation de la syntaxe de contexte pour une spécification YAML de composant de commande.

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

Définir des entrées facultatives dans la ligne de commande

Lorsque l’entrée est définie comme optional = true, vous devez utiliser $[[]] pour adapter la ligne de commande avec des entrées. Par exemple, $[[--input1 ${{inputs.input1}}]. La ligne de commande au moment de l’exécution peut avoir des entrées différentes.

  • Si vous utilisez uniquement les paramètres requis training_data et model_output, la ligne de commande ressemble à ceci :
python train.py --training_data some_input_path --learning_rate 0.01 --learning_rate_schedule time-based --model_output some_output_path

Si aucune valeur n’est spécifiée au moment de l’exécution, learning_rate et learning_rate_schedule utilisent la valeur par défaut.

  • Si toutes les entrées/sorties fournissent des valeurs pendant l’exécution, la ligne de commande ressemble à ceci :
python train.py --training_data some_input_path --max_epocs 10 --learning_rate 0.01 --learning_rate_schedule time-based --model_output some_output_path

Expressions de chemin de sortie

Les expressions suivantes peuvent être utilisées dans le chemin de sortie de votre travail :

Important

Les expressions suivantes sont résolues côté serveur, et non côté client. Pour les travaux planifiés où l’heure de création et l’heure d’envoi du travail sont différentes, les expressions sont résolues lors de l’envoi du travail. Étant donné que ces expressions sont résolues côté serveur, elles utilisent l’état actuel de l’espace de travail, et non l’état de l’espace de travail lors de la création du travail planifié. Par exemple, si vous modifiez le magasin de données par défaut de l’espace de travail après avoir créé un travail planifié, l’expression ${{default_datastore}} est résolue en fonction du nouveau magasin de données par défaut, et non du magasin de données par défaut lors de la création du travail planifié.

Expression Description Étendue
${{default_datastore}} Si le magasin de données par défaut du pipeline est configuré, cela est résolu en tant que nom de magasin de données par défaut du pipeline ; sinon , il est résolu en tant que nom de magasin de données par défaut de l’espace de travail.

Le magasin de données par défaut du pipeline peut être contrôlé à l’aide de pipeline_job.settings.default_datastore.		 Fonctionne pour tous les travaux.

Les travaux de pipeline ont un magasin de données par défaut de pipeline configurable.
${{name}} Nom du travail. Pour les pipelines, il s’agit du nom du travail d’étape, et non du nom du travail de pipeline. Fonctionne pour tous les travaux
${{output_name}} Nom de la sortie du travail Fonctionne pour tous les travaux

Par exemple, si azureml://datastores/${{default_datastore}}/paths/${{name}}/${{output_name}} est utilisé comme chemin de sortie, au moment de l’exécution, il est résolu en tant que chemin d’accès de azureml://datastores/workspaceblobstore/paths/<job-name>/model_path.

Étapes suivantes