Execute ficheiros de blocos de notas com o executor

Execute ficheiros de blocos de notas com o executor

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 descreve como usar o executor numa instância de blocos de notas geridos do Vertex AI Workbench para executar ficheiros de blocos de notas como uma execução única e de forma agendada.

Vista geral

O executor permite-lhe enviar um ficheiro de bloco de notas (ipynb) para execução na preparação personalizada do Vertex AI. Pode definir valores de parâmetros para cada execução de um ficheiro de bloco de notas. Também pode executar um ficheiro de bloco de notas com uma programação recorrente. Após a conclusão da execução, pode ver os resultados da execução e partilhá-los com outras pessoas.

Quando um ficheiro de bloco de notas é enviado para a preparação personalizada da Vertex AI, a Vertex AI cria uma nova tarefa de preparação personalizada que executa o ficheiro de bloco de notas de acordo com o ciclo de vida de uma tarefa de preparação.

Requisitos para o código do bloco de notas executado pelo executor

Quando escreve código de bloco de notas para executar no executor, tenha em atenção que o código é executado num projeto de inquilino separado do projeto da instância de blocos de notas geridos. Esta secção descreve como isto afeta o seu código quando é executado no executor.

Certifique-se de que as instalações de pacotes estão disponíveis para o executor

Se o seu bloco de notas depender de instalações de pacotes que ainda não estejam incluídas no kernel dos blocos de notas geridos que está a usar, certifique-se de que os pacotes estão disponíveis para o código do bloco de notas no executor de uma das seguintes formas:

• Use um contentor personalizado que já tenha o pacote instalado e, em seguida, execute o seu bloco de notas nesse contentor personalizado. Consulte os requisitos para usar um contentor personalizado com o executor.

• Instale o pacote no código do ficheiro do bloco de notas. O pacote é instalado sempre que o ficheiro do bloco de notas é executado, mas isto garante que o pacote está disponível no contentor que seleciona quando executa o bloco de notas.

Use a seleção explícita de projetos

Quando acede a recursos através de código executado pelo executor, o executor pode não estabelecer ligação aoGoogle Cloud projeto correto. Se encontrar erros de autorização, o problema pode estar relacionado com a ligação ao projeto errado.

Este problema ocorre porque o executor não executa o seu código diretamente na instância dos blocos de notas geridos do projetoGoogle Cloud . Em alternativa, o executor executa o seu código na preparação personalizada do Vertex AI num projeto de inquilino gerido pela Google. Por conseguinte, não tente inferir um ID do projeto a partir do ambiente no código do bloco de notas. Especifique os IDs dos projetos explicitamente.

Se não quiser codificar um ID do projeto no seu código, pode fazer referência à variável de ambiente CLOUD_ML_PROJECT_ID. O Vertex AI define esta variável de ambiente em todos os contentores de preparação personalizada para conter o número do projeto do projeto onde iniciou a preparação personalizada. Muitas Google Cloud ferramentas podem aceitar um número do projeto onde quer que aceitem um ID do projeto.

Por exemplo, se quiser usar o cliente Python para o Google BigQuery para aceder a uma tabela do BigQuery no mesmo projeto, não infira o projeto no código do bloco de notas:

Seleção implícita de projetos

from google.cloud import bigquery

client = bigquery.Client()

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

Seleção explícita de projetos

import os

from google.cloud import bigquery

project_number = os.environ["CLOUD_ML_PROJECT_ID"]

client = bigquery.Client(project=project_number)

Autentique o acesso através de contas de serviço

Por predefinição, a instância dos blocos de notas geridos pode ter acesso a recursos que existem no mesmo projeto. Por conseguinte, quando executa o código do ficheiro do bloco de notas manualmente, estes recursos não precisam de autenticação adicional. No entanto, como o executor é executado num projeto de inquilino separado, não tem o mesmo acesso predefinido.

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

Para resolver estes problemas, no código do ficheiro de bloco de notas, autentique o acesso aos recursos através de uma conta de serviço.

Em seguida, quando criar uma execução ou um agendamento, especifique a conta de serviço.

Por exemplo, enquanto cria uma execução, conclua estes passos:

1. Na caixa de diálogo Enviar notebooks para o Executor, expanda Opções avançadas.

2. Na secção Identidade e acesso à API, desmarque a caixa junto a Usar a conta de serviço predefinida da Vertex AI Training e introduza a conta de serviço específica a usar.

Veja a lista completa de passos para criar uma execução.

Requisitos quando usa um contentor personalizado

Pode usar o executor para executar código de bloco de notas num contentor personalizado. O seu contentor personalizado tem de incluir a extensão nbexecutor, que permite ao executor executar código de bloco de notas como uma tarefa de preparação personalizada do Vertex AI. Para garantir que o seu contentor personalizado tem a extensão nbexecutor, pode modificar uma das imagens de contentor dos Deep Learning Containers para criar uma imagem de contentor derivada. As imagens do Deep Learning Containers incluem a extensão nbexecutor.

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 Vertex AI 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 Vertex AI 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

Funções necessárias

Para garantir que a conta de serviço da sua instância tem as autorizações necessárias para interagir com o executor do Vertex AI Workbench, peça ao seu administrador para conceder à conta de serviço da sua instância as seguintes funções de IAM no projeto:

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.
• Visualizador de blocos de notas (roles/notebooks.viewer)
• Utilizador do Vertex AI (roles/aiplatform.user)
• Administrador de armazenamento (roles/storage.admin)

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.

Abra o JupyterLab

Para abrir o JupyterLab e preparar um ficheiro de bloco de notas para execução, conclua os seguintes passos.

1. Abra o JupyterLab.

2. Carregue um ficheiro de notebook (ipynb), abra um ficheiro existente ou abra um novo ficheiro de notebook e adicione o código que quer executar ao notebook.

3. Certifique-se de que o código do ficheiro do bloco de notas cumpre os requisitos para usar o executor.

Crie uma execução

Para criar uma execução que execute o ficheiro de bloco de notas, conclua os seguintes passos. Estes passos abrangem a programação de execuções e a criação de uma execução única.

1. Na interface do utilizador do JupyterLab da instância de blocos de notas geridos, abra o ficheiro de bloco de notas que quer executar.

2. Clique no botão  Executar.

3. Na caixa de diálogo Enviar blocos de notas para o Executor, no campo Nome da execução, introduza um nome para a 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 selecione Execuções recorrentes baseadas em agendamento e conclua a caixa de diálogo para agendar execuções.

7. Em Opções avançadas, selecione a Região onde quer executar o seu bloco de notas.

8. No campo Contentor do Cloud Storage, selecione um contentor do Cloud Storage disponível ou introduza um nome para um novo contentor e clique em Criar e selecionar. O executor armazena a saída do bloco de notas neste contentor do Cloud Storage.

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

   Saiba como usar os parâmetros do bloco de notas.

10. Opcional: na secção Identidade e acesso à API, selecione Usar a conta de serviço predefinida do Vertex AI Training ou desmarque a caixa de verificação e introduza uma conta de serviço específica a usar.

    Nota: se o código do ficheiro de bloco de notas autenticar o acesso aos serviços através de credenciais de utilizador final ou acesso predefinido no projeto da instância de blocos de notas geridos, consulte os requisitos para o código do bloco de notas executado pelo executor e considere especificar uma conta de serviço.

11. Opcional: na secção Rede, especifique uma rede de nuvem privada virtual. A utilização de uma rede VPC para a execução requer uma ligação de acesso a serviços privados.

12. Clique em Enviar.

    As execuções únicas começam imediatamente. As execuções agendadas são executadas automaticamente no horário que definiu.

    Nota: se a instância de blocos de notas geridos for encerrada, o executor continua a executar o ficheiro do bloco de notas de acordo com o agendamento.

Na Google Cloud consola, na página Vertex AI Workbench, pode ver as execuções concluídas no separador Execuções e as suas programações no separador Programações.

Veja, partilhe e importe um ficheiro de bloco de notas executado

Ao usar a interface do utilizador do JupyterLab da instância de notebooks geridos, pode ver o resultado de um notebook executado, partilhar os resultados com outras pessoas e importar o ficheiro do notebook executado para o JupyterLab.

Veja os resultados da execução de um bloco de notas

Pode ver os resultados da execução de um bloco de notas na Google Cloud consola ou na interface do utilizador do JupyterLab.

Consola

1. Na Google Cloud consola, aceda à página Vertex AI Workbench e clique no separador Execuções.

   Aceda a Execuções

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

3. Junto à execução que quer ver, clique em Ver resultado.

   O resultado é aberto num novo separador do navegador.

JupyterLab

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

2. Clique no separador Execuções.

3. Na execução que quer ver, clique em Ver resultado.

   O resultado é aberto num novo separador do navegador.

Partilhe os resultados da execução de um notebook

Pode partilhar os resultados da execução concedendo acesso ao contentor do Cloud Storage que contém a execução do bloco de notas. A concessão deste acesso também concede aos utilizadores acesso a quaisquer outros recursos no mesmo contentor do Cloud Storage. Para partilhar os resultados da execução, conclua os seguintes passos.

Consola

1. Na Google Cloud consola, aceda à página Vertex AI Workbench e clique no separador Execuções.

   Aceda a Execuções

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

3. Junto à execução que quer partilhar, clique no botão  Partilhar.

4. Siga as instruções na caixa de diálogo para conceder aos utilizadores acesso ao contentor do Cloud Storage que contém a execução do seu bloco de notas.

JupyterLab

1. Na interface do utilizador do JupyterLab da instância de blocos de notas geridos, no menu de navegação, clique no botão  Notebook Executor.

2. Clique no separador Execuções.

3. Junto à execução que quer partilhar, clique no  menu de opções e selecione Partilhar resultado da execução.

4. Siga as instruções na caixa de diálogo para conceder aos utilizadores acesso ao contentor do Cloud Storage que contém a execução do seu bloco de notas.

Importe um bloco de notas executado para o JupyterLab

Para importar um bloco de notas executado para o JupyterLab, conclua os seguintes passos.

1. Na interface do utilizador do JupyterLab da instância de blocos de notas geridos, no menu de navegação, clique no botão  Notebook Executor.

2. Clique no separador Execuções.

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

4. Junto à execução que quer importar, clique no  menu de opções e selecione Importar bloco de notas executado.

5. Selecione o kernel com o qual quer abrir o bloco de notas.

   O executor abre o ficheiro do bloco de notas executado no JupyterLab e armazena este ficheiro do bloco de notas no explorador de ficheiros do JupyterLab numa pasta denominada imported_notebook_jobs.

Veja ou elimine uma programação

Pode ver e eliminar agendamentos através da Google Cloud consola ou da interface do utilizador do JupyterLab da instância de blocos de notas gerida.

Veja um horário

Veja um agendamento para ver as definições de frequência do agendamento ou para ver os resultados das execuções do bloco de notas.

Consola

1. Na Google Cloud consola, aceda à página Vertex AI Workbench e clique no separador Programações.

   Aceda a Agendas

2. Selecione a região que contém o seu horário.

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

4. Junto ao nome de uma execução, clique em Ver resultado para abrir o ficheiro do bloco de notas executado. O executor abre o resultado num novo separador do navegador.

JupyterLab

1. Na interface do utilizador do JupyterLab da instância de blocos de notas geridos, no menu de navegação, clique no botão  Notebook Executor.

2. Clique no separador Programações.

3. Para ver a execução mais recente, na execução que quer ver, clique em Ver resultado da execução mais recente. O executor abre o resultado num novo separador do navegador.

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

4. Junto ao nome de uma execução, clique em Ver resultado para abrir o ficheiro do bloco de notas executado. O executor abre o resultado num novo separador do navegador.

Elimine um agendamento

A eliminação de um agendamento não elimina as execuções que foram geradas a partir desse agendamento.

Consola

1. Na Google Cloud consola, aceda à página Vertex AI Workbench e clique no separador Programações.

   Aceda a Agendas

2. Selecione a região que contém o seu horário.

3. Selecione o horário que quer eliminar.

4. Clique em  Eliminar.

JupyterLab

1. Na interface do utilizador do JupyterLab da instância de blocos de notas geridos, no menu de navegação, clique no botão  Notebook Executor.

2. Clique no separador Programações.

3. Clique no nome do horário que quer eliminar. O executor abre a página Detalhes do agendamento na consola Google Cloud .

4. Clique em  Eliminar.

Tarefas na preparação personalizada do Vertex AI

Uma vez que as execuções de blocos de notas são executadas na preparação personalizada do Vertex AI, são expostas como tarefas de preparação personalizada no Vertex AI. Pode ver estas tarefas de preparação personalizadas na Google Cloud consola, no separador Tarefas personalizadas da página Vertex AI Training. Saiba como trabalhar com tarefas de preparação personalizadas da Vertex AI.

O que se segue?

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

• Saiba mais sobre a preparação personalizada da Vertex AI.