Ejecuta archivos de notebook con el ejecutor

En esta página, se describe cómo usar el ejecutor en una instancia de notebooks administrada de Vertex AI para ejecutar archivos de notebook como una ejecución única y según una programación.

Descripción general

El ejecutor te permite enviar un archivo de notebook (ipynb) para que se ejecute en el entrenamiento personalizado de Vertex AI. Puedes establecer valores de parámetros para cada ejecución de un archivo de notebook. También puedes ejecutar un archivo de notebook según un programa recurrente. Una vez completada la ejecución, puedes ver sus resultados y compartirlos con otras personas.

Cuando se envía un archivo de notebook a un entrenamiento personalizado de Vertex AI, Vertex AI crea un nuevo trabajo de entrenamiento personalizado que ejecuta el archivo de notebook después del ciclo de vida de un trabajo de entrenamiento.

Requisitos para el código del notebook que ejecuta el ejecutor

Cuando escribas el código del notebook para que se ejecute en el ejecutor, ten en cuenta que el código se ejecutará en un proyecto de usuario separado del proyecto de la instancia de notebook administrado. En esta sección, se describe cómo esto afecta tu código cuando se ejecuta en el ejecutor.

Asegúrate de que las instalaciones de paquetes estén disponibles para el ejecutor

Si tu notebook depende de las instalaciones de paquetes que aún no están incluidas en el kernel de notebooks administrados que usas, asegúrate de que tus paquetes estén disponibles para el código del notebook en el ejecutor de una de las siguientes maneras:

  • Usa un contenedor personalizado que ya tenga el paquete instalado y, luego, ejecuta tu notebook en ese contenedor personalizado. Consulta los requisitos para usar un contenedor personalizado con el ejecutor.

  • Instala el paquete en el código de tu archivo de notebook. El paquete se instala cada vez que se ejecuta el archivo del notebook, pero esto garantiza que el paquete esté disponible en el contenedor que seleccionas cuando ejecutas el notebook.

Usa la selección explícita de proyectos

Cuando accedes a los recursos a través del código que ejecuta el ejecutor, es posible que el ejecutor no se conecte al proyecto correcto de Google Cloud. Si te encuentras con errores de permiso, conectarte con el proyecto equivocado puede ser el problema.

Este problema ocurre porque el ejecutor no ejecuta el código directamente en el proyecto de Google Cloud de la instancia de notebooks administrados. En cambio, el ejecutor ejecuta tu código en el entrenamiento personalizado de Vertex AI dentro de un proyecto de usuario administrado por Google. Por lo tanto, no intentes inferir un ID de proyecto del entorno en tu código de notebook; especifica explícitamente los ID del proyecto.

Si no deseas codificar un ID del proyecto en tu código, puedes hacer referencia a la variable de entorno CLOUD_ML_PROJECT_ID. Vertex AI establece esta variable de entorno en cada contenedor de entrenamiento personalizado para que contenga el número del proyecto en el que iniciaste el entrenamiento personalizado. Muchas herramientas de Google Cloud aceptan un número de proyecto cada vez que tomen un ID del proyecto.

Si deseas usar el cliente de Python para Google BigQuery a fin de acceder a una tabla de BigQuery en el mismo proyecto, no intentes inferir el proyecto en tu código de notebook:

Selección implícita del proyecto

from google.cloud import bigquery

client = bigquery.Client()

En su lugar, usa un código que elija de manera explícita un proyecto:

Selección explícita del proyecto

import os

from google.cloud import bigquery

project_number = os.environ["CLOUD_ML_PROJECT_ID"]

client = bigquery.Client(project=project_number)

Autentica el acceso mediante cuentas de servicio

De forma predeterminada, tu instancia de notebooks administrados puede tener acceso a recursos que existen en el mismo proyecto. Por lo tanto, cuando ejecutas el código de tu archivo de notebook de forma manual, estos recursos no necesitan autenticación adicional. Sin embargo, debido a que el ejecutor se ejecuta en un proyecto de usuario independiente, no tiene el mismo acceso predeterminado.

Además, el ejecutor no puede usar las credenciales del usuario final para autenticar el acceso a los recursos, por ejemplo, el comando gcloud auth login.

Para resolver estos problemas, en el código de tu archivo de notebook, autentica el acceso a los recursos mediante una cuenta de servicio.

Luego, cuando crees una ejecución o un programa, especifica la cuenta de servicio.

Por ejemplo, mientras creas una ejecución, completa estos pasos:

  1. En el cuadro de diálogo Enviar notebooks al ejecutor, expande Opciones avanzadas.

  2. En la sección Identidad y acceso a la API, desmarca la marca de verificación junto a Usar la cuenta de servicio predeterminada de Vertex AI Training y, luego, ingresa la cuenta de servicio específica para usar.

Consulta la lista completa de pasos para crear una ejecución.

Requisitos para usar un contenedor personalizado

Puedes usar el ejecutor para ejecutar código de notebook en un contenedor personalizado. El contenedor personalizado debe incluir la extensión nbexecutor, que permite al ejecutor ejecutar código de notebook como un trabajo de entrenamiento personalizado de Vertex AI. Para garantizar que el contenedor personalizado tenga la extensión nbexecutor, puedes modificar una de las imágenes de contenedor de contenedores de aprendizaje profundo a fin de crear una imagen de contenedor derivada. Las imágenes de contenedores de aprendizaje profundo incluyen la extensión nbexecutor.

Antes de comenzar

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Notebooks and Vertex AI APIs.

    Enable the APIs

    5.

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Notebooks and Vertex AI APIs.

    Enable the APIs

    8.
  8. Si aún no lo hiciste, crea una instancia de notebooks administrados.

Roles obligatorios

Para garantizar que la cuenta de servicio de tu instancia tenga los permisos necesarios para interactuar con el ejecutor de Vertex AI Workbench, pídele a tu administrador que le otorgue a la cuenta de servicio de tu instancia los siguientes roles de IAM en el proyecto:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Es posible que tu administrador también pueda otorgar a la cuenta de servicio de tu instancia los permisos necesarios mediante roles personalizados o con otros roles predefinidos.

Abre JupyterLab

Si deseas abrir JupyterLab y preparar un archivo de notebook para que se ejecute, completa los siguientes pasos.

  1. Abre JupyterLab.

  2. Sube un archivo de notebook (ipynb), abre un archivo existente o abre un archivo de notebook nuevo y agrega al notebook el código que deseas ejecutar.

  3. Asegúrate de que el código del archivo de notebook cumpla con los requisitos para usar el ejecutor.

Crear una ejecución

Para crear una ejecución que ejecute tu archivo de notebook, completa los siguientes pasos. Estos pasos abarcan la programación de ejecuciones y la creación de una ejecución única.

  1. En la interfaz de usuario de JupyterLab de tu instancia de notebooks administrados, abre el archivo de notebook que deseas ejecutar.

  2. Haz clic en el botón Ejecutar .

  3. En el diálogo Enviar notebooks al ejecutor, en el campo Nombre de ejecución, ingresa un nombre para tu ejecución.

  4. Selecciona un Tipo de máquina y un Tipo de acelerador.

  5. Selecciona un entorno.

  6. En el campo Tipo, selecciona Ejecución única o Ejecuciones recurrentes basadas en el programa y completa el cuadro de diálogo a fin de programar ejecuciones.

  7. En Opciones avanzadas, selecciona la Región en la que deseas ejecutar el notebook.

  8. En el campo Bucket de Cloud Storage, selecciona un bucket de Cloud Storage disponible o ingresa un nombre para un bucket nuevo y haz clic en Crear y seleccionar. El ejecutor almacena el resultado de tu notebook en este bucket de Cloud Storage.

  9. Opcional: en Parametrización del notebook en la sección Parámetros de entrada agrega cuadros de texto separados por comas, por ejemplo: optimizer="SGD",learning_rate=0.01.

    Obtén más información sobre cómo usar los parámetros de notebook.

  10. Opcional: En la sección Identidad y acceso a la API, selecciona Usar la cuenta de servicio predeterminada de Vertex AI Training o borra la marca de verificación e ingresa una cuenta de servicio específica para usar.

  11. Opcional: En la sección Herramientas de redes, especifica una red de nube privada virtual. El uso de una red de VPC para tu ejecución requiere una conexión de acceso privado a servicios.

  12. Haz clic en Enviar.

    Las ejecuciones únicas comienzan de inmediato. Las ejecuciones programadas se ejecutan automáticamente en el programa que estableciste.

En la consola de Google Cloud, en la página Vertex AI Workbench, puedes ver las ejecuciones completadas en la pestaña Ejecuciones y visualizar tus programas en la pestaña Programas.

Visualiza, comparte e importa un archivo de notebook ejecutado

Si usas la interfaz de usuario de JupyterLab de tu instancia de notebooks administrados, puedes ver el resultado de un notebook ejecutado, compartir los resultados con otros y, luego, importar el archivo del notebook ejecutado en JupyterLab.

Ve los resultados de la ejecución de un notebook

Puedes ver los resultados de la ejecución de un notebook en la consola de Google Cloud o en la interfaz de usuario de JupyterLab.

Console

  1. En la consola de Google Cloud, ve a la página Vertex AI Workbench y haz clic en la pestaña Ejecuciones.

    Ir a Ejecuciones

  2. Selecciona la Región que contiene los resultados.

  3. Junto a la ejecución que deseas ver, haz clic en Ver resultado.

    El resultado se abrirá en una pestaña nueva del navegador.

JupyterLab

  1. En el menú de navegación de JupyterLab, haz clic en el ícono Ejecutor de notebooks.

  2. Haz clic en la pestaña Ejecuciones.

  3. En la ejecución que deseas ver, haz clic en Ver resultado.

    El resultado se abrirá en una pestaña nueva del navegador.

Comparte los resultados de la ejecución de un notebook

Para compartir los resultados de la ejecución, proporciona acceso al bucket de Cloud Storage que contiene la ejecución del notebook. Cuando se proporciona este acceso, también se otorga a los usuarios acceso a cualquier otro recurso en el mismo bucket de Cloud Storage. Para compartir los resultados de la ejecución, completa los siguientes pasos.

Console

  1. En la consola de Google Cloud, ve a la página Vertex AI Workbench y haz clic en la pestaña Ejecuciones.

    Ir a Ejecuciones

  2. Selecciona la Región que contiene la ejecución.

  3. Junto a la ejecución que deseas compartir, haz clic en el botón  Compartir.

  4. Sigue las instrucciones del cuadro de diálogo para otorgar a los usuarios acceso al bucket de Cloud Storage que contiene la ejecución del notebook.

JupyterLab

  1. En la interfaz de usuario de JupyterLab de tu instancia de notebooks administrados, en el menú de navegación, haz clic en el siguiente botón: Ejecutor de notebooks.

  2. Haz clic en la pestaña Ejecuciones.

  3. Junto a la ejecución que deseas compartir, haz clic en el menú de opciones de y selecciona Compartir el resultado de la ejecución.

  4. Sigue las instrucciones del cuadro de diálogo para otorgar a los usuarios acceso al bucket de Cloud Storage que contiene la ejecución del notebook.

Importa un notebook ejecutado en JupyterLab

Para importar un notebook ejecutado en JupyterLab, completa los siguientes pasos.

  1. En la interfaz de usuario de JupyterLab de tu instancia de notebooks administrados, en el menú de navegación, haz clic en el siguiente botón: Ejecutor de notebooks.

  2. Haz clic en la pestaña Ejecuciones.

  3. Selecciona la Región que contiene el notebook ejecutado.

  4. Junto a la ejecución que deseas importar, haz clic en el menú de opciones y selecciona Importar notebook ejecutado.

  5. Selecciona el kernel en que deseas abrir el notebook.

    El ejecutor abre el archivo de notebook ejecutado en JupyterLab y almacena este archivo de notebook en el navegador de archivos de JupyterLab en una carpeta llamada imported_notebook_jobs.

Ve o borra un programa

Puedes ver y borrar los programas mediante la consola de Google Cloud o la interfaz de usuario de JupyterLab de tu instancia de notebooks administrados.

Ve una programación

Consulta un programa para ver su configuración de frecuencia o los resultados de tus ejecuciones de notebooks.

Console

  1. En la consola de Google Cloud, ve a la página Vertex AI Workbench y haz clic en la pestaña Programas.

    Ir a Programas

  2. Selecciona la Región que contiene tu programa.

  3. Haz clic en el nombre del programa para abrir la página Detalles del programa.

  4. Junto al nombre de una ejecución, haz clic en Ver resultado para abrir el archivo de notebook ejecutado. El ejecutor abre su resultado en una pestaña nueva del navegador.

JupyterLab

  1. En la interfaz de usuario de JupyterLab de tu instancia de notebooks administrados, en el menú de navegación, haz clic en el siguiente botón: Ejecutor de notebooks.

  2. Haz clic en la pestaña Programaciones.

  3. Para ver la última ejecución, en la ejecución que deseas ver, haz clic en Ver el resultado de la última ejecución. El ejecutor abre el resultado en una pestaña nueva del navegador.

    Para ver todas las ejecuciones, haz clic en el nombre del programa. El ejecutor abre la página Detalles del programa en la consola de Google Cloud.

  4. Junto al nombre de una ejecución, haz clic en Ver resultado para abrir el archivo de notebook ejecutado. El ejecutor abre su resultado en una pestaña nueva del navegador.

Borra un programa

Borrar una programación no borra las ejecuciones que se generaron a partir de esa programación.

Console

  1. En la consola de Google Cloud, ve a la página Vertex AI Workbench y haz clic en la pestaña Programas.

    Ir a Programas

  2. Selecciona la Región que contiene tu programa.

  3. Selecciona el programa que deseas borrar.

  4. Haz clic en Borrar.

JupyterLab

  1. En la interfaz de usuario de JupyterLab de tu instancia de notebooks administrados, en el menú de navegación, haz clic en el siguiente botón: Ejecutor de notebooks.

  2. Haz clic en la pestaña Programaciones.

  3. Haz clic en el nombre de la asignación que deseas borrar. El ejecutor abre la página Detalles del programa en la consola de Google Cloud.

  4. Haz clic en Borrar.

Trabajos en entrenamiento personalizado de Vertex AI

Debido a que las ejecuciones de notebooks se ejecutan en el entrenamiento personalizado de Vertex AI, se exponen como trabajos de entrenamiento personalizados en Vertex AI. Puedes ver estos trabajos de entrenamiento personalizados en la consola de Google Cloud en pestaña Trabajos personalizados de la página Entrenamiento de Vertex AI. Obtén más información sobre cómo trabajar con trabajos de entrenamiento personalizados de Vertex AI.

¿Qué sigue?