Schéma YAML du travail de balayage CLI (v2)

Article
03/07/2024

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

Le schéma JSON source se trouve à l’adresse https://azuremlschemas.azureedge.net/latest/sweepJob.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, vous pouvez appeler des achèvements de schéma et de ressource si vous ajoutez `$schema` en haut de votre fichier.
`type`	const	Obligatoire. Le type de travail.	`sweep`	`sweep`
`name`	string	Nom du travail. Doit être unique pour tous les travaux de l’espace de travail. S’il est omis, Azure Machine Learning génère automatiquement un GUID pour le nom.
`display_name`	string	Nom complet du travail dans l’interface utilisateur de Studio. Peut être non unique dans l’espace de travail. S’il est omis, Azure Machine Learning génère automatiquement un identificateur adjectif-nom lisible pour le nom d’affichage.
`experiment_name`	string	Organisez le travail sous le nom de l’expérience. L’enregistrement d’exécution de chaque travail est organisé sous l’expérience correspondante, sous l’onglet « Expériences » du Studio. En cas d’omission, Azure Machine Apprentissage est `experiment_name` défini par défaut sur le nom du répertoire de travail où le travail a été créé.
`description`	string	Description du travail.
`tags`	object	Dictionnaire d’étiquettes pour le travail.
`sampling_algorithm`	object	Obligatoire. Algorithme d’échantillonnage d’hyperparamètres à utiliser sur le `search_space`. RandomSamplingAlgorithm, GridSamplingAlgorithm ou BayesianSamplingAlgorithm.
`search_space`	object	Obligatoire. Définir l’espace de recherche d’hyperparamètres. Le nom d’hyperparamètre est la clé et la valeur est l’expression de paramètre. Les hyperparamètres peuvent être référencés dans l’expression `trial.command${{ search_space.<hyperparameter> }}` .
`search_space.<hyperparameter>`	object	Visitez les expressions de paramètre pour l’ensemble d’expressions possibles à utiliser.
`objective.primary_metric`	string	Obligatoire. Nom de la métrique principale signalée par chaque travail d’évaluation. La métrique doit être consignée dans le script d’entraînement de l’utilisateur à l’aide `mlflow.log_metric()` du même nom de métrique correspondant.
`objective.goal`	string	Obligatoire. Objectif d’optimisation de `objective.primary_metric`.	`maximize`, `minimize`
`early_termination`	object	Stratégie d’arrêt anticipé à utiliser. Un travail d’évaluation est annulé quand les critères de la stratégie spécifiée sont satisfaits. En cas d’omission, aucune stratégie d’arrêt anticipé n’est appliquée. BanditPolicy, MedianStoppingPolicy ou TruncationSelectionPolicy.
`limits`	object	Limites du travail de balayage. Consultez Attributs de la clé `limits`.
`compute`	string	Obligatoire. Nom de la cible de calcul sur laquelle exécuter le travail, avec la `azureml:<compute_name>` syntaxe.
`trial`	object	Obligatoire. Modèle de travail pour chaque évaluation. Chaque travail d’essai est fourni avec une combinaison différente de valeurs d’hyperparamètres que les échantillons système de l’objet `search_space`. Visitez les attributs de la `trial` clé.
`inputs`	object	Dictionnaire d’entrées du travail. La clé est un nom pour l’entrée dans le contexte du travail et la valeur est la valeur d’entrée. Les entrées peuvent être référencées dans la `command` à l’aide de l’expression `${{ inputs.<input_name> }}`.
`inputs.<input_name>`	nombre, entier, booléen, chaîne ou objet	Une valeur littérale (de type number, integer, boolean ou string) ou un objet qui contient une spécification de données d’entrée de travail.
`outputs`	object	Dictionnaire des configurations de sortie du travail. La clé est un nom pour l’entrée dans le contexte du travail et la valeur est la configuration de sortie. Les sorties peuvent être référencées dans la `command` à l’aide de l’expression `${{ outputs.<output_name> }}`.
`outputs.<output_name>`	object	Vous pouvez laisser l’objet vide et, dans ce cas, par défaut, la sortie est de `uri_folder` type et Azure Machine Apprentissage génère un emplacement de sortie pour la sortie. Tous les fichiers du répertoire de sortie sont écrits via le montage en lecture-écriture. Pour spécifier un mode différent pour la sortie, fournissez un objet qui contient la spécification de sortie du travail.
`identity`	object	L’identité est utilisée pour l’accès aux données. Il peut s’agir de la configuration de l’identité utilisateur, de la configuration de l’identité managée ou de none. Pour UserIdentityConfiguration, l’identité du submitter de travail est utilisée pour accéder aux données d’entrée et écrire le résultat dans le dossier de sortie. Sinon, l’identité managée de la cible de calcul est utilisée.

Algorithmes d’échantillonnage

RandomSamplingAlgorithm

Clé	Type	Description	Valeurs autorisées	Valeur par défaut
`type`	const	Obligatoire. Type d’algorithme d’échantillonnage.	`random`
`seed`	entier	Valeur initiale aléatoire à utiliser pour initialiser la génération de nombres aléatoires. Si elle est omise, la valeur initiale par défaut est Null.
`rule`	string	Type d’échantillonnage aléatoire à utiliser. La valeur par défaut, `random`utilise un échantillonnage aléatoire uniforme simple, tandis qu’il `sobol` utilise la séquence quasi aléatoire Sobol.	`random`, `sobol`	`random`

GridSamplingAlgorithm

Clé	Type	Description	Valeurs autorisées
`type`	const	Obligatoire. Type d’algorithme d’échantillonnage.	`grid`

BayesianSamplingAlgorithm

Clé	Type	Description	Valeurs autorisées
`type`	const	Obligatoire. Type d’algorithme d’échantillonnage.	`bayesian`

Stratégies d’arrêt anticipé

BanditPolicy

Clé	Type	Description	Valeurs autorisées	Valeur par défaut
`type`	const	Obligatoire. Type de stratégie.	`bandit`
`slack_factor`	number	Ratio utilisé pour calculer la distance autorisée par rapport à l’évaluation la plus performante. `slack_factor` ou `slack_amount` est obligatoire.
`slack_amount`	nombre	Distance absolue autorisée à partir de l’évaluation la plus performante. `slack_factor` ou `slack_amount` est obligatoire.
`evaluation_interval`	entier	Fréquence d’application de la stratégie.		`1`
`delay_evaluation`	entier	Nombre d’intervalles pour lesquels retarder la première évaluation de la stratégie. S’il est spécifié, la stratégie s’applique à chaque multiple de `evaluation_interval` supérieur ou égal à `delay_evaluation`.		`0`

MedianStoppingPolicy

Clé	Type	Description	Valeurs autorisées	Valeur par défaut
`type`	const	Obligatoire. Type de stratégie.	`median_stopping`
`evaluation_interval`	entier	Fréquence d’application de la stratégie.		`1`
`delay_evaluation`	entier	Nombre d’intervalles pour lesquels retarder la première évaluation de la stratégie. S’il est spécifié, la stratégie s’applique à chaque multiple de `evaluation_interval` supérieur ou égal à `delay_evaluation`.		`0`

TruncationSelectionPolicy

Clé	Type	Description	Valeurs autorisées	Valeur par défaut
`type`	const	Obligatoire. Type de stratégie.	`truncation_selection`
`truncation_percentage`	entier	Obligatoire. Pourcentage de travaux d’évaluation à annuler à chaque intervalle d’évaluation.
`evaluation_interval`	entier	Fréquence d’application de la stratégie.		`1`
`delay_evaluation`	entier	Nombre d’intervalles pour lesquels retarder la première évaluation de la stratégie. S’il est spécifié, la stratégie s’applique à chaque multiple de `evaluation_interval` supérieur ou égal à `delay_evaluation`.		`0`

Expressions de paramètre

Option

Clé	Type	Description	Valeurs autorisées
`type`	const	Obligatoire. Type d’expression.	`choice`
`values`	tableau	Obligatoire. Liste des valeurs discrètes à partir de laquelle choisir.

Randint

Clé	Type	Description	Valeurs autorisées
`type`	const	Obligatoire. Type d’expression.	`randint`
`upper`	entier	Obligatoire. Limite supérieure exclusive pour la plage d’entiers.

Qlognormal, qnormal

Clé	Type	Description	Valeurs autorisées
`type`	const	Obligatoire. Type d’expression.	`qlognormal`, `qnormal`
`mu`	nombre	Obligatoire. Moyenne de la distribution normale.
`sigma`	nombre	Obligatoire. Écart type de la distribution normale.
`q`	entier	Obligatoire. Facteur de lissage.

Qloguniform, quniform

Clé	Type	Description	Valeurs autorisées
`type`	const	Obligatoire. Type d’expression.	`qloguniform`, `quniform`
`min_value`	nombre	Obligatoire. Valeur minimale de la plage (inclusive).
`max_value`	nombre	Obligatoire. Valeur maximale de la plage (inclusive).
`q`	entier	Obligatoire. Facteur de lissage.

Lognormal, normal

Clé	Type	Description	Valeurs autorisées
`type`	const	Obligatoire. Type d’expression.	`lognormal`, `normal`
`mu`	nombre	Obligatoire. Moyenne de la distribution normale.
`sigma`	nombre	Obligatoire. Écart type de la distribution normale.

Loguniform

Clé	Type	Description	Valeurs autorisées
`type`	const	Obligatoire. Type d’expression.	`loguniform`
`min_value`	number	Obligatoire. La valeur minimale de la plage est `exp(min_value)` (inclusive).
`max_value`	number	Obligatoire. La valeur maximale de la plage est `exp(max_value)` (inclusive).

Uniforme

Clé	Type	Description	Valeurs autorisées
`type`	const	Obligatoire. Type d’expression.	`uniform`
`min_value`	number	Obligatoire. Valeur minimale de la plage (inclusive).
`max_value`	nombre	Obligatoire. Valeur maximale de la plage (inclusive).

Attributs de la clé `limits`

Clé	Type	Description	Valeur par défaut
`max_total_trials`	entier	Nombre maximal de travaux d’évaluation.	`1000`
`max_concurrent_trials`	entier	Nombre maximal de travaux d’évaluation qui peuvent s’exécuter simultanément.	La valeur par défaut est `max_total_trials`.
`timeout`	entier	Durée maximale en secondes pendant laquelle le travail de balayage entier est autorisé à s’exécuter. Une fois cette limite atteinte, le système annule le travail de balayage, y compris toutes ses essais.	`5184000`
`trial_timeout`	entier	Durée maximale, en minutes, pendant laquelle l’exécution de chaque travail d’évaluation est autorisée. Une fois cette limite atteinte, le système annule la version d’évaluation.

Attributs de la clé `trial`

Clé	Type	Description	Valeur par défaut
`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 travail.
`environment`	chaîne ou objet	Obligatoire. L’environnement à utiliser pour le travail. Cette valeur peut être une référence à un environnement versionné 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 `name` propriétés et `version` les propriétés, car les environnements inline ne les prennent pas en charge.
`environment_variables`	object	Dictionnaire de paires nom-valeur de variable d’environnement à définir sur le processus dans lequel la commande est exécutée.
`distribution`	object	Configuration de la distribution pour les scénarios de formation distribués. Une des configurations Mpi, PyTorch Configuration ou TensorFlow.
`resources.instance_count`	entier	Nombre de nœuds à dédier au travail.	`1`

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ées du travail

Clé	Type	Description	Valeurs autorisées	Valeur par défaut
`type`	string	Le type d’entrée de travail. Spécifiez `uri_file` pour les données d’entrée qui pointent vers une source de fichier unique, ou `uri_folder` pour les données d’entrée qui pointent vers une source de dossier. Pour plus d’informations, consultez En savoir plus sur l’accès aux données.	`uri_file`, , `uri_foldermltable`, ,`mlflow_model`	`uri_folder`
`path`	string	Le chemin vers les données à utiliser comme entrée. Cette valeur peut être spécifiée de plusieurs façons : - Chemin local du fichier ou dossier de source de données, par exemple `path: ./iris.csv`. Les données sont chargées pendant l’envoi du travail. - URI d’un chemin d’accès cloud au fichier ou dossier à utiliser comme entrée. Les types d’URI pris en charge sont `azureml`, `https`, `wasbs`, `abfss` et `adl`. Pour plus d’informations sur l’utilisation `azureml://` du format URI, consultez la syntaxe yaml Core. - Une ressource de données Azure Machine Learning inscrite existante à utiliser comme entrée. Pour référencer une ressource de données inscrite, utilisez la `azureml:<data_name>:<data_version>` syntaxe ou `azureml:<data_name>@latest` (pour référencer la dernière version de cette ressource de données) ( par exemple, `path: azureml:cifar10-data:1` ou `path: azureml:cifar10-data@latest`.
`mode`	string	Mode de remise des données à la cible de calcul. Pour le montage en lecture seule (`ro_mount`), les données sont consommées en tant que chemin de montage. Un dossier est monté en tant que dossier et un fichier est monté en tant que fichier. Azure Machine Apprentissage résout l’entrée vers le chemin de montage. Pour `download` le mode, les données sont téléchargées sur la cible de calcul. Azure Machine Apprentissage résout l’entrée vers le chemin téléchargé. Pour simplement l’URL de l’emplacement de stockage de l’artefact de données ou des artefacts, au lieu de monter ou de télécharger les données proprement dites, utilisez le `direct` mode. Cela passe l’URL de l’emplacement de stockage en tant qu’entrée de travail. Dans ce cas, vous êtes entièrement responsable de la gestion des informations d’identification pour accéder au stockage.	`ro_mount`, , `downloaddirect`	`ro_mount`

Sorties du travail

Clé	Type	Description	Valeurs autorisées	Valeur par défaut
`type`	string	Type de sortie du travail. Pour le type `uri_folder` par défaut, la sortie correspond à un dossier.	`uri_file`, , `uri_foldermltable`, ,`mlflow_model`	`uri_folder`
`mode`	string	Mode de remise du fichier de sortie ou des fichiers au stockage de destination. Pour le mode de montage en lecture-écriture (`rw_mount`), le répertoire de sortie est un répertoire monté. Pour le mode de chargement, tous les fichiers écrits sont chargés à la fin du travail.	`rw_mount`, `upload`	`rw_mount`

Configurations d’identité

UserIdentityConfiguration

Clé	Type	Description	Valeurs autorisées
`type`	const	Obligatoire. Type d’identité.	`user_identity`

ManagedIdentityConfiguration

Clé	Type	Description	Valeurs autorisées
`type`	const	Obligatoire. Type d’identité.	`managed` ou `managed_identity`

Notes

Vous pouvez utiliser la az ml job commande pour gérer les travaux Azure Machine Apprentissage.

Exemples

Consultez les exemples de référentiel GitHub pour obtenir des exemples. Vous en trouverez plusieurs ici :

YAML : hello sweep

$schema: https://azuremlschemas.azureedge.net/latest/sweepJob.schema.json
type: sweep
trial:
  command: >-
    python hello-sweep.py
    --A ${{inputs.A}}
    --B ${{search_space.B}}
    --C ${{search_space.C}}
  code: src
  environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest
inputs:
  A: 0.5
sampling_algorithm: random
search_space:
  B:
    type: choice
    values: ["hello", "world", "hello_world"]
  C:
    type: uniform
    min_value: 0.1
    max_value: 1.0
objective:
  goal: minimize
  primary_metric: random_metric
limits:
  max_total_trials: 4
  max_concurrent_trials: 2
  timeout: 3600
display_name: hello-sweep-example
experiment_name: hello-sweep-example
description: Hello sweep job example.

YAML : réglage d’hyperparamètre du modèle Python de base

$schema: https://azuremlschemas.azureedge.net/latest/sweepJob.schema.json
type: sweep
trial:
  code: src
  command: >-
    python main.py 
    --iris-csv ${{inputs.iris_csv}}
    --C ${{search_space.C}}
    --kernel ${{search_space.kernel}}
    --coef0 ${{search_space.coef0}}
  environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest
inputs:
  iris_csv: 
    type: uri_file
    path: wasbs://datasets@azuremlexamples.blob.core.windows.net/iris.csv
compute: azureml:cpu-cluster
sampling_algorithm: random
search_space:
  C:
    type: uniform
    min_value: 0.5
    max_value: 0.9
  kernel:
    type: choice
    values: ["rbf", "linear", "poly"]
  coef0:
    type: uniform
    min_value: 0.1
    max_value: 1
objective:
  goal: minimize
  primary_metric: training_f1_score
limits:
  max_total_trials: 20
  max_concurrent_trials: 10
  timeout: 7200
display_name: sklearn-iris-sweep-example
experiment_name: sklearn-iris-sweep-example
description: Sweep hyperparemeters for training a scikit-learn SVM on the Iris dataset.

Étapes suivantes

Installer et utiliser l’interface CLI (v2)

Schéma YAML du travail de balayage CLI (v2)

Syntaxe YAML

Algorithmes d’échantillonnage

RandomSamplingAlgorithm

GridSamplingAlgorithm

BayesianSamplingAlgorithm

Stratégies d’arrêt anticipé

BanditPolicy

MedianStoppingPolicy

TruncationSelectionPolicy

Expressions de paramètre

Option

Randint

Qlognormal, qnormal

Qloguniform, quniform

Lognormal, normal

Loguniform

Uniforme

Attributs de la clé limits

Attributs de la clé trial

Configurations de distribution

MpiConfiguration

PyTorchConfiguration

TensorFlowConfiguration

Entrées du travail

Sorties du travail

Configurations d’identité

UserIdentityConfiguration

ManagedIdentityConfiguration

Notes

Exemples

YAML : hello sweep

YAML : réglage d’hyperparamètre du modèle Python de base

Étapes suivantes

Ressources supplémentaires

Attributs de la clé `limits`

Attributs de la clé `trial`