Creazione di un'istanza utilizzando un container personalizzato
Questa pagina descrive come creare un'istanza di Vertex AI Workbench basata su un contenitore personalizzato.
Panoramica
Le istanze Vertex AI Workbench supportano l'utilizzo di un container personalizzato derivato da uno dei container di base forniti da Google. Puoi modificare questi container di base per creare un'immagine container personalizzata e utilizzare questi container personalizzati per creare un'istanza di Vertex AI Workbench.
I container di base sono configurati con un Container-Optimized
OS nella macchina virtuale (VM) host. L'immagine host è creata a partire dalla cos-stable
famiglia di immagini.
Limitazioni
Quando pianifichi il tuo progetto, tieni presente le seguenti limitazioni:
Il container personalizzato deve essere derivato da un container di base fornito da Google. L'utilizzo di un container non derivato da un container di base aumenta il rischio di problemi di compatibilità e limita la nostra capacità di supportare l'utilizzo delle istanze di Vertex AI Workbench.
L'utilizzo di più di un container con un'istanza Vertex AI Workbench non è supportato.
I metadati supportati per i container personalizzati dei notebook gestiti dall'utente e dei notebook gestiti possono avere un comportamento diverso se utilizzati con le istanze Vertex AI Workbench.
La VM che ospita il container personalizzato viene eseguita su Container-Optimized OS, che limita il modo in cui puoi interagire con la macchina host. Ad esempio, Container-Optimized OS non include un gestore di pacchetti. Ciò significa che i pacchetti che agiscono sull'host devono essere eseguiti su un container con montaggi. Ciò influisce sugli script post-avvio di cui viene eseguita la migrazione dalle istanze di notebook gestiti e dalle istanze di notebook gestiti dall'utente, in cui la macchina host contiene molti più strumenti rispetto a Container-Optimized OS.
Le istanze Vertex AI Workbench utilizzano
nerdctl
(un'interfaccia a riga di comando containerd) per l'esecuzione del container personalizzato. Questo è necessario per la compatibilità con il servizio di streaming delle immagini. Tutti i parametri del contenitore aggiunti utilizzando un valore dei metadati devono rispettare ciò che è supportato danerdctl
.Le istanze Vertex AI Workbench sono configurate per eseguire il pull da Artifact Registry o da un repository di container pubblico. Per configurare un'istanza in modo che estragga da un repository privato, devi configurare manualmente le credenziali utilizzate da containerd.
Container di base
Contenitore base standard
Il container di base standard supporta tutte le funzionalità di Vertex AI Workbench e include quanto segue:
- Pacchetti di data science preinstallati.
- Librerie Cuda simili a Deep Learning Containers.
- Google Cloud Integrazioni di JupyterLab come quelle di Dataproc e BigQuery.
- Pacchetti di sistema comuni come
curl
ogit
. - Configurazione di JupyterLab basata sui metadati.
- Gestione del kernel basata su micromamba.
Specifiche
Il contenitore base standard ha le seguenti specifiche:
- Immagine di base:
nvidia/cuda:12.6.1-cudnn-devel-ubuntu24.04
- Dimensioni dell'immagine: circa 22 GB
- URI:
us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest
Contenitore base sottile
Il contenitore di base slim fornisce un insieme minimo di configurazioni che consentono una connessione proxy all'istanza. Le funzionalità e i pacchetti standard di Vertex AI Workbench non sono inclusi, ad eccezione di quanto segue:
- JupyterLab
- Configurazione di JupyterLab basata sui metadati
- Gestione del kernel basata su micromamba
I pacchetti aggiuntivi o le estensioni JupyterLab devono essere installati e gestiti in modo indipendente.
Specifiche
Il contenitore base sottile ha le seguenti specifiche:
- Immagine di base:
marketplace.gcr.io/google/ubuntu24.04
- Dimensioni dell'immagine: circa 2 GB
- URI:
us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container-slim:latest
Prima di iniziare
- 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.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Notebooks API.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Notebooks API.
-
Notebooks Runner (
roles/notebooks.runner
) sull'account utente -
Per eseguire il pull delle immagini dal repository Artifact Registry:
Lettore Artifact Registry (
roles/artifactregistry.reader
) sul account di servizio Crea un container derivato da un'immagine container di base fornita da Google.
Crea ed esegui il push del container in Artifact Registry. Utilizzerai l'URI del container quando crei l'istanza Vertex AI Workbench. Ad esempio, l'URI potrebbe avere il seguente aspetto:
gcr.io/PROJECT_ID/IMAGE_NAME
.Nella console Google Cloud , vai alla pagina Istanze.
Fai clic su
Crea nuova.Nella finestra di dialogo Nuova istanza, fai clic su Opzioni avanzate.
Nella finestra di dialogo Crea istanza, nella sezione Ambiente, seleziona Usa contenitore personalizzato.
Per Immagine container Docker, fai clic su Seleziona.
Nella finestra di dialogo Seleziona immagine container, vai all'immagine container che vuoi utilizzare, quindi fai clic su Seleziona.
Facoltativo. Per Script post-avvio, inserisci un percorso a uno script post-avvio che vuoi utilizzare.
Facoltativo. Aggiungi metadati per l'istanza. Per saperne di più, consulta Metadati personalizzati del contenitore.
Facoltativo. Nella sezione Networking, personalizza le impostazioni di rete. Per saperne di più, consulta Opzioni di configurazione di rete.
Completa il resto della finestra di dialogo di creazione dell'istanza e poi fai clic su Crea.
Vertex AI Workbench crea un'istanza e la avvia automaticamente. Quando l'istanza è pronta per l'uso, Vertex AI Workbench attiva un link Apri JupyterLab.
-
INSTANCE_NAME
: il nome dell'istanza Vertex AI Workbench; deve iniziare con una lettera seguita da un massimo di 62 lettere minuscole, numeri o trattini (-) e non può terminare con un trattino PROJECT_ID
: il tuo ID progettoLOCATION
: la zona in cui vuoi che si trovi l'istanza-
CUSTOM_CONTAINER_PATH
: il percorso del repository dell'immagine container, ad esempio:gcr.io/PROJECT_ID/IMAGE_NAME
-
METADATA
: metadati personalizzati da applicare a questa istanza; ad esempio, per specificare uno script post-startup, puoi utilizzare il tag di metadatipost-startup-script
nel formato:"--metadata=post-startup-script=gs://BUCKET_NAME/hello.sh"
Crea un nuovo container personalizzato:
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"
Aggiungi il nuovo contenitore ad 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
Crea un'istanza:
gcloud workbench instances create INSTANCE_NAME \ --project=PROJECT_ID \ --location=ZONE \ --container-repository=REGION-docker.pkg.dev/PROJECT_ID/IMAGE_NAME \ --container-tag=latest
Crea un 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"
Sostituisci quanto segue:
- USER: il nome della directory utente, che per impostazione predefinita è
jupyter
- ENVIRONMENT_NAME: il nome dell'ambiente
- PYTHON_VERSION: la versione di Python, ad esempio
3.11
- USER: il nome della directory utente, che per impostazione predefinita è
Attendi da 30 secondi a 1 minuto affinché i kernel si aggiornino.
Assicurati che JupyterLab sia configurato per la porta 8080. Il nostro agente proxy è configurato per inoltrare qualsiasi richiesta alla porta 8080 e se il server Jupyter non è in ascolto sulla porta corretta, l'istanza riscontra problemi di provisioning.
Modifica i pacchetti JupyterLab nell'ambiente
jupyterlab
micromamba. Forniamo un ambiente di pacchetti separato per eseguire JupyterLab e il relativo plug-in per garantire che non vi siano conflitti di dipendenze con l'ambiente del kernel. Se vuoi installare un'estensione JupyterLab aggiuntiva, devi installarla nell'ambientejupyterlab
. Ad esempio:# DockerFile FROM us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest RUN micromamba activate jupyterlab && \ jupyter nbextension install nbdime
true
: attiva Cloud Storage FUSE.false
(impostazione predefinita): non abilita Cloud Storage FUSE.Utilizza SSH per connetterti all'istanza di Vertex AI Workbench.
Nel terminale SSH, esegui il seguente comando:
sudo docker exec diagnostic-service ./diagnostic_tool
Per visualizzare altre opzioni di comando, esegui questo comando:
sudo docker exec diagnostic-service ./diagnostic_tool --help
-
INSTANCE_NAME
: il nome dell'istanza Vertex AI Workbench PROJECT_ID
: il tuo ID progettoLOCATION
: la zona in cui si trova l'istanza
Ruoli obbligatori
Per ottenere le autorizzazioni necessarie per creare un'istanza Vertex AI Workbench con un container personalizzato, chiedi all'amministratore di concederti i seguenti ruoli IAM:
Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.
Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.
Creazione di un container personalizzato
Per creare un contenitore personalizzato da utilizzare con le istanze Vertex AI Workbench:
Crea l'istanza
Puoi creare un'istanza Vertex AI Workbench basata su un container personalizzato utilizzando la console Google Cloud o Google Cloud CLI.
Console
Per creare un'istanza di Vertex AI Workbench basata su un container personalizzato, svolgi i seguenti passaggi:
gcloud
Prima di utilizzare i dati dei comandi riportati di seguito, apporta le seguenti sostituzioni:
Esegui questo comando:
Linux, macOS o 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
Per ulteriori informazioni sul comando per creare un'istanza dalla riga di comando, consulta la documentazione della CLI gcloud.
Vertex AI Workbench crea un'istanza e la avvia automaticamente. Quando l'istanza è pronta per l'uso, Vertex AI Workbench attiva un link Apri JupyterLab nella console Google Cloud .
Opzioni di configurazione di rete
Oltre alle opzioni di rete generali, un'istanza di Vertex AI Workbench con un container personalizzato deve avere accesso al servizio Artifact Registry.
Se hai disattivato l'accesso IP pubblico per il tuo VPC, assicurati di aver abilitato l'accesso privato Google.
Abilita flusso immagine
L'host container personalizzato viene sottoposto a provisioning per interagire con lo streaming di immagini in Google Kubernetes Engine (GKE), che estrae i container più velocemente e riduce il tempo di inizializzazione per i container di grandi dimensioni una volta memorizzati nella cache nel file system remoto GKE.
Per visualizzare i requisiti per l'attivazione dello streaming di immagini, consulta Requisiti. Spesso, lo streaming di immagini può essere utilizzato con le istanze di Vertex AI Workbench attivando l'API Container File System.
Abilita l'API Container File System
Come la VM host esegue il container personalizzato
Anziché utilizzare Docker per eseguire il container personalizzato, la VM host utilizza
nerdctl
nello spazio dei nomi Kubernetes per caricare ed eseguire il
container. In questo modo, Vertex AI Workbench può utilizzare
lo streaming di immagini per i container personalizzati.
# Runs the custom container. sudo /var/lib/google/nerdctl/nerdctl --snapshotter=gcfs -n k8s.io run --name payload-container
Installazione di esempio: container personalizzato con un kernel predefinito personalizzato
Il seguente esempio mostra come creare un nuovo kernel con un pacchetto pip preinstallato.
Kernel persistenti per container personalizzati
I contenitori personalizzati di Vertex AI Workbench montano solo un disco di dati nella directory /home/USER
all'interno di ogni contenitore, dove jupyter
è l'utente predefinito. Ciò significa che
qualsiasi modifica al di fuori di /home/USER
è temporanea e
non verrà mantenuta dopo un riavvio. Se vuoi che i pacchetti installati vengano mantenuti
per un kernel specifico, puoi creare un kernel nella
directory /home/USER
.
Per creare un kernel nella directory /home/USER
:
Aggiornamento dell'avvio del container di base
Il container di base per un'istanza di Vertex AI Workbench
(us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest
)
avvia JupyterLab eseguendo /run_jupyter.sh
.
Se modifichi l'avvio del container in un container derivato, devi
aggiungere /run_jupyter.sh
per eseguire la configurazione predefinita di JupyterLab.
Di seguito è riportato un esempio di come potrebbe essere modificato il Dockerfile:
# 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
Aggiornamento della configurazione di JupyterLab all'interno del container di base
Se devi modificare la configurazione di JupyterLab nel container di base, devi procedere nel seguente modo:
Metadati del container personalizzati
Oltre all'elenco standard di metadati che possono essere applicati a un'istanza Vertex AI Workbench, le istanze con container personalizzati includono i seguenti metadati per la gestione dell'istanza del container di payload:
Funzionalità | Descrizione | Chiave dei metadati | Valori accettati e predefiniti |
---|---|---|---|
Abilita Cloud Storage FUSE su un'immagine container |
Monta |
container-allow-fuse |
|
Parametri di esecuzione del container aggiuntivi |
Aggiunge parametri del container aggiuntivi a |
container-custom-params |
Una stringa di parametri di esecuzione del container. Esempio:
|
Flag aggiuntivi per l'ambiente dei container |
Memorizza le variabili di ambiente in un flag in
|
container-env-file |
Una stringa di variabili di ambiente del container. Esempio:
|
Eseguire l'upgrade di un container personalizzato
Quando l'istanza viene avviata per la prima volta, recupera l'immagine container
da un URI archiviato nei metadati custom-container-payload
.
Se utilizzi il tag :latest
, il container viene aggiornato a
ogni riavvio. Il valore dei metadati custom-container-payload
non può essere modificato direttamente perché è una chiave di metadati protetta.
Per aggiornare l'immagine container personalizzata dell'istanza, puoi utilizzare i seguenti metodi supportati da Google Cloud CLI, Terraform o dall'API Notebooks.
gcloud
Puoi aggiornare i metadati dell'immagine container personalizzata su un'istanza di Vertex AI Workbench utilizzando il seguente comando:
gcloud workbench instances update INSTANCE_NAME \ --container-repository=CONTAINER_URI \ --container-tag=CONTAINER_TAG
Terraform
Puoi modificare il campo container_image
nella configurazione di Terraform
per aggiornare il payload del container.
Per scoprire come applicare o rimuovere una configurazione Terraform, consulta Comandi Terraform di base.
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
Utilizza il metodo instances.patch
con modifiche a gce_setup.container_image.repository
e gce_setup.container_image.tag
in updateMask
.
Esegui lo strumento di diagnostica
Lo strumento di diagnostica controlla e verifica lo stato di vari servizi Vertex AI Workbench. Per saperne di più, vedi Attività eseguite dallo strumento di diagnostica.
Quando crei un'istanza di Vertex AI Workbench utilizzando un container personalizzato, lo strumento di diagnostica non è disponibile come script nell'ambiente host che gli utenti possono eseguire. Viene invece compilato in un file binario e caricato in un container runtime Google creato per eseguire servizi di diagnostica in un ambiente Container-Optimized OS. Consulta la panoramica di Container-Optimized OS.
Per eseguire lo strumento di diagnostica, completa i seguenti passaggi:
Per saperne di più sulle opzioni dello strumento di diagnostica, consulta la documentazione sullo stato di integrità del monitoraggio.
Per eseguire lo strumento di diagnostica utilizzando l'API REST, consulta la documentazione dell'API REST.
Accedere all'istanza
Puoi accedere alla tua istanza tramite un URL proxy.
Una volta creata e attivata l'istanza, puoi ottenere l'URL proxy utilizzando gcloud CLI.
Prima di utilizzare i dati dei comandi riportati di seguito, apporta le seguenti sostituzioni:
Esegui questo comando:
Linux, macOS o 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
Il comando describe
restituisce l'URL del proxy. Per accedere alla tua istanza, apri l'URL del proxy in un browser web.
Per saperne di più sul comando per descrivere un'istanza dalla riga di comando, consulta la documentazione della CLI gcloud.