Ejecutar una canalización

Vertex AI Pipelines te permite ejecutar canalizaciones de aprendizaje automático (AA) compiladas con el SDK de Kubeflow Pipelines o TensorFlow Extended sin servidores. En este documento, se describe cómo ejecutar una canalización de AA.

También puedes crear ejecuciones de canalizaciones con plantillas compiladas previamente en la Galería de plantillas. Para obtener más información sobre la Galería de plantillas, consulta Usa una plantilla compilada previamente de la Galería de plantillas.

Antes de comenzar

Antes de ejecutar una canalización con Vertex AI Pipelines, usa las siguientes instrucciones para configurar el proyecto de Google Cloud y el entorno de desarrollo:

Compila una canalización.
Si deseas ejecutar una canalización con el SDK de Vertex AI para Python, instala el SDK de Vertex.
- Instala el SDK de Vertex AI.

Crea una ejecución de canalización

Usa las siguientes instrucciones para ejecutar una canalización de AA con la consola de Google Cloud o Python.

Consola

Usa las siguientes instrucciones para ejecutar una canalización de AA con la consola de Google Cloud.

En la sección Vertex AI de la consola de Google Cloud, ve a la página Canalizaciones.

Ir a Canalizaciones
En la lista desplegable Región, selecciona la región para crear la ejecución de la canalización.
Haz clic en Crear ejecución para abrir el panel Crear ejecución de canalización.
En la sección Run details, especifica la siguiente información:
1. Haz clic en una fuente de ejecución. Las siguientes opciones están disponibles:
  - Seleccionar entre las canalizaciones existentes: Para crear una ejecución de la canalización basada en una plantilla de canalización existente, haz clic en Seleccionar entre las canalizaciones existentes y, luego, ingresa los siguientes detalles:
    1. Selecciona el repositorio que contiene el archivo de definición de la canalización o del componente.
    2. Selecciona la canalización o componente y la versión.
    3. Especifica un nombre de ejecución para identificar de manera única la ejecución de la canalización.
  - Seleccionar una canalización de la Galería de plantillas: Para crear una ejecución de la canalización basada en una plantilla de canalización creada por Google desde el Galería de plantillas, haz clic Seleccionar una canalización de la Galería de plantillas e ingresa los siguientes detalles:
    1. En la lista Canalización de la Galería de plantillas, selecciona la plantilla de canalización.
    2. Opcional: Modifica el Nombre de ejecución predeterminado que identifica la ejecución de la canalización de forma única.
    Nota: En estas instrucciones, se describe cómo crear una ejecución de canalización con la interfaz predeterminada de la página Crea una ejecución de canalización, que consta de las secciones Detalles de ejecución y Configuración del entorno de ejecución. En algunas plantillas de la Galería de plantillas, esta página tiene secciones adicionales. Por ejemplo, la plantilla AutoML para regresión/clasificación tabular también incluye el Método de entrenamiento, las Opciones de entrenamiento, y Procesamiento y precios.
  - Subir archivo: Para subir una definición de canalización compilada, haz clic en Subir archivo y, luego, ingresa los siguientes detalles:
    1. Haz clic en Explorar para abrir el selector de archivos. Navega hasta el archivo YAML de canalización compilado que deseas ejecutar, selecciona la canalización y haz clic en Abrir.
    2. El nombre de la canalización o del componente muestra el nombre especificado en la definición de la canalización de forma predeterminada. De manera opcional, especifica un nombre de la canalización diferente.
    3. Especifica un nombre de ejecución para identificar de manera única la ejecución de la canalización.
  - Importar desde Cloud Storage: para importar un archivo de definición de canalización desde Cloud Storage, haz clic en Importar desde Cloud Storage e ingresa los siguientes detalles:
    1. Haz clic en Explorar para navegar al bucket de Cloud Storage que contiene el objeto de definición de la canalización, selecciona el archivo y, luego, haz clic en Seleccionar.
    2. Especifica el nombre de la canalización o del componente.
    3. Especifica un nombre de ejecución para identificar de manera única la ejecución de la canalización.
2. Opcional: para programar ejecuciones de canalizaciones recurrentes, especifica el Programa de ejecución de la siguiente manera:
  1. Selecciona Recurrente.
  2. En Hora de inicio, especifica cuándo se activa el programa.
    - Si quieres programar la primera ejecución para que se produzca de inmediato después de crear el programa, selecciona De inmediato.
    - A fin de programar la primera ejecución para que se realice en una hora y una fecha específicas, selecciona Activado.
  3. En el campo Frecuencia, especifica la frecuencia para programar y ejecutar las ejecuciones de canalización, mediante una expresión de programa cron basada en unix-cron.
  4. En Finaliza, especifica cuándo finaliza el programa.
    - Para indicar que el programa crea ejecuciones de canalizaciones de forma indefinida, selecciona Nunca.
    - Para indicar que el programa finaliza en una fecha y hora específicas, selecciona Activado y especifica la fecha y hora de finalización del programa.
  5. Opcional: Para especificar que la ejecución de la canalización use una cuenta de servicio personalizada, una clave de encriptación administrada por el cliente (CMEK) o una red de VPC con intercambio de tráfico, haz clic en Opciones avanzadas y, luego, usa las siguientes instrucciones:
    - Para especificar una cuenta de servicio, selecciona una cuenta de servicio de la lista desplegable Service account.
      
      Si no especificas una cuenta de servicio, Vertex AI Pipelines ejecuta la canalización con la cuenta de servicio predeterminada de Compute Engine.
      
      Obtén más información sobre cómo configurar una cuenta de servicio para usar con Vertex AI Pipelines.
    - Para usar una CMEK, selecciona Use a customer-managed encryption key. Aparecerá la lista desplegable Selecciona una clave administrada por el cliente. En la lista desplegable Selecciona una clave administrada por el cliente, selecciona la clave que deseas usar.
    - Para usar una red de VPC con intercambio de tráfico en la ejecución de esta canalización, ingresa el nombre de la red de VPC en el cuadro Peered VPC network.
3. Haz clic en Continuar.
En la sección Configuración del entorno de ejecución, configura la ejecución de la canalización de la siguiente manera:
1. En Ubicación de Cloud Storage, haz clic en Explorar para seleccionar el bucket de Cloud Storage a fin de almacenar los artefactos de salida de la canalización y, luego, haz clic en Seleccionar.
2. Opcional: Para configurar la política de fallas y la caché de la canalización, haz clic en Opciones avanzadas y, luego, usa las siguientes instrucciones:
  - En Política de fallas, especifica la política de fallas para toda la canalización. Obtén más información sobre las políticas sobre fallas de la canalización.
    - Para configurar la canalización a fin de continuar programando tareas después de que falle una, selecciona Ejecutar todos los pasos hasta el final. Esta opción está seleccionada de forma predeterminada.
    - Para configurar la canalización a fin de que falle después de que una tarea falle, selecciona Hacer que esta ejecución falle en cuanto ocurra una falla en un paso.
  - En Configuración de almacenamiento en caché, especifica la configuración de caché para toda la canalización.
    - Para usar la configuración de caché a nivel de la tarea para la tarea en la canalización, selecciona No anular la configuración de caché a nivel de la tarea.
    - Para activar el almacenamiento en caché para todas las tareas de la canalización y anular cualquier configuración de caché a nivel de la tarea, selecciona Habilitar lectura desde la caché para todos los pasos (opción más rápida).
    - Para desactivar el almacenamiento en caché de todas las tareas de la canalización y anular cualquier configuración de caché a nivel de la tarea, selecciona Inhabilitar lectura de la caché para todos los pasos (opción más rápida).
3. Opcional: Si tu canalización tiene parámetros, en Parámetros de canalización, especifica tus parámetros de ejecución de canalización.
Para crear la ejecución de la canalización, haz clic en Enviar.

SDK de Vertex AI para Python

Usa las siguientes instrucciones a fin de ejecutar una canalización de AA con el SDK de Vertex AI para Python. Antes de ejecutar la siguiente muestra de código, debes configurar la autenticación.

Configura la autenticación

Para configurar la autenticación, debes crear una clave de cuenta de servicio y establecer una variable de entorno para la ruta a la clave de la cuenta de servicio.

Crear una cuenta de servicio:
1. En la consola de Google Cloud, ve a la página Crear cuenta de servicio.
  
  Ve a Crear cuenta de servicio
2. Ingresa un nombre en el campo Nombre de cuenta de servicio.
3. Opcional: en el campo Descripción de la cuenta de servicio, ingresa una descripción.
4. Haz clic en Crear.
5. Haz clic en el campo Seleccionar una función. En Todas las funciones, selecciona Vertex AI > Administrador de Vertex AI.
6. Haz clic en Listo para crear la cuenta de servicio.
  
  No cierres la ventana del navegador. La usarás en la próxima tarea.
Crea una clave de cuenta de servicio para la autenticación:
1. En la consola de Google Cloud, haz clic en la dirección de correo electrónico de la cuenta de servicio que creaste.
2. Haga clic en Claves.
3. Haz clic en Agregar clave -> Crear nueva clave.
4. Haz clic en Crear. Se descargará un archivo de claves JSON en tu computadora.
5. Haga clic en Cerrar.
Otorga a tu cuenta de servicio nueva acceso a la cuenta que usas para ejecutar las canalizaciones.
1. Haz clic en para volver a la lista de cuentas de servicio.
2. Haz clic en el nombre de la cuenta de servicio que usas para ejecutar las canalizaciones. Aparecerá la página Service account details.
  
  Si seguiste las instrucciones de la guía para configurar tu proyecto de Vertex AI Pipelines, esta es la misma cuenta de servicio que creaste en la sección Configura una cuenta de servicio con permisos detallados. De lo contrario, Vertex AI usa la cuenta de servicio predeterminada de Compute Engine para ejecutar las canalizaciones. La cuenta de servicio predeterminada de Compute Engine se llama de la siguiente manera: PROJECT_NUMBER-compute@developer.gserviceaccount.com
3. Haz clic en la pestaña Permisos.
4. Haz clic en Grant access. Aparecerá el panel Agregar principales.
5. En el cuadro Principales nuevos, ingresa la dirección de correo electrónico de la cuenta de servicio que creaste en un paso anterior.
6. En la lista desplegable Role, selecciona Service accounts > Service account user.
7. Haga clic en Guardar.
Configura la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta del archivo JSON que contiene la clave de tu cuenta de servicio: Esta variable solo se aplica a tu sesión actual de shell. Por lo tanto, si abres una sesión nueva, deberás volver a configurar la variable.

Ejemplo: Linux o macOS

Reemplaza [PATH] por la ruta de acceso del archivo JSON que contiene la clave de tu cuenta de servicio.
```
export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
```
Por ejemplo:
```
export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"
```
Ejemplo: Windows

Reemplaza [PATH] con la ruta de acceso del archivo JSON que contiene la clave de tu cuenta de servicio y [FILE_NAME] con el nombre del archivo.

Con PowerShell:
```
$env:GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
```
Por ejemplo:
```
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\[FILE_NAME].json"
```
Con el símbolo del sistema:
```
set GOOGLE_APPLICATION_CREDENTIALS=[PATH]
```

Ejecutar una canalización

Para ejecutar un PipelineJob de Vertex AI, debes crear un objeto PipelineJob y, luego, invocar el método submit.

Tipos de entrada especiales compatibles con KFP

Cuando creas una ejecución de canalización, también puedes pasar los siguientes marcadores de posición compatibles con el SDK de KFP como entradas:

{{$.pipeline_job_name_placeholder}}
{{$.pipeline_job_resource_name_placeholder}}
{{$.pipeline_job_id_placeholder}}
{{$.pipeline_task_name_placeholder}}
{{$.pipeline_task_id_placeholder}}
{{$.pipeline_job_create_time_utc_placeholder}}
{{$.pipeline_root_placeholder}}

Para obtener más información, consulta los Tipos de entradas especiales en la documentación de Kubeflow Pipelines v2.

from google.cloud import aiplatform

job = aiplatform.PipelineJob(display_name = DISPLAY_NAME,
                             template_path = COMPILED_PIPELINE_PATH,
                             job_id = JOB_ID,
                             pipeline_root = PIPELINE_ROOT_PATH,
                             parameter_values = PIPELINE_PARAMETERS,
                             enable_caching = ENABLE_CACHING,
                             encryption_spec_key_name = CMEK,
                             labels = LABELS,
                             credentials = CREDENTIALS,
                             project = PROJECT_ID,
                             location = LOCATION,
                             failure_policy = FAILURE_POLICY)

job.submit(service_account=SERVICE_ACCOUNT,
           network=NETWORK)

Reemplaza lo siguiente:

DISPLAY_NAME: el nombre de la canalización, aparecerá en la consola de Google Cloud.
COMPILED_PIPELINE_PATH: Es la ruta de acceso al archivo YAML de canalización compilado. Puede ser una ruta local o un URI de Cloud Storage.

Opcional: Para especificar una versión en particular de una canalización compilada, incluye la etiqueta de versión en cualquiera de los siguientes formatos:
- COMPILED_PIPELINE_PATH:TAG, donde TAG es la etiqueta de la versión.
- COMPILED_PIPELINE_PATH@SHA256_TAG, donde SHA256_TAG es el valor de hash sha256 de la versión de la canalización.
JOB_ID: (opcional) un identificador único para esta ejecución de canalización. Si no se especifica el ID de trabajo, Vertex AI Pipelines crea un ID de trabajo por ti con el nombre de la canalización y la marca de tiempo de cuándo se inició la ejecución de la canalización.
PIPELINE_ROOT_PATH: (opcional) para anular la ruta de acceso raíz de la canalización especificada en la definición de la canalización, indica una ruta de acceso a la que pueda acceder el trabajo de canalización, como un URI de bucket de Cloud Storage.
PIPELINE_PARAMETERS: (opcional) los parámetros de canalización que se pasarán a esta ejecución. Por ejemplo, crea un dict() con los nombres de los parámetros como claves del diccionario y los valores de los parámetros como valores del diccionario.
ENABLE_CACHING: (opcional) especifica si la ejecución de esta canalización usa el almacenamiento en caché de ejecución. El almacenamiento en caché de ejecución reduce los costos, ya que omite las tareas de canalización en las que el resultado es conocido para el conjunto actual de entradas. Si el argumento de habilitación del almacenamiento en caché no se especifica, el almacenamiento en caché de ejecución se usa en la ejecución de esta canalización. Obtén más información sobre el almacenamiento en caché de ejecución.
CMEK: (opcional) el nombre de la clave de encriptación administrada por el cliente que deseas usar para la ejecución de esta canalización.
LABELS: (opcional) las etiquetas definidas por el usuario para organizar este PipelineJob. Para obtener más información sobre las etiquetas de recursos, consulta Crea y administra etiquetas en la documentación de Resource Manager.

Vertex AI Pipelines adjunta automáticamente la siguiente etiqueta a la ejecución de tu canalización:

vertex-ai-pipelines-run-billing-id: pipeline_run_id

En el ejemplo anterior, pipeline_run_id es el ID único de la ejecución de la canalización.

Esta etiqueta conecta el uso de los recursos de Google Cloud generados por la canalización que se ejecuta en los informes de facturación.
CREDENTIALS: (opcional) las credenciales personalizadas que se usarán para crear este PipelineJob. Anula las credenciales configuradas en aiplatform.init.
PROJECT_ID: (opcional) El proyecto de Google Cloud en el que deseas ejecutar la canalización. Si no configuras este parámetro, se usa el conjunto de proyectos en aiplatform.init.
LOCATION: (opcional) es la región en la que deseas ejecutar la canalización. Para obtener más información sobre las regiones en las que Vertex AI Pipelines está disponible, consulta la guía de ubicaciones de Vertex AI. Si no configuras este parámetro, se usa la ubicación predeterminada establecida en aiplatform.init.
FAILURE_POLICY: (opcional) Especifica la política de fallas para toda la canalización. Las siguientes opciones de configuración están disponibles:
- Para configurar la canalización a fin de que falle después de que una tarea falle, ingresa fast.
- Para configurar la canalización a fin de continuar programando tareas después de que falle una, ingresa slow.
Si no estableces este parámetro, la configuración de política de fallas se establece en slow de forma predeterminada. Obtén más información sobre las políticas sobre fallas de la canalización.
SERVICE_ACCOUNT: (opcional) el nombre de la cuenta de servicio que se usará para la ejecución de esta canalización. Si no especificas una cuenta de servicio, Vertex AI Pipelines ejecuta la canalización con la cuenta de servicio predeterminada de Compute Engine.
NETWORK: (opcional) el nombre de la red de VPC con intercambio de tráfico que se usará para ejecutar esta canalización.