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 2 o una posterior del SDK de Kubeflow Pipelines.

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

1. 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
   

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

3. 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.

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

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

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

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.

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

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.

  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