Partilhar via

Sintaxe YAML principal da CLI (v2)

  • Artigo

APLICA-SE A:Extensão 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 a partir de um arquivo de configuração YAML com uma .yml extensão ou .yaml .

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

Fazendo referência a uma entidade do Azure Machine Learning

O Azure Machine Learning fornece uma sintaxe de referência (que consiste em um formato abreviado e longhand) 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 espaço de trabalho para usar como o ambiente para um trabalho.

Fazendo referência a um ativo do Azure Machine Learning

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

  • Faça referência a uma versão explícita de um ativo:

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

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

    Em alguns cenários, você pode querer fazer referência à versão mais recente de um ativo sem ter que procurar explicitamente e especificar a própria cadeia de caracteres de versão real. A versão mais recente é definida como a versão mais recente (também conhecida como mais recente) criada de um ativo sob 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 a uma versão explícita do ativo no espaço de trabalho.

Fazer referência a um recurso do Azure Machine Learning

Para fazer referência a um recurso do Azure Machine Learning (como computação), você pode usar uma das seguintes sintaxes:

  • Sintaxe taquigráfica: azureml:<resource_name>
  • Sintaxe Longhand, que inclui o ID do recurso ARM:
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

O Azure Machine Learning oferece um formato de URI de referência de dados conveniente para apontar para dados em um serviço de armazenamento do Azure. Isso pode ser usado para cenários em que você precisa especificar um local de armazenamento em nuvem em seu arquivo YAML, como criar um modelo do Azure Machine Learning a partir de arquivo(s) no armazenamento ou apontar para dados para passar como entrada para um trabalho.

Para usar esse formato de URI de dados, o serviço de armazenamento que você deseja referenciar deve primeiro ser registrado como um armazenamento de dados em seu espaço de trabalho. O Aprendizado de Máquina do Azure manipulará o acesso a dados usando as credenciais fornecidas durante a criação do armazenamento de dados.

O formato consiste em um armazenamento de dados no espaço de trabalho 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, , e , wasbsabfssbem como URIs públicos e adlhttps públicoshttp.

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

Os arquivos YAML de trabalho e componente v2 permitem o uso de expressões para vincular a contextos para diferentes cenários. 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 em tempo de execução.

Use a sintaxe a seguir para dizer ao Aprendizado de Máquina do Azure para avaliar uma expressão em vez de tratá-la como uma cadeia de caracteres:

${{ <expression> }}

Os cenários suportados são abordados abaixo.

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

Você pode especificar valores literais, caminhos de URI e ativos de dados registrados do Aprendizado de Máquina do Azure como entradas para um trabalho. O command pode então ser parametrizado com referências à(s) entrada(s) usando a ${{inputs.<input_name>}} sintaxe. As referências a entradas literais serão resolvidas para o valor literal em tempo de execução, enquanto as referências a entradas de dados serão resolvidas para o caminho de download ou caminho de montagem (dependendo do mode especificado).

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, o outputs Aprendizado de Máquina do Azure gerará um local de saída no armazenamento de dados padrão no qual você pode gravar arquivos. O local de saída para cada saída nomeada é baseado no seguinte caminho templatizado: <default-datastore>/azureml/<job-name>/<output_name>/. Parametrizar o com a sintaxe resolverá essa referência ao caminho gerado pelo sistema, para que o command script possa gravar arquivos nesse local a ${{outputs.<output_name>}} partir do trabalho.

No exemplo abaixo para um arquivo YAML de trabalho de comando, o command é parametrizado com duas entradas, uma entrada literal e uma entrada de dados, e uma saída. No tempo de execução, a expressão será resolvida para , e a ${{inputs.learning_rate}}${{inputs.iris}} expressão será resolvida para 0.01o caminho de download do iris.csv arquivo. ${{outputs.model_dir}} resolverá para o caminho de montagem do local de saída gerado pelo sistema correspondente à model_dir saída.

$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 o com o commandsearch_space contexto de um trabalho de varredura

Você também usará essa sintaxe de expressão ao executar o ajuste de hiperparâmetros por meio de um trabalho de varredura, uma vez que os valores reais dos hiperparâmetros não são conhecidos durante o tempo de criação do trabalho. Quando você executa um trabalho de varredura, o Aprendizado de Máquina do Azure seleciona valores de hiperparâmetros para cada avaliação com base no search_space. Para acessar esses valores em seu script de treinamento, você deve passá-los por meio dos argumentos de linha de comando do script. Para fazer isso, use a ${{search_space.<hyperparameter>}} sintaxe no trial.command.

No exemplo abaixo para um arquivo YAML de trabalho de varredura, as ${{search_space.learning_rate}} referências e ${{search_space.boosting}} em trial.command serão resolvidas para os valores de hiperparâmetro reais 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

Vinculando entradas e saídas entre etapas em um trabalho de pipeline

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

Para um arquivo YAML de trabalho de pipeline, as inputs seções 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, vai resolver para o contexto atual (o trabalho infantil).

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

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

Você pode vincular 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>}}. Esta referência resolve-se ao parent contexto, daí as entradas/saídas de nível superior.

No exemplo abaixo, a entrada (raw_data) da primeira prep etapa está vinculada à entrada de pipeline de nível superior via ${{parent.inputs.input_data}}. A saída (model_dir) da etapa final train está vinculada à saída do trabalho de pipeline de nível superior via ${{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, portanto, a expressão deve começar com parent.jobs.<step_name>.

No exemplo abaixo, a entrada () da etapa está vinculada à saída (training_dataclean_data) da prep etapa via ${{parent.jobs.prep.outputs.clean_data}}.train Os dados preparados da prep etapa serão usados como os dados de treinamento para a train etapa.

Por outro lado, as referências de contexto dentro das command propriedades serão resolvidas para o contexto atual. Por exemplo, a ${{inputs.raw_data}} referência na prep etapa command resolverá para as entradas do contexto atual, que é o prep trabalho infantil. A pesquisa será feita em prep.inputs, portanto, uma entrada nomeada 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 o command com os inputs e outputs contextos de um componente

Semelhante ao command para um trabalho, o command para um componente também pode ser parametrizado com referências aos inputs contextos e outputs . Neste caso, a referência é às entradas e saídas do componente. Quando o componente é executado em um trabalho, o Aprendizado de Máquina do Azure resolverá essas referências aos valores de entrada e saída do tempo de execução do trabalho especificados para as respetivas entradas e saídas do componente. Abaixo está um exemplo de uso da 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
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 abraçar a linha de comando com entradas. Por exemplo, $[[--input1 ${{inputs.input1}}]. A linha de comando em tempo de execução pode ter entradas diferentes.

  • Se você estiver usando apenas os parâmetros e obrigatórios training_datamodel_output , a linha de comando terá a seguinte aparência:
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 no tempo de execução learning_rate e learning_rate_schedule usará o valor padrão.

  • Se todas as entradas/saídas fornecerem valores durante o tempo de execução, a linha de comando terá a seguinte aparência:
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 seguintes expressões podem ser usadas no caminho de saída do seu 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 o tempo de criação e o tempo 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 espaço de trabalho, não o estado do espaço de trabalho quando o trabalho agendado foi criado. Por exemplo, se você alterar o armazenamento de dados padrão do espaço de trabalho 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 Description Scope
${{default_datastore}} Se o armazenamento de dados padrão do pipeline estiver configurado, será resolvido como o nome do armazenamento de dados padrão do pipeline; caso contrário, é resolvido como nome do armazenamento de dados padrão do espaço de trabalho.

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

Os trabalhos de pipeline têm um armazenamento de dados padrão de pipeline configurável.
${{name}} O nome do trabalho. Para pipelines, é o nome do trabalho de etapa, não o nome do trabalho de 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 tempo de execução ele será resolvido como um caminho de azureml://datastores/workspaceblobstore/paths/<job-name>/model_path.

Próximos passos