Esquema YAML del trabajo de comando de la CLI (v2)

Artículo
04/04/2023

SE APLICA A:Extensión de ML de la CLI de Azure v2 (actual)

El esquema JSON de origen se puede encontrar en https://azuremlschemas.azureedge.net/latest/commandJob.schema.json.

Nota

La sintaxis de YAML que se detalla en este documento se basa en el esquema JSON de la versión más reciente de la extensión ML de la CLI v2. Se garantiza que esta sintaxis solo funciona con la versión más reciente de la extensión ML de la CLI v2. Dispone de los esquemas de las versiones de anteriores de la extensión en https://azuremlschemasprod.azureedge.net/.

Sintaxis de YAML

Clave	Tipo	Descripción	Valores permitidos	Valor predeterminado
`$schema`	string	Esquema de YAML. Si usa la extensión VS Code de Azure Machine Learning para crear el archivo YAML, la inclusión de `$schema` en la parte superior del archivo le permite invocar las finalizaciones del esquema y los recursos.
`type`	const	Tipo de trabajo.	`command`	`command`
`name`	string	Nombre del trabajo. Debe ser único en todos los trabajos del área de trabajo. Si se omite, Azure Machine Learning genera automáticamente un GUID para el nombre.
`display_name`	string	Nombre para mostrar del trabajo en la interfaz de usuario de Studio. Puede no ser único dentro del área de trabajo. Si se omite, Azure Machine Learning genera automáticamente un identificador adjetivo-sustantivo legible para el nombre para mostrar.
`experiment_name`	string	Nombre del experimento en el que se va a organizar el trabajo. El registro de ejecución de cada trabajo se organizará en el experimento correspondiente en la pestaña "Experiments" de Studio. Si se omite, Azure Machine Learning tomará como valor predeterminado el nombre del directorio de trabajo en que se creó el trabajo.
`description`	string	Descripción del trabajo.
`tags`	object	Diccionario de etiquetas para el trabajo.
`command`	string	Requerido (si no se usa el campo `component`). El comando que se debe ejecutar.
`code`	string	Ruta de acceso local al directorio de código fuente que se va a cargar y usar para el trabajo.
`environment`	cadena u objeto	Requerido (si no se usa el campo `component`). El entorno que se usará para el trabajo. Puede ser una referencia a un entorno con versiones existente en el área de trabajo o una especificación de entorno en línea. Para hacer referencia a un entorno existente, use la sintaxis `azureml:<environment_name>:<environment_version>` o `azureml:<environment_name>@latest` (para hacer referencia a la versión más reciente de un entorno). Para definir un entorno en línea, siga el Esquema de entorno. Excluya las propiedades `name` y `version`, ya que no se admiten para entornos en línea.
`environment_variables`	object	Diccionario de pares de clave-valor de variables de entorno que se establecerán en el proceso donde se ejecuta el comando.
`distribution`	object	La configuración de distribución para escenarios de entrenamiento distribuido. MpiConfiguration, PyTorchConfiguration o TensorFlowConfiguration.
`compute`	string	Nombre del destino de proceso en el que se ejecutará el trabajo. Puede ser una referencia a un proceso existente en el área de trabajo (mediante la sintaxis `azureml:<compute_name>`) o `local` para designar la ejecución local. Nota: Los trabajos de la canalización no admitieron `local` como `compute`.		`local`
`resources.instance_count`	integer	El número de nodos que se usarán para el trabajo.		`1`
`resources.instance_type`	string	Tipo de instancia que se usará para el trabajo. Aplicable a los trabajos que se ejecutan Azure Arc proceso de Kubernetes habilitado para el usuario (donde el destino de proceso especificado en el campo `compute` es de `type: kubernentes`). Si se omite, el valor predeterminado será el tipo de instancia predeterminado para el clúster de Kubernetes. Para más información, consulte Creación y selección de tipos de instancia de Kubernetes.
`resources.shm_size`	string	El tamaño del bloque de memoria compartida del contenedor docker. Debe tener el formato de `<number><unit>` donde el número debe ser mayor que 0 y la unidad puede ser uno de `b` (bytes), `k` (kilobytes), `m` (megabytes) o `g` (gigabytes).		`2g`
`limits.timeout`	integer	Tiempo máximo en segundos durante el que se puede ejecutar el trabajo. Una vez alcanzado este límite, el sistema cancelará el trabajo.
`inputs`	object	Diccionario de entradas para el trabajo. La clave es un nombre para la entrada dentro del contexto del trabajo y el valor es el valor de entrada. Se puede hacer referencia a las entradas en `command` mediante la expresión `${{ inputs.<input_name> }}`.
`inputs.<input_name>`	number, integer, boolean, string u object	Uno de un valor literal (de tipo número, entero, booleano o cadena) o un objeto que contiene una especificación de datos de entrada de trabajo.
`outputs`	object	Diccionario de configuraciones de salida del trabajo. La clave es un nombre para la salida dentro del contexto del trabajo y el valor es la configuración de salida. Se puede hacer referencia a las salidas en `command` mediante la expresión `${{ outputs.<output_name> }}`.
`outputs.<output_name>`	object	Puede dejar el objeto vacío, en cuyo caso de forma predeterminada la salida será de tipo `uri_folder` y Azure Machine Learning generará una ubicación de salida para la salida. Los archivos en el directorio de salida se escribirán a través del montaje de lectura y escritura. Si desea especificar un modo diferente de salida, proporcione un objeto que contenga la especificación de salida del trabajo.
`identity`	object	La identidad se usa para el acceso a datos. Puede ser UserIdentityConfiguration, ManagedIdentityConfiguration o None. Si es UserIdentityConfiguration, se usará la identidad del remitente del trabajo para acceder a los datos de entrada y escribir el resultado en la carpeta de salida; de lo contrario, se usará la identidad administrada del destino de proceso.

Configuraciones de distribución

MpiConfiguration

Clave	Tipo	Descripción	Valores permitidos
`type`	const	Necesario. Tipo de distribución.	`mpi`
`process_count_per_instance`	integer	Necesario. El número de procesos por nodo que se inician para el trabajo.

PyTorchConfiguration

Clave	Tipo	Descripción	Valores permitidos	Valor predeterminado
`type`	const	Necesario. Tipo de distribución.	`pytorch`
`process_count_per_instance`	integer	El número de procesos por nodo que se inician para el trabajo.		`1`

TensorFlowConfiguration

Clave	Tipo	Descripción	Valores permitidos	Valor predeterminado
`type`	const	Necesario. Tipo de distribución.	`tensorflow`
`worker_count`	integer	El número de trabajos que se inician para el trabajo.		Tiene como valor predeterminado `resources.instance_count`.
`parameter_server_count`	integer	El número de servidores de parámetros que se inician para el trabajo.		`0`

Entradas de trabajo

Clave	Tipo	Descripción	Valores permitidos	Valor predeterminado
`type`	string	Tipo de entrada de trabajo. Especifique `uri_file` para los datos de entrada que apunte a un único origen de archivo o `uri_folder` para los datos de entrada que apunte a un origen de carpeta.	`uri_file`, `uri_folder`, `mlflow_model`, `custom_model`	`uri_folder`
`path`	string	Ruta de acceso a los datos que se va a usar como entrada. Puede especificarse de algunas formas: - Ruta de acceso local al archivo o carpeta del origen de datos, por ejemplo, `path: ./iris.csv`. Los datos se cargarán durante el envío del trabajo. - URI de una ruta de acceso a la nube al archivo o carpeta que se va a usar como entrada. Los tipos de URI admitidos son `azureml`, `https`, `wasbs`, `abfss`, `adl`. Consulte Sintaxis principal de YAML para más información sobre cómo usar el formato de URI `azureml://`. - Recurso de datos de Azure Machine Learning registrado existente que se va a usar como entrada. Para hacer referencia a un recurso de datos registrado, use la sintaxis `azureml:<data_name>:<data_version>` o `azureml:<data_name>@latest` (para hacer referencia a la versión más reciente de ese recurso de datos), por ejemplo `path: azureml:cifar10-data:1` o `path: azureml:cifar10-data@latest`.
`mode`	string	Modo de cómo se deben entregar los datos al destino de proceso. Para el montaje de solo lectura (`ro_mount`), el conjunto de datos se consumirá como una ruta de acceso de montaje. Una carpeta se montará como una carpeta y un archivo se montará como un archivo. Azure Machine Learning resolverá la entrada en la ruta de acceso de montaje. Para el modo `download`, los datos se descargarán en el destino de proceso. Azure Machine Learning resolverá la entrada a la ruta de acceso descargada. Si solo desea la dirección URL de la ubicación de almacenamiento de los artefactos de datos en lugar de montar o descargar los datos en sí, puede usar el modo `direct`. Esto pasará la dirección URL de la ubicación de almacenamiento como entrada del trabajo. Tenga en cuenta que, en este caso, es el único responsable de controlar las credenciales para acceder al almacenamiento. Los modos `eval_mount` y `eval_download` son únicos para MLTable. Cualquiera de ellos monta los datos como una ruta de acceso o descarga los datos en el destino de proceso. Consulte Acceso a los datos en un trabajo para obtener más información sobre los modos	`ro_mount`, `download`, `direct`, `eval_download`, `eval_mount`	`ro_mount`

Salidas de trabajo

Clave	Tipo	Descripción	Valores permitidos	Valor predeterminado
`type`	string	Tipo de salida del trabajo. Para el tipo predeterminado `uri_folder`, la salida corresponderá a una carpeta.	`uri_folder` , `mlflow_model`, `custom_model`	`uri_folder`
`mode`	string	Modo de cómo se entregarán los archivos de salida al almacenamiento de destino. Para el modo de montaje de lectura y escritura (`rw_mount`), el directorio de salida será un directorio montado. En el modo de carga, los archivos escritos se cargan al final del trabajo.	`rw_mount`, `upload`	`rw_mount`

Configuraciones de identidad

UserIdentityConfiguration

Clave	Tipo	Descripción	Valores permitidos
`type`	const	Necesario. Tipo de identidad.	`user_identity`

ManagedIdentityConfiguration

Clave	Tipo	Descripción	Valores permitidos
`type`	const	Necesario. Tipo de identidad.	`managed` o `managed_identity`

Comentarios

El comando az ml job se puede usar para administrar los trabajos de Azure Machine Learning.

Ejemplos

Hay ejemplos disponibles en el repositorio de GitHub de ejemplos. A continuación, se muestran varios.

YAML: hola mundo

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: echo "hello world"
environment:
  image: library/python:latest

YAML: nombre para mostrar, nombre del experimento, descripción y etiquetas

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: echo "hello world"
environment:
  image: library/python:latest
tags:
  hello: world
display_name: hello-world-example
experiment_name: hello-world-example
description: |
  # Azure Machine Learning "hello world" job

  This is a "hello world" job running in the cloud via Azure Machine Learning!

  ## Description

  Markdown is supported in the studio for job descriptions! You can edit the description there or via CLI.

YAML: variables de entorno

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: echo $hello_env_var
environment:
  image: library/python:latest
environment_variables:
  hello_env_var: "hello world"

YAML: código fuente

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: ls
code: src
environment:
  image: library/python:latest

YAML: entradas literales

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  echo ${{inputs.hello_string}}
  echo ${{inputs.hello_number}}
environment:
  image: library/python:latest
inputs:
  hello_string: "hello world"
  hello_number: 42

YAML: escritura en salidas predeterminadas

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: echo "hello world" > ./outputs/helloworld.txt
environment:
  image: library/python:latest

YAML: escritura en la salida de datos con nombre

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: echo "hello world" > ${{outputs.hello_output}}/helloworld.txt
outputs:
  hello_output:
environment:
  image: python

YAML: entrada del archivo de URI del almacén de datos

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  echo "--iris-csv: ${{inputs.iris_csv}}"
  python hello-iris.py --iris-csv ${{inputs.iris_csv}}
code: src
inputs:
  iris_csv:
    type: uri_file 
    path: azureml://datastores/workspaceblobstore/paths/example-data/iris.csv
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest

YAML: entrada de la carpeta de URI del almacén de datos

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  ls ${{inputs.data_dir}}
  echo "--iris-csv: ${{inputs.data_dir}}/iris.csv"
  python hello-iris.py --iris-csv ${{inputs.data_dir}}/iris.csv
code: src
inputs:
  data_dir:
    type: uri_folder 
    path: azureml://datastores/workspaceblobstore/paths/example-data/
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest

YAML: entrada del archivo de URI

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  echo "--iris-csv: ${{inputs.iris_csv}}"
  python hello-iris.py --iris-csv ${{inputs.iris_csv}}
code: src
inputs:
  iris_csv:
    type: uri_file 
    path: https://azuremlexamples.blob.core.windows.net/datasets/iris.csv
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest

YAML: entrada de la carpeta de URI

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  ls ${{inputs.data_dir}}
  echo "--iris-csv: ${{inputs.data_dir}}/iris.csv"
  python hello-iris.py --iris-csv ${{inputs.data_dir}}/iris.csv
code: src
inputs:
  data_dir:
    type: uri_folder 
    path: wasbs://datasets@azuremlexamples.blob.core.windows.net/
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest

YAML: cuaderno a través de Papermill

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  pip install ipykernel papermill
  papermill hello-notebook.ipynb outputs/out.ipynb -k python
code: src
environment:
  image: library/python:3.11.6

YAML: entrenamiento básico del modelo de Python

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: src
command: >-
  python main.py 
  --iris-csv ${{inputs.iris_csv}}
  --C ${{inputs.C}}
  --kernel ${{inputs.kernel}}
  --coef0 ${{inputs.coef0}}
inputs:
  iris_csv: 
    type: uri_file
    path: wasbs://datasets@azuremlexamples.blob.core.windows.net/iris.csv
  C: 0.8
  kernel: "rbf"
  coef0: 0.1
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest
compute: azureml:cpu-cluster
display_name: sklearn-iris-example
experiment_name: sklearn-iris-example
description: Train a scikit-learn SVM on the Iris dataset.

YAML: entrenamiento básico del modelo de R con contexto de compilación de Docker local

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: >
  Rscript train.R 
  --data_folder ${{inputs.iris}}
code: src
inputs:
  iris: 
    type: uri_file
    path: https://azuremlexamples.blob.core.windows.net/datasets/iris.csv
environment:
  build:
    path: docker-context
compute: azureml:cpu-cluster
display_name: r-iris-example
experiment_name: r-iris-example
description: Train an R model on the Iris dataset.

YAML: PyTorch distribuido

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: src
command: >-
  python train.py 
  --epochs ${{inputs.epochs}}
  --learning-rate ${{inputs.learning_rate}}
  --data-dir ${{inputs.cifar}}
inputs:
  epochs: 1
  learning_rate: 0.2
  cifar: 
     type: uri_folder
     path: azureml:cifar-10-example@latest
environment: azureml:AzureML-pytorch-1.9-ubuntu18.04-py37-cuda11-gpu@latest
compute: azureml:gpu-cluster
distribution:
  type: pytorch 
  process_count_per_instance: 1
resources:
  instance_count: 2
display_name: pytorch-cifar-distributed-example
experiment_name: pytorch-cifar-distributed-example
description: Train a basic convolutional neural network (CNN) with PyTorch on the CIFAR-10 dataset, distributed via PyTorch.

YAML: TensorFlow distribuido

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: src
command: >-
  python train.py 
  --epochs ${{inputs.epochs}}
  --model-dir ${{inputs.model_dir}}
inputs:
  epochs: 1
  model_dir: outputs/keras-model
environment: azureml:AzureML-tensorflow-2.4-ubuntu18.04-py37-cuda11-gpu@latest
compute: azureml:gpu-cluster
resources:
  instance_count: 2
distribution:
  type: tensorflow
  worker_count: 2
display_name: tensorflow-mnist-distributed-example
experiment_name: tensorflow-mnist-distributed-example
description: Train a basic neural network with TensorFlow on the MNIST dataset, distributed via TensorFlow.

YAML: MPI distribuido

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: src
command: >-
  python train.py
  --epochs ${{inputs.epochs}}
inputs:
  epochs: 1
environment: azureml:AzureML-tensorflow-2.7-ubuntu20.04-py38-cuda11-gpu@latest
compute: azureml:gpu-cluster
resources:
  instance_count: 2
distribution:
  type: mpi
  process_count_per_instance: 1
display_name: tensorflow-mnist-distributed-horovod-example
experiment_name: tensorflow-mnist-distributed-horovod-example
description: Train a basic neural network with TensorFlow on the MNIST dataset, distributed via Horovod.

Pasos siguientes

Instalación y uso de la CLI (v2)