Crie uma instância com um contentor personalizado
Esta página descreve como criar uma instância do Vertex AI Workbench com base num contentor personalizado.
Vista geral
As instâncias do Vertex AI Workbench suportam a utilização de um contentor personalizado derivado de um dos contentores base fornecidos pela Google. Pode modificar estes contentores base para criar uma imagem de contentor personalizada e usar estes contentores personalizados para criar uma instância do Vertex AI Workbench.
Os contentores de base estão configurados com um SO otimizado para contentores na máquina virtual (VM) do anfitrião. A imagem anfitriã é criada a partir da cos-stable
família de imagens.
Limitações
Considere as seguintes limitações ao planear o seu projeto:
O contentor personalizado tem de ser derivado de um contentor base fornecido pela Google. A utilização de um contentor que não seja derivado de um contentor base aumenta o risco de problemas de compatibilidade e limita a nossa capacidade de apoiar a sua utilização de instâncias do Vertex AI Workbench.
A utilização de mais do que um contentor com uma instância do Vertex AI Workbench não é suportada.
Os metadados suportados para contentores personalizados de blocos de notas geridos pelo utilizador e blocos de notas geridos podem ter um comportamento diferente quando usados com instâncias do Vertex AI Workbench.
A VM que aloja o contentor personalizado está a ser executada num SO otimizado para contentores, o que restringe a forma como pode interagir com o computador anfitrião. Por exemplo, o SO otimizado para contentores não inclui um gestor de pacotes. Isto significa que os pacotes que atuam no anfitrião têm de ser executados num contentor com montagens. Isto afeta os scripts de pós-inicialização migrados de instâncias de blocos de notas geridas e instâncias de blocos de notas geridas pelo utilizador, em que a máquina anfitriã contém significativamente mais ferramentas do que o SO otimizado para contentores.
As instâncias do Vertex AI Workbench usam
nerdctl
(uma CLI do containerd) para executar o contentor personalizado. Isto é necessário para a compatibilidade com o serviço de streaming de imagens. Todos os parâmetros do contentor adicionados através de um valor de metadados têm de estar em conformidade com o que é suportado pelonerdctl
.As instâncias do Vertex AI Workbench estão configuradas para extrair dados do Artifact Registry ou de um repositório de contentores público. Para configurar uma instância para extrair de um repositório privado, tem de configurar manualmente as credenciais usadas pelo containerd.
Contentores base
Contentor base padrão
O contentor base padrão suporta todas as funcionalidades do Vertex AI Workbench e inclui o seguinte:
- Pacotes de ciência de dados pré-instalados.
- Bibliotecas Cuda semelhantes aos Deep Learning Containers.
- Google Cloud Integrações do JupyterLab, como as integrações do Dataproc e do BigQuery.
- Pacotes de sistema comuns, como
curl
ougit
. - Configuração do JupyterLab baseada em metadados.
- Gestão de kernels baseada no Micromamba.
Especificações
O contentor de base padrão tem as seguintes especificações:
- Imagem base:
nvidia/cuda:12.6.1-cudnn-devel-ubuntu24.04
- Tamanho da imagem: aproximadamente 22 GB
- URI:
us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest
Contentor de base compacta
O contentor base reduzido fornece um conjunto mínimo de configurações que permitem uma ligação de proxy à instância. As funcionalidades e os pacotes do Vertex AI Workbench não estão incluídos, exceto os seguintes:
- JupyterLab
- Configuração do JupyterLab baseada em metadados
- Gestão de kernels baseada no Micromamba
Os pacotes adicionais ou as extensões do JupyterLab têm de ser instalados e geridos de forma independente.
Especificações
O contentor de base simples tem as seguintes especificações:
- Imagem base:
marketplace.gcr.io/google/ubuntu24.04
- Tamanho da imagem: aproximadamente 2 GB
- URI:
us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container-slim:latest
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 theresourcemanager.projects.create
permission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
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 theserviceusage.services.enable
permission. Learn how to grant roles. -
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 theresourcemanager.projects.create
permission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
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 theserviceusage.services.enable
permission. Learn how to grant roles. -
Executador de blocos de notas (
roles/notebooks.runner
) na conta de utilizador -
Para extrair imagens do repositório do Artifact Registry:
Leitor do Artifact Registry (
roles/artifactregistry.reader
) na conta de serviço Crie um contentor derivado de uma imagem de contentor base fornecida pela Google.
Crie e envie o contentor para o Artifact Registry. Vai usar o URI do contentor quando criar a instância do Vertex AI Workbench. Por exemplo, o URI pode ter o seguinte aspeto:
gcr.io/PROJECT_ID/IMAGE_NAME
.Na Google Cloud consola, aceda à página Instâncias.
Clique em
Criar novo.Na caixa de diálogo Nova instância, clique em Opções avançadas.
Na caixa de diálogo Criar instância, na secção Ambiente, selecione Usar contentor personalizado.
Para Imagem do contentor Docker, clique em Selecionar.
Na caixa de diálogo Selecionar imagem do contentor, navegue até à imagem do contentor que quer usar e, de seguida, clique em Selecionar.
Opcional. Para o Script de pós-inicialização, introduza um caminho para um script de pós-inicialização que quer usar.
Opcional. Adicione metadados para a sua instância. Para saber mais, consulte o artigo Metadados do contentor personalizado.
Opcional. Na secção Rede, personalize as definições de rede. Para saber mais, consulte as opções de configuração de rede.
Conclua o resto da caixa de diálogo de criação da instância e, de seguida, clique em Criar.
O Vertex AI Workbench cria uma instância e inicia-a automaticamente. Quando a instância estiver pronta para utilização, o Vertex AI Workbench ativa um link Abrir JupyterLab.
-
INSTANCE_NAME
: o nome da sua instância do Vertex AI Workbench; tem de começar por uma letra seguida de até 62 letras minúsculas, números ou hífenes (-) e não pode terminar com um hífen PROJECT_ID
: o ID do seu projetoLOCATION
: a zona onde quer que a sua instância esteja localizada-
CUSTOM_CONTAINER_PATH
: o caminho para o repositório de imagens de contentores, por exemplo:gcr.io/PROJECT_ID/IMAGE_NAME
-
METADATA
: metadados personalizados a aplicar a esta instância; por exemplo, para especificar um script de pós-arranque, pode usar a etiqueta de metadadospost-startup-script
no formato:"--metadata=post-startup-script=gs://BUCKET_NAME/hello.sh"
Crie um novo contentor personalizado:
FROM us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest ENV MAMBA_ROOT_PREFIX=/opt/micromamba RUN micromamba create -n ENVIRONMENT_NAME -c conda-forge python=PYTHON_VERSION -y SHELL ["micromamba", "run", "-n", "ENVIRONMENT_NAME", "/bin/bash", "-c"] RUN micromamba install -c conda-forge pip -y RUN pip install PACKAGE RUN pip install ipykernel RUN python -m ipykernel install --prefix /opt/micromamba/envs/ENVIRONMENT_NAME --name ENVIRONMENT_NAME --display-name KERNEL_NAME # Creation of a micromamba kernel automatically creates a python3 kernel # that must be removed if it's in conflict with the new kernel. RUN rm -rf "/opt/micromamba/envs/ENVIRONMENT_NAME/share/jupyter/kernels/python3"
Adicione o novo contentor ao Artifact Registry:
gcloud auth configure-docker REGION-docker.pkg.dev docker build -t REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME . docker push REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME:latest
Crie uma instância:
gcloud workbench instances create INSTANCE_NAME \ --project=PROJECT_ID \ --location=ZONE \ --container-repository=REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME \ --container-tag=latest
Crie um ambiente micromamba:
micromamba create -p /home/USER/ENVIRONMENT_NAME -c conda-forge python=3.11 -y micromamba activate /home/USER/ENVIRONMENT_NAME pip install ipykernel pip install -r ~/requirement.txt python -m ipykernel install --prefix "/home/USER/ENVIRONMENT_NAME" --display-name "Example Kernel"
Substitua o seguinte:
- USER: o nome do diretório do utilizador, que é
jupyter
por predefinição - ENVIRONMENT_NAME: o nome do ambiente
- PYTHON_VERSION: a versão do Python, por exemplo,
3.11
- USER: o nome do diretório do utilizador, que é
Aguarde entre 30 segundos e 1 minuto para que os kernels sejam atualizados.
Certifique-se de que o JupyterLab está configurado para a porta 8080. O nosso agente de proxy está configurado para encaminhar qualquer pedido para a porta 8080 e, se o servidor Jupyter não estiver a ouvir a porta correta, a instância encontra problemas de aprovisionamento.
Modifique os pacotes do JupyterLab no ambiente
jupyterlab
micromamba. Disponibilizamos um ambiente de pacote separado para executar o JupyterLab e o respetivo plug-in para garantir que não existem conflitos de dependências com o ambiente do kernel. Se quiser instalar uma extensão adicional do JupyterLab, tem de a instalar no ambientejupyterlab
. Por exemplo:# DockerFile FROM us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest RUN micromamba activate jupyterlab && \ jupyter nbextension install nbdime
true
: ativa o FUSE do Cloud Storage.false
(predefinição): não ativa o FUSE do Cloud Storage.Use o SSH para se ligar à sua instância do Vertex AI Workbench.
No terminal SSH, execute o seguinte comando:
sudo docker exec diagnostic-service ./diagnostic_tool
Para ver opções de comandos adicionais, execute o seguinte comando:
sudo docker exec diagnostic-service ./diagnostic_tool --help
-
INSTANCE_NAME
: o nome da sua instância do Vertex AI Workbench PROJECT_ID
: o ID do seu projetoLOCATION
: a zona onde a sua instância está localizada
Funções necessárias
Para receber as autorizações de que precisa para criar uma instância do Vertex AI Workbench com um contentor personalizado, peça ao seu administrador para lhe conceder as seguintes funções de IAM:
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.
Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.
Crie um contentor personalizado
Para criar um contentor personalizado para utilização com instâncias do Vertex AI Workbench:
Crie a instância
Pode criar uma instância do Vertex AI Workbench com base num contentor personalizado através da Google Cloud consola ou da CLI Google Cloud.
Consola
Para criar uma instância do Vertex AI Workbench com base num contentor personalizado, faça o seguinte:
gcloud
Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:
Execute o seguinte comando:
Linux, macOS ou Cloud Shell
gcloud workbench instances create INSTANCE_NAME \ --project=PROJECT_ID \ --location=LOCATION \ --container-repository=CUSTOM_CONTAINER_URL \ --container-tag=latest \ --metadata=METADATA
Windows (PowerShell)
gcloud workbench instances create INSTANCE_NAME ` --project=PROJECT_ID ` --location=LOCATION ` --container-repository=CUSTOM_CONTAINER_URL ` --container-tag=latest ` --metadata=METADATA
Windows (cmd.exe)
gcloud workbench instances create INSTANCE_NAME ^ --project=PROJECT_ID ^ --location=LOCATION ^ --container-repository=CUSTOM_CONTAINER_URL ^ --container-tag=latest ^ --metadata=METADATA
Para mais informações sobre o comando para criar uma instância a partir da linha de comandos, consulte a documentação da CLI gcloud.
O Vertex AI Workbench cria uma instância e inicia-a automaticamente. Quando a instância estiver pronta a usar, o Vertex AI Workbench ativa um link Abrir JupyterLab na Google Cloud consola.
Opções de configuração de rede
Além das opções de rede gerais, uma instância do Vertex AI Workbench com um contentor personalizado tem de ter acesso ao serviço Artifact Registry.
Se tiver desativado o acesso ao IP público para a sua VPC, certifique-se de que ativou o acesso privado à Google.
Ative o streaming de imagens
O anfitrião do contentor personalizado é aprovisionado para interagir com o streaming de imagens no Google Kubernetes Engine (GKE), que extrai contentores mais rapidamente e reduz o tempo de inicialização para contentores grandes assim que são colocados em cache no sistema de ficheiros remoto do GKE.
Para ver os requisitos para ativar o streaming de imagens, consulte a secção Requisitos. Muitas vezes, o streaming de imagens pode ser usado com instâncias do Vertex AI Workbench ativando a API Container File System.
Ative a API Container File System
Como a VM anfitriã executa o contentor personalizado
Em vez de usar o Docker para executar o contentor personalizado, a VM anfitriã usa o nerdctl
no espaço de nomes do Kubernetes para carregar e executar o contentor. Isto permite que o Vertex AI Workbench use o streaming de imagens para contentores personalizados.
# Runs the custom container. sudo /var/lib/google/nerdctl/nerdctl --snapshotter=gcfs -n k8s.io run --name payload-container
Exemplo de instalação: contentor personalizado com um kernel predefinido personalizado
O exemplo seguinte mostra como criar um novo kernel com um pacote pip pré-instalado.
Kernels persistentes para contentores personalizados
Os contentores personalizados do Vertex AI Workbench apenas montam um disco de dados no diretório /home/USER
em cada contentor, onde jupyter
é o utilizador predefinido. Isto significa que
qualquer alteração fora de /home/USER
é efémera e
não é mantida após um reinício. Se precisar que os pacotes instalados persistam para um kernel específico, pode criar um kernel no diretório /home/USER
.
Para criar um kernel no diretório /home/USER
:
Atualizar o arranque do contentor base
O contentor base de uma instância do Vertex AI Workbench
(us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest
)
inicia o JupyterLab executando /run_jupyter.sh
.
Se modificar o arranque do contentor num contentor derivado, tem de
anexar /run_jupyter.sh
para executar a configuração predefinida do JupyterLab.
Segue-se um exemplo de como o Dockerfile pode ser modificado:
# DockerFile FROM us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest CP startup_file.sh / # Ensure that you have the correct permissions and startup is executable. RUN chmod 755 /startup_file.sh && \ chown jupyter:jupyter /startup_file.sh # Override the existing CMD directive from the base container. CMD ["/startup_file.sh"]
# /startup_file.sh
echo "Running startup scripts"
...
/run_jupyter.sh
Atualizar a configuração do JupyterLab no contentor base
Se precisar de modificar a configuração do JupyterLab no contentor base, tem de fazer o seguinte:
Metadados do contentor personalizados
Além da lista padrão de metadados que podem ser aplicados a uma instância do Vertex AI Workbench, as instâncias com contentores personalizados incluem os seguintes metadados para gerir a instanciação do contentor de payload:
Funcionalidade | Descrição | Chave de metadados | Valores aceites e predefinições |
---|---|---|---|
Ativa o FUSE do Cloud Storage numa imagem de contentor |
Monta |
container-allow-fuse |
|
Parâmetros de execução do contentor adicionais |
Anexa parâmetros de contentor adicionais a |
container-custom-params |
Uma string de parâmetros de execução do contentor. Exemplo:
|
Flags do ambiente do contentor adicionais |
Armazena variáveis de ambiente numa flag em
|
container-env-file |
Uma string de variáveis de ambiente do contentor. Exemplo:
|
Atualize um contentor personalizado
Quando a instância é iniciada pela primeira vez, extrai a imagem do contentor de um URI armazenado nos metadados custom-container-payload
.
Se usar a etiqueta :latest
, o contentor é atualizado a cada reinício. Não é possível modificar diretamente o custom-container-payload
valor dos metadados
porque é uma
chave de metadados protegida.
Para atualizar a imagem do contentor personalizada da sua instância, pode usar os seguintes métodos suportados pela CLI Google Cloud, pelo Terraform ou pela API Notebooks.
gcloud
Pode atualizar os metadados da imagem do contentor personalizado numa instância do Vertex AI Workbench através do seguinte comando:
gcloud workbench instances update INSTANCE_NAME \ --container-repository=CONTAINER_URI \ --container-tag=CONTAINER_TAG
Terraform
Pode alterar o campo container_image
na configuração do Terraform para atualizar a carga útil do contentor.
Para saber como aplicar ou remover uma configuração do Terraform, consulte os 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" container_image { repository = "us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container" family = "latest" } } }
API Notebooks
Use o método instances.patch
com alterações a gce_setup.container_image.repository
e gce_setup.container_image.tag
no updateMask
.
Execute a ferramenta de diagnóstico
A ferramenta de diagnóstico verifica o estado de vários serviços do Vertex AI Workbench. Para saber mais, consulte Tarefas realizadas pela ferramenta de diagnóstico.
Quando cria uma instância do Vertex AI Workbench com um contentor personalizado, a ferramenta de diagnóstico não está disponível como um script no ambiente de anfitrião que os utilizadores podem executar. Em alternativa, é compilado num ficheiro binário e carregado num contentor de tempo de execução da Google criado para executar serviços de diagnóstico num ambiente do SO otimizado para contentores. Consulte a descrição geral do SO otimizado para contentores.
Para executar a ferramenta de diagnóstico, conclua os passos seguintes:
Para mais informações sobre as opções da ferramenta de diagnóstico, consulte a documentação de monitorização do estado de funcionamento.
Para executar a ferramenta de diagnóstico através da API REST, consulte a documentação da API REST.
Aceda à sua instância
Pode aceder à sua instância através de um URL de proxy.
Depois de criar a instância e esta estar ativa, pode obter o URL do proxy através da CLI gcloud.
Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:
Execute o seguinte comando:
Linux, macOS ou Cloud Shell
gcloud workbench instances describe INSTANCE_NAME \ --project=PROJECT_ID \ --location=LOCATION | grep proxy-url
Windows (PowerShell)
gcloud workbench instances describe INSTANCE_NAME ` --project=PROJECT_ID ` --location=LOCATION | grep proxy-url
Windows (cmd.exe)
gcloud workbench instances describe INSTANCE_NAME ^ --project=PROJECT_ID ^ --location=LOCATION | grep proxy-url
proxy-url: 7109d1b0d5f850f-dot-datalab-vm-staging.googleusercontent.com
O comando describe
devolve o URL de proxy. Para aceder à instância, abra o URL do proxy num navegador de Internet.
Para mais informações sobre o comando para descrever uma instância a partir da linha de comando, consulte a documentação da CLI gcloud.