Atualize o ambiente de uma instância de notebooks geridos pelo utilizador

Atualize o ambiente de uma instância de notebooks geridos pelo utilizador

Os blocos de notas geridos pelo utilizador do Vertex AI Workbench estão descontinuados. A 14 de abril de 2025, o apoio técnico para os blocos de notas geridos pelo utilizador terminou e a capacidade de criar instâncias de blocos de notas geridos pelo utilizador 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 blocos de notas geridos pelo utilizador para instâncias do Vertex AI Workbench.

As instâncias de blocos de notas geridos pelo utilizador do Vertex AI Workbench são instâncias de imagens de VMs de aprendizagem avançada com ambientes de blocos de notas do JupyterLab ativados e prontos a usar. Esta página descreve como atualizar o ambiente de uma instância de blocos de notas gerida pelo utilizador.

Motivos para atualizar

Pode querer atualizar o ambiente da instância de blocos de notas geridos pelo utilizador por qualquer um dos seguintes motivos:

• Para usar novas capacidades que só estão disponíveis numa versão mais recente do seu ambiente.

• Para beneficiar das atualizações da framework, das atualizações de pacotes e das correções de erros que foram implementadas numa versão mais recente do seu ambiente.

Métodos de atualização

Existem duas formas de atualizar uma instância de blocos de notas gerida pelo utilizador:

• Atualização automática: ative a atualização automática quando criar uma instância de blocos de notas geridos pelo utilizador. Durante um período recorrente especificado, o Vertex AI Workbench verifica se a sua instância pode ser atualizada e, em caso afirmativo, atualiza-a.

• Atualização manual: se uma instância de notebooks gerida pelo utilizador existente cumprir os requisitos para a atualização, pode atualizar a instância manualmente.

Requisitos e limitações

A retrocompatibilidade com os seus blocos de notas geridos pelo utilizador não é garantida. Crie uma cópia dos seus dados antes de atualizar uma instância de blocos de notas gerida pelo utilizador.

Para determinar se pode atualizar uma instância de notebooks gerida pelo utilizador específica, consulte os seguintes requisitos e limitações:

• A API Notebooks tem de estar ativada no projetoGoogle Cloud da instância. Para mais informações, consulte os artigos Liste os serviços ativados e Ative uma API.

• A versão do ambiente da instância de blocos de notas gerida pelo utilizador tem de ser M54 ou superior.

• A instância de blocos de notas gerida pelo utilizador tem de ter sido criada através da API Notebooks ou tem de ter sido registada na API Notebooks.

• Se a sua instância de blocos de notas geridos pelo utilizador for baseada em contentores, o Vertex AI Workbench atualiza o SO. A versão da imagem depende da imagem específica extraída pelo seu Dockerfile.

  Para ajudar a garantir que a atualização usa a versão mais recente da imagem, considere usar a etiqueta latest no seu Dockerfile.

Se a atualização da sua instância não for uma opção para si, considere migrar os seus dados para uma nova instância de blocos de notas gerida pelo utilizador.

Como funciona a atualização

As instâncias de blocos de notas geridas pelo utilizador que podem ser atualizadas são de disco duplo, com um disco de arranque e um disco de dados. O processo de atualização atualiza o disco de arranque para uma nova imagem, ao mesmo tempo que preserva os seus dados no disco de dados.

Que componentes são atualizados ou preservados?

A tabela seguinte mostra os componentes da instância dos blocos de notas geridos pelo utilizador que são atualizados e os que são preservados.

Componente	Resultado da atualização
Frameworks de aprendizagem automática	Atualizado
Dados de aprendizagem automática	Preservados
Dependências pré-instaladas	Atualizado
Bibliotecas instaladas pelo utilizador	Por predefinição, tem de ser reinstalada (consulte Bibliotecas instaladas pelo utilizador)
Ficheiros locais no diretório /home/jupyter	Preservados
Ficheiros locais em qualquer outro diretório /home/	Não preservado
Pacotes de sistemas operativos pré-instalados	Atualizado
Pacotes de sistemas operativos instalados pelo utilizador	Não preservado
Controladores da GPU	Atualizado
Blocos de notas	Preservados
Configurações do utilizador	Preservados

Bibliotecas instaladas pelo utilizador

Por predefinição, as instâncias de blocos de notas geridas pelo utilizador armazenam bibliotecas pip e Conda no disco de arranque, que é substituído durante uma atualização. Quando instala bibliotecas pip, pode incluir a flag --user para as instalar no diretório /home/jupyter/, onde são preservadas durante uma atualização.

Por predefinição, se instalar bibliotecas pip ou Conda num kernel criado a partir de um contentor personalizado, as bibliotecas só persistem enquanto o kernel estiver em execução. Sempre que o kernel é reiniciado, essas bibliotecas têm de ser reinstaladas. Para instalar bibliotecas persistentes num contentor personalizado, inclua as instalações de bibliotecas no seu Dockerfile. Quando instala bibliotecas pip num kernel criado a partir de um contentor personalizado, pode incluir a flag --user para que as bibliotecas persistam até ao reinício da instância.

Versões do ambiente

O Vertex AI Workbench atualiza os ambientes regularmente (consulte as notas de lançamento da VM de aprendizagem profunda), mas, com cada versão lançada, nem todos os ambientes são atualizados. O Vertex AI Workbench só atualiza uma instância se existir uma versão do ambiente mais recente para a imagem de VM na qual a sua instância se baseia.

Para obter informações sobre como usar uma versão específica para criar uma instância de notebooks geridos pelo utilizador, consulte o artigo Crie uma versão específica de uma instância de notebooks geridos pelo utilizador.

Antes de atualizar

Antes de fazer a atualização, conclua os seguintes passos.

1. Consulte as notas de lançamento para saber mais sobre as atualizações para versões mais recentes.

2. Crie uma cópia dos seus dados como cópia de segurança.

Atualização automática

O Vertex AI Workbench pode atualizar automaticamente as instâncias em execução. Se a sua instância estiver parada, não é atualizada automaticamente, mesmo que tenha ativado a atualização automática quando a criou.

Quando ativa as atualizações automáticas do ambiente, especifica um período recorrente durante o qual o Vertex AI Workbench verifica se a instância pode ser atualizada e, se puder, atualiza-a.

O período especificado é armazenado como uma entrada de notebook-upgrade-schedulemetadados no formato unix-cron, Hora do Meridiano de Greenwich (GMT).

Para verificar se uma instância pode ser atualizada, o Vertex AI Workbench usa o método API isUpgradeable. Este método procura uma versão mais recente da imagem no disco de arranque da instância.

Se for possível atualizar a instância, o Vertex AI Workbench usa um método de atualização interno para atualizar a instância.

Crie uma instância de blocos de notas gerida pelo utilizador com a atualização automática ativada

Para criar uma instância de blocos de notas gerida pelo utilizador com a atualização automática ativada, selecione a caixa de verificação Ativar atualização automática do ambiente e defina um horário quando criar a instância.

Pode especificar a atualização automática através da Google Cloud consola ou da CLI do Google Cloud.

Antes de começar

Antes de poder criar uma instância de notebooks gerida pelo utilizador, tem de ter um Google Cloud projeto e ativar a API Notebooks para esse projeto.

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 API.

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 API

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 API.

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 API

1. Se planeia usar GPUs com a instância de blocos de notas geridos pelo utilizador, consulte a página de quotas na Google Cloud consola para garantir que tem GPUs suficientes disponíveis no seu projeto. Se as GPUs não forem apresentadas na página de quotas ou precisar de uma quota de GPUs adicional, pode pedir um aumento da quota. Consulte o artigo Pedir um aumento da quota na página Quotas de recursos do Compute Engine.

Funções necessárias

Se criou o projeto, tem a função de IAM de proprietário (roles/owner) no projeto, que inclui todas as autorizações necessárias. Ignore esta secção e comece a criar a sua instância de blocos de notas geridos pelo utilizador. Se não criou o projeto, continue nesta secção.

Para receber as autorizações de que precisa para criar uma instância do Vertex AI Workbench User Managed Notebooks, peça ao seu administrador para lhe conceder as seguintes funções de IAM no projeto:

• Administrador do Notebooks (roles/notebooks.admin)
• Utilizador da conta de serviço (roles/iam.serviceAccountUser)

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.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Crie a instância

Consola

1. Na Google Cloud consola, aceda à página Blocos de notas geridos pelo utilizador. Em alternativa, aceda a notebook.new (https://notebook.new) e ignore o passo seguinte.

   Aceda aos blocos de notas geridos pelo utilizador

2. Clique em  Novo bloco de notas e, de seguida, selecione Personalizar.

3. Na página Crie um bloco de notas gerido pelo utilizador, na secção Detalhes, faculte as seguintes informações para a sua nova instância:

   • Nome: um nome para a nova instância
   • Região e Zona: selecione uma região e uma zona para a nova instância. Para o melhor desempenho da rede, selecione a região geograficamente mais próxima de si. Consulte as localizações de blocos de notas geridos pelo utilizador disponíveis.

4. Na secção Estado do sistema, selecione Atualização automática do ambiente.

5. Escolha se quer atualizar o seu bloco de notas semanalmente ou mensalmente.

6. No campo Dia da semana, selecione a opção pretendida.

7. No campo Hora, escolha uma hora do dia.

8. Conclua o resto da caixa de diálogo de criação da instância e, de seguida, clique em Criar.

gcloud

1. A partir do Cloud Shell ou de qualquer ambiente onde a CLI do Google Cloud esteja instalada, introduza o seguinte comando da CLI do Google Cloud:

   gcloud notebooks instances create INSTANCE_NAME
       --metadata=notebook-upgrade-schedule=SCHEDULE
       --vm-image-project=deeplearning-platform-release
       --vm-image-family=VM_IMAGE_FAMILY
       --machine-type=MACHINE_TYPE
       --location=LOCATION
   

   Substitua o seguinte:

   • INSTANCE_NAME: o nome da nova instância
   • SCHEDULE: o agendamento semanal ou mensal que define no formato unix-cron; por exemplo, "00 19 * * MON" significa semanalmente na segunda-feira, às 19:00, hora de Greenwich (GMT)
   • VM_IMAGE_FAMILY: o nome da família de imagens que quer usar para criar a sua instância
   • MACHINE_TYPE: o tipo de máquina da VM da sua instância
   • LOCATION: a Google Cloud localização onde quer que a nova instância esteja

2. Aceda à sua instância a partir da Google Cloud consola.

Edite a programação da atualização automática

Para editar a programação da atualização automática depois de criar a instância de blocos de notas geridos pelo utilizador, conclua os seguintes passos:

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

   Aceda aos blocos de notas geridos pelo utilizador

2. Clique no nome da instância que precisa da alteração de horário.

3. Na página Detalhes do bloco de notas, na secção Atualização automática do ambiente, edite o horário.

4. Clique em Enviar para guardar as alterações.

Atualização manual

Pode atualizar manualmente as instâncias de blocos de notas geridas pelo utilizador que cumprem os requisitos.

Verifique se existe uma versão mais recente do ambiente da sua instância

Para verificar se está disponível uma versão mais recente do ambiente da sua instância, aceda à instância a partir da consola Google Cloud .

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

   Aceda aos blocos de notas geridos pelo utilizador

2. Se a instância não estiver em execução, inicie a instância. O Vertex AI Workbench só pode atualizar instâncias quando estão em execução.

3. Clique no nome da instância que quer verificar para saber se existe uma versão mais recente do ambiente.

4. Na página Detalhes do bloco de notas, junto a Detalhes da VM, clique em Ver no Compute Engine.

   Se estiver disponível uma versão mais recente do ambiente, é apresentada a mensagem "Esta instância tem de ser atualizada".

Atualize o ambiente da sua instância para uma versão mais recente

Pode atualizar manualmente uma instância de blocos de notas gerida pelo utilizador na Google Cloud consola ou através da Google Cloud CLI.

Nota: as atualizações podem afetar as operações do utilizador em execução.

Consola

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

   Aceda aos blocos de notas geridos pelo utilizador

2. Se a instância não estiver em execução, inicie a instância. O Vertex AI Workbench só pode atualizar instâncias quando estão em execução.

3. Clique no nome da instância que quer atualizar.

4. Na página Detalhes do bloco de notas, clique em  Atualizar.

5. Certifique-se de que fez uma cópia dos dados na sua instância antes de continuar.

6. Depois de fazer uma cópia de segurança dos dados, clique em Atualizar. O Vertex AI Workbench atualiza e inicia a sua instância.

gcloud

1. Para verificar se é possível atualizar uma instância, use o método da API isUpgradeable. Este método procura uma versão mais recente da imagem no disco de arranque da instância.

   gcloud notebooks instances is-upgradeable INSTANCE_NAME \
       --location=LOCATION
   

   Substitua o seguinte:

   • INSTANCE_NAME: o nome da sua instância
   • LOCATION: a localização Google Cloud onde a sua instância está localizada

   Se a instância for atualizável, a resposta é true. Se a resposta for false, não é possível atualizar a instância, mas ainda pode tentar migrar os seus dados para uma nova instância.

2. Se a instância não estiver em execução, inicie a instância. O Vertex AI Workbench só pode atualizar instâncias quando estão em execução.

3. Certifique-se de que fez uma cópia dos dados na sua instância antes de continuar.

4. Se a instância for atualizável, use o método da API upgrade para atualizar a instância:

   gcloud notebooks instances upgrade INSTANCE_NAME \
       --location=LOCATION
   

   O Vertex AI Workbench atualiza a instância.

Reverta uma atualização

Para reverter uma atualização, conclua os seguintes passos:

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

   Aceda aos blocos de notas geridos pelo utilizador

2. Clique no nome da instância que quer reverter.

3. Na página Detalhes do bloco de notas, em Histórico de atualizações, clique em Reverter.

4. O Vertex AI Workbench reverte a instância para a versão anterior.