Executar arquivos de notebook com o executor

Executar arquivos de notebook com o executor

Os notebooks gerenciados do Vertex AI Workbench foram descontinuados. Em 30 de janeiro de 2025, o suporte a notebooks gerenciados será encerrado, e não será mais possível criar instâncias de notebooks gerenciados. 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 para instâncias do Vertex AI Workbench.

Nesta página, descrevemos como usar o executor em uma instância de notebooks gerenciados do Vertex AI Workbench para executar arquivos de notebook como uma execução única e em uma programação.

Visão geral

O executor permite enviar um arquivo de notebook (ipynb) para ser executado no treinamento personalizado da Vertex AI (em inglês). É possível definir valores de parâmetro para cada execução de um arquivo de notebook. Também é possível executar um arquivo de notebook em uma programação recorrente. Após a conclusão da execução, você poderá ver os resultados da execução e compartilhá-los com outras pessoas.

Quando um arquivo de notebook é enviado ao treinamento personalizado da Vertex AI, a Vertex AI cria um novo job de treinamento personalizado que executa o arquivo de notebook após o ciclo de vida de um job de treinamento.

Requisitos para o código do notebook executado pelo executor

Ao escrever o código do notebook para ser executado no executor, lembre-se de que o código será executado em um projeto de locatário separado do projeto da instância de notebooks gerenciado. Esta seção descreve como isso afeta seu código quando ele é executado no executor.

Verificar se as instalações de pacote estão disponíveis para o executor

Se o notebook depender de instalações de pacotes ainda não incluídas no kernel de notebooks gerenciado que você está usando, verifique se os pacotes estão disponíveis para o código do notebook no executor de uma das seguintes maneiras:

• Use um contêiner personalizado que já tenha o pacote instalado e, em seguida, execute o notebook nesse contêiner personalizado. Consulte os requisitos para usar um contêiner personalizado com o executor.

• Instale o pacote no código do arquivo do notebook. O pacote é instalado sempre que o arquivo de notebook é executado, mas isso garante que o pacote esteja disponível no contêiner selecionado ao executar o notebook.

Usar a seleção explícita de projeto

Quando você acessa recursos por meio de código executado pelo executor, ele pode não se conectar ao projeto correto do Google Cloud. Se você encontrar erros de permissão, a conexão com o projeto errado pode ser o problema.

Esse problema ocorre porque o executor não executa seu código diretamente no projeto do Google Cloud da instância de notebooks gerenciado. Em vez disso, o executor executa seu código no treinamento personalizado da Vertex AI em um projeto de locatário gerenciado pelo Google. Portanto, não tente inferir um ID do projeto do ambiente no código do notebook. Especifique os IDs do projeto explicitamente.

Se você não quiser fixar um ID de projeto no código, consulte a variável de ambiente CLOUD_ML_PROJECT_ID. A Vertex AI define essa variável de ambiente em cada contêiner de treinamento personalizado para conter o número do projeto em que você iniciou o treinamento personalizado. Muitas ferramentas do Google Cloud aceitam um número de projeto sempre que recebem um ID do projeto.

Por exemplo, se você quiser acessar uma tabela do BigQuery no mesmo projeto usando o cliente Python para o Google BigQuery, não infira o projeto no código do notebook:

Seleção de projeto implícita

from google.cloud import bigquery

client = bigquery.Client()

Em vez disso, use um código que selecione explicitamente um projeto:

Seleção explícita do projeto

import os

from google.cloud import bigquery

project_number = os.environ["CLOUD_ML_PROJECT_ID"]

client = bigquery.Client(project=project_number)

Autenticar o acesso usando contas de serviço

Por padrão, sua instância de notebooks gerenciado pode ter acesso a recursos que existem no mesmo projeto. Portanto, quando você executa o código do arquivo do notebook manualmente, esses recursos não precisam de autenticação adicional. No entanto, como o executor é executado em um projeto de locatário separado, ele não tem o mesmo acesso padrão.

Além disso, o executor não pode usar credenciais de usuário final para autenticar o acesso a recursos, por exemplo, o comando gcloud auth login.

Para resolver esses problemas, autentique o acesso aos recursos por meio de uma conta de serviço no código do seu arquivo de notebook.

Em seguida, ao criar uma execução ou programação, especifique a conta de serviço.

Por exemplo, ao criar uma execução, conclua estas etapas:

1. Na caixa de diálogo Enviar notebooks ao executor, expanda Opções avançadas.

2. Na seção Identidade e acesso à API, desmarque a marca de seleção ao lado de Usar a conta de serviço padrão do Vertex AI Training e insira a conta de serviço específica a ser usada.

Veja a lista completa de etapas para criação de execução.

Requisitos para usar um contêiner personalizado

É possível usar o executor para executar o código do notebook em um contêiner personalizado. O contêiner personalizado precisa incluir a extensão nbexecutor, que permite que o executor execute o código do notebook como um job de treinamento personalizado da Vertex AI. Para garantir que o contêiner personalizado tenha a extensão nbexecutor, é possível modificar uma das imagens de contêiner de aprendizado profundo para criar uma imagem de contêiner derivada. As imagens de Deep Learning Containers incluem a extensão nbexecutor.

Antes de começar

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 and Vertex AI APIs.

   Enable the APIs

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 and Vertex AI APIs.

   Enable the APIs

8. Crie uma instância de notebook gerenciado se ainda não tiver feito isso.

Funções exigidas

Para garantir que a conta de serviço da instância tenha as permissões necessárias para interagir com o executor do Vertex AI Workbench, peça ao administrador para conceder a ela os seguintes papéis do IAM no projeto:

• Leitor do Notebooks (roles/notebooks.viewer)
• Usuário da Vertex AI (roles/aiplatform.user)
• Administrador do Storage (roles/storage.admin)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

O administrador também pode conceder à conta de serviço da instância as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Abrir JupyterLab

Para abrir o JupyterLab e preparar um arquivo de notebook para ser executado, conclua as etapas a seguir.

1. Abrir o JupyterLab.

2. Faça upload de um arquivo do notebook (ipynb), abra um atual ou abra um novo arquivo de notebook e adicione o código que você quer executar no notebook.

3. Verifique se o código do arquivo do notebook atende aos requisitos de uso do executor.

Criar execução

Para criar uma execução que execute o arquivo do notebook, conclua as etapas a seguir. Essas etapas abrangem a programação de execuções e a criação de uma execução única.

1. Na interface do usuário do JupyterLab da instância de notebooks gerenciados, abra o arquivo de notebook que você quer executar.

2. Clique no   botão Executar.

3. Na caixa de diálogo Enviar notebooks para o executor, insira um nome para a execução no campo Nome da execução.

4. Selecione um tipo de máquina e um tipo de acelerador.

5. Selecione um Ambiente.

6. No campo Tipo, selecione Execução única ou Execuções recorrentes baseadas em programação e complete a caixa de diálogo para programar execuções.

7. Em Opções avançadas, selecione a Região em que você quer executar o notebook.

8. No campo bucket do Cloud Storage, selecione um bucket disponível ou digite um nome para um novo bucket e clique em Criar e selecionar. O executor armazena a saída do notebook nesse bucket do Cloud Storage.

9. Opcional: Na seção Parametrização do notebook, na caixa de texto Parâmetros de entrada, adicione os parâmetros do notebook separados por vírgulas, por exemplo, optimizer="SGD",learning_rate=0.01.

   Saiba mais sobre como usar parâmetros de notebook.

10. Opcional: na seção Identidade e acesso à API, selecione Usar a conta de serviço padrão do Vertex AI Training ou desmarque a marca de seleção e insira uma conta de serviço específica a ser usada.

    Observação: se o código do arquivo de notebook autenticar o acesso aos serviços usando credenciais de usuário final ou acesso padrão no projeto da instância de notebooks gerenciado, consulte os requisitos para código de notebook executados pelo executor e considere especificar uma conta de serviço.

11. Opcional: na seção Rede, especifique uma rede de nuvem privada virtual. O uso de uma rede VPC para a execução requer uma conexão de acesso a serviços particulares.

12. Clique em Enviar.

    As execuções únicas começam imediatamente. As execuções programadas são executadas automaticamente de acordo com a programação que você definir.

    Observação: Se a instância de notebooks gerenciados estiver desligada, o executor ainda executará o arquivo de notebook na programação.

No console do Google Cloud, na página Vertex AI Workbench, é possível ver as execuções concluídas na guia Executions e veja suas programações na guia Programações.

Visualizar, compartilhar e importar um arquivo de notebook executado

Ao usar a interface do usuário do JupyterLab da instância de notebooks gerenciados, é possível visualizar a saída de um notebook executado, compartilhar os resultados com outras pessoas e importar o arquivo do notebook executado para o JupyterLab.

Ver os resultados da execução de um notebook

É possível ver os resultados da execução de um notebook no console do Google Cloud ou na interface do usuário do JupyterLab.

Console

1. No console do Google Cloud, acesse a página Vertex AI Workbench e clique na guia Executions.

   Acessar "Execuções"

2. Selecione a Região que contém seus resultados.

3. Ao lado da execução que você quer visualizar, clique em Ver resultado.

   O resultado é aberto em uma nova guia do navegador.

JupyterLab

1. No menu de navegação do JupyterLab, clique no botão  Executor do notebook.

2. Clique na guia Executions.

3. Na execução que você quer visualizar, clique em Ver resultado.

   O resultado é aberto em uma nova guia do navegador.

Compartilhar os resultados da execução de um notebook

Compartilhe os resultados da execução fornecendo acesso ao bucket do Cloud Storage que contém a execução do notebook. Fornecer esse acesso também concede aos usuários acesso a quaisquer outros recursos no mesmo bucket do Cloud Storage. Para compartilhar os resultados da execução, conclua as etapas a seguir.

Console

1. No console do Google Cloud, acesse a página Vertex AI Workbench e clique na guia Executions.

   Acessar "Execuções"

2. Selecione a Região que contém a execução.

3. Ao lado da execução que você quer compartilhar, clique no botão  Compartilhar.

4. Siga as instruções na caixa de diálogo para conceder aos usuários acesso ao bucket do Cloud Storage que contém a execução do notebook.

JupyterLab

1. Na interface do usuário do JupyterLab da instância de notebooks gerenciados, no menu de navegação, clique no botão  Executor de notebook.

2. Clique na guia Executions.

3. Ao lado da execução que você quer compartilhar, clique no menu de opções e selecione Compartilhar resultado da execução.

4. Siga as instruções na caixa de diálogo para conceder aos usuários acesso ao bucket do Cloud Storage que contém a execução do notebook.

Importar um notebook executado para o JupyterLab

Para importar um notebook executado no JupyterLab, siga as etapas a seguir.

1. Na interface do usuário do JupyterLab da instância de notebooks gerenciados, no menu de navegação, clique no botão  Executor de notebook.

2. Clique na guia Executions.

3. Selecione a Região que contém o notebook executado.

4. Ao lado da execução que você quer importar, clique no menu de opções e selecione Importar notebook executado.

5. Selecione o kernel em que você quer abrir o notebook.

   O executor abre o arquivo de notebook executado no JupyterLab e o armazena no navegador de arquivos do JupyterLab em uma pasta chamada imported_notebook_jobs.

Ver ou excluir uma programação

É possível visualizar e excluir programações usando o console do Google Cloud ou a interface de usuário do JupyterLab da instância de notebooks gerenciados.

Ver uma programação

Veja uma programação para ver as configurações de frequência dela ou para ver os resultados das execuções de notebook.

Console

1. No console do Google Cloud, acesse a página Workbench da Vertex AI e clique na guia Programações.

   Acessar "Programações"

2. Selecione a Região que contém a programação.

3. Clique no nome de uma programação para abrir a página Detalhes da programação.

4. Ao lado de um nome de execução, clique em Ver resultado para abrir o arquivo de notebook executado. O executor abre o resultado em uma nova guia do navegador.

JupyterLab

1. Na interface do usuário do JupyterLab da instância de notebooks gerenciados, no menu de navegação, clique no botão  Executor de notebook.

2. Clique na guia Programações.

3. Para ver a execução mais recente, na execução que você quer visualizar, clique em Visualizar o resultado mais recente de execução. O executor abre o resultado em uma nova guia do navegador.

   Para ver todas as execuções, clique no nome da programação. O executor abre a página Detalhes da programação no console do Google Cloud.

4. Ao lado de um nome de execução, clique em Ver resultado para abrir o arquivo de notebook executado. O executor abre o resultado em uma nova guia do navegador.

Excluir uma programação

A exclusão de uma programação não remove as execuções geradas a partir dela.

Console

1. No console do Google Cloud, acesse a página Workbench da Vertex AI e clique na guia Programações.

   Acessar "Programações"

2. Selecione a Região que contém a programação.

3. Selecione a programação que você quer excluir.

4. Clique Excluir.

JupyterLab

1. Na interface do usuário do JupyterLab da instância de notebooks gerenciados, no menu de navegação, clique no botão  Executor de notebook.

2. Clique na guia Programações.

3. Clique no nome da programação que você quer excluir. O executor abre a página Detalhes da programação no console do Google Cloud.

4. Clique Excluir.

Treinamento personalizado da Vertex AI para jobs

Como as execuções de notebook são executadas no treinamento personalizado da Vertex AI, elas são expostas como jobs de treinamento personalizados na Vertex AI. É possível visualizar esses jobs de treinamento personalizados no console do Google Cloud, na guia Jobs personalizados da página Treinamento da Vertex AI. Saiba mais sobre como trabalhar com jobs de treinamento personalizados da Vertex AI.

A seguir

• Saiba como executar execuções de notebook com parâmetros.

• Saiba mais sobre o treinamento personalizado da Vertex AI.