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.
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
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
Instala la versión 390.0.0 o una versión posterior de Google Cloud CLI (opcional).
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
oroles/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.
Console
Abre Vertex AI Pipelines en la consola de Google Cloud.
Haz clic en la pestaña Tus plantillas.
Para abrir el panel Seleccionar repositorio, haz clic en Seleccionar repositorio.
Haz clic en Crear repositorio.
Especifica
quickstart-kfp-repo
como el nombre del repositorio.En Formato, selecciona
Kubeflow Pipelines
.En Tipo de ubicación, selecciona Región.
En la lista desplegable Región, selecciona
us-central1
.Haz 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 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
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
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
Console
Abre Vertex AI Pipelines en la consola de Google Cloud.
Haz clic en Subir para abrir el panel Subir canalización o componente.
En la lista desplegable Repositorio, selecciona el repositorio
quickstart-kfp-repo
.Especifica un Nombre para la plantilla de canalizaciones.
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.
Después de subir la plantilla de canalización, aparecerá en la página Tus plantillas.
Cliente del SDK de Kubeflow Pipelines
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")
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."})
Para verificar que se subió la plantilla, haz lo siguiente:
Abre Vertex AI Pipelines en la consola de Google Cloud.
Haz clic en la pestaña Tus plantillas.
Haz clic en Seleccionar repositorio.
En la lista, selecciona el repositorio
quickstart-kfp-repo
y, luego, haz clic en Seleccionar.Debes encontrar el paquete de plantilla
hello-world
subido de la lista.Para ver una lista de las versiones de la plantilla de canalización, haz clic en la plantilla
hello-world
.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
Abre Vertex AI Pipelines en la consola de Google Cloud.
Haz clic en la pestaña Tus plantillas.
Para abrir el panel Seleccionar repositorio, haz clic en Seleccionar repositorio.
Selecciona el repositorio
quickstart-kfp-repo
y, luego, haz clic en Seleccionar.Haz clic en el paquete
hello-world
.Junto a la versión
4f245e8f9605
, haz clic en Crear ejecución.Haz clic en Configuración del entorno de ejecución.
En Ubicación de Cloud Storage, ingresa lo siguiente:
gs://BUCKET_NAME
Reemplaza BUCKET_NAME por el nombre del bucket que creaste para la etapa de pruebas de las ejecuciones de tu canalización.
Haz clic en Enviar.
SDK de Vertex AI para Python
Usa el siguiente ejemplo para crear una ejecución de canalización a partir de tu plantilla:
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()
Reemplaza lo siguiente:
PROJECT_ID: Es el proyecto de Google Cloud en el que se ejecuta esta canalización.
SHA256_TAG: El valor de hash SHA256 de la versión de la plantilla.
TAG: La etiqueta de versión de la plantilla.
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
Abre Vertex AI Pipelines en la consola de Google Cloud.
Haz clic en la pestaña Tus plantillas.
Haz clic en Seleccionar repositorio.
En la lista, selecciona el repositorio
quickstart-kfp-repo
y, luego, haz clic en Seleccionar.Para ver la lista de versiones de la plantilla de canalización
hello-world
, haz clic en la plantillahello world
.Haz clic en la versión que deseas para ver las ejecuciones de canalización.
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