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

Artículo
04/07/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/commandComponent.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 componente.	`command`	`command`
`name`	string	Necesario. Nombre del componente. Debe comenzar con una letra minúscula. Los caracteres permitidos son letras minúsculas, números y subrayado(_). La longitud máxima es de 255 caracteres.
`version`	string	Versión del componente. Si se omite, Azure Machine Learning genera automáticamente una versión.
`display_name`	string	Nombre para mostrar del componente en la interfaz de usuario de Studio. Puede no ser único dentro del área de trabajo.
`description`	string	Descripción del componente.
`tags`	object	Diccionario de etiquetas del componente.
`is_deterministic`	boolean	Esta opción determina si el componente genera la misma salida para los mismos datos de entrada. Normalmente, debe establecerlo en `false` para los componentes que cargan datos de orígenes externos, como importar datos desde una dirección URL. Esto se debe a que los datos de la dirección URL pueden cambiar con el tiempo.		`true`
`command`	string	Necesario. 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 componente.
`environment`	cadena u objeto	Necesario. Entorno que se usará para el componente. Este valor 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>`. 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.
`distribution`	object	La configuración de distribución para escenarios de entrenamiento distribuido. MpiConfiguration, PyTorchConfiguration o TensorFlowConfiguration.
`resources.instance_count`	integer	El número de nodos que se usarán para el trabajo.		`1`
`inputs`	object	Diccionario de entradas de componentes. La clave es un nombre para la entrada dentro del contexto del componente y el valor es la definición de entrada del componente. Se puede hacer referencia a las entradas en `command` mediante la expresión `${{ inputs.<input_name> }}`.
`inputs.<input_name>`	object	Definición de entrada del componente. Consulte Entrada del componente para el conjunto de propiedades configurables.
`outputs`	object	Diccionario de salidas de componentes. La clave es un nombre para la salida dentro del contexto del componente y el valor es la definición de salida del componente. Se puede hacer referencia a las salidas en `command` mediante la expresión `${{ outputs.<output_name> }}`.
`outputs.<output_name>`	object	Definición de salida del componente. Consulte Salida del componente para el conjunto de propiedades configurables.

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`

Entrada del componente

Clave	Tipo	Descripción	Valores permitidos	Valor predeterminado
`type`	string	Necesario. Tipo de entrada del componente. Más información sobre el acceso a datos	`number`, `integer`, `boolean`, `string`, `uri_file`, `uri_folder`, `mltable`, `mlflow_model`
`description`	string	Descripción de la entrada.
`default`	número, entero, booleano o cadena	El valor predeterminado de la entrada.
`optional`	boolean	Determina si la entrada es obligatoria. Si se establece en `true`, debe usar el comando includes optional inputs con `$[[]]`.		`false`
`min`	entero o número	Valor mínimo aceptado para la entrada. Este campo solo se puede especificar si el campo `type` es `number` o `integer`.
`max`	entero o número	Valor máximo aceptado para la entrada. Este campo solo se puede especificar si el campo `type` es `number` o `integer`.
`enum`	array	Lista de valores permitidos para la entrada. Solo aplicable si el campo `type` es `string`.

Salida del componente

Clave	Tipo	Descripción	Valores permitidos	Valor predeterminado
`type`	string	Necesario. Tipo de salida del componente.	`uri_file`, `uri_folder`, `mltable`, `mlflow_model`
`description`	string	Descripción de la salida.

Comentarios

Los comandos az ml component se pueden usar para administrar los componentes de Azure Machine Learning.

Ejemplos

Hay ejemplos de componentes de comandos disponibles en el repositorio de GitHub de ejemplos. A continuación se muestran ejemplos seleccionados.

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

YAML: componente de comando Hola mundo

$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: componente con diferentes tipos de entrada

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

Definición de entradas opcionales en la línea de comandos

Cuando la entrada se establece como optional = true, debe usar $[[]] para adoptar la línea de comandos con entradas. Por ejemplo, $[[--input1 ${{inputs.input1}}]. La línea de comandos en tiempo de ejecución puede tener entradas diferentes.

Si solo usa especificar los parámetros training_data y model_output necesarios, la línea de comandos tendrá el siguiente aspecto:

python train.py --training_data some_input_path --learning_rate 0.01 --learning_rate_schedule time-based --model_output some_output_path

Si no se especifica ningún valor en tiempo de ejecución, learning_rate y learning_rate_schedule usarán el valor predeterminado.

Si todas las entradas o salidas proporcionan valores durante el tiempo de ejecución, la línea de comandos tendrá el siguiente aspecto:

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

Errores comunes y recomendaciones

A continuación se indican algunos errores comunes y las correspondientes sugerencias recomendadas al definir un componente.

Clave	Errors	Recomendación
command	1. Solo las entradas opcionales pueden estar en `$[[]]` 2. No se admite el uso de `\` para crear una nueva línea en el comando. 3. No se encuentran entradas o salidas.	1. Compruebe que todas las entradas o salidas usadas en el comando ya están definidas en las secciones `inputs` y `outputs`, y use el formato correcto para las entradas opcionales `$[[]]` o las necesarias `${{}}`. 2. No use `\` para crear una nueva línea.
Environment	1. No existe ninguna definición para el ambiente `{envName}`, versión `{envVersion}`. 2. No existe ningún entorno para el nombre `{envName}`, versión `{envVersion}`. 3. No se pudo encontrar el recurso con el id. `{envAssetId}`.	1. Asegúrese de que existe el nombre del entorno y la versión que hace referencia en la definición del componente. 2. Debe especificar la versión si hace referencia a un entorno registrado.
entradas/salidas	1. Los nombres de entradas/salidas entran en conflicto con los parámetros reservados del sistema. 2. Nombres duplicados de entradas o salidas.	1. No use ninguno de estos parámetros reservados como nombre de entradas/salidas: `path`, `ld_library_path`, `user`, `logname`, `home`, `pwd` y `shell`. 2. Asegúrese de que los nombres de las entradas y salidas no están duplicados.