Sintaxe principal do YAML da CLI (v2)

  • Artigo

APLICA-SE A:Extensão de ML da CLI do Azure v2 (atual)

Cada entidade do Azure Machine Learning tem uma representação YAML esquematizada. Você pode criar uma nova entidade de um arquivo de configuração YAML com uma extensão .yml ou .yaml.

Este artigo fornece uma visão geral dos conceitos básicos de sintaxe que você encontrará ao configurar esses arquivos YAML.

Como referenciar uma entidade do Azure Machine Learning

O Azure Machine Learning fornece uma sintaxe de referência (que consiste em um formato abreviado e inteiro) para referenciar uma entidade existente do Azure Machine Learning ao configurar um arquivo YAML. Por exemplo, você pode fazer referência a um ambiente registrado existente em seu workspace para usar como ambiente para um trabalho.

Como referenciar um ativo do Azure Machine Learning

Há duas opções para referenciar um ativo do Azure Machine Learning (ambientes, modelos, dados e componentes):

  • Referenciar uma versão explícita de um ativo:

    • Sintaxe abreviada: azureml:<asset_name>:<asset_version>
    • Sintaxe longa, que inclui a ID de recurso do ARM (Azure Resource Manager) do ativo:
    azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/environments/<environment-name>/versions/<environment-version>

  • Referencie a versão mais recente de um ativo:

    Em alguns cenários, talvez você queira referenciar a versão mais recente de um ativo sem precisar procurar explicitamente e especificar a própria cadeia de caracteres da versão propriamente dita. A versão mais recente é definida como a versão mais recente (também conhecida como última) criada de um ativo com um determinado nome.

    Você pode fazer referência à versão mais recente usando a seguinte sintaxe: azureml:<asset_name>@latest. O Azure Machine Learning resolverá a referência para uma versão de ativo explícita no workspace.

Referenciar um recurso do Azure Machine Learning

Para referenciar um recurso do Azure Machine Learning (como a computação), use uma das seguintes sintaxes:

  • Sintaxe abreviada: azureml:<resource_name>
  • Sintaxe longa, que inclui a ID de recurso de ARM do recurso:
azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/computes/<compute-name>

URI de referência de dados do Azure Machine Learning

Para sua conveniência, o Azure Machine Learning oferece um formato de URI de referência de dados para apontá-lo para os dados em um serviço de armazenamento do Azure. Isso pode ser usado para os cenários em que você precisa especificar um local de armazenamento em nuvem no arquivo YAML, como criar um modelo do Azure Machine Learning com base em arquivos no armazenamento ou apontá-lo para os dados para transmiti-lo como a entrada para um trabalho.

Para usar esse formato de dados de URI, o serviço de armazenamento que você deseja referenciar deve primeiro ser registrado como um armazenamento de dados em seu workspace. O Azure Machine Learning processará o acesso aos dados usando as credenciais fornecidas durante a criação do armazenamento de dados.

O formato consiste em um armazenamento de dados no workspace atual e o caminho no armazenamento de dados para o arquivo ou pasta para o qual você deseja apontar:

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

Por exemplo:

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

Além do URI de referência de dados do Azure Machine Learning, o Azure Machine Learning também dá suporte aos seguintes protocolos de URI de armazenamento direto: https, wasbs, abfss e adl, bem como os URIs públicos http e https.

Sintaxe de expressão para configurar trabalhos e componentes do Azure Machine Learning

Arquivos YAML de trabalho e componente v2 permitem o uso de expressões para associação a contextos para cenários diferentes. O caso de uso essencial é usar uma expressão para um valor que pode não ser conhecido no momento da criação da configuração, mas deve ser resolvido no runtime.

Use a seguinte sintaxe para instruir o Azure Machine Learning a avaliar uma expressão em vez de tratá-la como uma cadeia de caracteres:

${{ <expression> }}

Os cenários com suporte são abordados abaixo.

Parametrizando command o com os contextos inputs e outputs de um trabalho

É possível especificar valores literais, caminhos de URI e ativos de dados registrados do Azure Machine Learning como entradas para um trabalho. O command pode, em seguida, ser parametrizado com referências a essas entradas usando a sintaxe ${{inputs.<input_name>}}. As referências a entradas literais serão resolvidas para o valor literal no runtime, enquanto as referências às entradas de dados serão resolvidas para o caminho de download ou caminho de montagem (dependendo do especificado mode).

Da mesma forma, as saídas para o trabalho também podem ser referenciadas no command. Para cada saída nomeada especificada no dicionário outputs, o Azure Machine Learning vai gerar pelo sistema um local de saída no armazenamento de dados padrão no qual você poderá gravar os arquivos. O local de saída para cada saída nomeada é baseado no seguinte caminho transformado em modelo: <default-datastore>/azureml/<job-name>/<output_name>/. Parametrizar o command com a sintaxe ${{outputs.<output_name>}} resolverá essa referência ao caminho gerado pelo sistema, para que o script possa gravar arquivos nesse local a partir do trabalho.

No exemplo abaixo para um arquivo YAML do trabalho de comando, o command é parametrizado com duas entradas, uma entrada literal e uma entrada de dados e uma saída. No runtime, a expressão ${{inputs.learning_rate}} será resolvida para 0.01 e a expressão ${{inputs.iris}} será resolvida para o caminho de download do arquivo iris.csv. ${{outputs.model_dir}} o será resolvido para o caminho de montagem do local de saída gerado pelo sistema correspondente à saída 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:

Parametrizando command o com o contexto search_space de um trabalho de limpeza

Você também usará essa sintaxe de expressão ao executar o ajuste de hiperparâmetro através de um trabalho de limpeza, pois os valores reais dos hiperparâmetros não são conhecidos durante o momento de criação do trabalho. Quando você executar um trabalho de limpeza, o Azure Machine Learning selecionará valores de hiperparâmetro para cada avaliação com base no search_space. Para acessar esses valores em seu script de treinamento, você deve passá-los através dos argumentos de linha de comando do script. Para fazer isso, use a sintaxe ${{search_space.<hyperparameter>}} no trial.command.

No exemplo abaixo para um arquivo YAML de trabalho de limpeza, as referências ${{search_space.learning_rate}} e ${{search_space.boosting}} em trial.command resolverão para os valores reais de hiperparâmetro selecionados para cada avaliação quando o trabalho de avaliação for enviado para execução.

$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

Associação de entradas e saídas entre etapas em um trabalho do pipeline

As expressões também são usadas para associar entradas e saídas entre etapas em um trabalho do pipeline. Por exemplo, você pode associar a entrada de um trabalho (trabalho B) em um pipeline à saída de outro trabalho (trabalho A). Esse uso sinalizará para o Azure Machine Learning o fluxo de dependência do grafo de pipeline e o trabalho B será executado após o trabalho A, pois a saída do trabalho A é necessária como uma entrada para o trabalho B.

Para um arquivo YAML do trabalho de pipeline, as seções inputs e outputs de cada trabalho filho são avaliadas dentro do contexto pai (o trabalho de pipeline de nível superior). O command, por outro lado, será resolvido para o contexto atual (o trabalho filho).

Há duas maneiras de associar entradas e saídas em um trabalho de pipeline:

Associar às entradas e saídas de nível superior do trabalho de pipeline

Você pode associar as entradas ou saídas de um trabalho filho (uma etapa de pipeline) às entradas/saídas do trabalho de pipeline pai de nível superior usando a seguinte sintaxe: ${{parent.inputs.<input_name>}} ou ${{parent.outputs.<output_name>}}. Essa referência é resolvida para o contexto parent; portanto, as entradas/saídas de nível superior.

No exemplo a seguir, a entrada (raw_data) da primeira etapa prep é vinculada à entrada do pipeline de nível superior por meio de ${{parent.inputs.input_data}}. A saída (model_dir) da etapa final train é vinculada à saída do trabalho de pipeline de nível superior por meio de ${{parent.outputs.trained_model}}.

Vincular às entradas e saídas de outro trabalho filho (etapa)

Para vincular as entradas/saídas de uma etapa às entradas/saídas de outra etapa, use a seguinte sintaxe: ${{parent.jobs.<step_name>.inputs.<input_name>}} ou ${{parent.jobs.<step_name>.outputs.<outputs_name>}}. Novamente, essa referência é resolvida para o contexto pai, de modo que a expressão deve começar com parent.jobs.<step_name>.

No exemplo a seguir, a entrada (training_data) da etapa train é vinculada à saída (clean_data) da etapa prep por meio de ${{parent.jobs.prep.outputs.clean_data}}. Os dados preparados da etapa prep serão usados como os dados de treinamento para a etapa train.

Por outro lado, as referências de contexto dentro das propriedades command serão resolvidas para o contexto atual. Por exemplo, a referência ${{inputs.raw_data}} na etapa prep de command será resolvida para as entradas do contexto atual, que é o trabalho filho prep. Uma pesquisa será feita em prep.inputs, portanto, uma entrada chamada raw_data deve ser definida lá.

$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

Parametrizando command o com os contextos inputs e outputs de um componente

Semelhante ao command para um trabalho, o command para um componente também pode ser parametrizado com referências aos contextos inputs e outputs. Nesse caso, a referência será às entradas e saídas do componente. Quando o componente for executado em um trabalho, o Azure Machine Learning resolverá essas referências aos valores de entrada e de saída do runtime do trabalho especificados para as respectivas entradas e saídas do componente. Veja abaixo um exemplo de como usar a sintaxe de contexto para uma especificação YAML do componente de comando.

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

Definir entradas opcionais na linha de comando

Quando a entrada é definida como optional = true, você precisa usar $[[]] para adotar a linha de comando com entradas. Por exemplo, $[[--input1 ${{inputs.input1}}]. A linha de comando em runtime pode ter entradas diferentes.

  • Se você estiver usando apenas os parâmetros necessários training_data e model_output, a linha de comando ficará assim:
python train.py --training_data some_input_path --learning_rate 0.01 --learning_rate_schedule time-based --model_output some_output_path

Se nenhum valor for especificado em runtime, learning_rate e learning_rate_schedule usarão o valor padrão.

  • Se todas as entradas/saídas fornecerem valores durante o runtime, a linha de comando será semelhante a:
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

Expressões de caminho de saída

As expressões a seguir podem ser usadas no caminho de saída do trabalho:

Importante

As expressões a seguir são resolvidas no lado do servidor, não no lado do cliente. Para trabalhos agendados em que a hora de criação do trabalho e a hora de envio do trabalho são diferentes, as expressões são resolvidas quando o trabalho é enviado. Como essas expressões são resolvidas no lado do servidor, elas usam o estado atual do workspace, não o estado do workspace quando o trabalho agendado foi criado. Por exemplo, se você alterar o armazenamento de dados padrão do workspace depois de criar um trabalho agendado, a expressão ${{default_datastore}} será resolvida para o novo armazenamento de dados padrão, não para o armazenamento de dados padrão quando o trabalho agendado foi criado.

Expression Descrição Escopo
${{default_datastore}} Se o armazenamento de dados padrão estiver configurado, será resolvido como o nome do armazenamento de dados padrão do pipeline; caso contrário, será resolvido como o nome do armazenamento de dados padrão do workspace.

O armazenamento de dados padrão do pipeline pode ser controlado usando pipeline_job.settings.default_datastore.		 Funciona para todos os trabalhos.

Os trabalhos de pipeline têm um armazenamento de dados padrão do pipeline configurável.
${{name}} O nome do trabalho. Para pipelines, é o nome do trabalho de etapa, não o nome do trabalho do pipeline. Funciona para todos os trabalhos
${{output_name}} O nome de saída do trabalho Funciona para todos os trabalhos

Por exemplo, se azureml://datastores/${{default_datastore}}/paths/${{name}}/${{output_name}} for usado como o caminho de saída, em runtime ele será resolvido como um caminho de azureml://datastores/workspaceblobstore/paths/<job-name>/model_path.

Próximas etapas