Executar um pipeline

O Vertex AI Pipelines permite executar pipelines de machine learning (ML) criados usando o SDK do Kubeflow Pipelines ou o TensorFlow Extended sem servidor. Neste documento, descrevemos como executar um pipeline de ML.

Também é possível criar execuções de pipeline usando modelos predefinidos na Galeria de modelos. Para mais informações sobre a Galeria de modelos, consulte Usar um modelo predefinido da Galeria de modelos.

Antes de começar

Antes de executar um pipeline com o Vertex AI Pipelines, siga as seguintes instruções para configurar seu projeto do Google Cloud e o ambiente de desenvolvimento.

Crie um pipeline.
Para executar um pipeline usando o SDK do Vertex AI para Python, instale o SDK Vertex.
- Instale o SDK do Vertex AI.

Criar uma execução de pipeline

Use as instruções a seguir para executar um pipeline de ML usando o Console do Google Cloud ou o Python.

Console

Siga as instruções a seguir para executar um pipeline de ML usando o console do Google Cloud.

No console do Google Cloud, na seção Vertex AI, acesse a página Pipelines.

Acessar "Pipelines"
Na lista suspensa Região, selecione a região para criar a execução do pipeline.
Clique em Criar execução para abrir o painel Criar execução do pipeline.
Na seção Detalhes de execução, faça o seguinte:
1. Clique em Executar origem. As seguintes opções estão disponíveis:
  - Selecionar pipelines atuais: para criar uma execução de pipeline com base em um modelo de pipeline atual, clique em Selecionar pipelines atuais e insira os seguintes detalhes:
    1. Selecione o Repositório que contém o pipeline ou o arquivo de definição do componente.
    2. Selecione o Pipeline ou componente e a Versão.
    3. Especifique um Nome de execução para identificar exclusivamente essa execução de pipeline.
  - Selecione um pipeline da galeria de modelos: para criar uma execução de pipeline com base em um modelo de pipeline criado pelo Google usando a Galeria de modelos, clique em Selecionar um pipeline da galeria de modelos e insira os seguintes detalhes:
    1. Na lista Pipeline da galeria de modelos, selecione o modelo de pipeline.
    2. Opcional: modifique o Nome de execução padrão que identifica exclusivamente a execução do pipeline.
    Observação: estas instruções descrevem como criar uma execução de pipeline usando a interface padrão da página Criar execução do pipeline, que compreende as seções Detalhes da execução e Configuração do ambiente de execução. Para alguns modelos da Galeria de modelos, esta página tem seções adicionais. Por exemplo, o modelo AutoML para classificação / regressão tabular também inclui as seções Método de treinamento, Opções de treinamento, e Computação e preços.
  - Fazer upload do arquivo: para fazer o upload de uma definição de pipeline compilada, clique em Fazer upload de arquivo e insira os seguintes detalhes:
    1. Clique em Procurar para abrir o seletor de arquivos. Acesse o arquivo YAML de pipeline compilado que você quer executar, selecione o pipeline e clique em Abrir.
    2. O Nome do pipeline ou do componente mostra o nome especificado na definição de pipeline por padrão. Opcionalmente, especifique um nome de pipeline diferente.
    3. Especifique um Nome de execução para identificar exclusivamente essa execução de pipeline.
  - Importar do Cloud Storage: para importar um arquivo de definição de pipeline do Cloud Storage, clique em Importar do Cloud Storage e insira os seguintes detalhes:
    1. Clique em Procurar para acessar o bucket do Cloud Storage que contém o objeto de definição de pipeline, selecione o arquivo e clique em Selecionar.
    2. Especifique o Nome do pipeline ou do componente.
    3. Especifique um Nome de execução para identificar exclusivamente essa execução de pipeline.
2. Opcional: para programar execuções de pipeline recorrentes, especifique a Programação de execução da seguinte maneira:
  1. Selecione Recorrente.
  2. Em Horário de início, especifique quando a programação ficará ativa.
    - Para programar a primeira execução imediatamente após a criação da programação, selecione Imediatamente.
    - Para programar que a primeira execução ocorra em um horário e uma data específicos, selecione Ativado.
  3. No campo Frequência, especifique a frequência para programar e executar as execuções do pipeline usando uma expressão de programação cron baseada em unix-cron.
  4. Em Término, especifique quando a programação termina.
    - Para indicar que a programação cria execuções do pipeline indefinidamente, selecione Nunca.
    - Para indicar que a programação termina em uma data e hora específicas, selecione Ativado e especifique a data e a hora de término.
  5. Opcional: para especificar que a execução do pipeline usa uma conta de serviço personalizada, uma chave de criptografia gerenciada pelo cliente (CMEK) ou uma rede VPC com peering, clique em Opções avançadas e siga estas instruções:
    - Para especificar uma conta de serviço, selecione uma na lista suspensa Conta de serviço.
      
      Se você não especificar uma conta de serviço, o Vertex AI Pipelines executará o pipeline usando a conta de serviço padrão do Compute Engine.
      
      Saiba mais sobre Como configurar uma conta de serviço para uso com o Vertex AI Pipelines.
    - Para usar uma CMEK, selecione Usar uma chave de criptografia gerenciada pelo cliente. A lista suspensa Selecionar uma chave gerenciada pelo cliente é exibida. Na lista suspensa Selecionar uma chave gerenciada pelo cliente, selecione a chave que você quer usar.
    - Para usar uma rede VPC com peering nesta execução do pipeline, insira o nome da rede VPC na caixa Rede VPC com peering.
3. Clique em Continuar.
Na seção Configuração do ambiente de execução, defina a execução do pipeline da seguinte maneira:
1. Em Local de armazenamento do Cloud, clique em Procurar para selecionar o bucket do Cloud Storage para armazenar os artefatos de saída do pipeline e, em seguida, clique em Selecionar.
2. Opcional: para configurar a política de falha e o cache da execução do pipeline, clique em Opções avançadas e use as seguintes instruções:
  - Em Política de falha, especifique a política de falha de todo o pipeline. Saiba mais sobre as políticas de falha do pipeline.
    - Para configurar o pipeline para continuar a programar tarefas depois que uma tarefa falhar, selecione Executar todas as etapas até a conclusão. Por padrão, essa opção é selecionada.
    - Para configurar a falha do pipeline depois que uma tarefa falhar, selecione Falha na execução assim que uma etapa falhar.
  - Em Configuração de armazenamento em cache, especifique a configuração de cache para todo o pipeline.
    - Para usar a configuração de cache no nível da tarefa para tarefa no pipeline, selecione Não modificar a configuração do cache no nível da tarefa.
    - Para ativar o armazenamento em cache de todas as tarefas no pipeline e modificar qualquer configuração de cache no nível da tarefa, selecione Ativar leitura do cache para todas as etapas (mais rápido).
    - Para desativar o armazenamento em cache de todas as tarefas no pipeline e substituir qualquer configuração de cache no nível da tarefa, selecione Desativar leitura do cache para todas as etapas (mais rápido).
3. Opcional: se o pipeline tiver parâmetros, especifique-os em Parâmetros de pipeline.
Para criar a execução do pipeline, clique em Enviar.

SDK da Vertex AI para Python

Use as instruções a seguir para executar um pipeline de ML usando o SDK do Vertex AI para Python. Antes de executar o código de exemplo a seguir, é necessário configurar a autenticação.

Configurar a autenticação

Para configurar a autenticação, crie uma chave de conta de serviço e defina uma variável de ambiente para o caminho dessa chave.

Crie uma conta de serviço:
1. No Console do Google Cloud, acesse a página Criar conta de serviço.
  
  Acesse "Criar conta de serviço"
2. No campo Nome da conta de serviço, insira um nome.
3. Opcional: no campo Descrição da conta de serviço, digite uma descrição.
4. Clique em Criar.
5. Clique no campo Selecionar um papel. Em Todos os papéis, selecione Vertex AI > Usuário da Vertex AI.
6. Clique em Concluído para criar a conta de serviço.
  
  Não feche a janela do navegador. Você vai usá-la na próxima etapa.
Crie uma chave da conta de serviço para autenticação:
1. No console do Google Cloud, clique no endereço de e-mail da conta de serviço que você criou.
2. Clique em Chaves.
3. Clique em Adicionar chave e, depois, em Criar nova chave.
4. Clique em Criar. O download de um arquivo de chave JSON é feito no seu computador.
5. Clique em Fechar.
Conceda à nova conta de serviço acesso à conta de serviço usada para executar pipelines.
1. Clique em para retornar à lista de contas de serviço.
2. Clique no nome da conta de serviço que você usa para executar pipelines. A página Detalhes da conta de serviço é exibida.
  
  Se você tiver seguido as instruções no guia para configurar o projeto para o Vertex AI Pipelines, essa é a mesma conta de serviço criada em Configurar uma conta de serviço com permissões granulares. Caso contrário, o Vertex AI usa a conta de serviço padrão do Compute Engine para executar pipelines. O nome da conta de serviço padrão do Compute Engine tem o seguinte formato: PROJECT_NUMBER-compute@developer.gserviceaccount.com
3. Clique na guia Permissões..
4. Clique em Conceder acesso. O painel Adicionar principais será exibido.
5. Na caixa Novos principais, digite o endereço de e-mail da conta de serviço que você criou em uma etapa anterior.
6. Na lista suspensa Papel, selecione Contas de serviço > Usuário da conta de serviço.
7. Clique em Salvar.
Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo JSON que contém a chave da conta de serviço: Essa variável aplica-se apenas à sessão de shell atual. Portanto, se você abrir uma nova sessão, defina a variável novamente.

Exemplo: Linux ou macOS

Substitua [PATH] pelo caminho do arquivo JSON que contém a chave da conta de serviço.
```
export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
```
Por exemplo:
```
export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"
```
Exemplo: Windows

Substitua [PATH] pelo caminho do arquivo JSON que contém a chave da conta de serviço e [FILE_NAME] pelo nome de arquivo.

Com o PowerShell:
```
$env:GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
```
Por exemplo:
```
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\[FILE_NAME].json"
```
Com prompt de comando:
```
set GOOGLE_APPLICATION_CREDENTIALS=[PATH]
```

Executar um pipeline

A execução de um Vertex AI PipelineJob requer que você crie um objeto PipelineJob e depois invoque o método submit.

Tipos de entrada especiais compatíveis com o KFP

Ao criar uma execução de pipeline, também é possível transmitir os seguintes marcadores com suporte do SDK do KFP como entradas:

{{$.pipeline_job_name_placeholder}}
{{$.pipeline_job_resource_name_placeholder}}
{{$.pipeline_job_id_placeholder}}
{{$.pipeline_task_name_placeholder}}
{{$.pipeline_task_id_placeholder}}
{{$.pipeline_job_create_time_utc_placeholder}}
{{$.pipeline_root_placeholder}}

Para mais informações, consulte Tipos de entrada especiais na documentação do Kubeflow Pipelines v2 (em inglês).

from google.cloud import aiplatform

job = aiplatform.PipelineJob(display_name = DISPLAY_NAME,
                             template_path = COMPILED_PIPELINE_PATH,
                             job_id = JOB_ID,
                             pipeline_root = PIPELINE_ROOT_PATH,
                             parameter_values = PIPELINE_PARAMETERS,
                             enable_caching = ENABLE_CACHING,
                             encryption_spec_key_name = CMEK,
                             labels = LABELS,
                             credentials = CREDENTIALS,
                             project = PROJECT_ID,
                             location = LOCATION,
                             failure_policy = FAILURE_POLICY)

job.submit(service_account=SERVICE_ACCOUNT,
           network=NETWORK)

Substitua:

DISPLAY_NAME: o nome do pipeline, que é mostrado no console do Google Cloud.
COMPILED_PIPELINE_PATH: o caminho para o arquivo YAML do pipeline compilado. Pode ser um caminho local ou um URI do Cloud Storage.

Opcional: para especificar uma versão específica de um pipeline compilado, inclua a tag de versão em qualquer um dos seguintes formatos:
- COMPILED_PIPELINE_PATH:TAG, em que TAG é a tag de versão.
- COMPILED_PIPELINE_PATH@SHA256_TAG, em que SHA256_TAG é o valor de hash sha256 da versão do pipeline.
JOB_ID: (opcional) Um identificador exclusivo da execução deste pipeline. Se o ID do job não for especificado, o Vertex AI Pipelines criará um ID de job para você usando o nome do pipeline e o carimbo de data/hora de quando a execução do pipeline foi iniciada.
PIPELINE_ROOT_PATH: (opcional) Para substituir o caminho raiz do pipeline especificado na definição do pipeline, especifique um caminho que o job do pipeline possa acessar, como um URI do bucket do Cloud Storage.
PIPELINE_PARAMETERS: (opcional) os parâmetros de pipeline a serem transmitidos para essa execução. Por exemplo, crie um dict() com os nomes do parâmetro como as chaves do dicionário e os valores de parâmetro como os valores do dicionário.
ENABLE_CACHING: (opcional) especifica se esta execução de pipeline usa o armazenamento em cache de execução. O cache de execução reduz os custos ignorando as tarefas do pipeline em que a saída é conhecida pelo conjunto atual de entradas. Se o argumento de ativação do armazenamento em cache não for especificado, o cache de execução será usado na execução do pipeline. Saiba mais sobre o armazenamento em cache de execução.
CMEK: (opcional) O nome da chave de criptografia gerenciada pelo cliente que você quer usar nesta execução de pipeline.
LABELS: (opcional) os rótulos definidos pelo usuário para organizar esse PipelineJob. Para mais informações sobre rótulos de recursos, consulte Como criar e gerenciar rótulos na documentação do Resource Manager.

O Vertex AI Pipelines anexa automaticamente o seguinte rótulo à execução do pipeline:

vertex-ai-pipelines-run-billing-id: pipeline_run_id

em que pipeline_run_id é o ID exclusivo da execução do pipeline.

Esse rótulo conecta o uso de recursos do Google Cloud gerados pelo pipeline executado nos relatórios de faturamento.
CREDENTIALS: (opcional) credenciais personalizadas para usar para criar esse PipelineJob. Substitui as credenciais definidas em aiplatform.init.
PROJECT_ID: (opcional) o projeto do Google Cloud em que você quer executar o pipeline. Se você não definir esse parâmetro, o projeto definido em aiplatform.init será usado.
LOCATION: (opcional) a região em que você quer executar o pipeline. Para mais informações sobre as regiões em que o Vertex AI Pipelines está disponível, consulte o guia de locais do Vertex AI. Se você não definir esse parâmetro, o local padrão definido em aiplatform.init é usado.
FAILURE_POLICY: (opcional) especifica a política de falha para todo o pipeline. As configurações a seguir estão disponíveis:
- Para configurar o pipeline para falhar se uma tarefa falhar, digite fast.
- Para configurar o pipeline de modo a continuar a programar tarefas se uma tarefa falhar, insira slow.
Se você não definir o parâmetro, a configuração da política de falha é definida como slow, por padrão. Saiba mais sobre as políticas de falha do pipeline.
SERVICE_ACCOUNT: (opcional) o nome da conta de serviço a ser usada nesta execução do pipeline. Se você não especificar uma conta de serviço, o Vertex AI Pipelines executará o pipeline usando a conta de serviço padrão do Compute Engine.
NETWORK: (opcional) o nome da rede VPC com peering a ser usada nesta execução do pipeline.