Crea, sube y usa una plantilla de canalización

Una plantilla de canalización es un recurso que puedes usar para publicar una definición de flujo de trabajo para que un usuario único o varios usuarios puedan reutilizarla múltiples veces.

El cliente de registro del SDK de Kubeflow Pipelines es una interfaz de cliente nueva que puedes usar con un servidor de registro compatible, como Artifact Registry, para controlar las versiones de las plantillas de Kubeflow Pipelines (KFP). Para obtener más información, consulta Usa la plantilla en un cliente de registro del SDK de Kubeflow Pipelines.

En esta página, se muestra cómo realizar las siguientes acciones:

• Crear una plantilla de canalización de KFP
• Usar el cliente de registro del SDK de Kubeflow Pipelines para subir la plantilla a un repositorio de plantillas de canalización
• Usar la plantilla en el cliente de Kubeflow Pipelines

Antes de comenzar

Antes de compilar y ejecutar tu canalización, usa las siguientes instrucciones para configurar tu proyecto de Google Cloud y el entorno de desarrollo en la consola de Google Cloud.

1. Instala la versión v2 o una versión posterior del SDK de Kubeflow Pipelines.
   Opcional: Antes de instalar, ejecuta el siguiente comando para ver qué versión del SDK de Kubeflow Pipelines está instalada:

     pip freeze | grep kfp
   

   Nota: Para actualizar a la última versión del SDK de Kubeflow Pipelines, ejecuta el siguiente comando:
   pip install kfp --upgrade
   Si hay una versión actualizada disponible, este comando desinstala la versión instalada actualmente y la instala.

2. Instala la versión 1.15.0 o una versión posterior del SDK de Vertex AI para Python.
   Opcional: Antes de instalar, ejecuta el siguiente comando a fin de ver qué versión del SDK de Vertex AI para Python está instalada:

     pip freeze | grep google-cloud-aiplatform
   

   Nota: A fin de actualizar a la última versión del SDK de Vertex AI para Python, ejecuta el siguiente comando:
   pip install google-cloud-aiplatform --upgrade
   Si hay una versión actualizada disponible, ejecutar este comando desinstala la versión instalada actualmente e instala la más reciente.

3. Instala la versión 390.0.0 o una versión posterior de Google Cloud CLI (opcional).

4. Habilita la API de Artifact Registry.

Configurar permisos

Si aún no has configurado tu proyecto de la CLI de gcloud para Vertex AI Pipelines, sigue las instrucciones en Configura tu proyecto de Google Cloud para Vertex AI Pipelines.

Además, asigna los siguientes permisos predefinidos de Identity and Access Management para usar Artifact Registry como el registro de plantillas:

• roles/artifactregistry.admin: Asigna este rol para crear y administrar un repositorio.
• roles/artifactregistry.repoAdmin o roles/artifactregistry.writer: Asigna cualquiera de estos roles para administrar plantillas dentro de un repositorio.
• roles/artifactregistry.reader: Asigna este rol para descargar plantillas desde un repositorio.
• roles/artifactregistry.reader: Asigna este rol a una cuenta de servicio asociada con Vertex AI Pipelines para crear una ejecución de canalización a partir de una plantilla.

Para obtener más información sobre los roles predefinidos de Identity and Access Management para Artifact Registry, consulta Funciones predefinidas de Artifact Registry.

Usa la siguiente muestra para asignar roles:

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

Reemplaza lo siguiente:

• PROJECT_ID: El proyecto en el que deseas crear la canalización.
• PRINCIPAL: La cuenta principal a la que agregas permisos.
• ROLE: El rol de Identity and Access Management que deseas otorgar a la cuenta principal.

Consulta Funciones y permisos en la documentación de Artifact Registry para obtener más información sobre lo siguiente:

• Otorga permisos en todo el proyecto
• Otorga permisos específicos del repositorio
• Otorga roles básicos de Identity and Access Management a usuarios individuales

Crea un repositorio en Artifact Registry

A continuación, crearás un repositorio en Artifact Registry para tus plantillas de canalización.

Consola

1. Abre Vertex AI Pipelines en la consola de Google Cloud.

   Ir a Vertex AI Pipelines

2. Haz clic en la pestaña Tus plantillas.

3. Para abrir el panel Seleccionar repositorio, haz clic en Seleccionar repositorio.

4. Haz clic en Crear repositorio.

5. Especifica quickstart-kfp-repo como el nombre del repositorio.

6. En Formato, selecciona Kubeflow Pipelines.

7. En Tipo de ubicación, selecciona Región.

8. En la lista desplegable Región, selecciona us-central1.

   Nota: En los comandos y la configuración de ejemplo de estas instrucciones, se usa us-central1, pero puedes usar cualquiera de las regiones admitidas.

9. Haga clic en Crear.

Google Cloud CLI

Ejecuta el siguiente comando para crear un repositorio.

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

• LOCATION: La ubicación o la región en la que deseas crear el repositorio, por ejemplo, us-central1

Ejecuta el comando gcloud artifacts repositories create:

Linux, macOS o Cloud Shell

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init o gcloud auth login y gcloud config set project.

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

Windows (PowerShell)

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init o gcloud auth login y gcloud config set project.

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

Windows (cmd.exe)

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init o gcloud auth login y gcloud config set project.

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

 

Crea una plantilla

Usa la siguiente muestra de código para definir una canalización con un solo componente. Para obtener información sobre cómo definir una canalización con KFP, consulta Compila una canalización.

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')

Cuando ejecutas la muestra, la declaración compiler.Compiler().compile(...) compila la canalización “hello-world” en el archivo YAML local llamado hello_world_pipeline.yaml.

Sube la plantilla

Consola

1. Abre Vertex AI Pipelines en la consola de Google Cloud.

   Ir a Vertex AI Pipelines

2. Haz clic en Subir para abrir el panel Subir canalización o componente.

3. En la lista desplegable Repositorio, selecciona el repositorio quickstart-kfp-repo.

4. Especifica un Nombre para la plantilla de canalizaciones.

5. En el campo Archivo, haz clic en Elegir para seleccionar y subir el YAML de la plantilla de canalización compilada desde tu sistema de archivos local.

6. Después de subir la plantilla de canalización, aparecerá en la página Tus plantillas.

   Ir a Tus plantillas

Cliente del SDK de Kubeflow Pipelines

1. Para configurar tu cliente de registro del SDK de Kubeflow Pipelines, ejecuta los siguientes comandos:

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

2. Sube el archivo YAML compilado a tu repositorio en 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 que se subió la plantilla, haz lo siguiente:

   1. Abre Vertex AI Pipelines en la consola de Google Cloud.

      Ir a Vertex AI Pipelines

   2. Haz clic en la pestaña Tus plantillas.

   3. Haz clic en Seleccionar repositorio.

   4. En la lista, selecciona el repositorio quickstart-kfp-repo y, luego, haz clic en Seleccionar.

   5. Debes encontrar el paquete de plantilla hello-world subido de la lista.

   6. Para ver una lista de versiones de la plantilla de canalización, haz clic en la plantilla hello-world.

   7. Para ver la topología de la canalización, haz clic en la versión.

Usa la plantilla en Vertex AI

Después de subir la plantilla de canalización a tu repositorio en Artifact Registry, estará lista para usarse en Vertex AI Pipelines.

Crea un bucket de etapa de pruebas para tu plantilla

Antes de que puedas usar tu plantilla de canalización, deberás crear un bucket de Cloud Storage para ejecuciones de canalizaciones de etapa de pruebas.

Para crear el bucket, sigue las instrucciones en Configura un bucket de Cloud Storage para artefactos de canalización y, luego, ejecuta el siguiente comando:

STAGING_BUCKET="gs://BUCKET_NAME"

Reemplaza BUCKET_NAME por el nombre del bucket que acabas de crear.

Crea una ejecución de canalización a partir de tu plantilla

Puedes usar el SDK de Vertex AI para Python o la consola de Google Cloud a fin de crear una ejecución de canalización que se ejecute desde tu plantilla en Artifact Registry.

Console

1. Abre Vertex AI Pipelines en la consola de Google Cloud.

   Ir a Vertex AI Pipelines

2. Haz clic en la pestaña Tus plantillas.

3. Para abrir el panel Seleccionar repositorio, haz clic en Seleccionar repositorio.

4. Selecciona el repositorio quickstart-kfp-repo y, luego, haz clic en Seleccionar.

5. Haz clic en el paquete hello-world.

6. Junto a la versión 4f245e8f9605, haz clic en Crear ejecución.

7. Haz clic en Configuración del entorno de ejecución.

8. Ingresa lo siguiente en Ubicación de Cloud Storage:

   gs://BUCKET_NAME
   

   Reemplaza BUCKET_NAME por el nombre del bucket que creaste para la etapa de pruebas de tu canalización.

9. Haz clic en Enviar.

SDK de Vertex AI para Python

Ejecuta los siguientes comandos y reemplaza PROJECT_ID por el proyecto de Google Cloud en el que se ejecuta esta canalización.

from google.cloud import aiplatform

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

# Create a job via 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/" + \
        versionName)
# Or via tag.
job = aiplatform.PipelineJob(
    display_name="hello-world-latest",
    template_path="https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo/hello-world/v1")

job.submit()

Visualiza las ejecuciones de canalización creadas

Puedes ver las ejecuciones que crea una versión de canalización específica en el SDK de Vertex AI para Python.

Console

1. Abre Vertex AI Pipelines en la consola de Google Cloud.

   Ir a Vertex AI Pipelines

2. Haz clic en la pestaña Tus plantillas.

3. Haz clic en Seleccionar repositorio.

4. En la lista, selecciona el repositorio quickstart-kfp-repo y, luego, haz clic en Seleccionar.

5. Para ver la lista de versiones de la plantilla de canalización hello-world, haz clic en la plantilla hello world.

6. Haz clic en la versión deseada para la que deseas ver las ejecuciones de canalización.

7. Para ver las ejecuciones de canalizaciones de la versión seleccionada, haz clic en Ver ejecuciones y, luego, en la pestaña Ejecuciones.

SDK de Vertex AI para Python

Para enumerar las ejecuciones de canalizaciones, ejecuta el comando pipelineJobs.list como se muestra en uno o más de los siguientes ejemplos:

  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)

Usa la plantilla en un cliente de registro del SDK de Kubeflow Pipelines

Puedes usar un cliente de registro del SDK de Kubeflow Pipelines junto con Artifact Registry para descargar y usar la plantilla de canalización.

• Para enumerar los recursos del repositorio, ejecuta los siguientes 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 obtener una lista completa de los métodos y documentos disponibles, consulta los archivos proto en el repositorio de GitHub de Artifact Registry.

• Para descargar la plantilla en tu sistema de archivos local, ejecuta los siguientes 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")
  

Usa la API de REST de Artifact Registry

En las siguientes secciones, se resume cómo usar la API de REST de Artifact Registry para administrar las plantillas de canalización en tu repositorio de Artifact Registry.

Sube una plantilla de canalización con la API de REST de Artifact Registry

Puedes subir una plantilla de canalización si creas una solicitud HTTP con los valores de los parámetros descritos en esta sección, en los que se muestra lo siguiente:

• PROJECT_ID es el proyecto de Google Cloud en el que se ejecuta esta canalización.
• REPO_ID es el ID de tu repositorio de Artifact Registry.

Solicitud cURL de ejemplo

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

Crea la solicitud de carga

La solicitud es una solicitud multiparte HTTP o HTTPS. Debe incluir el token de autenticación en el encabezado de la solicitud. Para obtener más información, consulta gcloud auth print-access-token.

La carga útil de la solicitud es el contenido del archivo pipeline_spec.yaml (o el paquete .zip). El límite de tamaño recomendado es de 10 MiB.

El nombre del paquete se toma de la entrada pipeline_spec.pipeline_info.name del archivo pipeline_spec.yaml. El nombre del paquete identifica de forma única el paquete y es inmutable en todas las versiones. Puede tener entre 4 y 128 caracteres y debe coincidir con la siguiente expresión regular: ^[a-z0-9][a-z0-9-]{3,127}$.

El paquete tags es una lista de hasta ocho etiquetas separadas por comas. Cada etiqueta debe coincidir con la siguiente expresión regular: ^[a-zA-Z0-9\-._~:@+]{1,128}$.

Si existe una etiqueta y apunta a una canalización que ya se subió, la etiqueta se actualiza para que apunte a la canalización que estás subiendo en ese momento. Por ejemplo, si la etiqueta latest apunta a una canalización que ya subiste y subes una versión nueva con --tag=latest, la etiqueta latest se quita de la canalización que se subió antes y se asigna a la canalización nueva que estás subiendo.

Si la canalización que subes es idéntica a la canalización que subiste antes, la carga se realiza de forma correcta. Los metadatos de la canalización subidos, incluidas sus etiquetas de versión, se actualizan para coincidir con los valores del parámetro de tu solicitud de carga.

Respuesta de carga

Si la solicitud de carga se realiza correctamente, se muestra un estado HTTP OK. El cuerpo de la respuesta es el siguiente:

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

En el ejemplo anterior, versionName es el resumen sha256 de pipeline_spec.yaml con formato como una string hexadecimal.

Descarga una plantilla de canalización con la API de REST de Artifact Registry

Puedes descargar una plantilla de canalización si creas una solicitud HTTP con los valores de los parámetros descritos en esta sección, en los que se muestra lo siguiente:

• PROJECT_ID es el proyecto de Google Cloud en el que se ejecuta esta canalización.
• REPO_ID es el ID de tu repositorio de Artifact Registry.
• PACKAGE_ID es el ID del paquete de tu plantilla subida.
• TAG es la etiqueta de la versión.
• VERSION es la versión de la plantilla en el formato sha256:abcdef123456....

Para la descarga la versión estándar de Artifact Registry, debes formar el vínculo de descarga de la siguiente manera:

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

Solicitudes cURL de ejemplo

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

Puedes reemplazar VERSION por TAG y descargar la misma plantilla, como se muestra en el siguiente ejemplo:

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

Descarga la respuesta

Si la solicitud de descarga se realiza correctamente, se muestra un estado HTTP OK. El cuerpo de la respuesta es el contenido del archivo pipeline_spec.yaml.

Vínculos de referencia

• Artifact Registry: Descripción general de los repositorios para obtener más información sobre cómo administrar tus repositorios.
• API de repositorio
  • la palabra clave de formato es “KFP”
• API de paquetes
• API de versión
• API de etiquetas
• Definiciones de proto en GitHub