Programar a execução de um notebook

Nesta página, mostramos como programar uma execução de notebook no Colab Enterprise.

Visão geral

É possível programar um notebook para execução imediata uma vez ou em uma programação recorrente.

Ao programar a execução do notebook, você seleciona um modelo de ambiente de execução. O Colab Enterprise usa esse modelo de ambiente de execução para criar o ambiente de execução que executa seu bloco.

O ambiente de execução precisa de permissões específicas para executar o código do notebook e acessar serviços e APIs Google Cloud .

  • Se a configuração do modelo de ambiente de execução tiver as credenciais do usuário final ativadas, o ambiente de execução vai usar as permissões associadas às suas credenciais de usuário.

  • Se as credenciais do usuário final não estiverem ativadas, será necessário especificar uma conta de serviço ao programar a execução do notebook. O Colab Enterprise usa as credenciais dessa conta de serviço para executar o notebook.

Para mais informações, consulte Papéis necessários para executar o notebook.

Depois que o Colab Enterprise concluir a execução do notebook, os resultados serão armazenados em um bucket compartilhável do Cloud Storage.

Limitações

Os ambientes de execução do Colab Enterprise usam a cota do Compute Engine. Consulte a página de cotas de alocação do Compute Engine.

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.

    Go to project selector

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

  4. Enable the Vertex AI, Dataform, and Compute Engine APIs.

    Enable the APIs

    5.

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

    Go to project selector

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

  7. Enable the Vertex AI, Dataform, and Compute Engine APIs.

    Enable the APIs

    8.

Papéis necessários para programar a execução do notebook

Para garantir que sua conta de usuário tenha as permissões necessárias para programar uma execução de bloco no Colab Enterprise, peça ao administrador para conceder à sua conta de usuário os seguintes papéis do IAM no projeto:

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 à sua conta de usuário as permissões necessárias via funções personalizadas ou outros papéis predefinidos.

Papéis necessários para executar o notebook

O principal que executa o notebook precisa de permissões específicas. O principal é sua conta de usuário ou uma conta de serviço especificada, conforme descrito na visão geral.

Para garantir que o principal tenha as permissões necessárias para executar um bloco no Colab Enterprise, peça ao administrador para conceder ao principal os seguintes papéis do IAM:

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

Esses papéis predefinidos contêm as permissões necessárias para executar um notebook no Colab Enterprise. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para executar um notebook no Colab Enterprise:

  • dataform.locations.list no caderno
  • dataform.repositories.computeAccessTokenStatus no caderno
  • dataform.repositories.fetchHistory no caderno
  • dataform.repositories.fetchRemoteBranches no caderno
  • dataform.repositories.get no caderno
  • dataform.repositories.getIamPolicy no caderno
  • dataform.repositories.list no caderno
  • dataform.repositories.queryDirectoryContents no caderno
  • dataform.repositories.readFile no caderno
  • logging.logEntries.create no projeto
  • logging.logEntries.route no projeto
  • monitoring.metricDescriptors.create no projeto
  • monitoring.metricDescriptors.get no projeto
  • monitoring.metricDescriptors.list no projeto
  • monitoring.monitoredResourceDescriptors.get no projeto
  • monitoring.monitoredResourceDescriptors.list no projeto
  • monitoring.timeSeries.create no projeto
  • resourcemanager.projects.get no projeto
  • resourcemanager.projects.list no projeto
  • storage.buckets.get no caderno
  • storage.managedFolders.create no caderno
  • storage.managedFolders.delete no caderno
  • storage.managedFolders.get no caderno
  • storage.managedFolders.list no caderno
  • storage.multipartUploads.abort no caderno
  • storage.multipartUploads.create no caderno
  • storage.multipartUploads.list no caderno
  • storage.multipartUploads.listParts no caderno
  • storage.objects.create no caderno
  • storage.objects.delete no caderno
  • storage.objects.get no caderno
  • storage.objects.list no caderno
  • storage.objects.restore no caderno
  • storage.objects.setRetention no caderno

O administrador também pode conceder essas permissões ao principal com papéis personalizados ou outros papéis predefinidos.

Executar um notebook uma vez

Para executar um notebook uma vez, use o console do Google Cloud, a CLI do Google Cloud ou a biblioteca de cliente Python da Vertex AI.

Console

  1. No console do Google Cloud, acesse a página Meus notebooks do Colab Enterprise.

    Acessar "Meus cadernos"

  2. No menu Região, selecione a região que contém o notebook.

  3. Ao lado de um notebook, clique no menu Ações do notebook e selecione Programar.

  4. No campo Nome da programação, insira um nome para a programação.

  5. Clique na lista Modelo de execução e selecione um modelo de execução. O modelo de ambiente de execução determina as especificações do ambiente de execução que executa o notebook.

  6. Em Programação de execução, selecione Único para executar o notebook assim que você enviar a execução.

  7. Ao lado do campo Local de saída do Cloud Storage, clique em Procurar para abrir a caixa de diálogo Selecionar pasta.

  8. Selecione um bucket do Cloud Storage. Ou, para criar um bucket, clique em  Criar novo bucket e conclua a caixa de diálogo.

  9. Se você selecionou um modelo de ambiente de execução sem as credenciais do usuário final ativadas, a caixa de diálogo inclui um campo Conta de serviço. No campo Conta de serviço, insira o endereço de e-mail de uma conta de serviço.

  10. Clique em Enviar.

    A execução do notebook começa imediatamente.

gcloud

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

  • DISPLAY_NAME: o nome de exibição da execução do notebook.
  • NOTEBOOK_RUNTIME_TEMPLATE: o modelo de ambiente de execução do notebook que especifica a configuração de computação do ambiente de execução.
  • NOTEBOOK_URI: o URI do Cloud Storage do notebook a ser executado.
  • OUTPUT_URI: o local do Cloud Storage em que você quer armazenar os resultados.
  • USER_EMAIL: o endereço de e-mail da conta de usuário que especifica o acesso da execução do notebook aos recursos Google Cloud .
  • PROJECT_ID: o ID do projeto.
  • REGION: a região em que o notebook será executado.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud colab executions create --display-name="DISPLAY_NAME" \
    --notebook-runtime-template=NOTEBOOK_RUNTIME_TEMPLATE \
    --gcs-notebook-uri=NOTEBOOK_URI \
    --gcs-output-uri=OUTPUT_URI \
    --user-email=USER_EMAIL \
    --project=PROJECT_ID \
    --region=REGION

Windows (PowerShell)

gcloud colab executions create --display-name="DISPLAY_NAME" `
    --notebook-runtime-template=NOTEBOOK_RUNTIME_TEMPLATE `
    --gcs-notebook-uri=NOTEBOOK_URI `
    --gcs-output-uri=OUTPUT_URI `
    --user-email=USER_EMAIL `
    --project=PROJECT_ID `
    --region=REGION

Windows (cmd.exe)

gcloud colab executions create --display-name="DISPLAY_NAME" ^
    --notebook-runtime-template=NOTEBOOK_RUNTIME_TEMPLATE ^
    --gcs-notebook-uri=NOTEBOOK_URI ^
    --gcs-output-uri=OUTPUT_URI ^
    --user-email=USER_EMAIL ^
    --project=PROJECT_ID ^
    --region=REGION

Para mais informações sobre como gerenciar execuções de notebooks do Colab Enterprise na linha de comando, consulte a documentação da CLI gcloud.

Python

Antes de testar este exemplo, instale o SDK da Vertex AI para Python. A biblioteca de cliente Python da Vertex AI é instalada quando você instala o SDK da Vertex AI para Python. Saiba mais na documentação de referência da API SDK da Vertex AI para Python. 

from google.cloud import aiplatform_v1beta1

PROJECT_ID = "my-project"
LOCATION = "us-central1"

API_ENDPOINT = f"{LOCATION}-aiplatform.googleapis.com"
PARENT = f"projects/{PROJECT_ID}/locations/{LOCATION}"

notebook_service_client = aiplatform_v1beta1.NotebookServiceClient(client_options = {
    "api_endpoint": API_ENDPOINT,
})

operation = notebook_service_client.create_notebook_execution_job(parent=PARENT, notebook_execution_job={
    "display_name": "my-execution-job",

    # Specify a NotebookRuntimeTemplate to source compute configuration from
    "notebook_runtime_template_resource_name": f"projects/{PROJECT_ID}/locations/{LOCATION}/notebookRuntimeTemplates/{template_id}",

    # Specify a Colab Enterprise notebook to run
    "dataformRepositorySource": {
        "dataformRepositoryResourceName": f"projects/{PROJECT_ID}/locations/{LOCATION}/repositories/{repository_id}",
    },

    # Specify a Cloud Storage bucket to store output artifacts
    "gcs_output_uri": "gs://my-bucket/,

    # Specify the identity that runs the notebook
    "execution_user": {EMAIL},

    # Run as the service account instead
    # "service_account": "my-service-account",
})
print("Waiting for operation to complete...")
result = operation.result()

É possível conferir os resultados das execuções de notebooks concluídas na página Executions.

Programar a execução de um notebook

Para programar uma execução de notebook, use o console do Google Cloud, a CLI gcloud ou a biblioteca de cliente Python da Vertex AI.

Console

  1. No console do Google Cloud, acesse a página Meus notebooks do Colab Enterprise.

    Acessar "Meus cadernos"

  2. No menu Região, selecione a região que contém o notebook.

  3. Ao lado de um notebook, clique no menu Ações do notebook e selecione Programar.

  4. No campo Nome da programação, insira um nome para a programação.

  5. Clique na lista Modelo de execução e selecione um modelo de execução. O modelo de ambiente de execução determina as especificações do ambiente de execução que executa o notebook.

  6. Em Programação de execução, selecione Recorrente para programar a execução do notebook em um intervalo específico.

  7. Conclua a caixa de diálogo de programação.

  8. Ao lado do campo Local de saída do Cloud Storage, clique em Procurar para abrir a caixa de diálogo Selecionar pasta.

  9. Selecione um bucket do Cloud Storage. Ou, para criar um bucket, clique em  Criar novo bucket e conclua a caixa de diálogo.

  10. Se você selecionou um modelo de ambiente de execução sem as credenciais do usuário final ativadas, a caixa de diálogo inclui um campo Conta de serviço. No campo Conta de serviço, insira o endereço de e-mail de uma conta de serviço.

  11. Clique em Enviar.

    As execuções de notebooks programadas começam automaticamente na programação que você definir.

gcloud

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

  • DISPLAY_NAME: o nome de exibição da programação.
  • CRON_SCHEDULE: a programação definida no formato unix-cron. Por exemplo, 00 19 * * MON significa "semanalmente" às segundas-feiras, às 19h, horário de Greenwich (GMT).
  • NOTEBOOK_RUN_NAME: o nome de exibição das execuções de notebooks geradas por essa programação.
  • NOTEBOOK_RUNTIME_TEMPLATE: o modelo de ambiente de execução do notebook que especifica a configuração de computação do ambiente de execução.
  • NOTEBOOK_URI: o URI do Cloud Storage do notebook a ser executado.
  • OUTPUT_URI: o local do Cloud Storage em que você quer armazenar os resultados.
  • USER_EMAIL: o endereço de e-mail da conta de usuário que especifica o acesso da execução do notebook aos recursos Google Cloud .
  • PROJECT_ID: o ID do projeto.
  • REGION: a região em que a programação será executada.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud colab schedules create --display-name="DISPLAY_NAME" \
    --cron-schedule=CRON_SCHEDULE \
    --execution-display-name=NOTEBOOK_RUN_NAME \
    --notebook-runtime-template=NOTEBOOK_RUNTIME_TEMPLATE \
    --gcs-notebook-uri=NOTEBOOK_URI \
    --gcs-output-uri=OUTPUT_URI \
    --user-email=USER_EMAIL \
    --project=PROJECT_ID \
    --region=REGION

Windows (PowerShell)

gcloud colab schedules create --display-name="DISPLAY_NAME" `
    --cron-schedule=CRON_SCHEDULE `
    --execution-display-name=NOTEBOOK_RUN_NAME `
    --notebook-runtime-template=NOTEBOOK_RUNTIME_TEMPLATE `
    --gcs-notebook-uri=NOTEBOOK_URI `
    --gcs-output-uri=OUTPUT_URI `
    --user-email=USER_EMAIL `
    --project=PROJECT_ID `
    --region=REGION

Windows (cmd.exe)

gcloud colab schedules create --display-name="DISPLAY_NAME" ^
    --cron-schedule=CRON_SCHEDULE ^
    --execution-display-name=NOTEBOOK_RUN_NAME ^
    --notebook-runtime-template=NOTEBOOK_RUNTIME_TEMPLATE ^
    --gcs-notebook-uri=NOTEBOOK_URI ^
    --gcs-output-uri=OUTPUT_URI ^
    --user-email=USER_EMAIL ^
    --project=PROJECT_ID ^
    --region=REGION

Para mais informações sobre como criar programações de notebooks do Colab Enterprise na linha de comando, consulte a documentação da CLI gcloud.

Python

Antes de testar este exemplo, instale o SDK da Vertex AI para Python. A biblioteca de cliente Python da Vertex AI é instalada quando você instala o SDK da Vertex AI para Python. Saiba mais na documentação de referência da API SDK da Vertex AI para Python. 

from google.cloud import aiplatform_v1beta1

PROJECT_ID = "my-project"
LOCATION = "us-central1"

API_ENDPOINT = f"{LOCATION}-aiplatform.googleapis.com"
PARENT = f"projects/{PROJECT_ID}/locations/{LOCATION}"

schedules_service_client = aiplatform_v1beta1.ScheduleServiceClient(client_options = {
    "api_endpoint": API_ENDPOINT,
})

schedule = schedules_service_client.create_schedule(parent=PARENT, schedule={
    "display_name": "my-notebook-schedule",

    # Time specification. TZ is optional.
    # cron = "* * * * *" to run it in the next minute.
    "cron": "TZ=America/Los_Angeles * * * * *",

    # How many runs the schedule will trigger before it becomes COMPLETED.
    # A Schedule in COMPLETED state will not trigger any more runs.
    "max_run_count": 1,
    "max_concurrent_run_count": 1,

    "create_notebook_execution_job_request": {
      "parent": PARENT,
      "notebook_execution_job": {
        "display_name": "my-execution-job",

        # Specify a NotebookRuntimeTemplate to source compute configuration from
        "notebook_runtime_template_resource_name": f"projects/{PROJECT_ID}/locations/{LOCATION}/notebookRuntimeTemplates/{template_id}",

        # Specify a Colab Enterprise notebook to run
        "dataformRepositorySource": {
            "dataformRepositoryResourceName": f"projects/{PROJECT_ID}/locations/{LOCATION}/repositories/{repository_id}",
        },

        # Specify a Cloud Storage bucket to store output artifacts
        "gcs_output_uri": "gs://my-bucket/,


        # Specify the identity that runs the notebook
        "execution_user": {EMAIL},

        # Run as the service account instead
        # "service_account": "my-service-account",
    }
  }
})

No console do Google Cloud, é possível conferir suas programações na página Programações. É possível conferir os resultados das execuções de notebooks concluídas na página Execuções.

Ver resultados

Para conferir os resultados da execução do notebook, use o console do Google Cloud, a CLI gcloud ou a biblioteca de clientes Python da Vertex AI.

Console

  1. No console do Google Cloud, acesse a página Execuções do Colab Enterprise.

    Acessar "Execuções"

  2. Ao lado da execução de notebook que você quer conferir, clique em Ver resultado.

    O Colab Enterprise abre o resultado da execução do notebook em uma nova guia.

  3. Para conferir o resultado, clique na guia.

gcloud

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

  • PROJECT_ID: o ID do projeto.
  • REGION: a região em que os resultados da execução do notebook estão localizados.
  • SCHEDULE_NAME: o nome da programação para conferir os resultados. Para conferir os resultados de todas as programações, omita a flag --filter.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud colab executions list --project=PROJECT_ID \
    --region=REGION \
    --filter="scheduleResourceName:SCHEDULE_NAME"

Windows (PowerShell)

gcloud colab executions list --project=PROJECT_ID `
    --region=REGION `
    --filter="scheduleResourceName:SCHEDULE_NAME"

Windows (cmd.exe)

gcloud colab executions list --project=PROJECT_ID ^
    --region=REGION ^
    --filter="scheduleResourceName:SCHEDULE_NAME"

Para mais informações sobre como listar execuções de notebooks do Colab Enterprise na linha de comando, consulte a documentação da CLI gcloud.

Python

Antes de testar este exemplo, instale o SDK da Vertex AI para Python. A biblioteca de cliente Python da Vertex AI é instalada quando você instala o SDK da Vertex AI para Python. Saiba mais na documentação de referência da API SDK da Vertex AI para Python. 

from google.cloud import aiplatform_v1beta1

PROJECT_ID = "my-project"
LOCATION = "us-central1"

API_ENDPOINT = f"{LOCATION}-aiplatform.googleapis.com"
PARENT = f"projects/{PROJECT_ID}/locations/{LOCATION}"

notebook_service_client = aiplatform_v1beta1.NotebookServiceClient(client_options = {
    "api_endpoint": API_ENDPOINT,
})

notebook_execution_jobs = notebook_service_client.list_notebook_execution_jobs(parent=PARENT)
notebook_execution_jobs

Excluir resultados

Para excluir um resultado de uma das execuções do seu notebook, use o console do Google Cloud ou a gcloud CLI.

Console

  1. No console do Google Cloud, acesse a página Execuções do Colab Enterprise.

    Acessar "Execuções"

  2. Selecione a execução do notebook para a qual você quer excluir o resultado.

  3. Clique em  Excluir.

  4. Para confirmar a exclusão, clique em Confirmar.

gcloud

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

  • NOTEBOOK_RUN_ID: o ID da execução do notebook que você quer excluir.
  • PROJECT_ID: o ID do projeto.
  • REGION: a região em que a execução do notebook está localizada.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud colab executions delete NOTEBOOK_RUN_ID \
    --project=PROJECT_ID \
    --region=REGION

Windows (PowerShell)

gcloud colab executions delete NOTEBOOK_RUN_ID `
    --project=PROJECT_ID `
    --region=REGION

Windows (cmd.exe)

gcloud colab executions delete NOTEBOOK_RUN_ID ^
    --project=PROJECT_ID ^
    --region=REGION

Para mais informações sobre como excluir execuções de notebooks do Colab Enterprise na linha de comando, consulte a documentação da CLI gcloud.

Compartilhar os resultados de uma execução de notebook

Compartilhe os resultados da execução do notebook fornecendo acesso ao bucket do Cloud Storage que contém a execução. Fornecer esse acesso também concede aos usuários acesso a quaisquer outros recursos no mesmo bucket do Cloud Storage (consulte Considerações de segurança).

Para mais informações, consulte a página de compartilhamento e colaboração do Cloud Storage.

Considerações sobre segurança

Os resultados da execução do notebook são armazenados como arquivos de notebook (IPYNB) em um bucket do Cloud Storage. Considere o seguinte ao conceder acesso a esse bucket:

  • Qualquer pessoa com acesso ao bucket pode conferir o código do arquivo do notebook e os resultados da execução.

  • Qualquer pessoa com capacidade de alterar o conteúdo do bucket pode mudar o conteúdo do arquivo do bloco de notas.

Quando a programação estiver configurada para usar credenciais pessoais, somente o usuário especificado poderá modificar ou acionar a programação.

Quando a programação estiver configurada para usar uma conta de serviço, somente os usuários com a permissão iam.serviceAccounts.actAs na conta de serviço poderão modificar ou acionar a programação.

Conferir detalhes da programação

Você pode conferir informações sobre uma programação, incluindo:

  • O bucket do Cloud Storage em que a programação armazena resultados.
  • Horário de início e término.
  • A frequência.

Para conferir os detalhes da programação, use o console do Google Cloud ou a gcloud CLI.

Console

  1. No console do Google Cloud, acesse a página Programações do Colab Enterprise.

    Acessar "Programações"

  2. Clique no nome de uma programação.

    A página Detalhes da programação é aberta.

  3. Para voltar à página Programações, clique em  Voltar à página anterior.

gcloud

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

  • SCHEDULE: o ID da sua programação.
  • PROJECT_ID: o ID do projeto.
  • REGION: a região em que a programação está localizada.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud colab schedules describe SCHEDULE \
    --project=PROJECT_ID \
    --region=REGION

Windows (PowerShell)

gcloud colab schedules describe SCHEDULE `
    --project=PROJECT_ID `
    --region=REGION

Windows (cmd.exe)

gcloud colab schedules describe SCHEDULE ^
    --project=PROJECT_ID ^
    --region=REGION

Para mais informações sobre como visualizar os horários do Colab Enterprise na linha de comando, consulte a documentação da CLI gcloud.

Pausar, retomar ou excluir uma programação

Para pausar, retomar ou excluir uma programação, use o console do Google Cloud ou a CLI gcloud.

Console

  1. No console do Google Cloud, acesse a página Programações do Colab Enterprise.

    Acessar "Programações"

  2. Selecione uma programação.

  3. Clique em  Pausar,  Retomar ou  Excluir.

gcloud

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

  • ACTION: um de pause, resume ou delete.
  • SCHEDULE_ID: o ID da sua programação.
  • PROJECT_ID: o ID do projeto.
  • REGION: a região em que a programação está localizada.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud colab schedules ACTION SCHEDULE_ID \
    --project=PROJECT_ID \
    --region=REGION

Windows (PowerShell)

gcloud colab schedules ACTION SCHEDULE_ID `
    --project=PROJECT_ID `
    --region=REGION

Windows (cmd.exe)

gcloud colab schedules ACTION SCHEDULE_ID ^
    --project=PROJECT_ID ^
    --region=REGION

Para mais informações sobre como gerenciar programações do Colab Enterprise na linha de comando, consulte a documentação da CLI gcloud.

A seguir