Crie uma instância de blocos de notas geridos com um contentor personalizado

Crie uma instância de blocos de notas geridos com um contentor personalizado

Os blocos de notas geridos do Vertex AI Workbench foram descontinuados. A 14 de abril de 2025, o apoio técnico dos blocos de notas geridos terminou e a capacidade de criar instâncias de blocos de notas geridos foi removida. As instâncias existentes vão continuar a funcionar até 30 de março de 2026, mas os patches, as atualizações e as atualizações não vão estar disponíveis. Para continuar a usar o Vertex AI Workbench, recomendamos que migre as suas instâncias de notebooks geridos para instâncias do Vertex AI Workbench.

Esta página mostra como adicionar um contentor personalizado a uma instância de blocos de notas geridos do Vertex AI Workbench como um kernel no qual pode executar os seus ficheiros de blocos de notas.

Vista geral

Pode adicionar um contentor personalizado para utilização com a sua instância de blocos de notas geridos. O contentor personalizado fica disponível como um kernel local que pode executar no seu ficheiro de bloco de notas.

Requisitos de contentores personalizados

Os blocos de notas geridos do Vertex AI Workbench suportam qualquer uma das atuais imagens de contentores dos Deep Learning Containers.

Para criar uma imagem de contentor personalizada, pode modificar uma das imagens de contentor dos Deep Learning Containers para criar uma imagem de contentor derivada.

Para criar uma imagem de contentor personalizada de raiz, certifique-se de que a imagem de contentor cumpre os seguintes requisitos:

• Use uma imagem de contentor do Docker com, pelo menos, uma especificação do kernel do Jupyter válida. Esta especificação do kernel exposta permite que os Vertex AI Workbench managed notebooks carreguem a imagem do contentor como um kernel. Se a sua imagem de contentor incluir uma instalação do JupyterLab ou do Jupyter Notebook, a instalação inclui o kernelspec por predefinição. Se a imagem do contentor não tiver o kernelspec, pode instalar o kernelspec diretamente.

  Nota: se o seu contentor tiver um kernelspec Jupyter válido, responde a jupyter kernelspec list --json com uma lista de kernelspecs disponíveis.

• A imagem do contentor Docker tem de ser compatível com sleep infinity.

• Para usar o seu contentor personalizado com o executor de blocos de notas geridos, certifique-se de que o contentor personalizado tem a extensão nbexecutor.

Nota: as imagens de contentores Deep Learning Containers incluem uma especificação do kernel Jupyter válida e a extensão nbexecutor por predefinição.

O texto do Dockerfile de exemplo seguinte cria uma imagem de Docker personalizada a partir do zero com base numa imagem do Ubuntu e inclui a versão mais recente do 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

Substitua VERSION_NUMBER pela versão do Python que está a usar.

Como um contentor personalizado se torna um kernel em notebooks geridos

Para cada imagem de contentor personalizada fornecida, a instância de blocos de notas geridos identifica o kernelspec do Jupyter disponível na imagem de contentor quando a instância é iniciada. O kernelspec aparece como um kernel local na interface do JupyterLab. Quando a especificação do kernel é selecionada, o gestor de kernels dos blocos de notas geridos executa o contentor personalizado como um kernel e inicia uma sessão do Jupyter nesse kernel.

Como são atualizados os kernels de contentores personalizados

O Vertex AI Workbench extrai a imagem do contentor mais recente para o seu kernel:

• Quando cria a instância.

• Quando atualiza a sua instância.

• Quando inicia a instância.

O kernel do contentor personalizado não persiste quando a instância é interrompida. Por isso, sempre que a instância é iniciada, o Vertex AI Workbench extrai a versão mais recente da imagem do contentor.

Se a sua instância estiver em execução quando for lançada uma nova versão de um contentor, o kernel da instância não é atualizado até parar e iniciar a instância.

Disponibilidade de imagens de contentores personalizadas

As imagens de contentores do Deep Learning Containers estão disponíveis para todos os utilizadores. Quando usa uma imagem de contentor dos Deep Learning Containers, tem de conceder funções específicas à conta de serviço da sua instância para que a instância possa carregar a imagem de contentor dos Deep Learning Containers como um kernel. Saiba mais sobre as autorizações necessárias e como concedê-las na secção Autorizações.

Se quiser usar a sua própria imagem de contentor personalizada, tem de estar localizada no Artifact Registry e a imagem de contentor tem de estar disponível publicamente.

Antes de começar

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

Adicione um contentor personalizado ao criar uma instância

Para adicionar um contentor personalizado a uma instância de blocos de notas geridos, a imagem do contentor personalizado tem de ser especificada na criação da instância.

Para adicionar um contentor personalizado enquanto cria uma instância de blocos de notas geridos, conclua os seguintes passos.

1. Na Google Cloud consola, aceda à página Blocos de notas geridos.

   Aceda a notebooks geridos

2. Clique em  Criar novo.

3. No campo Nome, introduza um nome para a instância.

4. Clique na lista Região e selecione uma região para a sua instância.

5. Na secção Ambiente, selecione Facultar imagens Docker personalizadas.

6. Adicione uma imagem de contentor Docker de uma das seguintes formas:

   • Introduza um caminho de imagem de contentor do Docker. Por exemplo, para usar uma imagem de contentor do TensorFlow 2.12 com aceleradores dos Deep Learning Containers, introduza us-docker.pkg.dev/deeplearning-platform-release/gcr.io/tf-cpu.2-12.py310.
   • Clique em Selecionar para adicionar uma imagem de contentor Docker do Artifact Registry. Em seguida, no separador Artifact Registry, onde a imagem de contentor está armazenada, altere o projeto para o projeto que inclui a imagem de contentor e selecione a imagem de contentor.

7. Conclua o resto da caixa de diálogo Criar instância de acordo com as suas necessidades.

8. Clique em Criar.

9. O Vertex AI Workbench inicia automaticamente a instância. Quando a instância está pronta a usar, o Vertex AI Workbench ativa um link Abrir JupyterLab.

Conceda autorizações a imagens de contentores do Deep Learning Containers

Se não estiver a usar uma imagem de contentor do Deep Learning Containers, ignore esta secção.

Para garantir que a conta de serviço da sua instância tem as autorizações necessárias para carregar uma imagem de contentor do Deep Learning Containers a partir do Artifact Registry, peça ao seu administrador para conceder à conta de serviço da sua instância as seguintes funções do IAM na sua instância:

Importante: tem de conceder estas funções à conta de serviço da sua instância e não à sua conta de utilizador. Se não conceder as funções ao principal correto, podem ocorrer erros de autorização.
• Administrador de instâncias do Compute (v1) (roles/compute.instanceAdmin.v1)
• Leitor do Artifact Registry (roles/artifactregistry.reader)

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

O administrador também pode conceder à conta de serviço da sua instância as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Configure um ficheiro de notebook para ser executado no seu contentor personalizado

Para abrir o JupyterLab, criar um novo ficheiro de notebook e configurá-lo para ser executado no kernel do seu contentor personalizado, conclua os seguintes passos.

1. Junto ao nome da instância de blocos de notas geridos, clique em Abrir JupyterLab.

2. Na caixa de diálogo Autentique o seu bloco de notas gerido, clique no botão para receber um código de autenticação.

3. Escolha uma conta e clique em Permitir. Copie o código de autenticação.

4. Na caixa de diálogo Autentique o seu bloco de notas gerido, cole o código de autenticação e, de seguida, clique em Autenticar.

   A sua instância de blocos de notas geridos abre o JupyterLab.

5. Selecione Ficheiro > Novo > Bloco de notas.

6. Na caixa de diálogo Selecionar kernel, selecione o kernel para a imagem do contentor personalizada que quer usar e, de seguida, clique em Selecionar. As imagens de contentores maiores podem demorar algum tempo a aparecer como um kernel. Se o kernel que quer ainda não estiver disponível, tente novamente dentro de alguns minutos. Pode alterar o kernel sempre que quiser executar o ficheiro de bloco de notas num kernel diferente.

   O novo ficheiro do bloco de notas é aberto.

O que se segue?

• Saiba como aceder a contentores e ficheiros do Cloud Storage a partir do JupyterLab.

• Saiba como consultar dados em tabelas do BigQuery a partir do JupyterLab.