Criar, fazer upload e usar um modelo de pipeline

Um modelo de pipeline é um recurso que pode ser usado para publicar uma definição de fluxo de trabalho. Assim, ele pode ser reutilizado várias vezes por um único usuário ou por vários usuários.

O cliente de registro do SDK do Kubeflow Pipelines é uma nova interface de cliente que pode ser usada com um servidor de registros compatível, como o Artifact Registry, para controle de versões dos modelos do Kubeflow Pipelines (KFP). Para mais informações, consulte Usar o modelo em um cliente de registro do SDK do Kubeflow Pipelines.

Esta página mostra como:

Criar um modelo de pipeline do KFP
Usar o cliente de registro do SDK do Kubeflow Pipelines para fazer upload do modelo para um repositório de modelos de pipeline
Usar o modelo no cliente do Kubeflow Pipelines

Antes de começar

Antes de criar e executar o pipeline, use as instruções a seguir para configurar o ambiente de desenvolvimento e projeto do Google Cloud no console do Google Cloud.

Instale a v2 ou mais recente do SDK do Kubeflow Pipelines.
(Opcional) Antes da instalação, execute o seguinte comando para ver qual versão do SDK do Kubeflow Pipelines está instalada no momento:
```
  pip freeze | grep kfp
```
Observação: para fazer upgrade para a versão mais recente do SDK do Kubeflow Pipelines, execute o seguinte comando:
pip install kfp --upgrade
Se uma versão atualizada estiver disponível, executar este comando desinstala a versão instalada e instala a mais recente.
Instale a versão 1.15.0 ou mais recente do SDK da Vertex AI para Python.
(Opcional) Antes da instalação, execute o seguinte comando para ver qual versão do SDK da Vertex AI para Python está instalada:
```
  pip freeze | grep google-cloud-aiplatform
```
Observação: para fazer upgrade para a versão mais recente do SDK da Vertex AI para Python, execute este comando:
pip install google-cloud-aiplatform --upgrade
Se uma versão atualizada estiver disponível, executar esse comando desinstala a versão instalada e instala a mais recente.
(Opcional) Instale a versão 390.0.0 ou superior da CLI do Google Cloud.
Ative a API Artifact Registry.

Como configurar permissões

Se você ainda não configurou seu projeto da CLI gcloud para pipelines da Vertex AI, siga as instruções em Configurar seu projeto do Google Cloud para pipelines da Vertex AI.

Além disso, atribua as seguintes permissões predefinidas do Identity and Access Management para usar o Artifact Registry como o registro de modelo:

roles/artifactregistry.admin: atribua esse papel para criar e gerenciar um repositório.
roles/artifactregistry.repoAdmin ou roles/artifactregistry.writer: atribua qualquer um desses papéis para gerenciar modelos em um repositório.
roles/artifactregistry.reader: atribua esse papel para fazer o download de modelos de um repositório.
roles/artifactregistry.reader: atribua esse papel a uma conta de serviço associada aos pipelines da Vertex AI para criar um pipeline executado a partir de um modelo.

Para mais informações sobre os papéis predefinidos do Identity and Access Management do Artifact Registry, consulte Papéis predefinidos do Artifact Registry.

Use o exemplo a seguir para atribuir papéis:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=PRINCIPAL \
    --role=ROLE

Substitua:

PROJECT_ID: o projeto em que você quer criar o pipeline.
PRINCIPAL: o principal ao qual você está adicionando permissões.
ROLE: o papel de gerenciamento de identidade e acesso que você quer conceder ao principal.

Consulte Papéis e permissões na documentação do Artifact Registry para mais informações sobre:

Criar um repositório no Artifact Registry

Em seguida, crie um repositório no Artifact Registry para os modelos de pipeline.

Console

Abra o Vertex AI Pipelines no console do Google Cloud.

Acessar o Vertex AI Pipelines
Clique na guia Seus modelos.
Para abrir o painel Selecionar repositório, clique em Selecionar repositório.
Clique em Criar repositório.
Especifique quickstart-kfp-repo como o nome do repositório.
Em Formato, selecione Kubeflow Pipelines.
Em Tipo de local, selecione Região.
Na lista suspensa Região, selecione us-central1.

Observação: os comandos de exemplo e a configuração nestas instruções usam us-central1, mas é possível usar qualquer uma das regiões compatíveis.
Clique em Criar.

CLI do Google Cloud

Execute este comando para criar um repositório.

Antes de usar os dados do comando abaixo, faça estas substituições:

LOCATION: o local ou a região em que você quer criar o repositório, por exemplo, us-central1.

Execute o comando gcloud artifacts repositories create:

Linux, macOS ou Cloud Shell

gcloud artifacts repositories create quickstart-kfp-repo --location=LOCATION_ID --repository-format=KFP

Windows (PowerShell)

gcloud artifacts repositories create quickstart-kfp-repo --location=LOCATION_ID --repository-format=KFP

Windows (cmd.exe)

gcloud artifacts repositories create quickstart-kfp-repo --location=LOCATION_ID --repository-format=KFP

Criar um modelo

Use o exemplo de código a seguir para definir um pipeline com um único componente. Para saber como definir um pipeline usando KFP, consulte Criar um pipeline.

from kfp import dsl
from kfp import compiler

@dsl.component()
def hello_world(text: str) -> str:
    print(text)
    return text

@dsl.pipeline(name='hello-world', description='A simple intro pipeline')
def pipeline_hello_world(text: str = 'hi there'):
    """Pipeline that passes small pipeline parameter string to consumer op."""

    consume_task = hello_world(
        text=text)  # Passing pipeline parameter as argument to consumer op

compiler.Compiler().compile(
    pipeline_func=pipeline_hello_world,
    package_path='hello_world_pipeline.yaml')

Quando você executa a amostra, a instrução compiler.Compiler().compile(...) compila o pipeline "hello-world" no arquivo YAML local chamado hello_world_pipeline.yaml.

Fazer upload do modelo

Console

Abra o Vertex AI Pipelines no console do Google Cloud.

Acessar o Vertex AI Pipelines
Clique em Fazer upload para abrir o painel Fazer upload do pipeline ou componente.
Na lista suspensa Repositório, selecione o repositório quickstart-kfp-repo.
Especifique um Nome para o modelo de pipeline.
No campo Arquivo, clique em Escolher para selecionar e fazer upload do YAML de modelo de pipeline compilado do sistema de arquivos local.
Depois de fazer upload do modelo de pipeline, ele é listado na página Seus modelos.

Acesse Seus modelos

Cliente do SDK de pipelines do Kubeflow

Para configurar o cliente de registro do SDK de pipelines do Kubeflow, execute os seguintes comandos:

from kfp.registry import RegistryClient

client = RegistryClient(host=f"https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo")

Faça upload do arquivo YAML compilado para seu repositório no Artifact Registry.

templateName, versionName = client.upload_pipeline(
  file_name="hello_world_pipeline.yaml",
  tags=["v1", "latest"],
  extra_headers={"description":"This is an example pipeline template."})

Para verificar se o upload do modelo foi feito:
1. Abra o Vertex AI Pipelines no console do Google Cloud.
  
  Acessar o Vertex AI Pipelines
2. Clique na guia Seus modelos.
3. Clique em Selecionar repositório.
4. Na lista, selecione o repositório quickstart-kfp-repo e clique em Selecionar.
5. Você verá o pacote do modelo do upload feito hello-world na lista.
6. Para acessar a lista de versões do modelo de pipeline, clique no modelo hello-world.
7. Para acessar a topologia do pipeline, clique na versão.

Usar o modelo na Vertex AI

Depois de fazer upload do modelo de pipeline para o repositório no Artifact Registry, ele estará pronto para ser usado no Vertex AI Pipelines.

Criar um bucket de preparo para o modelo

Antes de usar o modelo de pipeline, você precisa criar um bucket do Cloud Storage para preparo das execuções de pipelines.

Para criar o bucket, siga as instruções em Configurar um bucket do Cloud Storage para artefatos de pipeline e execute o seguinte comando:

STAGING_BUCKET="gs://BUCKET_NAME"

Substitua BUCKET_NAME pelo nome do bucket que você acabou de criar.

Criar uma execução de pipeline com base no modelo

É possível usar o SDK da Vertex AI para Python ou o console do Google Cloud para criar uma execução de pipeline no modelo do Artifact Registry.

Console

Abra o Vertex AI Pipelines no console do Google Cloud.

Acessar o Vertex AI Pipelines
Clique na guia Seus modelos.
Para abrir o painel Selecionar repositório, clique em Selecionar repositório.
Selecione o repositório quickstart-kfp-repo e clique em Selecionar.
Clique no pacote hello-world.
Ao lado da versão 4f245e8f9605, clique em Criar execução.
Clique em Configuração do ambiente de execução.
Digite o seguinte em Local do Cloud Storage:
```
gs://BUCKET_NAME
```
Substitua BUCKET_NAME pelo nome do bucket criado para preparar as execuções do pipeline.
Selecione Enviar.

SDK da Vertex AI para Python

Use o exemplo a seguir para criar uma execução de pipeline usando seu modelo:

from google.cloud import aiplatform

# Initialize the aiplatform package
aiplatform.init(
    project="PROJECT_ID",
    location='us-central1',
    staging_bucket=STAGING_BUCKET)

# Create a pipeline job using a version ID.
job = aiplatform.PipelineJob(
    display_name="hello-world-latest",
    template_path="https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo/hello-world@SHA256_TAG" + \
        versionName)

# Alternatively, create a pipeline job using a tag.
job = aiplatform.PipelineJob(
    display_name="hello-world-latest",
    template_path="https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo/hello-world:TAG")

job.submit()

Substitua:

PROJECT_ID: o projeto do Google Cloud em que este pipeline é executado.
SHA256_TAG: o valor de hash sha256 da versão do modelo.
TAG: a tag da versão do modelo.

Visualizar execuções de pipeline criadas

É possível visualizar as execuções criadas por uma versão específica do pipeline no SDK da Vertex AI para Python.

Console

Abra o Vertex AI Pipelines no console do Google Cloud.

Acessar o Vertex AI Pipelines
Clique na guia Seus modelos.
Clique em Selecionar repositório.
Na lista, selecione o repositório quickstart-kfp-repo e clique em Selecionar.
Para acessar a lista de versões do modelo de pipeline hello-world, clique no modelo hello world.
Clique na versão desejada.
Para acessar as execuções de pipeline da versão selecionada, clique em Acessar execuções e, em seguida, na guia Execuções.

SDK da Vertex AI para Python

Para listar as execuções de pipelines, execute o comando pipelineJobs.list conforme mostrado em um ou mais exemplos a seguir:

  from google.cloud import aiplatform

  # To filter all runs created from a specific version
  filter = 'template_uri:"https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo/hello-world/*" AND ' + \
           'template_metadata.version="%s"' % versionName
  aiplatform.PipelineJob.list(filter=filter)

  # To filter all runs created from a specific version tag
  filter = 'template_uri="https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo/hello-world/latest"'
  aiplatform.PipelineJob.list(filter=filter)

  # To filter all runs created from a package
  filter = 'template_uri:"https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo/hello-world/*"'
  aiplatform.PipelineJob.list(filter=filter)

  # To filter all runs created from a repo
  filter = 'template_uri:"https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo/*"'
  aiplatform.PipelineJob.list(filter=filter)

Usar o modelo em um cliente de registro do SDK do Kubeflow Pipelines

É possível usar um cliente de registro do SDK do Kubeflow Pipelines com o Artifact Registry para fazer o download e usar o modelo de pipeline.

Para listar os recursos no repositório, execute os seguintes comandos:

templatePackages = client.list_packages()
templatePackage = client.get_package(package_name = "hello-world")

versions = client.list_versions(package_name="hello-world")
version = client.get_version(package_name="hello-world", version=versionName)

tags = client.list_tags(package_name = "hello-world")
tag = client.get_tag(package_name = "hello-world", tag="latest")

Para ver a lista completa de métodos e documentos disponíveis, consulte os arquivos proto no repositório do GitHub do Artifact Registry.

Para fazer o download do modelo no sistema de arquivos local, execute os seguintes comandos:

# Sample 1
filename = client.download_pipeline(
  package_name = "hello-world",
  version = versionName)
# Sample 2
filename = client.download_pipeline(
  package_name = "hello-world",
  tag = "v1")
# Sample 3
filename = client.download_pipeline(
  package_name = "hello-world",
  tag = "v1",
  file_name = "hello-world-template.yaml")

Usar a API REST do Artifact Registry

As seções a seguir resumem como usar a API REST do Artifact Registry para gerenciar os modelos de pipeline no repositório do Artifact Registry.

Fazer upload de um modelo de pipeline usando a API REST do Artifact Registry

É possível fazer upload de um modelo de pipeline criando uma solicitação HTTP usando os valores de parâmetro descritos nesta seção, em que:

PROJECT_ID é o projeto do Google Cloud em que este pipeline é executado.
REPO_ID é o ID do repositório do Artifact Registry.

Exemplo de solicitação curl

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -F tags=v1,latest \
    -F content=@pipeline_spec.yaml \
    https://us-central1-kfp.pkg.dev/PROJECT_ID/REPO_ID

Como criar a solicitação de upload

A solicitação é HTTP ou HTTPS de várias partes. Ela precisa incluir o token de autenticação no cabeçalho da solicitação. Para mais informações, consulte gcloud auth print-access-token.

O payload da solicitação é o conteúdo do arquivo pipeline_spec.yaml (ou pacote .zip). O limite de tamanho recomendado é de 10 MiB.

O nome do pacote é retirado da entrada pipeline_spec.pipeline_info.name no arquivo pipeline_spec.yaml. O nome do pacote o identifica exclusivamente e é imutável entre as versões. Ele pode ter entre 4 e 128 caracteres e precisa corresponder à seguinte expressão regular: ^[a-z0-9][a-z0-9-]{3,127}$.

O pacote de tags é uma lista de até oito tags separadas por vírgulas. Cada tag precisa corresponder à seguinte expressão regular: ^[a-zA-Z0-9\-._~:@+]{1,128}$.

Se existir uma tag que aponta para um pipeline com upload já feito, a tag será atualizada para apontar para o pipeline com upload que você está fazendo no momento. Por exemplo, se a tag latest apontar para um pipeline com upload já feito e você fizer upload de uma nova versão com --tag=latest, a tag latest será removida do pipeline com upload feito anteriormente e será atribuída ao novo pipeline com upload que você está fazendo.

Se o pipeline com upload que você está fazendo for idêntico a um pipeline com upload feito anteriormente, o upload será bem-sucedido. Os metadados do pipeline com upload feito, incluindo as tags de versão, são atualizados para corresponder aos valores de parâmetro da solicitação de upload.

Resposta do upload

Se a solicitação de upload for bem-sucedida, ela retornará um status HTTP OK. O corpo da resposta é assim:

{packageName}/{versionName=sha256:abcdef123456...}

em que versionName é o resumo sha256 de pipeline_spec.yaml formatado como uma string hexadecimal.

Fazer o download de um modelo de pipeline usando a API REST do Artifact Registry

É possível fazer o download de um modelo de pipeline criando uma solicitação HTTP usando os valores de parâmetro descritos nesta seção, em que:

PROJECT_ID é o projeto do Google Cloud em que este pipeline é executado.
REPO_ID é o ID do repositório do Artifact Registry.
PACKAGE_ID é o ID do pacote do modelo com upload feito.
TAG é a tag de versão.
VERSION é a versão do modelo no formato de sha256:abcdef123456....

Para o download padrão do Artifact Registry, é necessário criar o link de download da seguinte maneira:

url = https://us-central1-kfp.pkg.dev/PROJECT_ID/REPO_ID/PACKAGE_ID/VERSION
url = https://us-central1-kfp.pkg.dev/PROJECT_ID/REPO_ID/PACKAGE_ID/TAG

Exemplo de solicitações curl

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://us-central1-kfp.pkg.dev/PROJECT_ID/REPO_ID/PACKAGE_ID/VERSION

É possível substituir VERSION por TAG e fazer o download do mesmo modelo, conforme mostrado no exemplo a seguir:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://us-central1-kfp.pkg.dev/PROJECT_ID/REPO_ID/PACKAGE_ID/TAG

Resposta do download

Se a solicitação de download for bem-sucedida, ela retornará um status HTTP OK. O corpo da resposta é o conteúdo do arquivo pipeline_spec.yaml.

Links de referência

Artifact Registry: visão geral do repositório para mais informações sobre como gerenciar seus repositórios.
API para repositório
- A palavra-chave do formato é "KFP"
API para pacote
API para versão
API para tag
Definições de proto no GitHub