Esquema YAML do trabalho de comando da CLI (v2)

Artigo
04/14/2023

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

O esquema JSON de origem pode ser encontrado em https://azuremlschemas.azureedge.net/latest/commandJob.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	Tipo	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 trabalho.	`command`	`command`
`name`	string	Nome do trabalho. Precisa ser exclusivo em todos os trabalhos no espaço de trabalho. Se isso for omitido, o Azure Machine Learning vai gerar automaticamente um GUID para o nome.
`display_name`	string	Nome de exibição do trabalho na interface do usuário no Estúdio. Dentro do espaço de trabalho ele pode ser não exclusivo. Se isso for omitido, o Azure Machine Learning vai gerar automaticamente um identificador adjetivo-substantivo legível como o nome de exibição.
`experiment_name`	string	Nome do experimento sob o qual o trabalho é organizado. O registro de execução de cada trabalho será organizado sob o experimento correspondente na guia "Experimentos" do estúdio. Se isso for omitido, o Azure Machine Learning usará como padrão o nome do diretório de trabalho no qual o trabalho foi criado.
`description`	string	Descrição do trabalho.
`tags`	objeto	Dicionário de tags para o trabalho.
`command`	string	Necessário (se não estiver usando o campo `component`). O comando a ser executado.
`code`	string	Caminho local para o diretório de código-fonte a ser carregado e usado para o trabalho.
`environment`	cadeia de caracteres ou objeto	Necessário (se não estiver usando o campo `component`). O ambiente a ser usado para o trabalho. Ele pode ser uma referência para um ambiente com versão existente no espaço de trabalho ou uma especificação de ambiente embutido. Para fazer referência a um ambiente existente, use a sintaxe `azureml:<environment_name>:<environment_version>` ou `azureml:<environment_name>@latest` (para fazer referência à versão mais recente de um ambiente). 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 em linha.
`environment_variables`	objeto	Dicionário de pares chave-valor da variável de ambiente a ser definido no processo em que o comando é executado.
`distribution`	objeto	A configuração de distribuição nos cenários de treinamento distribuídos. Um de MpiConfiguration, PyTorchConfiguration ou TensorFlowConfiguration.
`compute`	string	Nome do destino de computação no qual executar o trabalho. Isso pode ser uma referência a uma computação existente no espaço de trabalho (usando a sintaxe `azureml:<compute_name>`) ou `local` para designar a execução local. Observação: os trabalhos no pipeline não dão suporte a `local` como `compute`		`local`
`resources.instance_count`	inteiro	O número de nós que serão usados para o trabalho.		`1`
`resources.instance_type`	cadeia de caracteres	O tipo de instância a ser usado para o trabalho. Aplicável para trabalhos em execução na computação Kubernetes habilitada para o Azure Arc (onde o destino de computação especificado no campo `compute` é de `type: kubernentes`). Se for omitido, o padrão será o tipo de instância padrão para o cluster de Kubernetes. Para obter mais informações, consulte Criar e selecionar tipos de instância de Kubernetes.
`resources.shm_size`	string	O tamanho do bloco de memória compartilhada do contêiner do docker. Isso deve estar no formato de `<number><unit>`, em que o número deve ser maior que 0 e a unidade pode ser de `b` (bytes), `k` (kilobytes), `m` (megabytes) ou `g` (gigabytes).		`2g`
`limits.timeout`	Número inteiro	O tempo máximo em segundos que o trabalho tem permissão para ser executado. Quando esse limite for atingido, o sistema cancelará o trabalho.
`inputs`	objeto	Dicionário de entradas para o trabalho. A chave é um nome para a entrada dentro do contexto do trabalho e o valor é o valor de entrada. As entradas podem ser referenciadas em `command` usando a expressão `${{ inputs.<input_name> }}`.
`inputs.<input_name>`	número, número inteiro, booliano, cadeia de caracteres ou objeto	Um dos valores literais (de número de tipo, inteiro, booliano ou cadeia de caracteres) ou um objeto que contém uma especificação de dados de entrada de trabalho.
`outputs`	objeto	Dicionário de configurações de saída do trabalho. A chave é um nome para a saída dentro do contexto do trabalho e o valor é a configuração de saída. As saídas podem ser referenciadas em `command` usando a expressão `${{ outputs.<output_name> }}`.
`outputs.<output_name>`	objeto	Você pode deixar o objeto vazio. Nesse caso, a saída será do tipo `uri_folder` por padrão e o Azure Machine Learning vai gerar pelo sistema um local de saída para a saída. Os arquivos no diretório de saída serão gravados por meio da montagem de leitura/gravação. Se você desejar especificar um modo diferente para a saída, forneça um objeto que contenha a especificação de saída do trabalho.
`identity`	objeto	A identidade é usada para acessar dados. Pode ser UserIdentityConfiguration, ManagedIdentityConfiguration ou None. Se for UserIdentityConfiguration, a identidade do remetente do trabalho será usada para acessar dados de entrada e gravar o resultado na pasta de saída; caso contrário, será usada a identidade gerenciada do destino de computação.

Configurações de distribuição

MpiConfiguration

Chave	Tipo	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	Tipo	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	Tipo	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`

Entradas de trabalho

Chave	Tipo	Descrição	Valores permitidos	Valor padrão
`type`	string	O tipo de entrada de trabalho. Especifique `uri_file` para dados de entrada que apontem para uma única fonte de arquivo ou `uri_folder` para dados de entrada que apontem para uma fonte de pasta.	`uri_file`, `uri_folder`, `mlflow_model`, `custom_model`	`uri_folder`
`path`	string	O caminho para os dados a serem usados como entrada. Ele pode ser especificado de algumas maneiras: - Um caminho local para o arquivo ou pasta da fonte de dados, por exemplo `path: ./iris.csv`. Os dados serão carregados durante o envio do trabalho. - Um URI de um caminho de nuvem para o arquivo ou pasta a ser usado como entrada. Os tipos de URI com suporte são `azureml`, `https`, `wasbs`, `abfss`, `adl`. Confira Sintaxe principal do YAML para saber mais sobre como usar o formato URI `azureml://`. – Um ativo de dados existente e registrado do Azure Machine Learning a ser usado como a entrada. Para fazer referência a um ativo de dados registrado, use a sintaxe `azureml:<data_name>:<data_version>` ou `azureml:<data_name>@latest` (para fazer referência à versão mais recente desse ativo de dados), por exemplo `path: azureml:cifar10-data:1` ou `path: azureml:cifar10-data@latest`.
`mode`	string	Modo como os dados devem ser entregues ao destino de computação. Na montagem somente leitura (`ro_mount`), os dados serão consumidos como um caminho de montagem. Uma pasta será montada como uma pasta e um arquivo será montado como um arquivo. O Azure Machine Learning resolverá a entrada para o caminho de montagem. Para o modo `download`, os dados serão baixados para o destino de computação. O Azure Machine Learning resolverá a entrada para o caminho baixado. Se desejar somente a URL do local de armazenamento dos artefatos de dados em vez de montar ou baixar os próprios dados, você pode usar o modo `direct`. Isso passará a URL do local de armazenamento como a entrada do trabalho. Observe que, nesse caso, você é totalmente responsável por identificar credenciais para acessar o armazenamento. Os modos `eval_mount` e `eval_download` são exclusivos da MLTable e montam os dados como um caminho ou baixam os dados para o destino de computação. Para obter mais informações sobre os modos, confira Acessar dados em um trabalho	`ro_mount`, `download`, `direct`, `eval_download`, `eval_mount`	`ro_mount`

Saídas de trabalho

Chave	Tipo	Descrição	Valores permitidos	Valor padrão
`type`	string	O tipo de saída de trabalho. Para o tipo padrão `uri_folder`, a saída corresponderá a uma pasta.	`uri_folder` , `mlflow_model`, `custom_model`	`uri_folder`
`mode`	string	Modo como os arquivos de saída serão entregues ao armazenamento de destino. No modo de montagem de leitura/gravação (`rw_mount`), o diretório de saída será um diretório montado. No modo de upload, os arquivos gravados serão carregados no final do trabalho.	`rw_mount`, `upload`	`rw_mount`

Configurações de identidade

UserIdentityConfiguration

Chave	Tipo	Descrição	Valores permitidos
`type`	const	Obrigatórios. Tipo de identidade.	`user_identity`

ManagedIdentityConfiguration

Chave	Tipo	Descrição	Valores permitidos
`type`	const	Obrigatórios. Tipo de identidade.	`managed` ou `managed_identity`

Comentários

O comando az ml job pode ser usado para gerenciar trabalhos no Azure Machine Learning.

Exemplos

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

YAML: olá, mundo

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: echo "hello world"
environment:
  image: library/python:latest

YAML: nome de exibição, nome do experimento, descrição e marcas

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: echo "hello world"
environment:
  image: library/python:latest
tags:
  hello: world
display_name: hello-world-example
experiment_name: hello-world-example
description: |
  # Azure Machine Learning "hello world" job

  This is a "hello world" job running in the cloud via Azure Machine Learning!

  ## Description

  Markdown is supported in the studio for job descriptions! You can edit the description there or via CLI.

YAML: variáveis de ambiente

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: echo $hello_env_var
environment:
  image: library/python:latest
environment_variables:
  hello_env_var: "hello world"

YAML: código-fonte

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: ls
code: src
environment:
  image: library/python:latest

YAML: entradas literais

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  echo ${{inputs.hello_string}}
  echo ${{inputs.hello_number}}
environment:
  image: library/python:latest
inputs:
  hello_string: "hello world"
  hello_number: 42

YAML: gravar em saídas padrão

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: echo "hello world" > ./outputs/helloworld.txt
environment:
  image: library/python:latest

YAML: gravar em saídas de dados nomeados

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: echo "hello world" > ${{outputs.hello_output}}/helloworld.txt
outputs:
  hello_output:
environment:
  image: python

YAML: entrada de arquivo de URI de armazenamento de dados

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  echo "--iris-csv: ${{inputs.iris_csv}}"
  python hello-iris.py --iris-csv ${{inputs.iris_csv}}
code: src
inputs:
  iris_csv:
    type: uri_file 
    path: azureml://datastores/workspaceblobstore/paths/example-data/iris.csv
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest

YAML: entrada de pasta de URI de armazenamento de dados

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  ls ${{inputs.data_dir}}
  echo "--iris-csv: ${{inputs.data_dir}}/iris.csv"
  python hello-iris.py --iris-csv ${{inputs.data_dir}}/iris.csv
code: src
inputs:
  data_dir:
    type: uri_folder 
    path: azureml://datastores/workspaceblobstore/paths/example-data/
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest

YAML: entrada de arquivo de URI

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  echo "--iris-csv: ${{inputs.iris_csv}}"
  python hello-iris.py --iris-csv ${{inputs.iris_csv}}
code: src
inputs:
  iris_csv:
    type: uri_file 
    path: https://azuremlexamples.blob.core.windows.net/datasets/iris.csv
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest

YAML: entrada de pasta de URI

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  ls ${{inputs.data_dir}}
  echo "--iris-csv: ${{inputs.data_dir}}/iris.csv"
  python hello-iris.py --iris-csv ${{inputs.data_dir}}/iris.csv
code: src
inputs:
  data_dir:
    type: uri_folder 
    path: wasbs://datasets@azuremlexamples.blob.core.windows.net/
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest

YAML: Notebook através de papermill

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  pip install ipykernel papermill
  papermill hello-notebook.ipynb outputs/out.ipynb -k python
code: src
environment:
  image: library/python:3.11.6

YAML: treinamento básico do modelo Python

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: src
command: >-
  python main.py 
  --iris-csv ${{inputs.iris_csv}}
  --C ${{inputs.C}}
  --kernel ${{inputs.kernel}}
  --coef0 ${{inputs.coef0}}
inputs:
  iris_csv: 
    type: uri_file
    path: wasbs://datasets@azuremlexamples.blob.core.windows.net/iris.csv
  C: 0.8
  kernel: "rbf"
  coef0: 0.1
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest
compute: azureml:cpu-cluster
display_name: sklearn-iris-example
experiment_name: sklearn-iris-example
description: Train a scikit-learn SVM on the Iris dataset.

YAML: treinamento básico do modelo R com contexto de compilação local do Docker

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: >
  Rscript train.R 
  --data_folder ${{inputs.iris}}
code: src
inputs:
  iris: 
    type: uri_file
    path: https://azuremlexamples.blob.core.windows.net/datasets/iris.csv
environment:
  build:
    path: docker-context
compute: azureml:cpu-cluster
display_name: r-iris-example
experiment_name: r-iris-example
description: Train an R model on the Iris dataset.

YAML: PyTorch distribuído

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: src
command: >-
  python train.py 
  --epochs ${{inputs.epochs}}
  --learning-rate ${{inputs.learning_rate}}
  --data-dir ${{inputs.cifar}}
inputs:
  epochs: 1
  learning_rate: 0.2
  cifar: 
     type: uri_folder
     path: azureml:cifar-10-example@latest
environment: azureml:AzureML-pytorch-1.9-ubuntu18.04-py37-cuda11-gpu@latest
compute: azureml:gpu-cluster
distribution:
  type: pytorch 
  process_count_per_instance: 1
resources:
  instance_count: 2
display_name: pytorch-cifar-distributed-example
experiment_name: pytorch-cifar-distributed-example
description: Train a basic convolutional neural network (CNN) with PyTorch on the CIFAR-10 dataset, distributed via PyTorch.

YAML: TensorFlow distribuído

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: src
command: >-
  python train.py 
  --epochs ${{inputs.epochs}}
  --model-dir ${{inputs.model_dir}}
inputs:
  epochs: 1
  model_dir: outputs/keras-model
environment: azureml:AzureML-tensorflow-2.4-ubuntu18.04-py37-cuda11-gpu@latest
compute: azureml:gpu-cluster
resources:
  instance_count: 2
distribution:
  type: tensorflow
  worker_count: 2
display_name: tensorflow-mnist-distributed-example
experiment_name: tensorflow-mnist-distributed-example
description: Train a basic neural network with TensorFlow on the MNIST dataset, distributed via TensorFlow.

YAML: MPI distribuído

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: src
command: >-
  python train.py
  --epochs ${{inputs.epochs}}
inputs:
  epochs: 1
environment: azureml:AzureML-tensorflow-2.7-ubuntu20.04-py38-cuda11-gpu@latest
compute: azureml:gpu-cluster
resources:
  instance_count: 2
distribution:
  type: mpi
  process_count_per_instance: 1
display_name: tensorflow-mnist-distributed-horovod-example
experiment_name: tensorflow-mnist-distributed-horovod-example
description: Train a basic neural network with TensorFlow on the MNIST dataset, distributed via Horovod.

Próximas etapas

Instalar e usar a CLI (v2)