Criar uma instância do Workbench da plataforma de agentes

Nesta página, mostramos como criar uma instância do Gemini Enterprise Agent Platform Workbench usando o console Google Cloud ou a Google Cloud CLI. Ao criar a instância, é possível configurar o hardware, o tipo de criptografia, a rede e outros detalhes dela.

Antes de começar

Antes de criar uma instância do Agent Platform Workbench, conclua as etapas a seguir:

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

  2. 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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

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

  5. 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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

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

    8.

Funções exigidas

Para receber as permissões necessárias para criar e gerenciar uma instância do Agent Platform Workbench, peça ao administrador para conceder a você o papel do IAM de Administrador de Notebooks (roles/notebooks.admin) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Criar uma instância

É possível criar uma instância do Agent Platform Workbench usando o Google Cloud console, a CLI gcloud ou o Terraform:

Console

  1. No console do Google Cloud , acesse a página Instâncias.

    Acesse "Instâncias"

  2. Clique em Criar.

  3. Na caixa de diálogo Nova instância, clique em Opções avançadas.

  4. Na caixa de diálogo Criar instância, na seção Detalhes, insira as seguintes informações sobre a nova instância:

    • Nome: forneça um nome para a nova instância. O nome precisa começar com uma letra seguida por até 62 letras minúsculas, números ou hifens (-) e não pode terminar com um hífen.
    • 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ê. Confira os locais disponíveis do Workbench da plataforma de agentes.
    • Rótulos: opcional. Forneça rótulos personalizados de chave-valor para a instância.
    • Tags de rede: opcional. Forneça tags de rede para a instância.

  5. Na seção Ambiente, forneça as seguintes informações:

    • Versão do JupyterLab: selecione uma versão do JupyterLab.
    • Versão: use a versão mais recente ou uma versão anterior das instâncias do Workbench da plataforma do agente.
    • Script pós-inicialização: opcional. Clique em Procurar para selecionar um script para ser executado uma vez, após a criação da instância. O caminho precisa ser um URL ou do Cloud Storage, por exemplo: gs://PATH_TO_FILE/FILE_NAME.
    • Metadados: opcional. Informe as chaves de metadados personalizadas para a instância.

  6. Na seção Tipo de máquina, forneça as seguintes informações:

    • Tipo de máquina: selecione o número de CPUs e a quantidade de RAM para a nova instância. O Workbench da Agent Platform fornece estimativas de custo mensais para cada tipo de máquina selecionada.

    • GPU: Opcional. Se você quiser GPUs, selecione o Tipo de GPU e o Número de GPUs para a nova instância. O tipo de acelerador que você quer precisa estar disponível na zona da instância. Para saber mais sobre a disponibilidade do acelerador por zona, consulte Disponibilidade de zonas e regiões da GPU. Para informações sobre as diferentes GPUs, consulte GPUs no Compute Engine.

    • VM protegida: opcional. Marque ou desmarque as seguintes caixas de seleção:

      • inicialização segura;
      • Módulo de plataforma confiável e virtual (vTPM)
      • monitoramento de integridade

    • Desligamento de inatividade: opcional.

      • Para alterar o número de minutos antes do encerramento, no campo Tempo de inatividade antes do encerramento (minutos), altere o valor para um número inteiro de 10 a 1.440.

      • Para desativar o encerramento por inatividade, desmarque a opção Ativar encerramento por inatividade.

  7. Na seção Discos, forneça as seguintes informações:

    • Discos: opcional. Para alterar as configurações padrão do disco de dados, selecione um Tipo de disco de dados e Tamanho do disco de dados em GB. Para mais informações sobre tipos de disco, consulte Opções de armazenamento.

    • Excluir na lixeira: opcional. Marque essa caixa de seleção para usar o comportamento padrão da lixeira do sistema operacional. Se você usar o comportamento padrão, os arquivos excluídos usando a interface do usuário do JupyterLab serão recuperados, mas os arquivos excluídos usarão o espaço em disco.

    • Criptografia: selecione Google-managed encryption key ou Chave de criptografia gerenciada pelo cliente (CMEK). Para usar CMEK, consulte Chaves de criptografia gerenciadas pelo cliente.

  8. Na seção Rede, forneça as seguintes informações:

  9. Na seção IAM e segurança, forneça o seguinte:

    • IAM e segurança: para conceder acesso à interface do JupyterLab da instância, conclua uma das seguintes etapas:

      • Para conceder acesso ao JupyterLab por meio de uma conta de serviço, selecione Conta de serviço.

        • Para usar a conta de serviço padrão do Compute Engine, selecione Usar a conta de serviço padrão do Compute Engine.

        • Para usar uma conta de serviço personalizada, desmarque a opção Usar a conta de serviço padrão do Compute Engine e, no campo E-mail da conta de serviço, digite seu endereço de e-mail da conta de serviço personalizada.

      • Para conceder a um único usuário acesso à interface JupyterLab, faça o seguinte:

        1. Selecione Usuário único e, no campo E-mail do usuário, insira a conta de usuário à qual você quer conceder acesso. Se o usuário especificado não for o criador da instância, você precisará conceder o papel de usuário da conta de serviço (roles/iam.serviceAccountUser) ao conta de serviço da instância.

        2. A instância usa uma conta de serviço para interagir com os serviços e as APIs doGoogle Cloud .

          • Para usar a conta de serviço padrão do Compute Engine, selecione Usar a conta de serviço padrão do Compute Engine.

          • Para usar uma conta de serviço personalizada, desmarque a opção Usar a conta de serviço padrão do Compute Engine e, no campo E-mail da conta de serviço, digite seu endereço de e-mail da conta de serviço personalizada.

      Para saber mais sobre como conceder acesso, consulte Gerenciar acesso.

    • Opções de segurança: marque ou desmarque as seguintes caixas de seleção:

      • Acesso raiz à instância
      • nbconvert
      • Permitir downloads do arquivo
      • Acesso ao terminal

  10. Na seção Integridade do sistema, forneça as seguintes informações:

    • Atualização do ambiente e integridade do sistema: para atualizar automaticamente para versões de ambiente recém-lançadas, selecione Upgrade automático do ambiente e conclua a Programação de upgrade.

    • Em Relatórios, marque ou desmarque as seguintes caixas de seleção:

      • Relatar a integridade do sistema
      • Relatar métricas personalizadas para o Cloud Monitoring
      • Instalar o Cloud Monitoring
      • Informar o status de DNS dos domínios obrigatórios do Google

  11. Clique em Criar.

    O Workbench da plataforma do agente cria e inicia uma instância automaticamente. Quando a instância estiver pronta para uso, o Agent Platform Workbench vai ativar um link Abrir JupyterLab.

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

  • INSTANCE_NAME: o nome da sua instância do Agent Platform Workbench. Precisa começar com uma letra seguida por até 62 letras minúsculas, números ou hifens (-) e não pode terminar com um hífen.
  • PROJECT_ID: ID do projeto;
  • LOCATION: a zona em que você quer que a instância esteja localizada
  • VM_IMAGE_PROJECT: o ID do projeto Google Cloud a que a imagem da VM pertence. O ID do projeto Google Cloud padrão para imagens compatíveis é cloud-notebooks-managed.
  • VM_IMAGE_NAME: o nome da imagem. Para encontrar o nome da imagem de uma versão específica, consulte Encontrar a versão específica.
  • MACHINE_TYPE: o tipo de máquina da VM da instância

  • METADATA: metadados personalizados a serem aplicados a esta instância. Por exemplo, para especificar um script pós-inicialização, use a tag de metadados post-startup-script no formato: --metadata=post-startup-script=gs://BUCKET_NAME/hello.sh

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud workbench instances create INSTANCE_NAME \
    --project=PROJECT_ID \
    --location=LOCATION \
    --vm-image-project=VM_IMAGE_PROJECT \
    --vm-image-name=VM_IMAGE_NAME \
    --machine-type=MACHINE_TYPE \
    --metadata=METADATA

Windows (PowerShell)

gcloud workbench instances create INSTANCE_NAME `
    --project=PROJECT_ID `
    --location=LOCATION `
    --vm-image-project=VM_IMAGE_PROJECT `
    --vm-image-name=VM_IMAGE_NAME `
    --machine-type=MACHINE_TYPE `
    --metadata=METADATA

Windows (cmd.exe)

gcloud workbench instances create INSTANCE_NAME ^
    --project=PROJECT_ID ^
    --location=LOCATION ^
    --vm-image-project=VM_IMAGE_PROJECT ^
    --vm-image-name=VM_IMAGE_NAME ^
    --machine-type=MACHINE_TYPE ^
    --metadata=METADATA

Para mais informações sobre o comando para criar uma instância usando a linha de comando, consulte a documentação da CLI gcloud.

O Workbench da plataforma do agente cria e inicia uma instância automaticamente. Quando a instância estiver pronta para uso, o Agent Platform Workbench vai ativar um link Abrir JupyterLab no console Google Cloud .

Terraform

No exemplo a seguir, usamos o recurso do Terraform google_workbench_instance para criar uma instância do Workbench da Agent Platform chamada workbench-instance-example.

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform.

resource "google_workbench_instance" "default" {
  name     = "workbench-instance-example"
  location = "us-central1-a"

  gce_setup {
    machine_type = "n1-standard-1"
    accelerator_configs {
      type       = "NVIDIA_TESLA_T4"
      core_count = 1
    }
    vm_image {
      project = "cloud-notebooks-managed"
      family  = "workbench-instances"
    }
  }
}

Mudar a versão do JupyterLab em uma instância atual

Nesta seção, descrevemos como mudar a versão do JupyterLab na sua instância usando o console do Google Cloud ou a CLI gcloud.

Console

Para mudar a versão do JupyterLab em uma instância atual, faça o seguinte:

  1. No console do Google Cloud , acesse a página Instâncias.

    Acesse "Instâncias"

  2. Desligue a instância.

  3. Clique no nome da instância para abrir a página Detalhes da instância.

  4. Na guia Sistema, faça o seguinte:

    • Para ativar o JupyterLab 3, desmarque a caixa de seleção Ativar o JupyterLab 4.

    • Para ativar o JupyterLab 4, deixe a caixa de seleção Ativar o JupyterLab 4 marcada.

  5. Clique em Enviar.

  6. Para reiniciar a instância, selecione-a e clique em  Iniciar.

gcloud

É possível mudar a versão do JupyterLab em uma instância usando o seguinte comando:

gcloud workbench instances update INSTANCE_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --metadata=enable-jupyterlab4=ENABLEMENT_BOOLEAN

Substitua:

  • PROJECT_ID: ID do projeto;
  • LOCATION: a zona em que você quer que a instância esteja localizada
  • INSTANCE_NAME: o nome da sua instância do Workbench da plataforma de agentes

  • ENABLEMENT_BOOLEAN: use uma das seguintes opções:

    • false: mudanças no JupyterLab 3.
    • true: mudanças no JupyterLab 4. O JupyterLab 4 está ativado por padrão.

Limitação do JupyterLab 4

Ao programar uma execução de notebook no JupyterLab 4, o Agent Platform Workbench armazena uma cópia do notebook no estado atual no Cloud Storage e executa essa cópia de acordo com a programação. Se você editar o notebook original, crie uma nova programação para executar a versão atualizada.

Opções de configuração de rede

Uma instância do Agent Platform Workbench precisa acessar endpoints de serviço que estejam fora da rede VPC.

Você pode fornecer esse acesso de uma das seguintes maneiras:

Se você usa o VIP private.googleapis.com ou restricted.googleapis.com para fornecer acesso aos endpoints do serviço, adicione entradas DNS para cada um dos endpoints de serviço necessários:

  • notebooks.cloud.google.com
  • notebooks.googleapis.com
  • *.notebooks.byoid.googleusercontent.com
  • *.notebooks.cloud.google.com
  • *.notebooks.googleusercontent.com
  • *.kernels.googleusercontent.com

Se você usa credenciais de terceiros, use restricted.googleapis.com e adicione a seguinte entrada DNS:

  • *.byoid.googleusercontent.com

Tags de rede

Sua nova instância do Workbench da plataforma do agente tem as tags de rede deeplearning-vm e notebook-instance atribuídas automaticamente.

A seção "Máquinas virtuais" do menu de navegação do console, com instâncias de VM selecionadas, mostrando as tags de rede atribuídas no momento.

Com essas tags, é possível gerenciar o acesso à rede de e para sua instância do Agent Platform Workbench, referenciando as tags nas regras de firewall da rede VPC. Para mais informações sobre tags de rede, consulte Adicionar tags de rede.

Para visualizar as tags de rede de uma instância do Agent Platform Workbench, faça o seguinte:

  1. No console do Google Cloud , acesse a página Instâncias de VM.

    Acessar instâncias de VM

  2. Clique no nome da instância.

  3. Na seção Rede, localize Tags de rede.

Solução de problemas

Se você encontrar problemas ao criar uma instância, consulte Como solucionar problemas do Agent Platform Workbench para receber ajuda.

A seguir