Sintaxis básica de YAML de la CLI (v2)

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

Cada entidad de Azure Machine Learning tiene una representación de YAML esquematizada. Puede crear una nueva entidad a partir de un archivo de configuración YAML con una extensión .yml o .yaml.

En este artículo se proporciona una introducción a conceptos de la sintaxis básica que va a encontrar al configurar estos archivos YAML.

Referencia a una entidad de Azure Machine Learning

Azure Machine Learning proporciona una sintaxis de referencia (que consta de un formato abreviado y largo) para hacer referencia a una entidad de Azure Machine Learning existente al configurar un archivo YAML. Por ejemplo, puede hacer referencia a un entorno registrado existente del área de trabajo para usarlo como el entorno de un trabajo.

Referencia a un activo de Azure Machine Learning

Hay dos opciones para hacer referencia a un activo de Azure Machine Learning (entornos, modelos, datos y componentes):

• Haga referencia a una versión explícita de un recurso:

  • Sintaxis abreviada: azureml:<asset_name>:<asset_version>
  • Sintaxis larga, que incluye el identificador de recurso de Azure Resource Manager (ARM) del recurso:

  azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/environments/<environment-name>/versions/<environment-version>
  

• Haga referencia a la versión más reciente de un recurso:

  En algunos escenarios, puede que quiera hacer referencia a la versión más reciente de un recurso sin tener que buscar explícitamente y especificar la propia cadena de versión real. La última versión se define como la versión más reciente creada de un recurso con un nombre determinado.

  Puede hacer referencia a la versión más reciente mediante la sintaxis siguiente: azureml:<asset_name>@latest. Azure Machine Learning resolverá la referencia a una versión de recurso explícita en el área de trabajo.

Referencia a un recurso de Azure Machine Learning

Para hacer referencia a un recurso de Azure Machine Learning (por ejemplo, proceso), puede usar cualquiera de las sintaxis siguientes:

• Sintaxis abreviada: azureml:<resource_name>
• Sintaxis de larga duración, que incluye el identificador de recurso de ARM del recurso:

azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/computes/<compute-name>

URI de referencia de datos de Azure Machine Learning

Azure Machine Learning ofrece un cómodo formato de URI de referencia de datos para apuntar a datos de un servicio de almacenamiento de Azure. Se puede usar en escenarios en los que es necesario especificar una ubicación de almacenamiento en la nube en el archivo YAML, como al crear un modelo de Azure Machine Learning a partir de archivos en el almacenamiento, o al apuntar a datos para pasarlos como entrada para un trabajo.

Para usar este formato de URI de datos, el servicio de almacenamiento al que se quiere hacer referencia primero debe registrarse como almacén de datos del área de trabajo. Azure Machine Learning controla el acceso a los datos con las credenciales proporcionadas durante la creación del almacén de datos.

El formato consta de un almacén de datos del área de trabajo actual y la ruta de acceso en el almacén de datos al archivo o la carpeta a los que se quiere apuntar:

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

Por ejemplo:

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

Además del URI de referencia de datos de Azure Machine Learning, Azure Machine Learning también admite los siguientes protocolos de URI de almacenamiento directo: https, wasbs, abfss y adl, así como URI públicos http y https.

Sintaxis de expresión para configurar trabajos y componentes de Azure Machine Learning

Los archivos YAML de trabajos y componentes v2 permiten el uso de expresiones para enlazar a contextos de distintos escenarios. El caso de uso básico es el empleo de una expresión para un valor que podría no conocerse en el momento de crear la configuración, pero que debe resolverse en tiempo de ejecución.

Use la siguiente sintaxis para indicar a Azure Machine Learning que evalúe una expresión en lugar de tratarla como una cadena:

${{ <expression> }}

Los escenarios admitidos se tratan a continuación.

Parametrización de command con los contextos inputs y outputs de un trabajo

Puede especificar valores literales, rutas de acceso URI y recursos de datos registrados de Azure Machine Learning como entradas para un trabajo. Luego command se puede parametrizar con referencias a esas entradas mediante la sintaxis ${{inputs.<input_name>}}. Las referencias a entradas literales se resuelven en el valor literal en tiempo de ejecución, mientras que las referencias a entradas de datos se resuelven en la ruta de acceso de descarga o la ruta de acceso de montaje (según el valor mode especificado).

Del mismo modo, en command también se puede hacer referencia a las salidas para el trabajo. Por cada salida con nombre especificada en el diccionario outputs, Azure Machine Learning genera sistemáticamente una ubicación de salida en el almacén de datos predeterminado donde se pueden escribir archivos. La ubicación de salida de cada salida con nombre se basa en la siguiente ruta de acceso con plantilla: <default-datastore>/azureml/<job-name>/<output_name>/. La parametrización de command con la sintaxis ${{outputs.<output_name>}} resuelve esa referencia en la ruta de acceso generada sistemáticamente, de modo que el script puede escribir archivos en esa ubicación desde el trabajo.

En el ejemplo siguiente de un archivo YAML de trabajo de comandos, se parametriza command con dos entradas, una entrada literal y una entrada de datos, y una salida. En tiempo de ejecución, la expresión ${{inputs.learning_rate}} se resuelve en 0.01 y la expresión ${{inputs.iris}} se resuelve en la ruta de acceso de descarga del archivo iris.csv. ${{outputs.model_dir}} se resolverá en la ruta de acceso de montaje de la ubicación de salida generada por el sistema correspondiente a la salida 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:

Parametrización de command con el contexto search_space de un trabajo de barrido

Esta sintaxis de expresión también se usa para realizar el ajuste de hiperparámetros mediante un trabajo de barrido, ya que los valores reales de los hiperparámetros no se conocen durante el tiempo de creación del trabajo. Al ejecutar un trabajo de barrido, Azure Machine Learning selecciona los valores de los hiperparámetros de cada evaluación en función de search_space. Para acceder a esos valores en el script de entrenamiento, debe pasarlos mediante los argumentos de la línea de comandos del script. Para ello, use la sintaxis ${{search_space.<hyperparameter>}} de trial.command.

En el ejemplo siguiente de un archivo YAML de trabajo de barrido, las referencias ${{search_space.learning_rate}} y ${{search_space.boosting}} de trial.command se resuelven en los valores de los hiperparámetros reales seleccionados para cada evaluación al enviar el trabajo de evaluación para su ejecución.

$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

Enlace de entradas y salidas entre pasos de un trabajo de canalización

Las expresiones también se usan para enlazar entradas y salidas entre pasos de un trabajo de canalización. Por ejemplo, puede enlazar la entrada de un trabajo (trabajo B) de una canalización a la salida de otro trabajo (trabajo A). Este uso indica a Azure Machine Learning el flujo de dependencias del grafo de canalización, y el trabajo B se ejecuta después del trabajo A, ya que la salida del trabajo A es necesaria como entrada del trabajo B.

En un archivo YAML de trabajo de canalización, las secciones inputs y outputs de cada trabajo secundario se evalúan dentro del contexto principal (el trabajo de canalización de nivel superior). Por otro lado, command se resuelve en el contexto actual (el trabajo secundario).

Hay dos maneras de enlazar entradas y salidas en un trabajo de canalización:

Enlazar a las entradas y salidas de nivel superior del trabajo de canalización

Puede enlazar las entradas o salidas de un trabajo secundario (un paso de canalización) a las entradas o salidas del trabajo de canalización principal de nivel superior mediante la sintaxis siguiente: ${{parent.inputs.<input_name>}} o ${{parent.outputs.<output_name>}}. Esta referencia se resuelve en el contexto parent, es decir, las entradas o salidas de nivel superior.

En el ejemplo siguiente, la entrada (raw_data) del primer paso prep está enlazada a la entrada de canalización de nivel superior mediante ${{parent.inputs.input_data}}. La salida (model_dir) del paso train final está enlazada a la salida del trabajo de canalización de nivel superior mediante ${{parent.outputs.trained_model}}.

Enlazar a las entradas y salidas de otro trabajo secundario (paso)

Para enlazar las entradas o salidas de un paso a las entradas o salidas de otro paso, use la sintaxis siguiente: ${{parent.jobs.<step_name>.inputs.<input_name>}} o ${{parent.jobs.<step_name>.outputs.<outputs_name>}}. De nuevo, esta referencia se resuelve en el contexto principal, por lo que la expresión de contexto debe comenzar por parent.jobs.<step_name>.

En el ejemplo siguiente, la entrada (training_data) del paso train se enlaza a la salida (clean_data) del paso prep mediante ${{parent.jobs.prep.outputs.clean_data}}. Los datos preparados del paso prep se usan como datos de entrenamiento del paso train.

Por otro lado, las referencias de contexto en las propiedades command se resuelven en el contexto actual. Por ejemplo, la referencia ${{inputs.raw_data}} de command del paso prep se resuelve en las entradas del contexto actual, que es el trabajo secundario prep. La búsqueda se realiza en prep.inputs, por lo que se debe definir allí una entrada de nombre raw_data.

$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

Parametrización de command con los contextos inputs y outputs de un componente

De forma similar al valor command de un trabajo, el valor command de un componente también se puede parametrizar con referencias a los contextos inputs y outputs. En este caso, la referencia es a las entradas y salidas del componente. Cuando el componente se ejecuta en un trabajo, Azure Machine Learning resuelve esas referencias en los valores de entrada y salida en tiempo de ejecución del trabajo especificados para las entradas y salidas respectivas del componente. A continuación se muestra un ejemplo del uso de la sintaxis de contexto en una especificación de YAML del componente de comandos.

$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
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.5/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 lo requerido training_data y model_output los parámetros, 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

Expresiones de ruta de acceso de salida

Las expresiones siguientes se pueden usar en la ruta de acceso de salida del trabajo:

Importante

Las expresiones siguientes se resuelven en el lado servidor, no en el lado cliente. En el caso de los trabajos programados en los que la hora de creación del trabajo y la hora de envío son diferentes, las expresiones se resuelven cuando se envía el trabajo. Dado que estas expresiones se resuelven en el lado servidor, usan el estado actual del área de trabajo, no el estado del área de trabajo de cuando se creó el trabajo programado. Por ejemplo, si cambia el almacén de datos predeterminado del área de trabajo una vez creado un trabajo programado, la expresión ${{default_datastore}} se resuelve en el nuevo almacén de datos predeterminado, no en el almacén de datos predeterminado cuando se creó el trabajo programado.

Expression	Descripción	Ámbito
${{default_datastore}}	Si se configura el almacén de datos predeterminado de canalización, se resuelve como nombre predeterminado del almacén de datos de canalización; de lo contrario, se resuelve como nombre predeterminado del almacén de datos del área de trabajo. El almacén de datos predeterminado de canalización se puede controlar utilizando pipeline_job.settings.default_datastore.	Funciona para todos los trabajos. Los trabajos de canalización tienen un almacén de datos predeterminado de canalización configurable.
${{name}}	Nombre del trabajo. En el caso de las canalizaciones, es el nombre del trabajo del paso, no el nombre del trabajo de canalización.	Funciona para todos los trabajos
${{output_name}}	El nombre de la salida del trabajo	Funciona para todos los trabajos

Por ejemplo, si azureml://datastores/${{default_datastore}}/paths/${{name}}/${{output_name}} se usa como ruta de acceso de salida, en runtime se resuelve como una ruta de acceso de azureml://datastores/workspaceblobstore/paths/<job-name>/model_path.

Pasos siguientes

• Instalación y uso de la CLI (v2)
• Entrenamiento de modelos con la CLI (v2)
• Esquemas YAML de la CLI (v2)