Esquema YAML do componente de comando da CLI (v2)

  • Artigo

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

O esquema JSON de origem pode ser encontrado em https://azuremlschemas.azureedge.net/latest/commandComponent.schema.json.

Observação

A sintaxe YAML detalhada neste documento baseia-se no esquema JSON da última versão da extensão de ML da CLI v2. Essa sintaxe só tem a garantia de funcionar com a última versão da extensão de ML da CLI v2. Encontre os esquemas para as versões mais antigas da extensão em https://azuremlschemasprod.azureedge.net/.

Sintaxe YAML

Chave Type Descrição Valores permitidos Valor padrão
$schema string O esquema YAML. Se você usar a extensão do Azure Machine Learning para VS Code para criar o arquivo YAML, a inclusão de $schema no início do arquivo permitirá invocar conclusões de esquema e recursos.
type const O tipo de componente. command command
name string Obrigatórios. Nome do componente. Deve começar com letra minúscula. Os caracteres permitidos são letras minúsculas, números e sublinhado (_). O comprimento máximo é de 255 caracteres.
version string A versão do componente. Se isso for omitido, o Azure Machine Learning vai gerar uma versão automaticamente.
display_name string Nome de exibição do componente na interface do usuário no estúdio. Dentro do espaço de trabalho ele pode ser não exclusivo.
description string Descrição do componente.
tags objeto Dicionário de marcas para o componente.
is_deterministic booleano Essa opção determina se o componente produzirá a mesma saída para os mesmos dados de entrada. Normalmente, você deve defini-la como false para os componentes que carregam dados de fontes externas, como no caso da importação de dados de uma URL. Isso se deve ao fato de os dados na URL correrem o risco de mudar ao longo do tempo. true
command string Obrigatórios. O comando a ser executado.
code string Caminho local para o diretório de código-fonte a ser carregado e usado para o componente.
environment cadeia de caracteres ou objeto Obrigatórios. O ambiente a ser usado para o componente. Esse valor pode ser uma referência para um ambiente com versão existente no espaço de trabalho ou uma especificação de ambiente embutido.

Use a sintaxe azureml:<environment-name>:<environment-version> para referenciar um ambiente existente.

Siga o esquema do ambiente para definir um ambiente embutido. Exclua as propriedades name e version, pois não há suporte para elas nos ambientes embutidos.
distribution objeto A configuração de distribuição nos cenários de treinamento distribuídos. Um de MpiConfiguration, PyTorchConfiguration ou TensorFlowConfiguration.
resources.instance_count inteiro O número de nós que serão usados para o trabalho. 1
inputs objeto Dicionário de entradas de componente. A chave é um nome para a entrada dentro do contexto do componente e o valor é a definição de entrada do componente.

As entradas podem ser referenciadas em command usando a expressão ${{ inputs.<input_name> }}.
inputs.<input_name> objeto A definição de entrada do componente. Confira a Entrada de componente para obter o conjunto de propriedades configuráveis.
outputs objeto Dicionário de saídas de componente. A chave é um nome para a saída dentro do contexto do componente e o valor é a definição de saída do componente.

As saídas podem ser referenciadas em command usando a expressão ${{ outputs.<output_name> }}.
outputs.<output_name> objeto A definição de saída do componente. Confira a Saída de componente para obter o conjunto de propriedades configuráveis.

Configurações de distribuição

MpiConfiguration

Chave Type Descrição Valores permitidos
type const Obrigatórios. Tipo de distribuição. mpi
process_count_per_instance inteiro Obrigatórios. O número de processos por nó a iniciar para o trabalho.

PyTorchConfiguration

Chave Type Descrição Valores permitidos Valor padrão
type const Obrigatórios. Tipo de distribuição. pytorch
process_count_per_instance inteiro O número de processos por nó a iniciar para o trabalho. 1

TensorFlowConfiguration

Chave Type Descrição Valores permitidos Valor padrão
type const Obrigatórios. Tipo de distribuição. tensorflow
worker_count inteiro O número de trabalhos a iniciar para o trabalho. Assume o padrão de resources.instance_count.
parameter_server_count inteiro O número de servidores de parâmetros a iniciar para o trabalho. 0

Entrada do componente

Chave Type Descrição Valores permitidos Valor padrão
type string Obrigatórios. O tipo de entrada do componente. Saiba mais sobre acesso aos dados number, integer, boolean, string, uri_file, uri_folder, mltable, mlflow_model
description string Descrição da entrada.
default número, número inteiro, booliano ou cadeia de caracteres O valor padrão para a entrada.
optional booleano Se a entrada for necessária. Se definido como true, você precisa usar o comando inclui entradas opcionais com $[[]] false
min número inteiro ou número O valor mínimo aceito para a entrada. Esse campo somente pode ser especificado se o campo type for number ou integer.
max número inteiro ou número O valor máximo aceito para a entrada. Esse campo somente pode ser especificado se o campo type for number ou integer.
enum array A lista de valores permitidos para a entrada. Somente aplicável se o campo type for string.

Saída do componente

Chave Type Descrição Valores permitidos Valor padrão
type string Obrigatórios. O tipo de saída do componente. uri_file, uri_folder, mltable, mlflow_model
description string Descrição da saída.

Comentários

Os comandos az ml component podem ser usados para gerenciar os componentes do Azure Machine Learning.

Exemplos

Os exemplos de componente de comando estão disponíveis no repositório de exemplos do GitHub. Os exemplos selecionados são apresentados a seguir.

Os exemplos estão disponíveis no repositório de exemplos do GitHub. Vários são mostrados abaixo.

YAML: componente de comando Olá, 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 com tipos de entrada diferentes

$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 as opções de especificar os parâmetros 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

Erros comuns e recomendações

A seguir estão alguns erros comuns e sugestões recomendadas correspondentes ao definir um componente.

Chave Errors Recomendação
. 1. Somente entradas opcionais podem estar em $[[]]
2. Não há suporte para o uso de \ para criar uma nova linha no comando.
3. Entradas ou saídas não são encontradas.		 1. Verifique se todas as entradas ou saídas usadas no comando já estão definidas nas seções inputs e outputs e use o formato correto para entradas opcionais $[[]] ou necessárias ${{}}.
2. Não use \ para criar uma nova linha.
environment 1. Não existe nenhuma definição para o ambiente {envName}, versão {envVersion}.
2. Não existe nenhum ambiente para o nome {envName}, versão {envVersion}.
3. Não foi possível localizar o ativo com a ID {envAssetId}.		 1. Verifique se o nome do ambiente e a versão referentes à definição do componente existem.
2. É necessário especificar a versão caso se refira a um ambiente registrado.
entradas/saídas 1. Os nomes de entradas/saídas entram em conflito com os parâmetros reservados do sistema.
2. Nomes duplicados de entradas ou saídas.		 1. Não use nenhum desses parâmetros reservados como o nome de entradas/saídas: path, ld_library_path, user, logname, home, pwd, shell.
2. Verifique se os nomes de entradas e saídas não estão duplicados.

Próximas etapas