Schéma YAML du composant de commande CLI (v2)

  • Article

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

Le schéma JSON source se trouve à l’adresse https://azuremlschemas.azureedge.net/latest/commandComponent.schema.json.

Notes

La syntaxe YAML détaillée dans ce document est basée sur le schéma JSON pour la dernière version de l’extension ML CLI v2. Le fonctionnement de cette syntaxe est garanti uniquement avec la dernière version de l’extension ML CLI v2. Vous trouverez les schémas des versions d’extension plus anciennes sur https://azuremlschemasprod.azureedge.net/.

Syntaxe YAML

Clé Type Description Valeurs autorisées Valeur par défaut
$schema string Schéma YAML. Si vous utilisez l’extension VS Code d’Azure Machine Learning pour créer le fichier YAML, en incluant $schema en haut de votre fichier, vous pouvez appeler des complétions de schémas et de ressources.
type const Le type de composant. command command
name string Obligatoire. Nom du composant. Doit commencer par une lettre minuscule. Les caractères autorisés sont des lettres minuscules, des chiffres et des traits de soulignement (_). La longueur maximale est de 255 caractères.
version string Numéro de version du composant. En cas d’omission, Azure Machine Learning génère automatiquement une version.
display_name string Nom complet du composant dans l’interface utilisateur de Studio. Peut être non unique dans l’espace de travail.
description string Description du composant.
tags object Dictionnaire d’étiquettes pour le composant.
is_deterministic boolean Cette option détermine si le composant produira la même sortie pour les mêmes données d’entrée. Vous devez généralement la définir avec la valeur false pour les composants qui chargent des données à partir de sources externes, comme l’importation de données à partir d’une URL. C’est parce que les données à cette URL risquent de changer au fil du temps. true
command string Obligatoire. Commande à exécuter.
code string Chemin d’accès local au répertoire du code source à télécharger et à utiliser pour le composant.
environment chaîne ou objet Obligatoire. L’environnement à utiliser pour le composant. Cette valeur peut être une référence à un environnement avec version existant dans l’espace de travail ou une spécification d’environnement inline.

Pour référencer un environnement existant, utilisez la syntaxe azureml:<environment-name>:<environment-version>.

Pour définir un environnement inline, suivez le schéma de l’environnement. Excluez les propriétés name et version, car elles ne sont pas prises en charge pour les environnements inline.
distribution object Configuration de la distribution pour les scénarios de formation distribués. MpiConfiguration, PyTorchConfiguration ou TensorFlowConfiguration.
resources.instance_count entier Nombre de nœuds à dédier au travail. 1
inputs object 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 command à l’aide de l’expression ${{ inputs.<input_name> }}.
inputs.<input_name> object Définition d’entrée du composant. Consultez Entrée de composant pour l’ensemble de propriétés configurables.
outputs object 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 command à l’aide de l’expression ${{ outputs.<output_name> }}.
outputs.<output_name> object Définition de sortie du composant. Consultez Sortie du composant pour l’ensemble des propriétés configurables.

Configurations de distribution

MpiConfiguration

Clé Type Description Valeurs autorisées
type const Obligatoire. Type de distribution. mpi
process_count_per_instance entier Obligatoire. Nombre de processus par nœud à lancer pour le travail.

PyTorchConfiguration

Clé Type Description Valeurs autorisées Valeur par défaut
type const Obligatoire. Type de distribution. pytorch
process_count_per_instance entier Nombre de processus par nœud à lancer pour le travail. 1

TensorFlowConfiguration

Clé Type Description Valeurs autorisées Valeur par défaut
type const Obligatoire. Type de distribution. tensorflow
worker_count entier Nombre de Workers à lancer pour le travail. La valeur par défaut est resources.instance_count.
parameter_server_count entier Nombre de serveurs de paramètres à lancer pour le travail. 0

Entrée du composant

Clé Type Description Valeurs autorisées Valeur par défaut
type string Obligatoire. Type d’entrée du composant. En savoir plus sur l’accès aux données number, integer, boolean, string, uri_file, uri_folder, mltable, mlflow_model
description string Description de l’entrée.
default nombre, entier, booléen ou chaîne Valeur par défaut de l’entrée.
optional boolean Indique si l’entrée est requise. Si la valeur est définie sur true, vous devez utiliser la commande qui inclut des entrées facultatives avec $[[]] false
min entier ou nombre Valeur minimale acceptée pour l’entrée. Ce champ ne peut être spécifié que si le champ type est number ou integer.
max entier ou nombre Valeur maximale acceptée pour l’entrée. Ce champ ne peut être spécifié que si le champ type est number ou integer.
enum tableau Liste des valeurs autorisées pour l’entrée. Uniquement applicable si le champ type est string.

Sortie du composant

Clé Type Description Valeurs autorisées Valeur par défaut
type string Obligatoire. Type de sortie du composant. uri_file, uri_folder, mltable, mlflow_model
description string Description de la sortie.

Remarques

La commande az ml component peut être utilisée pour gérer les composants Azure Machine Learning.

Exemples

Les exemples de composant de commande sont disponibles dans le référentiel d’exemples GitHub. Certains exemples sont affichés ci-dessous.

Des exemples sont disponibles dans le référentiel d’exemples GitHub. Vous en trouverez plusieurs ci-dessous.

YAML : Composant de commande Hello World

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

name: hello_python_world
display_name: Hello_Python_World
version: 1

code: ./src

environment: 
  image: python

command: >-
  python hello.py

YAML : Composant avec différents types d’entrée

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

Erreurs courantes et recommandations

Voici quelques erreurs courantes associées à la définition d’un composant et les recommandations correspondantes.

Clé : Erreurs Recommandation
command 1. Seules les entrées facultatives peuvent se trouver dans $[[]].
2. La commande ne prend pas en charge l’utilisation de \ pour créer une ligne.
3. Les entrées ou sorties sont introuvables.		 1. Vérifiez que toutes les entrées ou sorties utilisées dans la commande sont déjà définies dans les sections inputs et outputs. Veillez aussi à utiliser le format $[[]] pour les entrées facultatives ou ${{}} pour celles obligatoires.
2. N’utilisez pas \ pour créer une ligne.
Environnement 1. Il n’existe aucune définition pour l’environnement {envName} version {envVersion}.
2. Il n’existe aucun environnement avec le nom {envName} et la version {envVersion}.
3. La ressource avec l’ID {envAssetId} est introuvable.		 1. Vérifiez que le nom et la version de l’environnement que vous référencez dans la définition du composant existent.
2. Vous devez spécifier la version si vous faites référence à un environnement inscrit.
entrées/sorties 1. Les noms des entrées/sorties sont en conflit avec les paramètres réservés au système.
2. Noms d’entrées ou de sorties en double.		 1. N’utilisez aucun de ces paramètres réservés comme noms d’entrées/sorties : path, ld_library_path, user, logname, home, pwd, shell.
2. Vérifiez que les entrées et les sorties n’ont pas des noms dupliqués.

Étapes suivantes