Crear una instancia de cuadernos gestionados con un contenedor personalizado

Crear una instancia de cuadernos gestionados con un contenedor personalizado

Los notebooks gestionados de Vertex AI Workbench están obsoletos. El 14 de abril del 2025, se dejó de ofrecer asistencia para los cuadernos gestionados y se eliminó la posibilidad de crear instancias de cuadernos gestionados. Las instancias actuales seguirán funcionando hasta el 30 de marzo del 2026, pero no habrá parches, actualizaciones ni mejoras disponibles. Para seguir usando Vertex AI Workbench, te recomendamos que migres tus instancias de cuadernos gestionados a instancias de Vertex AI Workbench.

En esta página se explica cómo añadir un contenedor personalizado a una instancia de notebooks gestionados de Vertex AI Workbench como kernel en el que puedes ejecutar tus archivos de cuaderno.

Información general

Puedes añadir un contenedor personalizado para usarlo con tu instancia de cuadernos gestionados. El contenedor personalizado estará disponible como kernel local en el que podrás ejecutar tu archivo de cuaderno.

Requisitos de los contenedores personalizados

Los cuadernos gestionados de Vertex AI Workbench admiten cualquiera de las imágenes de contenedor de contenedores de aprendizaje profundo actuales.

Para crear tu propia imagen de contenedor personalizada, puedes modificar una de las imágenes de contenedor de Deep Learning Containers para crear una imagen de contenedor derivada.

Para crear una imagen de contenedor personalizada desde cero, asegúrate de que la imagen de contenedor cumpla los siguientes requisitos:

• Usa una imagen de contenedor Docker con al menos una especificación de kernel de Jupyter válida. Este archivo kernelspec expuesto permite que los cuadernos gestionados de Vertex AI Workbench carguen la imagen del contenedor como un kernel. Si tu imagen de contenedor incluye una instalación de JupyterLab o Jupyter Notebook, la instalación incluirá el archivo kernelspec de forma predeterminada. Si la imagen de tu contenedor no tiene el archivo kernelspec, puedes instalarlo directamente.

  Nota: Si tu contenedor tiene un archivo kernelspec de Jupyter válido, responderá a jupyter kernelspec list --json con una lista de archivos kernelspec disponibles.

• La imagen del contenedor Docker debe admitir sleep infinity.

• Para usar tu contenedor personalizado con el ejecutor de notebooks gestionados, asegúrate de que tu contenedor personalizado tenga la extensión nbexecutor.

Nota: Las imágenes de contenedor de Deep Learning Containers incluyen un archivo kernelspec de Jupyter válido y la extensión nbexecutor de forma predeterminada.

El siguiente texto de Dockerfile crea una imagen Docker personalizada desde cero basada en una imagen de Ubuntu e incluye la versión más reciente de Python.

FROM --platform=linux/amd64 ubuntu:22.04

RUN apt-get -y update
RUN apt-get install -y --no-install-recommends \
python3-pip \
pipx \
git \
make \
jq

RUN pip install \
argcomplete>=1.9.4 \
poetry==1.1.14 \
jupyterlab==3.3.0

# Create a link that points to the right python bin directory
RUN ln -s /usr/bin/pythonVERSION_NUMBER /usr/bin/python

Sustituye VERSION_NUMBER por la versión de Python que estés usando.

Cómo se convierte un contenedor personalizado en un kernel en cuadernos gestionados

Por cada imagen de contenedor personalizada que proporciones, tu instancia de notebooks gestionados identificará la especificación de kernel de Jupyter disponible en la imagen de contenedor cuando se inicie la instancia. El kernelspec aparece como un kernel local en la interfaz de JupyterLab. Cuando se selecciona el archivo kernelspec, el gestor de kernels de los cuadernos gestionados ejecuta el contenedor personalizado como un kernel e inicia una sesión de Jupyter en ese kernel.

Cómo se actualizan los kernels de contenedores personalizados

Vertex AI Workbench extrae la imagen de contenedor más reciente de tu kernel:

• Cuando creas tu instancia.

• Cuando actualices tu instancia.

• Cuando inicies la instancia.

El kernel del contenedor personalizado no se conserva cuando se detiene la instancia, por lo que, cada vez que se inicia, Vertex AI Workbench extrae la versión más reciente de la imagen del contenedor.

Si tu instancia está en ejecución cuando se lanza una nueva versión de un contenedor, el kernel de tu instancia no se actualizará hasta que detengas y vuelvas a iniciar la instancia.

Disponibilidad de imágenes de contenedor personalizadas

Las imágenes de contenedor de Deep Learning Containers están disponibles para todos los usuarios. Cuando usas una imagen de contenedor de Deep Learning Containers, debes conceder roles específicos a la cuenta de servicio de tu instancia para que pueda cargar la imagen de contenedor de Deep Learning Containers como kernel. Consulta más información sobre los permisos necesarios y cómo concederlos en la sección Permisos.

Si quieres usar tu propia imagen de contenedor personalizada, debe estar ubicada en Artifact Registry y debe ser de acceso público.

Antes de empezar

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.

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Notebooks and Artifact Registry APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Notebooks and Artifact Registry APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Añadir un contenedor personalizado al crear una instancia

Para añadir un contenedor personalizado a una instancia de notebooks gestionados, la imagen del contenedor personalizado debe especificarse al crear la instancia.

Para añadir un contenedor personalizado al crear una instancia de cuadernos gestionados, sigue estos pasos.

1. En la Google Cloud consola, ve a la página Notebooks gestionados.

   Ir a Cuadernos gestionados

2. Haz clic en  Crear.

3. En el campo Name (Nombre), introduce un nombre para la instancia.

4. Haz clic en la lista Región y selecciona una región para tu instancia.

5. En la sección Entorno, selecciona Proporcionar imágenes Docker personalizadas.

6. Añade una imagen de contenedor de Docker de una de las siguientes formas:

   • Introduce la ruta de una imagen de contenedor Docker. Por ejemplo, para usar una imagen de contenedor de TensorFlow 2.12 con aceleradores de Deep Learning Containers, introduce us-docker.pkg.dev/deeplearning-platform-release/gcr.io/tf-cpu.2-12.py310.
   • Haga clic en Seleccionar para añadir una imagen de contenedor Docker de Artifact Registry. A continuación, en la pestaña Artifact Registry donde se almacena la imagen de contenedor, cambia el proyecto al proyecto que incluye la imagen de contenedor y selecciona la imagen de contenedor.

7. Completa el resto del cuadro de diálogo Crear instancia según tus necesidades.

8. Haz clic en Crear.

9. Vertex AI Workbench inicia la instancia automáticamente. Cuando la instancia esté lista para usarse, Vertex AI Workbench activará un enlace Abrir JupyterLab.

Conceder permisos a imágenes de contenedor de Deep Learning Containers

Si no usas una imagen de contenedor de Deep Learning Containers, salta esta sección.

Para asegurarte de que la cuenta de servicio de tu instancia tiene los permisos necesarios para cargar una imagen de contenedor de Deep Learning Containers desde Artifact Registry, pide a tu administrador que conceda a la cuenta de servicio de tu instancia los siguientes roles de gestión de identidades y accesos en tu instancia:

Importante: Debes asignar estos roles a la cuenta de servicio de tu instancia, no a tu cuenta de usuario. Si no se conceden los roles a la entidad correcta, pueden producirse errores de permisos.
• Administrador de instancias de Compute (v. 1) (roles/compute.instanceAdmin.v1)
• Lector de Artifact Registry (roles/artifactregistry.reader)

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

Es posible que tu administrador también pueda conceder a la cuenta de servicio de tu instancia los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Configurar un archivo de cuaderno para que se ejecute en tu contenedor personalizado

Para abrir JupyterLab, crea un archivo de cuaderno y configúralo para que se ejecute en el kernel de tu contenedor personalizado. Para ello, sigue estos pasos.

1. Junto al nombre de la instancia de cuadernos gestionados, haz clic en Abrir JupyterLab.

2. En el cuadro de diálogo Autentica tu cuaderno gestionado, haz clic en el botón para obtener un código de autenticación.

3. Elige una cuenta y haz clic en Permitir. Copia el código de autenticación.

4. En el cuadro de diálogo Autentica tu cuaderno gestionado, pega el código de autenticación y haz clic en Autenticar.

   Tu instancia de cuadernos gestionados abre JupyterLab.

5. Selecciona Archivo > Nuevo > Cuaderno.

6. En el cuadro de diálogo Seleccionar kernel, selecciona el kernel de la imagen de contenedor personalizada que quieras usar y, a continuación, haz clic en Seleccionar. Las imágenes de contenedor de mayor tamaño pueden tardar un tiempo en aparecer como kernel. Si el kernel que quieres no aparece, vuelve a intentarlo dentro de unos minutos. Puedes cambiar el kernel cuando quieras ejecutar tu archivo de cuaderno en otro kernel.

   Se abrirá el archivo del nuevo cuaderno.

Siguientes pasos

• Consulta cómo acceder a los grupos y archivos de Cloud Storage desde JupyterLab.

• Consulta cómo consultar datos de tablas de BigQuery desde JupyterLab.