Crie e execute pipelines de machine learning usando componentes com a CLI do Azure Machine Learning

  • Artigo

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

Neste artigo, você aprenderá a criar e executar pipelines de machine learning usando a CLI do Azure e componentes. Você pode criar pipelines sem usar componentes, mas os componentes oferecem a maior quantidade de flexibilidade e reutilização. Os Pipelines do Azure Machine Learning podem ser definidos no YAML e executados a partir da CLI, criados em Python ou compostos no Designer do Estúdio do Azure Machine Learning com uma interface do usuário do tipo "arrastar e soltar". Este documento se concentra na CLI.

Pré-requisitos

Leitura prévia sugerida

Criar seu primeiro pipeline com componente

Vamos criar seu primeiro pipeline com componentes usando um exemplo. Esta seção tem como objetivo dar uma impressão inicial de como o pipeline e o componente ficam no Azure Machine Learning com um exemplo concreto.

No diretório cli/jobs/pipelines-with-components/basics do repositório azureml-examples, navegue para o subdiretório 3b_pipeline_with_data. Há três tipos de arquivos nesse diretório. Esses são os arquivos que você precisará criar ao criar seu pipeline.

  • pipeline.yml: esse arquivo YAML define o pipeline de machine learning. Este arquivo YAML descreve como dividir uma tarefa completa de machine learning em um fluxo de trabalho de vários passos. Por exemplo, considerando uma tarefa simples de machine learning para usar dados históricos para treinar um modelo de previsão de vendas, convém criar um fluxo de trabalho sequencial com etapas de processamento de dados, treinamento do modelo e avaliação do modelo. Cada etapa é um componente que tem uma interface bem definida e pode ser desenvolvida, testada e otimizada de modo independente. O YAML de pipeline também define como as etapas filho se conectam a outras etapas no pipeline, por exemplo, a etapa de treinamento do modelo gera um arquivo de modelo e o arquivo de modelo passa para uma etapa de avaliação de modelo.

  • component.yml: esse arquivo YAML define o componente. Ele empacota as seguintes informações:

    • Metadados: nome, nome de exibição, versão, descrição, tipo etc. Os metadados ajudam a descrever e gerenciar o componente.
    • Interface: entradas e saídas. Por exemplo, um componente de treinamento de modelo usará dados de treinamento e número de épocas como entrada e gerará um arquivo de modelo treinado como saída. Depois que a interface for definida, diferentes equipes poderão desenvolver e testar o componente de modo independente.
    • Comando, código e ambiente: o comando, o código e o ambiente para executar o componente. O comando é o comando de shell para executar o componente. O código geralmente se refere a um diretório de código-fonte. O ambiente pode ser um ambiente do Azure Machine Learning (coletado ou criado pelo cliente), uma imagem do Docker ou um ambiente do Conda.

  • component_src: esse é o diretório de código-fonte para um componente específico. Ele contém o código-fonte que será executado no componente. Você pode usar sua linguagem preferida (Python, R etc.). O código deve ser executado por um comando de shell. O código-fonte pode usar algumas entradas da linha de comando do shell para controlar como essa etapa será executada. Por exemplo, uma etapa de treinamento pode pegar dados de treinamento, taxa de aprendizado e número de épocas para controlar o processo de treinamento. O argumento de um comando de shell é usado para passar entradas e saídas para o código.

Agora vamos criar um pipeline usando o exemplo 3b_pipeline_with_data. Explicaremos o significado detalhado de cada arquivo nas seções a seguir.

Primeiro, liste os recursos de computação disponíveis com o seguinte comando:

az ml compute list

Se você não o tiver, crie um cluster chamado cpu-cluster executando:

Observação

Ignore esta etapa para usar a computação sem servidor.

az ml compute create -n cpu-cluster --type amlcompute --min-instances 0 --max-instances 10

Agora, crie um trabalho de pipeline definido no arquivo pipeline.yml com o comando a seguir. O destino de computação será referenciado no arquivo pipeline.yml como azureml:cpu-cluster. Se o destino de computação usar um nome diferente, lembre-se de atualizá-lo no arquivo pipeline.yml.

az ml job create --file pipeline.yml

Você deve receber um dicionário JSON com informações sobre o trabalho de pipeline, incluindo:

Chave Descrição
name O nome baseado em GUID do trabalho.
experiment_name O nome sob o qual os trabalhos serão organizados no Estúdio.
services.Studio.endpoint Uma URL para monitorar e revisar o trabalho do pipeline.
status O status do trabalho. Isso provavelmente será Preparing neste momento.

Abra a URL services.Studio.endpoint para ver uma visualização de grafo do pipeline.

Screenshot of a graph visualization of the pipeline.

Entender a definição de pipeline YAML

Vamos dar uma olhada na definição de pipeline no arquivo 3b_pipeline_with_data/pipeline.yml.

Observação

Para usar a computação sem servidor, substitua default_compute: azureml:cpu-cluster por default_compute: azureml:serverless neste arquivo.

$schema: https://azuremlschemas.azureedge.net/latest/pipelineJob.schema.json
type: pipeline

display_name: 3b_pipeline_with_data
description: Pipeline with 3 component jobs with data dependencies

settings:
  default_compute: azureml:cpu-cluster

outputs:
  final_pipeline_output:
    mode: rw_mount

jobs:
  component_a:
    type: command
    component: ./componentA.yml
    inputs:
      component_a_input: 
        type: uri_folder
        path: ./data

    outputs:
      component_a_output: 
        mode: rw_mount
  component_b:
    type: command
    component: ./componentB.yml
    inputs:
      component_b_input: ${{parent.jobs.component_a.outputs.component_a_output}}
    outputs:
      component_b_output: 
        mode: rw_mount
  component_c:
    type: command
    component: ./componentC.yml
    inputs:
      component_c_input: ${{parent.jobs.component_b.outputs.component_b_output}}
    outputs:
      component_c_output: ${{parent.outputs.final_pipeline_output}}
      #  mode: upload

A tabela descreve os campos usados mais comuns do esquema YAML do pipeline. Para saber mais, confira o esquema YAML de pipeline completo.

chave descrição
type Obrigatório. Tipo de trabalho, deve ser pipeline para trabalhos de pipeline.
display_name Nome de exibição do trabalho de pipeline na interface do usuário do Estúdio. Editável na interface do usuário do Estúdio. Não precisa ser exclusivo em todos os trabalhos no workspace.
jobs Obrigatório. Dicionário do conjunto de trabalhos individuais a serem executados como etapas no pipeline. Esses trabalhos são considerados trabalhos filho do trabalho do pipeline pai. Nesta versão, os tipos de trabalho com suporte no pipeline são command e sweep
entradas Dicionário de entradas para o trabalho de pipeline. A chave é um nome para a entrada dentro do contexto do trabalho e o valor é o valor de entrada. Essas entradas de pipeline podem ser referenciadas pelas entradas de um trabalho de etapa individual no pipeline por meio da expressão ${{ parent.inputs.<input_name> }}.
outputs Dicionário de configurações de saída do trabalho de pipeline. A chave é um nome para a saída dentro do contexto do trabalho e o valor é a configuração de saída. Essas saídas de pipeline podem ser referenciadas pelas saídas de um trabalho de etapa individual no pipeline por meio da expressão ${{ parents.outputs.<output_name> }}.

No exemplo 3b_pipeline_with_data, criamos um pipeline de três etapas.

  • As três etapas são definidas em jobs. O tipo de três etapas é o trabalho de comando. A definição de cada etapa está no arquivo correspondente component.yml. Você pode ver os arquivos YAML do componente no diretório 3b_pipeline_with_data. Explicaremos o componentA.yml na próxima seção.
  • Esse pipeline tem dependência de dados, o que é comum na maioria dos pipelines do mundo real. O Component_a usa a entrada de dados da pasta local em ./data(linha 17-20) e passa sua saída para componentB (linha 29). A saída do Component_a pode ser referenciada como ${{parent.jobs.component_a.outputs.component_a_output}}.
  • O compute define a computação padrão para esse pipeline. Se um componente em jobs definir uma computação diferente para esse componente, o sistema respeitará a configuração específica do componente.

Screenshot of the pipeline with data example.

Ler e gravar dados no pipeline

Um cenário comum é ler e gravar dados no pipeline. No Azure Machine Learning, usamos o mesmo esquema para ler e gravar dados para todos os tipos de trabalhos (trabalho de pipeline, trabalho de comando e trabalho de limpeza). Veja a seguir exemplos de trabalho de pipeline de uso de dados para cenários comuns.

Entender o YAML de definição do componente

Agora vamos examinar o componentA.yml como um exemplo para entender o YAML de definição do componente.

$schema: https://azuremlschemas.azureedge.net/latest/commandComponent.schema.json
type: command

name: component_a
display_name: componentA
version: 1

inputs:
  component_a_input:
    type: uri_folder

outputs:
  component_a_output:
    type: uri_folder

code: ./componentA_src

environment: 
  image: python

command: >-
  python hello.py --componentA_input ${{inputs.component_a_input}} --componentA_output ${{outputs.component_a_output}}

O esquema usado mais comum do componente YAML é descrito na tabela. Para saber mais, consulte o esquema YAML de componente completo.

chave descrição
name Obrigatório. Nome do componente. Precisa ser exclusivo no workspace do Azure Machine Learning. Deve começar com letra minúscula. Permitir letras minúsculas, números e sublinhados (_). O comprimento máximo é de 255 caracteres.
display_name Nome de exibição do componente na interface do usuário no estúdio. Dentro do workspace ele pode ser não exclusivo.
command Obrigatório o comando para executar
code Caminho local para o diretório de código-fonte a ser carregado e usado para o componente.
environment Obrigatório. O ambiente que será usado para executar o componente.
entradas 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 no comando usando a expressão ${{ inputs.<input_name> }}.
outputs 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 no comando usando a expressão ${{ outputs.<output_name> }}.
is_deterministic Se será necessário reutilizar o resultado do trabalho anterior se as entradas do componente não mudarem. O valor padrão é true, também conhecido como reuse por padrão. O cenário comum quando definido como false é forçar o recarregamento de dados de um armazenamento ou URL na nuvem.

Para o exemplo em 3b_pipeline_with_data/componentA.yml, o componentA tem uma entrada de dados e uma saída de dados, que podem ser conectadas a outras etapas no pipeline pai. Todos os arquivos da seção code no componente YAML serão carregados no Azure Machine Learning durante o envio do trabalho de pipeline. Neste exemplo, os arquivos em ./componentA_src serão carregados (linha 16 em componentA.yml). Você pode ver o código-fonte carregado na interface do usuário do Studio: selecione duas vezes a etapa ComponentA e navegue até a guia Instantâneo, conforme mostrado na captura de tela a seguir. Podemos ver que é um script hello-world apenas fazendo uma impressão simples e gravar a datetime atual no caminho componentA_output. O componente usa entrada e saída por meio do argumento de linha de comando e é processado em hello.py usando argparse.

Screenshot of pipeline with data example showing componentA.

Entrada e saída

A entrada e a saída definem a interface de um componente. A entrada e a saída podem ser de um valor literal (do tipo string,number,integer ou boolean) ou um objeto que contém o esquema de entrada.

A entrada de objeto (do tipo uri_file, uri_folder,mltable,mlflow_model,custom_model) pode se conectar a outras etapas no trabalho de pipeline pai e, portanto, passar dados/modelo para outras etapas. No grafo de pipeline, a entrada do tipo de objeto será renderizada como um ponto de conexão.

Entradas de valor literal (string,number,integer,boolean) são os parâmetros que você pode passar para o componente no tempo de execução. Você pode adicionar o valor padrão de entradas literais no campo default. Para os tipos number e integer, você também pode adicionar os valores mínimo e máximo aceitos usando os campos min e max. Se o valor de entrada exceder o mínimo e o máximo, o pipeline falhará na validação. A validação ocorre antes de você enviar um trabalho de pipeline para poupar tempo. A validação funciona para a CLI, o SDK do Python e a interface do usuário do designer. A captura de tela a seguir mostra um exemplo de validação na interface do usuário do designer. Da mesma forma, você pode definir valores permitidos no campo enum.

Screenshot of the input and output of the train linear regression model component.

Se você quiser adicionar uma entrada a um componente, lembre-se de editar três locais:

  • campo inputs no componente YAML
  • campo command no componente YAML.
  • Código-fonte do componente para lidar com a entrada da linha de comando. Ele está marcado em caixa verde na captura de tela anterior.

Para saber mais sobre entradas e saídas, consulte Gerenciar entradas e saídas de componente e pipeline.

Environment

Ambiente define o ambiente para executar o componente. Pode ser um ambiente do Azure Machine Learning (coletado ou personalizado registrado), uma imagem do Docker ou um ambiente do Conda. Consulte os exemplos a seguir.

Registrar componente para reutilização e compartilhamento

Embora alguns componentes sejam específicos para um pipeline específico, o benefício real dos componentes é derivado da reutilização e do compartilhamento. Registre um componente em seu workspace do Machine Learning para disponibilizá-lo para reutilização. Os componentes registrados são compatíveis com controle de versão automático para que você possa atualizar o componente, mas garantir que os pipelines que exigem uma versão mais antiga continuem funcionando.

No repositório azureml-examples, navegue até o diretório cli/jobs/pipelines-with-components/basics/1b_e2e_registered_components.

Para registrar um componente, use o comando az ml component create:

az ml component create --file train.yml
az ml component create --file score.yml
az ml component create --file eval.yml

Depois que esses comandos forem executados até a conclusão, os componentes poderão ser vistos no Studio em Ativo –> Componentes:

Screenshot of Studio showing the components that were just registered.

Selecione um componente. Você verá informações detalhadas para cada versão do componente.

Na guia Detalhes, você verá informações básicas do componente, como nome, criado por, versão etc. Você verá campos editáveis para Marcas e Descrição. As tags podem ser usadas para adicionar palavras-chave pesquisadas rapidamente. O campo de descrição dá suporte à formatação Markdown e deve ser usado para descrever a funcionalidade e o uso básico do componente.

Na guia Trabalhos, você verá o histórico de todos os trabalhos que usam esse componente.

Use componentes registrados em um arquivo YAML do trabalho do pipeline

Vamos usar 1b_e2e_registered_components para demonstrar como usar o componente registrado no YAML do pipeline. Navegue até o diretório 1b_e2e_registered_components, abra o arquivo pipeline.yml. As chaves e os valores nos campos inputs e outputs são semelhantes aos já discutidos. A única diferença significativa é o valor dos campos component nas entradas jobs.<JOB_NAME>.component. O valor component está no formato azureml:<COMPONENT_NAME>:<COMPONENT_VERSION>. A definição train-job, por exemplo, especifica que a versão mais recente do componente my_train registrado deve ser usada:

type: command
component: azureml:my_train@latest
inputs:
  training_data: 
    type: uri_folder 
    path: ./data      
  max_epocs: ${{parent.inputs.pipeline_job_training_max_epocs}}
  learning_rate: ${{parent.inputs.pipeline_job_training_learning_rate}}
  learning_rate_schedule: ${{parent.inputs.pipeline_job_learning_rate_schedule}}
outputs:
  model_output: ${{parent.outputs.pipeline_job_trained_model}}
services:
  my_vscode:

Gerenciar componentes

Você pode verificar os detalhes do componente e gerenciar o componente usando a CLI (v2). Use az ml component -h para obter instruções detalhadas sobre o comando de componente. A seguinte tabela lista todas os comandos disponíveis. Veja mais exemplos na referência da CLI do Azure.

commands descrição
az ml component create Criar um componente
az ml component list Listar componentes em um workspace
az ml component show Mostrar detalhes de um componente
az ml component update Atualizar um componente. Apenas alguns campos (descrição, display_name) dão suporte para atualização
az ml component archive Arquivar um contêiner de componentes
az ml component restore Restaurar um componente arquivado

Próximas etapas