Esta página foi traduzida pela API Cloud Translation.

Usar um script pós-inicialização

Este guia descreve como usar um script pós-inicialização com o Colab Enterprise. Este guia também descreve como definir variáveis de ambiente para uso com o script de pós-inicialização.

Visão geral

É possível usar um script pós-inicialização para realizar tarefas após o processo de inicialização do ambiente de execução do Colab Enterprise. Por exemplo, é possível usar um script pós-inicialização para instalar pacotes específicos ou fazer mudanças específicas na VM do seu ambiente de execução.

Para usar um script pós-inicialização no Colab Enterprise, especifique o script de inicialização ao criar um modelo de ambiente de execução. Depois, quando você cria um ambiente de execução com base nesse modelo, o script pós-inicialização é executado no final do processo de inicialização.

Local do script pós-inicialização

O URI do script de pós-inicialização pode ser qualquer um dos seguintes:

Um URI do Cloud Storage: por exemplo, gs://BUCKET_NAME/SCRIPT_FILE_NAME. Se o script pós-inicialização estiver armazenado no Cloud Storage, use um ambiente de execução com credenciais de usuário final ativadas. Isso acontece porque o Colab Enterprise usa suas credenciais de usuário para acessar o bucket do Cloud Storage.
Um URL HTTPS: por exemplo, https://example.com/FOLDER_NAME/SCRIPT_FILE_NAME. Não é possível usar um URL HTTPS ao criar seu modelo de tempo de execução usando o console do Google Cloud .

Comportamento do script de pós-inicialização

É possível especificar o comportamento do script pós-inicialização. Confira a tabela a seguir:

Comportamento	Descrição
Executar uma vez (`RUN_ONCE`)	Padrão. O Colab Enterprise executa o script pós-inicialização apenas uma vez, durante a criação do ambiente de execução.
Executar a cada início (`RUN_EVERY_START`)	Após cada inicialização, o Colab Enterprise executa o script de pós-inicialização. Por exemplo, se o encerramento por inatividade interromper o ambiente de execução, o Colab Enterprise vai executar o script pós-inicialização novamente quando o ambiente de execução for reiniciado.
Fazer o download e executar a cada início (`DOWNLOAD_AND_RUN_EVERY_START`)	Após cada inicialização, o Colab Enterprise baixa novamente o script pós-inicialização da fonte e o executa.

Variáveis de ambiente

É possível especificar variáveis de ambiente no modelo de tempo de execução e fazer referência a elas no script pós-inicialização.

Por exemplo, é possível definir o projeto de cota usando uma variável de ambiente. É possível definir o projeto de cota para um ID do projeto específico usando GOOGLE_CLOUD_QUOTA_PROJECT, uma variável comum usada em bibliotecas de cliente Google Cloud.

Para usar um script pós-inicialização com variáveis de ambiente, consulte Criar um modelo de execução com um script pós-inicialização e variáveis de ambiente.

Acompanhar mudanças e recuperar scripts de pós-inicialização

Para rastrear mudanças no script de pós-inicialização e permitir a recuperação de uma versão específica dele, armazene o script de inicialização em um bucket do Cloud Storage com o controle de versões de objetos ativado. O controle de versões de objetos preserva objetos excluídos como objetos não atuais e com controle de versão que permanecem acessíveis no bucket até serem removidos explicitamente.

Para especificar uma versão do script pós-inicialização, adicione #GENERATION_NUMBER ao URI do script ao criar o modelo de ambiente de execução, por exemplo, gs://BUCKET_NAME/FOLDER_NAME/FILE_NAME.py#GENERATION_NUMBER. Para mais informações sobre o controle de versões de objetos e números de geração, consulte Controle de versões de objetos.

Não é possível especificar um número de geração para o script de pós-inicialização ao usar o console Google Cloud para criar o modelo de ambiente de execução.

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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Dataform, and Compute Engine 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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Dataform, and Compute Engine 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 exigidas

Para receber as permissões necessárias para criar um modelo de ambiente de execução no Colab Enterprise, peça ao administrador para conceder a você o papel de Administrador do Colab Enterprise (roles/aiplatform.colabEnterpriseAdmin) 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.

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

Um ou mais dos papéis necessários incluem a permissão dataform.repositories.list. Os usuários que recebem a permissão dataform.repositories.list ou o papel de criador de código (roles/dataform.codeCreator) em um projeto podem listar os nomes dos recursos de código nesse projeto usando a API Dataform ou a interface de linha de comando (CLI) do Dataform. Os não administradores que usam o BigQuery Studio só podem ver os recursos de código que criaram ou que foram compartilhados com eles.

Criar um modelo de ambiente de execução que use um script pós-inicialização

Para criar um modelo de tempo de execução que usa um script pós-inicialização, use o console Google Cloud , a Google Cloud CLI ou a API REST.

Console

Para criar um modelo de ambiente de execução que usa um script pós-inicialização, faça o seguinte:

No console do Google Cloud , acesse a página Modelos de ambiente de execução do Colab Enterprise.

Acessar "Modelos de ambiente de execução"
Clique em Novo modelo.

A caixa de diálogo Criar novo modelo de ambiente de execução será exibida.
Na seção Fundamentos do ambiente de execução, insira um Nome de exibição.
No menu Região, selecione a região em que você quer o modelo de ambiente de execução.
Na seção Ambiente, no campo Script de pós-inicialização, clique em Procurar e navegue até um script de pós-inicialização localizado no Cloud Storage. Para mais informações, consulte Local do script de inicialização-inicialização.
Em "URL do script de pós-inicialização", selecione o comportamento do script de pós-inicialização. O comportamento padrão é Executar uma vez. Para mais informações, consulte Comportamento do script de inicialização inicialização.
Na seção Rede e segurança, verifique se a opção Ativar credenciais do usuário final está selecionada.
Preencha o restante da caixa de diálogo e clique em Criar.

Seu modelo de ambiente de execução aparece na lista da guia Modelos de ambiente de execução.

gcloud

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

DISPLAY_NAME: o nome de exibição do modelo de tempo de execução.
PROJECT_ID: o ID do projeto.
REGION: a região em que você quer o modelo de tempo de execução.
POST_STARTUP_SCRIPT_URI: o URI do script pós-inicialização. Para mais informações, consulte Local do script de inicialização-inicialização.
POST_STARTUP_SCRIPT_BEHAVIOR: o comportamento do script pós-inicialização. Consulte Comportamento do script de inicialização-inicialização.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud colab runtime-templates create --display-name="DISPLAY_NAME" \
    --project=PROJECT_ID \
    --region=REGION \
    --machine-type=e2-standard-4 \
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI \
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR

Windows (PowerShell)

gcloud colab runtime-templates create --display-name="DISPLAY_NAME" `
    --project=PROJECT_ID `
    --region=REGION `
    --machine-type=e2-standard-4 `
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI `
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR

Windows (cmd.exe)

gcloud colab runtime-templates create --display-name="DISPLAY_NAME" ^
    --project=PROJECT_ID ^
    --region=REGION ^
    --machine-type=e2-standard-4 ^
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI ^
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR

Para mais informações sobre o comando para criar um modelo de tempo de execução usando a linha de comando, consulte a documentação da CLI gcloud.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

REGION: a região em que você quer o modelo de tempo de execução.
PROJECT_ID: o ID do projeto.
DISPLAY_NAME: o nome de exibição do modelo de tempo de execução.
POST_STARTUP_SCRIPT_URI: o URI do script pós-inicialização. Para mais informações, consulte Local do script de inicialização-inicialização.
POST_STARTUP_SCRIPT_BEHAVIOR: o comportamento do script pós-inicialização. Consulte Comportamento do script de inicialização-inicialização.

Método HTTP e URL:

POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates

Corpo JSON da solicitação:

{
  "displayName": "DISPLAY_NAME",
  "machineSpec": {
    "machineType": "e2-standard-4"
  },
  softwareConfig: {
    postStartupScriptConfig: {
      postStartupScriptUrl: "POST_STARTUP_SCRIPT_URI",
      postStartupScriptBehavior: "POST_STARTUP_SCRIPT_BEHAVIOR"
    },
  },
  "networkSpec": {
    "enableInternetAccess": true
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Observação: o comando a seguir pressupõe que você tenha feito login na gcloud CLI com sua conta de usuário executando gcloud init ou gcloud auth login ou usando o Cloud Shell, que faz login automaticamente na gcloud CLI. Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates"

PowerShell

Observação: o comando a seguir pressupõe que você fez login na gcloud CLI com sua conta de usuário executando gcloud init ou gcloud auth login. Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates" | Select-Object -Expand Content

Se a solicitação for bem-sucedida, o corpo da resposta conterá uma instância de Operation.

Para mais informações, consulte a documentação da API REST do notebookRuntimeTemplates.create.

Criar o ambiente de execução

Depois de criar um modelo de ambiente de execução que use seu script pós-inicialização, crie um ambiente de execução com base nesse modelo. O ambiente de execução é iniciado, e o script pós-inicialização é executado de acordo com o comportamento especificado. Consulte Criar um ambiente de execução.

Criar um modelo de ambiente de execução com um script pós-inicialização e variáveis de ambiente

Para criar um modelo de execução que use um script pós-inicialização e variáveis de ambiente, use o console Google Cloud , a Google Cloud CLI ou a API REST.