Esquema de YAML do trabalho de pipeline da CLI (v1)

Artigo
09/01/2024

APLICA-SE A: Extensão ML da CLI do Azure v1

Observação

A sintaxe YAML detalhada neste documento baseia-se no esquema JSON na versão v1 da extensão da CLI de ML. Essa sintaxe tem apenas a garantia de funcionar com a extensão v1 da CLI de ML. Alterne para a v2 (versão atual) para a sintaxe da CLI de ML v2.

Importante

Alguns comandos da CLI do Azure neste artigo usam a extensão azure-cli-ml ou v1 do Azure Machine Learning. O suporte à 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 extensão ml ou v2, antes de 30 de setembro de 2025. Para obter mais informações sobre a extensão v2, confira Extensão da CLI do Azure ML e SDK do Python v2.

Defina pipelines de machine learning no YAML. Ao se 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 tem e o que não tem suporte atualmente ao definir um pipeline no YAML para uso com a CLI v1:

Tipo de etapa	Compatível?
PythonScriptStep	Sim
ParallelRunStep	Sim
AdlaStep	Sim
AzureBatchStep	Sim
DatabricksStep	Yes
DataTransferStep	Sim
AutoMLStep	Não
HyperDriveStep	Não
ModuleStep	Yes
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	Descrição
`name`	A descrição do pipeline.
`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 são executadas todas as etapas no pipeline.
`steps`	As etapas usadas no pipeline.

Parâmetros

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

Chave YAML	Descrição
`type`	O tipo de valor do parâmetro. Os tipos válidos são `string`, `int`, `float`, `bool`, ou `datapath`.
`default`	O valor padrão.

Cada parâmetro é nomeado. Por exemplo, o trecho de código YAML a seguir define três parâmetros chamados NumIterationsParameter, DataPathParameter e 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 seção data_references usa as seguintes chaves, que correspondem à DataReference:

Chave YAML	Descrição
`datastore`	O armazenamento de dados para referenciar.
`path_on_datastore`	O caminho relativo no armazenamento de suporte para referência de dados.

Cada referência de dados está contida em uma chave. Por exemplo, o snippet YAML a seguir 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"

Etapas

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

Tipo de etapa	Descrição
`AdlaStep`	Executa um script U-SQL com 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 do Databricks, um script do Python ou um JAR. Corresponde à classe DatabricksStep.
`DataTransferStep`	Transfere dados entre as opções de armazenamento. Corresponde à classe DataTransferStep.
`PythonScriptStep`	Executa um script do Python. Corresponde à classe PythonScriptStep.
`ParallelRunStep`	Executa um script do Python para processar grandes quantidades de dados de forma assíncrona e em paralelo. Corresponde à classe ParallelRunStep.

Etapa ADLA

Chave YAML	Descrição
`script_name`	O nome do script U-SQL (relativo ao `source_directory`).
`compute`	O destino de computação 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, DatasetDefinitionou PipelineDataset.
`outputs`	As saídas podem ser PipelineData ou OutputPortBinding.
`source_directory`	Diretório que contém o script, os assemblies, etc.
`priority`	O valor da prioridade a ser usado para o trabalho atual.
`params`	Dicionário de pares nome-valor.
`degree_of_parallelism`	O grau de paralelismo a ser usado para este trabalho.
`runtime_version`	A versão de tempo de execução do mecanismo de Data Lake Analytics.
`allow_reuse`	Determina se a etapa deve reutilizar os resultados anteriores quando for 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	Descrição
`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, DatasetDefinitionou PipelineDataset.
`outputs`	As saídas podem ser PipelineData ou OutputPortBinding.
`source_directory`	Diretório que contém os binários de módulo, executáveis, assemblies, etc.
`executable`	Nome do comando/executável que será executado como parte desse trabalho.
`create_pool`	Sinalizador booliano para indicar se o pool deve ser criado antes da execução do trabalho.
`delete_batch_job_after_finish`	Sinalizador booliano para indicar se o trabalho da conta do Lote deve ser excluído após ser concluído.
`delete_batch_pool_after_finish`	Sinalizador booliano para indicar se o pool deve ser excluído após a conclusão do trabalho.
`is_positive_exit_code_failure`	Sinalizador booliano para indicar se o trabalho falhará se a tarefa for encerrada com um código positivo.
`vm_image_urn`	Se `create_pool` é `True` e a VM usa `VirtualMachineConfiguration`.
`pool_id`	A ID do pool em que o trabalho será executado.
`allow_reuse`	Determina se a etapa deve reutilizar os resultados anteriores quando for 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	Descrição
`compute`	O destino de computação Azure Databricks a ser usado para esta etapa.
`inputs`	As entradas podem ser InputPortBinding, DataReference, PortDataReference, PipelineData, DataSet, DatasetDefinitionou 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 Databricks executar o cluster.
`runconfig`	O caminho para um arquivo `.runconfig`. Esse arquivo é uma representação YAML da classe RunConfiguration. Para obter mais informações sobre a estrutura desse arquivo, consulte o runconfigschema.json.
`allow_reuse`	Determina se a etapa deve reutilizar os resultados anteriores quando for executada novamente com as mesmas configurações.

O exemplo a seguir contém uma etapa do 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

Etapade transferência de dados

Chave YAML	Descrição
`compute`	O destino de computação Azure Data Factory a ser usado para esta etapa.
`source_data_reference`	Conexão de entrada que serve como a fonte de operações de transferência de dados. Os valores com suporte são InputPortBinding, DataReference, PortDataReference, PipelineData, DataSet, DatasetDefinitionou PipelineDataset.
`destination_data_reference`	Conexão de entrada que serve como o destino das operações de transferência de dados. Os valores com suporte são PipelineData e OutputPortBinding.
`allow_reuse`	Determina se a etapa deve reutilizar os resultados anteriores quando for 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 do Python

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

O exemplo a seguir contém uma etapa de script do 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	Descrição
`inputs`	As entradas podem ser DataSet, DatasetDefinitionou PipelineDataset.
`outputs`	As saídas podem ser PipelineData ou OutputPortBinding.
`script_name`	O nome do script do Python (relativo a `source_directory`).
`source_directory`	Diretório que contém o script, o ambiente Conda, etc.
`parallel_run_config`	O caminho para um arquivo `parallel_run_config.yml`. Esse arquivo é uma representação YAML da classe ParallelRunConfig.
`allow_reuse`	Determina se a etapa deve reutilizar os resultados anteriores quando for 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	Descrição
`steps`	Sequência de uma ou mais definições de PipelineStep. Observe que as chaves `destination` de uma etapa de `outputs` se tornam as chaves `source` para o `inputs` da 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 de um pipeline, ele pode ser disparado por armazenamento de dados ou ser recorrente com base em um intervalo de tempo. A seguir estão as chaves usadas para definir uma agenda:

Chave YAML	Descrição
`description`	Uma descrição da agenda.
`recurrence`	Contém configurações de recorrência, se a agenda for recorrente.
`pipeline_parameters`	Quaisquer parâmetros obrigatórios pelo pipeline.
`wait_for_provisioning`	Se deve aguardar a conclusão do provisionamento da agenda.
`wait_timeout`	O número de segundos a aguardar antes de esgotar o tempo limite.
`datastore_name`	O armazenamento de dados a ser monitorado para blobs modificados/adicionados.
`polling_interval`	Por quanto tempo, em minutos, entre a sondagem para blobs modificados/adicionados. Valor padrão: 5 minutos. Com suporte apenas para agendas 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. Com suporte apenas para agendas de armazenamento de dados.
`continue_on_step_failure`	Se deseja continuar a execução de outras etapas no PipelineRun enviado se uma etapa falhar. Se fornecido, substituirá a configuração do pipeline `continue_on_step_failure`.
`path_on_datastore`	Opcional. O caminho no armazenamento de dados a ser monitorado para blobs modificados/adicionados. O caminho está sob o contêiner para o armazenamento de dados, portanto, o caminho real que o agendamento monitora é contêiner/`path_on_datastore`. Se nenhum, será monitorado o contêiner do armazenamento de dados. Adições/modificações feitas em uma subpasta do `path_on_datastore` não são monitoradas. Com suporte apenas para agendas de armazenamento de dados.

O exemplo a seguir contém a definição de uma agenda disparada 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 um agendamento recorrente, use as seguintes chaves em recurrence :

Chave YAML	Descrição
`frequency`	Com que frequência a agenda se repete. Os valores válidos são `"Minute"`, `"Hour"`, `"Day"`, `"Week"`, ou `"Month"`.
`interval`	Com que frequência a agenda é disparada. O valor inteiro é o número de unidades de tempo a aguardar até que a agenda seja disparada novamente.
`start_time`	A hora de início da agenda. O formato da 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 agenda. 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`	Fuso horário para a hora de início. Se nenhum fuso horário for fornecido, será usado o UTC.
`hours`	Se `frequency` for `"Day"` ou `"Week"`, você pode especificar um ou mais números inteiros, de 0 a 23, separados por vírgulas, como as horas do dia em que o pipeline deve ser executado. Somente `time_of_day` ou `hours` e `minutes` podem ser usados.
`minutes`	Se `frequency` for `"Day"` ou `"Week"`, você pode especificar um ou mais números inteiros, de 0 a 59, separados por vírgulas, como as os minutos da hora em que o pipeline deve ser executado. Somente `time_of_day` ou `hours` e `minutes` podem ser usados.
`time_of_day`	Se `frequency` for `"Day"` ou `"Week"`, você pode especificar uma hora do dia para a execução da agenda. O formato da cadeia de caracteres do valor é `hh:mm`. Somente `time_of_day` ou `hours` e `minutes` podem ser usados.
`week_days`	Se `frequency` for `"Week"`, você poderá especificar um ou mais dias, separados por vírgulas, em que a agenda deve ser executada. Os valores válidos são `"Monday"`, `"Tuesday"`, `"Wednesday"`, `"Thursday"`, `"Friday"`, `"Saturday"` e `"Sunday"`.

O exemplo a seguir contém a definição de um agendamento 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óximas etapas

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

Compartilhar via