Esquema YAML do trabalho de pipeline CLI (v1)

Artigo
12/08/2023

APLICA-SE A:Azure CLI ml extension v1

Nota

A sintaxe YAML detalhada neste documento é baseada no esquema JSON para a versão v1 da extensão ML CLI. Esta sintaxe é garantida apenas para trabalhar com a extensão ML CLI v1. Alterne para a v2 (versão atual) para a sintaxe da CLI de ML v2.

Importante

Alguns dos comandos da CLI do Azure neste artigo usam a extensão , ou v1, para o azure-cli-mlAzure Machine Learning. O suporte para a extensão v1 terminará em 30 de setembro de 2025. Você poderá instalar e usar a extensão v1 até essa data.

Recomendamos que você faça a transição para a mlextensão , ou v2, antes de 30 de setembro de 2025. Para obter mais informações sobre a extensão v2, consulte Extensão CLI do Azure ML e Python SDK v2.

Defina seus pipelines de aprendizado de máquina no YAML. Ao usar a extensão de aprendizado de máquina para a CLI do Azure v1., muitos dos comandos relacionados ao pipeline esperam um arquivo YAML que define o pipeline.

A tabela a seguir lista o que é e o que não é suportado atualmente ao definir um pipeline no YAML para uso com a CLI v1:

Tipo de passo	Suportada?
PythonScriptStep	Sim
ParallelRunStep	Sim
AdlaStep	Sim
AzureBatchStep	Sim
DatabricksStep	Sim
DataTransferStep	Sim
AutoMLStep	Não
HyperDriveStep	Não
ModuleStep	Sim
MPIStep	Não
EstimatorStep	Não

Definição de pipeline

Uma definição de pipeline usa as seguintes chaves, que correspondem à classe Pipelines:

Chave YAML	Description
`name`	A descrição do gasoduto.
`parameters`	Parâmetro(s) para o pipeline.
`data_reference`	Define como e onde os dados devem ser disponibilizados em uma execução.
`default_compute`	Destino de computação padrão onde todas as etapas do pipeline são executadas.
`steps`	As etapas usadas no pipeline.

Parâmetros

A parameters seção usa as seguintes chaves, que correspondem à classe PipelineParameter :

Chave YAML	Description
`type`	O tipo de valor do parâmetro. Os tipos válidos são `string`, , , , `boolintfloat`ou .`datapath`
`default`	O valor padrão.

Cada parâmetro é nomeado. Por exemplo, o seguinte trecho de YAML define três parâmetros chamados NumIterationsParameter, DataPathParametere NodeCountParameter:

pipeline:
    name: SamplePipelineFromYaml
    parameters:
        NumIterationsParameter:
            type: int
            default: 40
        DataPathParameter:
            type: datapath
            default:
                datastore: workspaceblobstore
                path_on_datastore: sample2.txt
        NodeCountParameter:
            type: int
            default: 4

Referência de dados

A data_references seção usa as seguintes chaves, que correspondem ao DataReference:

Chave YAML	Description
`datastore`	O armazenamento de dados a ser referenciado.
`path_on_datastore`	O caminho relativo no armazenamento de backup para a referência de dados.

Cada referência de dados está contida em uma chave. Por exemplo, o seguinte trecho do YAML define uma referência de dados armazenada na chave chamada employee_data:

pipeline:
    name: SamplePipelineFromYaml
    parameters:
        PipelineParam1:
            type: int
            default: 3
    data_references:
        employee_data:
            datastore: adftestadla
            path_on_datastore: "adla_sample/sample_input.csv"

Passos

As etapas definem um ambiente computacional, juntamente com os arquivos a serem executados no ambiente. Para definir o tipo de uma etapa, use a type chave:

Tipo de passo	Description
`AdlaStep`	Executa um script U-SQL com o Azure Data Lake Analytics. Corresponde à classe AdlaStep .
`AzureBatchStep`	Executa trabalhos usando o Lote do Azure. Corresponde à classe AzureBatchStep .
`DatabricsStep`	Adiciona um bloco de anotações Databricks, script Python ou JAR. Corresponde à classe DatabricksStep .
`DataTransferStep`	Transfere dados entre opções de armazenamento. Corresponde à classe DataTransferStep .
`PythonScriptStep`	Executa um script Python. Corresponde à classe PythonScriptStep .
`ParallelRunStep`	Executa um script Python para processar grandes quantidades de dados de forma assíncrona e em paralelo. Corresponde à classe ParallelRunStep .

Passo ADLA

Chave YAML	Description
`script_name`	O nome do script U-SQL (relativo ao `source_directory`).
`compute`	O destino de computação do Azure Data Lake a ser usado para esta etapa.
`parameters`	Parâmetros para o pipeline.
`inputs`	As entradas podem ser InputPortBinding, DataReference, PortDataReference , PipelineData , Dataset, DatasetDefinition ou PipelineDataset.
`outputs`	As saídas podem ser PipelineData ou OutputPortBinding.
`source_directory`	Diretório que contém o script, assemblies, etc.
`priority`	O valor de prioridade a ser usado para o trabalho atual.
`params`	Dicionário de pares nome-valor.
`degree_of_parallelism`	O grau de paralelismo a utilizar para este trabalho.
`runtime_version`	A versão de tempo de execução do mecanismo do Data Lake Analytics.
`allow_reuse`	Determina se a etapa deve reutilizar os resultados anteriores quando executada novamente com as mesmas configurações.

O exemplo a seguir contém uma definição de etapa ADLA:

pipeline:
    name: SamplePipelineFromYaml
    parameters:
        PipelineParam1:
            type: int
            default: 3
    data_references:
        employee_data:
            datastore: adftestadla
            path_on_datastore: "adla_sample/sample_input.csv"
    default_compute: adlacomp
    steps:
        Step1:
            runconfig: "D:\\Yaml\\default_runconfig.yml"
            parameters:
                NUM_ITERATIONS_2:
                    source: PipelineParam1
                NUM_ITERATIONS_1: 7
            type: "AdlaStep"
            name: "MyAdlaStep"
            script_name: "sample_script.usql"
            source_directory: "D:\\scripts\\Adla"
            inputs:
                employee_data:
                    source: employee_data
            outputs:
                OutputData:
                    destination: Output4
                    datastore: adftestadla
                    bind_mode: mount

Etapa do Lote do Azure

Chave YAML	Description
`compute`	O destino de computação do Lote do Azure a ser usado para esta etapa.
`inputs`	As entradas podem ser InputPortBinding, DataReference, PortDataReference , PipelineData , Dataset, DatasetDefinition ou PipelineDataset.
`outputs`	As saídas podem ser PipelineData ou OutputPortBinding.
`source_directory`	Diretório que contém os binários do módulo, executável, assemblies, etc.
`executable`	Nome do comando/executável que será executado como parte deste trabalho.
`create_pool`	Sinalizador booleano para indicar se o pool deve ser criado antes de executar o trabalho.
`delete_batch_job_after_finish`	Sinalizador booleano para indicar se o trabalho deve ser excluído da conta Batch após sua conclusão.
`delete_batch_pool_after_finish`	Sinalizador booleano para indicar se o pool deve ser excluído após a conclusão do trabalho.
`is_positive_exit_code_failure`	Sinalizador booleano para indicar se o trabalho falhar se a tarefa for encerrada com um código positivo.
`vm_image_urn`	Se `create_pool` é `True`, e VM usa `VirtualMachineConfiguration`.
`pool_id`	A ID do pool onde o trabalho será executado.
`allow_reuse`	Determina se a etapa deve reutilizar os resultados anteriores quando executada novamente com as mesmas configurações.

O exemplo a seguir contém uma definição de etapa do Lote do Azure:

pipeline:
    name: SamplePipelineFromYaml
    parameters:
        PipelineParam1:
            type: int
            default: 3
    data_references:
        input:
            datastore: workspaceblobstore
            path_on_datastore: "input.txt"
    default_compute: testbatch
    steps:
        Step1:
            runconfig: "D:\\Yaml\\default_runconfig.yml"
            parameters:
                NUM_ITERATIONS_2:
                    source: PipelineParam1
                NUM_ITERATIONS_1: 7
            type: "AzureBatchStep"
            name: "MyAzureBatchStep"
            pool_id: "MyPoolName"
            create_pool: true
            executable: "azurebatch.cmd"
            source_directory: "D:\\scripts\\AureBatch"
            allow_reuse: false
            inputs:
                input:
                    source: input
            outputs:
                output:
                    destination: output
                    datastore: workspaceblobstore

Etapa do Databricks

Chave YAML	Description
`compute`	O destino de computação do Azure Databricks a ser usado para esta etapa.
`inputs`	As entradas podem ser InputPortBinding, DataReference, PortDataReference , PipelineData , Dataset, DatasetDefinition ou PipelineDataset.
`outputs`	As saídas podem ser PipelineData ou OutputPortBinding.
`run_name`	O nome no Databricks para esta execução.
`source_directory`	Diretório que contém o script e outros arquivos.
`num_workers`	O número estático de trabalhadores para o cluster de execução Databricks.
`runconfig`	O caminho para um `.runconfig` arquivo. Este arquivo é uma representação YAML da classe RunConfiguration . Para obter mais informações sobre a estrutura desse arquivo, consulte runconfigschema.json.
`allow_reuse`	Determina se a etapa deve reutilizar os resultados anteriores quando executada novamente com as mesmas configurações.

O exemplo a seguir contém uma etapa Databricks:

pipeline:
    name: SamplePipelineFromYaml
    parameters:
        PipelineParam1:
            type: int
            default: 3
    data_references:
        adls_test_data:
            datastore: adftestadla
            path_on_datastore: "testdata"
        blob_test_data:
            datastore: workspaceblobstore
            path_on_datastore: "dbtest"
    default_compute: mydatabricks
    steps:
        Step1:
            runconfig: "D:\\Yaml\\default_runconfig.yml"
            parameters:
                NUM_ITERATIONS_2:
                    source: PipelineParam1
                NUM_ITERATIONS_1: 7
            type: "DatabricksStep"
            name: "MyDatabrickStep"
            run_name: "DatabricksRun"
            python_script_name: "train-db-local.py"
            source_directory: "D:\\scripts\\Databricks"
            num_workers: 1
            allow_reuse: true
            inputs:
                blob_test_data:
                    source: blob_test_data
            outputs:
                OutputData:
                    destination: Output4
                    datastore: workspaceblobstore
                    bind_mode: mount

Etapa de transferência de dados

Chave YAML	Description
`compute`	O destino de computação do Azure Data Factory a ser usado para esta etapa.
`source_data_reference`	Conexão de entrada que serve como fonte de operações de transferência de dados. Os valores suportados são InputPortBinding, DataReference, PortDataReference , PipelineData , Dataset, DatasetDefinition ou PipelineDataset.
`destination_data_reference`	Conexão de entrada que serve como destino de operações de transferência de dados. Os valores suportados são PipelineData e OutputPortBinding.
`allow_reuse`	Determina se a etapa deve reutilizar os resultados anteriores quando executada novamente com as mesmas configurações.

O exemplo a seguir contém uma etapa de transferência de dados:

pipeline:
    name: SamplePipelineFromYaml
    parameters:
        PipelineParam1:
            type: int
            default: 3
    data_references:
        adls_test_data:
            datastore: adftestadla
            path_on_datastore: "testdata"
        blob_test_data:
            datastore: workspaceblobstore
            path_on_datastore: "testdata"
    default_compute: adftest
    steps:
        Step1:
            runconfig: "D:\\Yaml\\default_runconfig.yml"
            parameters:
                NUM_ITERATIONS_2:
                    source: PipelineParam1
                NUM_ITERATIONS_1: 7
            type: "DataTransferStep"
            name: "MyDataTransferStep"
            adla_compute_name: adftest
            source_data_reference:
                adls_test_data:
                    source: adls_test_data
            destination_data_reference:
                blob_test_data:
                    source: blob_test_data

Etapa de script Python

Chave YAML	Description
`inputs`	As entradas podem ser InputPortBinding, DataReference, PortDataReference , PipelineData , Dataset, DatasetDefinition ou PipelineDataset.
`outputs`	As saídas podem ser PipelineData ou OutputPortBinding.
`script_name`	O nome do script Python (relativo a `source_directory`).
`source_directory`	Diretório que contém o script, ambiente Conda, etc.
`runconfig`	O caminho para um `.runconfig` arquivo. Este arquivo é uma representação YAML da classe RunConfiguration . Para obter mais informações sobre a estrutura desse arquivo, consulte runconfig.json.
`allow_reuse`	Determina se a etapa deve reutilizar os resultados anteriores quando executada novamente com as mesmas configurações.

O exemplo a seguir contém uma etapa de script Python:

pipeline:
    name: SamplePipelineFromYaml
    parameters:
        PipelineParam1:
            type: int
            default: 3
    data_references:
        DataReference1:
            datastore: workspaceblobstore
            path_on_datastore: testfolder/sample.txt
    default_compute: cpu-cluster
    steps:
        Step1:
            runconfig: "D:\\Yaml\\default_runconfig.yml"
            parameters:
                NUM_ITERATIONS_2:
                    source: PipelineParam1
                NUM_ITERATIONS_1: 7
            type: "PythonScriptStep"
            name: "MyPythonScriptStep"
            script_name: "train.py"
            allow_reuse: True
            source_directory: "D:\\scripts\\PythonScript"
            inputs:
                InputData:
                    source: DataReference1
            outputs:
                OutputData:
                    destination: Output4
                    datastore: workspaceblobstore
                    bind_mode: mount

Etapa de execução paralela

Chave YAML	Description
`inputs`	As entradas podem ser Dataset, DatasetDefinition ou PipelineDataset .
`outputs`	As saídas podem ser PipelineData ou OutputPortBinding.
`script_name`	O nome do script Python (relativo a `source_directory`).
`source_directory`	Diretório que contém o script, ambiente Conda, etc.
`parallel_run_config`	O caminho para um `parallel_run_config.yml` arquivo. Este arquivo é uma representação YAML da classe ParallelRunConfig .
`allow_reuse`	Determina se a etapa deve reutilizar os resultados anteriores quando executada novamente com as mesmas configurações.

O exemplo a seguir contém uma etapa de execução paralela:

pipeline:
    description: SamplePipelineFromYaml
    default_compute: cpu-cluster
    data_references:
        MyMinistInput:
            dataset_name: mnist_sample_data
    parameters:
        PipelineParamTimeout:
            type: int
            default: 600
    steps:        
        Step1:
            parallel_run_config: "yaml/parallel_run_config.yml"
            type: "ParallelRunStep"
            name: "parallel-run-step-1"
            allow_reuse: True
            arguments:
            - "--progress_update_timeout"
            - parameter:timeout_parameter
            - "--side_input"
            - side_input:SideInputData
            parameters:
                timeout_parameter:
                    source: PipelineParamTimeout
            inputs:
                InputData:
                    source: MyMinistInput
            side_inputs:
                SideInputData:
                    source: Output4
                    bind_mode: mount
            outputs:
                OutputDataStep2:
                    destination: Output5
                    datastore: workspaceblobstore
                    bind_mode: mount

Pipeline com várias etapas

Chave YAML	Description
`steps`	Sequência de uma ou mais definições de PipelineStep. Observe que as chaves de uma etapa se `outputs` tornam as `destinationsource` chaves da `inputs` próxima etapa.

pipeline:
    name: SamplePipelineFromYAML
    description: Sample multistep YAML pipeline
    data_references:
        TitanicDS:
            dataset_name: 'titanic_ds'
            bind_mode: download
    default_compute: cpu-cluster
    steps:
        Dataprep:
            type: "PythonScriptStep"
            name: "DataPrep Step"
            compute: cpu-cluster
            runconfig: ".\\default_runconfig.yml"
            script_name: "prep.py"
            arguments:
            - '--train_path'
            - output:train_path
            - '--test_path'
            - output:test_path
            allow_reuse: True
            inputs:
                titanic_ds:
                    source: TitanicDS
                    bind_mode: download
            outputs:
                train_path:
                    destination: train_csv
                    datastore: workspaceblobstore
                test_path:
                    destination: test_csv
        Training:
            type: "PythonScriptStep"
            name: "Training Step"
            compute: cpu-cluster
            runconfig: ".\\default_runconfig.yml"
            script_name: "train.py"
            arguments:
            - "--train_path"
            - input:train_path
            - "--test_path"
            - input:test_path
            inputs:
                train_path:
                    source: train_csv
                    bind_mode: download
                test_path:
                    source: test_csv
                    bind_mode: download

Agendas

Ao definir o agendamento para um pipeline, ele pode ser acionado por armazenamento de dados ou recorrente com base em um intervalo de tempo. A seguir estão as chaves usadas para definir uma agenda:

Chave YAML	Description
`description`	Uma descrição do calendário.
`recurrence`	Contém configurações de recorrência, se o agendamento for recorrente.
`pipeline_parameters`	Quaisquer parâmetros exigidos pelo pipeline.
`wait_for_provisioning`	Se deve aguardar a conclusão do provisionamento do agendamento.
`wait_timeout`	O número de segundos a aguardar antes do tempo limite.
`datastore_name`	O armazenamento de dados para monitorar blobs modificados/adicionados.
`polling_interval`	Quanto tempo, em minutos, entre a sondagem para blobs modificados/adicionados. Valor padrão: 5 minutos. Suporte apenas para agendamentos de armazenamento de dados.
`data_path_parameter_name`	O nome do parâmetro de pipeline de caminho de dados a ser definido com o caminho de blob alterado. Suporte apenas para agendamentos de armazenamento de dados.
`continue_on_step_failure`	Se a execução de outras etapas no PipelineRun enviado deve continuar se uma etapa falhar. Se fornecido, substituirá a `continue_on_step_failure` configuração do pipeline.
`path_on_datastore`	Opcional. O caminho no armazenamento de dados para monitorar blobs modificados/adicionados. O caminho está sob o contêiner para o armazenamento de dados, portanto, o caminho real que o agendamento monitora é container/`path_on_datastore`. Se nenhum, o contêiner de armazenamento de dados é monitorado. As adições/modificações feitas em uma subpasta do `path_on_datastore` não são monitoradas. Suporte apenas para agendamentos de armazenamento de dados.

O exemplo a seguir contém a definição para uma agenda acionada por armazenamento de dados:

Schedule: 
      description: "Test create with datastore" 
      recurrence: ~ 
      pipeline_parameters: {} 
      wait_for_provisioning: True 
      wait_timeout: 3600 
      datastore_name: "workspaceblobstore" 
      polling_interval: 5 
      data_path_parameter_name: "input_data" 
      continue_on_step_failure: None 
      path_on_datastore: "file/path"

Ao definir uma agenda recorrente, use as seguintes teclas em recurrence:

Chave YAML	Description
`frequency`	Com que frequência o horário se repete. Os valores válidos são `"Minute"`, , , , `"Week""Hour""Day"`ou .`"Month"`
`interval`	Quantas vezes o cronograma é acionado. O valor inteiro é o número de unidades de tempo a aguardar até que a agenda seja acionada novamente.
`start_time`	A hora de início da programação. O formato de cadeia de caracteres do valor é `YYYY-MM-DDThh:mm:ss`. Se nenhuma hora de início for fornecida, a primeira carga de trabalho será executada instantaneamente e as cargas de trabalho futuras serão executadas com base na programação. Se a hora de início estiver no passado, a primeira carga de trabalho será executada no próximo tempo de execução calculado.
`time_zone`	O fuso horário para a hora de início. Se nenhum fuso horário for fornecido, o UTC será usado.
`hours`	Se `frequency` for `"Day"` ou , você pode especificar um ou `"Week"`mais inteiros de 0 a 23, separados por vírgulas, como as horas do dia em que o pipeline deve ser executado. Apenas `time_of_day` ou `hours` e `minutes` pode ser usado.
`minutes`	Se `frequency` for `"Day"` ou , você pode especificar um ou `"Week"`mais inteiros de 0 a 59, separados por vírgulas, como os minutos da hora em que o pipeline deve ser executado. Apenas `time_of_day` ou `hours` e `minutes` pode ser usado.
`time_of_day`	Se `frequency` for `"Day"` ou `"Week"`, você pode especificar uma hora do dia para que a agenda seja executada. O formato de cadeia de caracteres do valor é `hh:mm`. Apenas `time_of_day` ou `hours` e `minutes` pode ser usado.
`week_days`	Se `frequency` for `"Week"`, você pode especificar um ou mais dias, separados por vírgulas, quando a programação deve ser executada. Os valores válidos são `"Monday"`, , , `"Thursday"`, , `"Friday""Saturday""Tuesday""Wednesday"`e .`"Sunday"`

O exemplo a seguir contém a definição para uma agenda recorrente:

Schedule: 
    description: "Test create with recurrence" 
    recurrence: 
        frequency: Week # Can be "Minute", "Hour", "Day", "Week", or "Month". 
        interval: 1 # how often fires 
        start_time: 2019-06-07T10:50:00 
        time_zone: UTC 
        hours: 
        - 1 
        minutes: 
        - 0 
        time_of_day: null 
        week_days: 
        - Friday 
    pipeline_parameters: 
        'a': 1 
    wait_for_provisioning: True 
    wait_timeout: 3600 
    datastore_name: ~ 
    polling_interval: ~ 
    data_path_parameter_name: ~ 
    continue_on_step_failure: None 
    path_on_datastore: ~

Próximos passos

Saiba como usar a extensão CLI para o Azure Machine Learning.

Partilhar via