Crie, carregue e use um modelo de pipeline

Um modelo de pipeline é um recurso que pode usar para publicar uma definição de fluxo de trabalho para que possa ser reutilizada várias vezes por um único utilizador ou por vários utilizadores.

O cliente de registo do SDK do Kubeflow Pipelines é uma nova interface de cliente que pode usar com um servidor de registo compatível, como o Artifact Registry, para o controlo de versões dos seus modelos do Kubeflow Pipelines (KFP). Para mais informações, consulte o artigo Use o modelo num cliente de registo do SDK Kubeflow Pipelines.

Esta página mostra como:

• Crie um modelo de pipeline do KFP
• Use o cliente de registo do SDK do Kubeflow Pipelines para carregar o modelo para um repositório de modelos de pipelines
• Use o modelo no cliente Kubeflow Pipelines

Antes de começar

Antes de criar e executar o pipeline, use as instruções seguintes para configurar o Google Cloud projeto e o ambiente de desenvolvimento na Google Cloud consola.

1. Instale a versão 2 ou posterior do SDK Kubeflow Pipelines.

   pip install --upgrade "kfp>=2,<3"
   

Nota: para atualizar para a versão mais recente do SDK Kubeflow Pipelines, execute o seguinte comando:
pip install kfp --upgrade
Se estiver disponível uma versão atualizada, a execução deste comando desinstala o KFP e instala a versão mais recente.

1. Instale a versão 1.15.0 ou posterior do SDK Vertex AI para Python.
   (Opcional) Antes de instalar, execute o seguinte comando para ver que versão do SDK Vertex AI para Python está instalada:

     pip freeze | grep google-cloud-aiplatform
   

   Nota: para atualizar para a versão mais recente do Vertex AI SDK para Python, execute o seguinte comando:
   pip install google-cloud-aiplatform --upgrade
   Se estiver disponível uma versão atualizada, a execução deste comando desinstala a versão instalada e instala a versão mais recente.

2. (Opcional) Instale a versão 390.0.0 ou posterior da CLI Google Cloud.

3. Ative a API Artifact Registry.

Configurar autorizações

Se ainda não configurou o seu projeto da CLI gcloud para o Vertex AI Pipelines, siga as instruções em Configure o seu Google Cloud projeto para o Vertex AI Pipelines.

Além disso, atribua as seguintes autorizações de gestão de identidades e acessos predefinidas para usar o Artifact Registry como o registo de modelos:

• roles/artifactregistry.admin: atribua esta função para criar e gerir um repositório.
• roles/artifactregistry.repoAdmin ou roles/artifactregistry.writer: atribua qualquer uma destas funções para gerir modelos num repositório.
• roles/artifactregistry.reader: atribua esta função para transferir modelos de um repositório.
• roles/artifactregistry.reader: atribua esta função a uma conta de serviço associada ao Vertex AI Pipelines para criar uma execução de pipeline a partir de um modelo.

Para mais informações sobre as funções de gestão de identidades e acessos predefinidas para o Artifact Registry, consulte o artigo Funções predefinidas do Artifact Registry.

Use o exemplo seguinte para atribuir funções:

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

Substitua o seguinte:

• PROJECT_ID: o projeto onde quer criar o pipeline.
• PRINCIPAL: o principal ao qual está a adicionar autorizações.
• ROLE: a função de gestão de acessos e identidade que quer conceder ao principal.

Consulte Funções e autorizações na documentação do Artifact Registry para mais informações acerca do seguinte:

• Conceder autorizações ao nível do projeto
• Conceder autorizações específicas do repositório
• Conceder funções básicas de Identity and Access Management a utilizadores individuais

Crie um repositório no Artifact Registry

Em seguida, vai criar um repositório no Artifact Registry para os modelos de pipelines.

Consola

1. Abra o Vertex AI Pipelines na Google Cloud consola.

   Aceda a Vertex AI Pipelines

2. Clique no separador Os seus modelos.

3. Para abrir o painel Selecionar repositório, clique em Selecionar repositório.

4. Clique em Criar repositório.

5. Especifique quickstart-kfp-repo como o nome do repositório.

6. Em Formatar, selecione Kubeflow Pipelines.

7. Em Tipo de localização, selecione Região.

8. Na lista pendente Região, selecione us-central1.

   Nota: os exemplos de comandos e configuração nestas instruções usam us-central1, mas pode usar qualquer uma das regiões suportadas.

9. Clique em Criar.

CLI do Google Cloud

Execute o seguinte comando para criar um repositório.

Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

• LOCATION: A localização ou a região onde quer criar o repositório, por exemplo, us-central1

Execute o comando gcloud artifacts repositories create:

Linux, macOS ou Cloud Shell

Nota: Certifique-se de que inicializou a CLI Google Cloud com autenticação e um projeto executando gcloud init; ou gcloud auth login e gcloud config set project.

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

Windows (PowerShell)

Nota: Certifique-se de que inicializou a CLI Google Cloud com autenticação e um projeto executando gcloud init; ou gcloud auth login e gcloud config set project.

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

Windows (cmd.exe)

Nota: Certifique-se de que inicializou a CLI Google Cloud com autenticação e um projeto executando gcloud init; ou gcloud auth login e gcloud config set project.

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

 

Crie um modelo

Use o seguinte exemplo de código para definir um pipeline com um único componente. Para ver informações sobre como definir um pipeline através do KFP, consulte o artigo Crie 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 executa o exemplo, a declaração compiler.Compiler().compile(...) compila o pipeline "hello-world" no ficheiro YAML local com o nome hello_world_pipeline.yaml.

Carregue o modelo

Consola

1. Abra o Vertex AI Pipelines na Google Cloud consola.

   Aceda a Vertex AI Pipelines

2. Clique em Carregar para abrir o painel Carregar pipeline ou componente.

3. Na lista pendente Repositório, selecione o repositório quickstart-kfp-repo.

4. Especifique um Nome para o modelo de pipeline.

5. No campo Ficheiro, clique em Escolher para selecionar e carregar o YAML do modelo de pipeline compilado a partir do sistema de ficheiros local.

6. Depois de carregar o modelo de pipeline, este é apresentado na página Os seus modelos.

   Aceda a Os seus modelos

Cliente do SDK Kubeflow Pipelines

1. Para configurar o cliente de registo do SDK do Kubeflow Pipelines, execute os seguintes comandos:

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

2. Carregue o ficheiro YAML compilado para o 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."})
   

3. Para verificar se o modelo foi carregado:

   1. Abra o Vertex AI Pipelines na Google Cloud consola.

      Aceda a Vertex AI Pipelines

   2. Clique no separador Os seus modelos.

   3. Clique em Selecionar repositório.

   4. Na lista, selecione o repositório quickstart-kfp-repo e, de seguida, clique em Selecionar.

   5. Deve encontrar o pacote de modelos carregado hello-world na lista.

   6. Para ver a lista de versões do modelo de pipeline, clique no modelo hello-world.

   7. Para ver a topologia do pipeline, clique na versão.

Use o modelo no Vertex AI

Depois de carregar o modelo de pipeline para o repositório no Artifact Registry, está pronto para ser usado nos Vertex AI Pipelines.

Crie um contentor de preparação para o seu modelo

Antes de poder usar o modelo de pipeline, tem de criar um contentor do Cloud Storage para preparar as execuções de pipelines.

Para criar o contentor, siga as instruções em Configure um contentor do Cloud Storage para artefactos de pipeline e, em seguida, execute o seguinte comando:

STAGING_BUCKET="gs://BUCKET_NAME"

Substitua BUCKET_NAME pelo nome do contentor que acabou de criar.

Crie uma execução de pipeline a partir do seu modelo

Pode usar o SDK do Vertex AI para Python ou a Google Cloud consola para criar uma execução de pipeline a partir do seu modelo no Artifact Registry.

Consola

1. Abra o Vertex AI Pipelines na Google Cloud consola.

   Aceda a Vertex AI Pipelines

2. Clique no separador Os seus modelos.

3. Para abrir o painel Selecionar repositório, clique em Selecionar repositório.

4. Selecione o repositório quickstart-kfp-repo e, de seguida, clique em Selecionar.

5. Clique no pacote hello-world.

6. Junto à versão 4f245e8f9605, clique em Criar execução.

7. Clique em Configuração de tempo de execução.

8. Introduza o seguinte em Localização do Cloud Storage:

   gs://BUCKET_NAME
   

   Substitua BUCKET_NAME pelo nome do contentor que criou para preparar as execuções do pipeline.

9. Clique em Enviar.

SDK Vertex AI para Python

Use o exemplo seguinte para criar uma execução de pipeline a partir do 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 o seguinte:

• PROJECT_ID: O Google Cloud projeto no qual esta pipeline é executada.

• SHA256_TAG: O valor hash sha256 da versão do modelo.

• TAG: a etiqueta de versão do modelo.

Veja execuções de pipelines criadas

Pode ver as execuções criadas por uma versão específica do pipeline no SDK Vertex AI para Python.

Consola

1. Abra o Vertex AI Pipelines na Google Cloud consola.

   Aceda a Vertex AI Pipelines

2. Clique no separador Os seus modelos.

3. Clique em Selecionar repositório.

4. Na lista, selecione o repositório quickstart-kfp-repo e, de seguida, clique em Selecionar.

5. Para ver a lista de versões do modelo de pipeline hello-world, clique no modelo hello world.

6. Clique na versão pretendida para a qual quer ver execuções de pipelines.

7. Para ver as execuções da pipeline para a versão selecionada, clique em Ver execuções e, de seguida, clique no separador Execuções.

SDK Vertex AI para Python

Para apresentar uma lista das execuções de pipelines, execute o comando pipelineJobs.list conforme mostrado num ou mais dos seguintes exemplos:

  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)

Use o modelo num cliente de registo do SDK Kubeflow Pipelines

Pode usar um cliente de registo do SDK Kubeflow Pipelines juntamente com o Artifact Registry para transferir e usar o modelo de pipeline.

• Para apresentar uma lista dos 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 proto ficheiros no repositório do GitHub do Artifact Registry.

• Para transferir o modelo para o seu sistema de ficheiros 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")
  

Use a API REST do Artifact Registry

As secções seguintes resumem como usar a API REST do Artifact Registry para gerir os seus modelos de pipelines no repositório do Artifact Registry.

Carregue um modelo de pipeline através da API REST do Artifact Registry

Pode carregar um modelo de pipeline criando um pedido HTTP com os valores dos parâmetros descritos nesta secção, em que:

• PROJECT_ID é o Google Cloud projeto no qual este pipeline é executado.
• REPO_ID é o ID do seu repositório do Artifact Registry.

Exemplo de pedido 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

Construir o pedido de carregamento

O pedido é um pedido multipart HTTP ou HTTPS. Tem de incluir o token de autenticação no cabeçalho do pedido. Para mais informações, consulte o artigo gcloud auth print-access-token.

O payload do pedido é o conteúdo do ficheiro pipeline_spec.yaml (ou do pacote .zip). O limite de tamanho recomendado é de 10 MiB.

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

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

Se existir uma etiqueta e esta apontar para um pipeline que já foi carregado, a etiqueta é atualizada para apontar para o pipeline que está a carregar. Por exemplo, se a etiqueta latest apontar para um pipeline que já carregou e carregar uma nova versão com --tag=latest, a etiqueta latest é removida do pipeline carregado anteriormente e atribuída ao novo pipeline que está a carregar.

Se o pipeline que está a carregar for idêntico a um pipeline que carregou anteriormente, o carregamento é bem-sucedido. Os metadados do pipeline carregado, incluindo as respetivas etiquetas de versão, são atualizados para corresponderem aos valores dos parâmetros do seu pedido de carregamento.

Resposta de carregamento

Se o pedido de carregamento for bem-sucedido, devolve um estado HTTP OK. O corpo da resposta é o seguinte:

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

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

Transfira um modelo de pipeline através da API REST do Artifact Registry

Pode transferir um modelo de pipeline criando um pedido HTTP com os valores dos parâmetros descritos nesta secção, em que:

• PROJECT_ID é o Google Cloud projeto no qual este pipeline é executado.
• REPO_ID é o ID do seu repositório do Artifact Registry.
• PACKAGE_ID é o ID do pacote do modelo carregado.
• TAG é a etiqueta de versão.
• VERSION é a versão do modelo no formato sha256:abcdef123456....

Para a transferência padrão do Artifact Registry, deve formar o link de transferência da seguinte forma:

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

Exemplos de pedidos 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

Pode substituir VERSION por TAG e transferir o mesmo modelo, conforme mostrado no exemplo seguinte:

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

Transferir resposta

Se o pedido de transferência for bem-sucedido, devolve um estado HTTP OK. O corpo da resposta é o conteúdo do ficheiro pipeline_spec.yaml.

Links de referência

• Artifact Registry – Vista geral do repositório para mais informações sobre como gerir os seus repositórios.
• API Repository
  • A palavra-chave format é "KFP"
• API Package
• API Version
• API Tag
• Definições de proto no GitHub