Fazer upgrade do ambiente de uma instância de notebooks gerenciada pelo usuário

Fazer upgrade do ambiente de uma instância de notebooks gerenciada pelo usuário

Os notebooks gerenciados pelo usuário do Vertex AI Workbench foram descontinuados. Em 30 de janeiro de 2025, o suporte a notebooks gerenciados pelo usuário será encerrado, e não será mais possível criar instâncias de notebooks gerenciados pelo usuário. As instâncias que já existem continuarão funcionando, mas patches, atualizações e upgrades não estarão disponíveis. Para continuar usando o Vertex AI Workbench, recomendamos que você migre suas instâncias de notebooks gerenciados pelo usuário para instâncias do Vertex AI Workbench.

As instâncias de notebooks gerenciados pelo usuário do Vertex AI Workbench são instâncias de Deep Learning VM Images com ambientes de notebook do JupyterLab ativados e prontos para uso. Nesta página, descrevemos como fazer upgrade do ambiente de uma instância de notebooks gerenciada pelo usuário.

Motivos do upgrade

É possível fazer upgrade do ambiente da instância de notebooks gerenciados pelo usuário por um dos seguintes motivos:

• Para usar os novos recursos que estão disponíveis apenas em uma versão mais recente do ambiente.

• Para aproveitar as atualizações de framework e de pacote, além de correções de bugs que foram implementadas em uma versão mais recente do ambiente.

Métodos de upgrade

Há duas maneiras de fazer upgrade de uma instância de notebooks gerenciados pelo usuário:

• Upgrade automático: ative o upgrade automático ao criar uma instância de notebooks gerenciada pelo usuário. Durante um período recorrente especificado, o Vertex AI Workbench verificará se é possível fazer upgrade da instância. Em caso afirmativo, o Vertex AI Workbench fará o upgrade da instância.

• Upgrade manual: será possível fazer o upgrade manual de uma instância atual de notebooks gerenciados pelo usuário que atender aos requisitos.

Requisitos e limitações

Não há garantia de compatibilidade com versões anteriores dos seus notebooks gerenciados pelo usuário. Faça uma cópia dos seus dados antes de fazer upgrade de uma instância de notebooks gerenciados.

Para determinar se é possível fazer upgrade de uma instância específica de notebooks gerenciada pelo usuário, consulte os seguintes requisitos e limitações:

• A API Notebooks precisa ser ativada no projeto do Google Cloud da instância. Para mais informações, consulte Listar serviços ativados e Ativar uma API.

• A versão do ambiente da instância de notebooks gerenciados pelo usuário precisa ser M54 ou superior.

• A instância de notebooks gerenciados pelo usuário precisa ter sido criada com a API Notebooks ou registrada com a API Notebooks.

• Se a instância de notebooks gerenciada pelo usuário for baseada em contêiner, o Vertex AI Workbench fará upgrade do SO. A versão da imagem depende da imagem específica extraída pelo Dockerfile.

  Para garantir que o upgrade use a versão mais recente da imagem, use a tag latest no Dockerfile.

Se o upgrade da instância não for uma opção para você, considere migrar seus dados para uma nova instância de notebooks gerenciados pelo usuário.

Como o upgrade funciona

As instâncias de notebooks gerenciados pelo usuário que podem ser atualizadas são discos duplos, com um disco de inicialização e um disco de dados. O processo de upgrade atualiza o disco de inicialização para uma nova imagem e preserva seus dados no disco.

Quais componentes são atualizados ou preservados?

A tabela a seguir mostra quais componentes da instância de notebooks gerenciados pelo usuário são atualizados e quais são preservados.

Componente	Resultado do upgrade
Frameworks de machine learning	Com upgrade
Dados de machine learning	Preservado
Dependências pré-instaladas	Upgrade concluído
Bibliotecas instaladas pelo usuário	Por padrão, precisa ser reinstalado (consulte Bibliotecas instaladas pelo usuário)
Arquivos locais no diretório /home/jupyter	Preservado
Arquivos locais em qualquer outro diretório /home/	Não preservado.
Pacotes de sistema operacional pré-instalados	Com upgrade
Pacotes de sistema operacional instalados pelo usuário	Não preservado.
Drivers de GPU	Com upgrade
Notebooks	Preservado
Configurações do usuário	Preservado

Bibliotecas instaladas pelo usuário

Por padrão, as instâncias de notebooks gerenciados pelo usuário armazenam bibliotecas pip e Conda no disco de inicialização, que é substituído durante um upgrade. Ao instalar bibliotecas pip, é possível incluir a sinalização --user para instalá-las no diretório /home/jupyter/, em que elas são preservadas durante um upgrade.

Por padrão, se você instalar bibliotecas pip ou Conda em um kernel criado a partir de um contêiner personalizado, as bibliotecas só persistirão enquanto o kernel estiver em execução. Sempre que o kernel for reiniciado, essas bibliotecas precisarão ser reinstaladas. Para instalar bibliotecas permanentes em um contêiner personalizado, inclua as instalações da biblioteca no Dockerfile. Ao instalar bibliotecas pip em um kernel criado a partir de um contêiner personalizado, é possível incluir a sinalização --user para que as bibliotecas persistam até a reinicialização da instância.

Versões do ambiente

O Vertex AI Workbench atualiza os ambientes regularmente. Consulte as notas da versão da VM de aprendizado profundo (em inglês), mas a cada versão lançada, nem todos os ambientes são atualizados. O Vertex AI Workbench só faz upgrade de uma instância se houver uma versão de ambiente mais recente para a imagem de VM em que a instância é baseada.

Para informações sobre como usar uma versão específica para criar uma instância de notebooks gerenciados pelo usuário, consulte Criar uma versão específica de uma instância de notebooks gerenciados pelo usuário.

Antes da atualização

Antes de fazer upgrade, siga estas etapas.

1. Consulte asnotas da versão para ver as mudanças das novas versões.

2. Faça uma cópia dos dados como backup.

Upgrade automático

O Vertex AI Workbench pode fazer upgrade automaticamente das instâncias que estiverem em execução. Se a instância estiver interrompida, o upgrade não será feito automaticamente, mesmo que você tenha ativado o upgrade automático ao criá-la.

Ao ativar upgrades automáticos do ambiente, você especifica um período recorrente em que o Vertex AI Workbench verifica se a instância pode ser atualizada e, se puder, faz upgrade da instância.

O período especificado é armazenado como uma entrada de metadados notebook-upgrade-schedule, no formato unix-cron, Horário do Meridiano de Greenwich (GMT)

Para verificar se é possível fazer upgrade de uma instância, o Vertex AI Workbench usa o método de API isUpgradeable. Esse método verifica se há uma versão mais recente da imagem no disco de inicialização da instância.

Se for possível fazer upgrade da instância, o Vertex AI Workbench usará um método de upgrade interno para fazer upgrade.

Criar uma instância de notebooks gerenciada pelo usuário com o upgrade automático ativado

Para criar uma instância de notebooks gerenciados pelo usuário com o upgrade automático ativado, marque a caixa de seleção Ativar upgrade automático do ambiente e defina uma programação ao criar a instância.

É possível especificar o upgrade automático usando o console do Google Cloud ou a Google Cloud CLI.

Antes de começar

Antes de criar uma instância de notebooks gerenciados pelo usuário, é necessário ter um projeto do Google Cloud e ativar a API Notebooks para esse projeto.

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.

   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

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

4. Enable the Notebooks API.

   Enable the API

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

   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

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

7. Enable the Notebooks API.

   Enable the API

8. Se você planeja usar GPUs com a instância de notebooks gerenciada pelo usuário, consulte a página de cotas no Console do Google Cloud para garantir que há GPUs suficientes disponíveis no seu projeto. Se as GPUs não estiverem listadas nessa página ou se você precisar de mais cotas, solicite um aumento de cota. Consulte Como solicitar um aumento na cota na página Cotas de recursos do Compute Engine.

Funções exigidas

Caso tenha criado o projeto, você terá o papel do IAM de Proprietário (roles/owner) no projeto, que inclui todas as permissões necessárias. Pule esta seção e comece a criar sua instância de notebooks gerenciados pelo usuário. Se você não criou o projeto, continue nesta seção.

Para garantir que sua conta de usuário tenha as permissões necessárias para criar uma instância de notebooks gerenciados pelo usuário do Vertex AI Workbench, peça ao administrador para conceder à sua conta de usuário os seguintes papéis do IAM no projeto:

• Administrador de notebooks (roles/notebooks.admin)
• Usuário da conta de serviço (roles/iam.serviceAccountUser)

Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

O administrador também pode conceder à sua conta de usuário as permissões necessárias via papéis personalizados ou outros papéis predefinidos.

Criar instância

Console

1. No Console do Google Cloud, acesse a página Notebooks gerenciados pelo usuário. Ou acesse notebook.new (https://notebook.new) e pule a próxima etapa.

   Acesse Notebooks gerenciados pelo usuário

2. Clique em  Novo notebook e, em seguida, selecione Personalizar.

3. Na página Criar um notebook gerenciado pelo usuário, na seção Detalhes, forneça as seguintes informações para a nova instância:

   • Nome da instância: forneça um nome para a nova instância.
   • Região e Zona: selecione uma região e zona para a nova instância. Para ter o melhor desempenho de rede, selecione a região mais próxima de você. Consulte os locais de notebooks gerenciados pelo usuário disponíveis.

4. Na seção Integridade do sistema, selecione Upgrade automático do ambiente.

5. Escolha se você quer fazer upgrade do notebook semanal ou mensal.

6. No campo Weekday, selecione a opção que você quer.

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

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

gcloud

1. No Cloud Shell ou em qualquer ambiente em que a Google Cloud CLI esteja instalada, insira os comandos da Google Cloud CLI a seguir.

   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:

   • INSTANCE_NAME: o nome da nova instância.
   • SCHEDULE: a programação semanal ou mensal definida por você, no formato unix-cron. Por exemplo, "00 19 * * MON" significa semanalmente na segunda-feira, em 1900 horas, Horário de Greenwich (GMT)
   • VM_IMAGE_FAMILY: o nome da família de imagens que você quer usar para criar sua instância
   • MACHINE_TYPE: o tipo de máquina da VM da instância
   • LOCATION: o local do Google Cloud em que você quer que a nova instância fique

2. Acesse sua instância no Console do Google Cloud.

Editar a programação do upgrade automático

Para editar a programação de upgrade automático após a criação da instância de notebooks gerenciados pelo usuário, conclua as seguintes etapas:

1. No Console do Google Cloud, acesse a página Notebooks gerenciados pelo usuário.

   Acesse Notebooks gerenciados pelo usuário

2. Clique no nome da instância que precisa ser alterada.

3. Na página Detalhes da instância, na seção Upgrade automático do ambiente, edite a programação.

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

Upgrade manual

É possível fazer upgrade manual das instâncias de notebooks gerenciados pelo usuário que atendem aos requisitos.

Verificar se há uma versão mais recente do ambiente da instância

Para verificar se uma versão mais recente do ambiente da instância está disponível, acesse a instância no console do Google Cloud.

1. No Console do Google Cloud, acesse a página Notebooks gerenciados pelo usuário.

   Acesse Notebooks gerenciados pelo usuário

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

3. Clique no nome da instância que você quer verificar a disponibilidade de uma versão mais recente do ambiente.

4. Na página Detalhes da instância, ao lado de Detalhes da VM, clique em Ver no Compute Engine.

   Se uma versão mais recente do ambiente estiver disponível, a mensagem "Esta instância precisa de upgrade" será exibida.

Fazer upgrade do ambiente da instância para uma versão mais recente

É possível fazer upgrade manual de uma instância de notebooks gerenciados pelo usuário no console do Google Cloud ou usando a CLI do Google Cloud.

Observação: os upgrades podem afetar as operações do usuário em execução.

Console

1. No Console do Google Cloud, acesse a página Notebooks gerenciados pelo usuário.

   Acesse Notebooks gerenciados pelo usuário

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

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

4. Na página Detalhes do Notebook, clique em  Fazer upgrade.

5. Verifique se você fez uma cópia dos dados na instância antes de continuar.

6. Após o backup dos dados, clique em Fazer upgrade. O Vertex AI Workbench faz upgrade e inicia sua instância.

gcloud

1. Para verificar se é possível fazer upgrade de uma instância, use o método de API isUpgradeable. Esse método verifica se há uma versão mais recente da imagem no disco de inicialização da instância.

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

   Substitua:

   • INSTANCE_NAME: o nome da instância.
   • LOCATION: a região do Google Cloud em que a instância está localizada.

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

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

3. Verifique se você fez uma cópia dos dados na instância antes de continuar.

4. Se a instância puder ser atualizada, use o método da API upgrade para fazer upgrade da instância:

   gcloud notebooks instances upgrade INSTANCE_NAME \
       --location=LOCATION
   

   O Vertex AI Workbench faz upgrade da instância.

Reverter um upgrade

Para reverter um upgrade, siga estas etapas:

1. No Console do Google Cloud, acesse a página Notebooks gerenciados pelo usuário.

   Acesse Notebooks gerenciados pelo usuário

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

3. Na página Detalhes do notebook, em Histórico de upgrade, clique em Reverter.

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