Instanz mit einem benutzerdefinierten Container erstellen
Auf dieser Seite wird beschrieben, wie Sie eine Vertex AI Workbench-Instanz basierend auf einem benutzerdefinierten Container erstellen.
Übersicht
Vertex AI Workbench-Instanzen unterstützen die Verwendung eines benutzerdefinierten Containers, der von einem der von Google bereitgestellten Basiscontainer abgeleitet ist. Sie können diese Basiscontainer ändern, um ein benutzerdefiniertes Container-Image zu erstellen, und diese benutzerdefinierten Container verwenden, um eine Vertex AI Workbench-Instanz zu erstellen.
Die Basiscontainer sind mit einem Container-Optimized OS auf der virtuellen Hostmaschine (VM) konfiguriert. Das Host-Image wird aus der cos-stable
-Image-Familie erstellt.
Beschränkungen
Beachten Sie beim Planen Ihres Projekts die folgenden Einschränkungen:
Der benutzerdefinierte Container muss von einem von Google bereitgestellten Basiscontainer abgeleitet sein. Die Verwendung eines Containers, der nicht von einem Basiscontainer abgeleitet ist, erhöht das Risiko von Kompatibilitätsproblemen und schränkt unsere Möglichkeiten ein, Sie bei der Verwendung von Vertex AI Workbench-Instanzen zu unterstützen.
Verwendung mehrerer Container mit einer Vertex AI Workbench-Instanz wird nicht unterstützt.
Unterstützte Metadaten für benutzerdefinierte Container aus nutzerverwalteten Notebooks und verwalteten Notebooks können sich bei der Verwendung mit Vertex AI Workbench-Instanzen unterschiedlich verhalten.
Die VM, auf der der benutzerdefinierte Container gehostet wird, wird mit einem Container-Optimized OS ausgeführt. Dadurch wird eingeschränkt, wie Sie mit dem Hostcomputer interagieren können. Container-Optimized OS enthält beispielsweise keinen Paketmanager. Das bedeutet, dass Pakete, die auf den Host wirken, in einem Container mit Mounts ausgeführt werden müssen. Dies betrifft die Post-Startup-Skripts, die von verwalteten Notebook-Instanzen und von nutzerverwalteten Notebook-Instanzen migriert werden, da die Hostmaschine deutlich mehr Tools als Container-Optimized OS enthält.
Vertex AI Workbench-Instanzen verwenden
nerdctl
(eine containerd-Befehlszeilenschnittstelle) zum Ausführen des benutzerdefinierten Containers. Dies ist für die Kompatibilität mit dem Bild-Streamingdienst erforderlich. Alle Containerparameter, die mit einem Metadatenwert hinzugefügt werden, müssen den vonnerdctl
unterstützten Parametern entsprechen.Vertex AI Workbench-Instanzen sind so konfiguriert, dass sie entweder aus Artifact Registry oder aus einem öffentlichen Container-Repository abgerufen werden. Wenn Sie eine Instanz so konfigurieren möchten, dass sie aus einem privaten Repository abgerufen wird, müssen Sie die von containerd verwendeten Anmeldedaten manuell konfigurieren.
Basiscontainer
Standard-Basiscontainer
Der Standard-Basiscontainer unterstützt alle Vertex AI Workbench-Funktionen und umfasst Folgendes:
- Vorinstallierte Data Science-Pakete.
- CUDA-Bibliotheken ähnlich wie Deep Learning Containers.
- Google Cloud JupyterLab-Integrationen wie die Dataproc- und BigQuery-Integrationen.
- Gängige Systempakete wie
curl
odergit
. - Metadatenbasierte JupyterLab-Konfiguration.
- Micromamba-basierte Kernelverwaltung.
Spezifikationen
Der Standard-Basiscontainer hat die folgenden Spezifikationen:
- Basis-Image:
nvidia/cuda:12.6.1-cudnn-devel-ubuntu24.04
- Bildgröße: ca. 22 GB
- URI:
us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest
Schlanker Basiscontainer
Der schlanke Basiscontainer bietet eine minimale Konfiguration, die eine Proxyverbindung zur Instanz ermöglicht. Standardfunktionen und ‑pakete von Vertex AI Workbench sind nicht enthalten, mit Ausnahme der folgenden:
- JupyterLab
- Metadatenbasierte JupyterLab-Konfiguration
- Micromamba-basierte Kernelverwaltung
Zusätzliche Pakete oder JupyterLab-Erweiterungen müssen separat installiert und verwaltet werden.
Spezifikationen
Der schlanke Basiscontainer hat die folgenden Spezifikationen:
- Basis-Image:
marketplace.gcr.io/google/ubuntu24.04
- Bildgröße: ca. 2 GB
- URI:
us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container-slim:latest
Hinweise
- 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-Ausführer (
roles/notebooks.runner
) für das Nutzerkonto -
So rufen Sie Images aus dem Artifact Registry-Repository ab:
Artifact Registry-Leser (
roles/artifactregistry.reader
) für das Dienstkonto Erstellen Sie einen Container, der von einem von Google bereitgestellten Basiscontainer-Image abgeleitet ist.
Erstellen Sie den Container und übertragen Sie ihn per Push in die Artifact Registry. Sie verwenden die URI des Containers, wenn Sie Ihre Vertex AI Workbench-Instanz erstellen. Dieser URI könnte so aussehen:
gcr.io/PROJECT_ID/IMAGE_NAME
.Rufen Sie in der Google Cloud Console die Seite Instanzen auf.
Klicken Sie auf
NEU ERSTELLEN.Klicken Sie im Dialogfeld Neue Instanz auf Erweiterte Optionen.
Wählen Sie im Dialogfeld Instanz erstellen im Abschnitt Umgebung die Option Benutzerdefinierten Container verwenden aus.
Klicken Sie für Docker-Container-Image auf Auswählen.
Suchen Sie im Dialogfeld Container-Image auswählen nach dem Container-Image, das Sie verwenden möchten, und klicken Sie dann auf Auswählen.
Optional. Geben Sie für Post-Startskript einen Pfad zu einem Post-Startskript ein, das Sie verwenden möchten.
Optional. Fügen Sie Metadaten für Ihre Instanz hinzu. Weitere Informationen finden Sie unter Metadaten für benutzerdefinierte Container.
Optional. Passen Sie im Bereich „Netzwerk“ Ihre Netzwerkeinstellungen an. Weitere Informationen finden Sie unter Netzwerkkonfigurationsoptionen.
Schließen Sie den Rest des Dialogfelds zur Instanzerstellung ab und klicken Sie dann auf Erstellen.
Vertex AI Workbench erstellt eine Instanz und startet sie automatisch. Sobald die Instanz einsatzbereit ist, aktiviert Vertex AI Workbench den Link JupyterLab öffnen.
-
INSTANCE_NAME
: der Name Ihrer Vertex AI Workbench-Instanz; muss mit einem Buchstaben beginnen, gefolgt von bis zu 62 Kleinbuchstaben, Ziffern oder Bindestrichen (-) und darf nicht mit einem Bindestrich enden PROJECT_ID
: Ihre Projekt-ID.LOCATION
: die Zone, in der sich Ihre Instanz befinden soll-
CUSTOM_CONTAINER_PATH
: der Pfad zum Container-Image-Repository, z. B.gcr.io/PROJECT_ID/IMAGE_NAME
-
METADATA
: Benutzerdefinierte Metadaten, die auf diese Instanz angewendet werden sollen. Wenn Sie beispielsweise ein Post-Startscript angeben möchten, können Sie das Metadaten-Tagpost-startup-script
im folgenden Format verwenden:"--metadata=post-startup-script=gs://BUCKET_NAME/hello.sh"
So erstellen Sie einen neuen benutzerdefinierten Container:
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"
Fügen Sie den neuen Container zu Artifact Registry hinzu:
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
Instanz erstellen:
gcloud workbench instances create INSTANCE_NAME \ --project=PROJECT_ID \ --location=ZONE \ --container-repository=REGION-docker.pkg.dev/PROJECT_ID/IMAGE_NAME \ --container-tag=latest
Micromamba-Umgebung erstellen:
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"
Ersetzen Sie Folgendes:
- USER: der Name des Nutzerverzeichnisses, der standardmäßig
jupyter
ist - ENVIRONMENT_NAME: der Name der Umgebung
- PYTHON_VERSION: Die Python-Version, z. B.
3.11
- USER: der Name des Nutzerverzeichnisses, der standardmäßig
Warten Sie 30 Sekunden bis 1 Minute, bis die Kernel aktualisiert werden.
Achten Sie darauf, dass JupyterLab für Port 8080 konfiguriert ist. Unser Proxy-Agent ist so konfiguriert, dass er alle Anfragen an Port 8080 weiterleitet. Wenn der Jupyter-Server nicht auf dem richtigen Port wartet, treten bei der Instanz Bereitstellungsprobleme auf.
Ändern Sie JupyterLab-Pakete in der
jupyterlab
-Micromamba-Umgebung. Wir stellen eine separate Paketumgebung für die Ausführung von JupyterLab und seinem Plug-in bereit, um Abhängigkeitskonflikte mit der Kernelumgebung zu vermeiden. Wenn Sie eine zusätzliche JupyterLab-Erweiterung installieren möchten, müssen Sie sie in der Umgebungjupyterlab
installieren. Beispiel:# DockerFile FROM us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest RUN micromamba activate jupyterlab && \ jupyter nbextension install nbdime
true
: Aktiviert Cloud Storage FUSEfalse
(Standardeinstellung): Cloud Storage FUSE ist nicht aktiviertStellen Sie eine SSH-Verbindung zur Vertex AI Workbench-Instanz her.
Führen Sie im SSH-Terminal den folgenden Befehl aus:
sudo docker exec diagnostic-service ./diagnostic_tool
Führen Sie den folgenden Befehl aus, um sich weitere Befehlsoptionen anzeigen zu lassen:
sudo docker exec diagnostic-service ./diagnostic_tool --help
-
INSTANCE_NAME
: Der Name Ihrer Vertex AI Workbench-Instanz PROJECT_ID
: Ihre Projekt-ID.LOCATION
: Zone, in der sich Ihre Instanz befindet.
Erforderliche Rollen
Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen einer Vertex AI Workbench-Instanz mit einem benutzerdefinierten Container benötigen:
Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.
Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.
Benutzerdefinierten Container erstellen
So erstellen Sie einen benutzerdefinierten Container für die Verwendung mit Vertex AI Workbench-Instanzen:
Die Instanz erstellen
Sie können eine Vertex AI Workbench-Instanz auf Grundlage eines benutzerdefinierten Containers mit der Google Cloud Console oder der Google Cloud CLI erstellen.
Console
So erstellen Sie eine Vertex AI Workbench-Instanz basierend auf einem benutzerdefinierten Container:
gcloud
Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:
Führen Sie folgenden Befehl aus:
Linux, macOS oder 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
Weitere Informationen zum Befehl zum Erstellen einer Instanz über die Befehlszeile ausführen, siehe gcloud CLI Dokumentation.
Vertex AI Workbench erstellt eine Instanz und startet sie automatisch. Sobald die Instanz einsatzbereit ist, aktiviert Vertex AI Workbench den Link JupyterLab öffnen in der Google Cloud Console.
Optionen für die Netzwerkkonfiguration
Zusätzlich zu den allgemeinen Netzwerkoptionen muss eine Vertex AI Workbench-Instanz mit einem benutzerdefinierten Container Zugriff auf den Artifact Registry-Dienst haben.
Wenn Sie den Zugriff über öffentliche IP-Adressen für Ihre VPC deaktiviert haben, müssen Sie den privater Google-Zugriff aktivieren.
Image-Streaming aktivieren
Der benutzerdefinierte Container-Host wird für die Interaktion mit dem Image-Streaming in Google Kubernetes Engine (GKE) bereitgestellt. Dadurch werden Container schneller abgerufen und die Initialisierungszeit für große Container verkürzt, sobald sie im GKE-Remote-Dateisystem zwischengespeichert sind.
Die Anforderungen für die Aktivierung von Image-Streaming findest du unter Anforderungen. Oft kann Image-Streaming mit Vertex AI Workbench-Instanzen verwendet werden, indem die Container File System API aktiviert wird.
Container File System API aktivieren
So wird der benutzerdefinierte Container auf der Host-VM ausgeführt
Anstatt Docker zum Ausführen des benutzerdefinierten Containers zu verwenden, lädt und führt die Host-VM den Container mit nerdctl
unter dem Kubernetes-Namespace aus. So kann Vertex AI Workbench Image-Streaming für benutzerdefinierte Container verwenden.
# Runs the custom container. sudo /var/lib/google/nerdctl/nerdctl --snapshotter=gcfs -n k8s.io run --name payload-container
Beispiel für die Installation: benutzerdefinierter Container mit einem benutzerdefinierten Standardkernel
Im folgenden Beispiel wird gezeigt, wie Sie einen neuen Kernel mit einem vorinstallierten Pip-Paket erstellen.
Persistente Kernel für benutzerdefinierte Container
Bei benutzerdefinierten Containern von Vertex AI Workbench wird nur eine Datenlaufwerk im Verzeichnis /home/USER
in jedem Container bereitgestellt, wobei jupyter
der Standardnutzer ist. Das bedeutet, dass alle Änderungen außerhalb von /home/USER
nur vorübergehend sind und nach einem Neustart nicht mehr vorhanden sind. Wenn installierte Pakete für einen bestimmten Kernel beibehalten werden sollen, können Sie einen Kernel im Verzeichnis /home/USER
erstellen.
So erstellen Sie einen Kernel im Verzeichnis /home/USER
:
Start des Basiscontainers aktualisieren
Der Basiscontainer für eine Vertex AI Workbench-Instanz (us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest
) startet JupyterLab durch Ausführen von /run_jupyter.sh
.
Wenn Sie den Start des Containers in einem abgeleiteten Container ändern, müssen Sie /run_jupyter.sh
anhängen, um die Standardkonfiguration von JupyterLab auszuführen.
Hier sehen Sie ein Beispiel dafür, wie das Dockerfile geändert werden könnte:
# 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
JupyterLab-Konfiguration im Basiscontainer aktualisieren
Wenn Sie die JupyterLab-Konfiguration im Basiscontainer ändern müssen, gehen Sie so vor:
Benutzerdefinierte Containermetadaten
Zusätzlich zur Standardliste der Metadaten, die auf eine Vertex AI Workbench-Instanz angewendet werden können, enthalten Instanzen mit benutzerdefinierten Containern die folgenden Metadaten zum Verwalten der Instanziierung des Nutzlastcontainers:
Funktion | Beschreibung | Metadatenschlüssel | Gültige Werte und Standardeinstellungen |
---|---|---|---|
Aktiviert Cloud Storage FUSE in einem Container-Image |
|
container-allow-fuse |
|
Zusätzliche Parameter für die Containerausführung |
Fügt |
container-custom-params |
Ein String mit Parametern für die Containerausführung. Beispiel:
|
Zusätzliche Flags für die Containerumgebung |
Speichert Umgebungsvariablen in einem Flag unter |
container-env-file |
Ein String mit Container-Umgebungsvariablen. Beispiel:
|
Benutzerdefinierten Container aktualisieren
Wenn Ihre Instanz zum ersten Mal gestartet wird, wird das Container-Image aus einem URI abgerufen, der in den custom-container-payload
-Metadaten gespeichert ist.
Wenn Sie das Tag :latest
verwenden, wird der Container bei jedem Neustart aktualisiert. Der Metadatenwert custom-container-payload
kann nicht direkt geändert werden, da es sich um einen geschützten Metadatenschlüssel handelt.
Sie können das benutzerdefinierte Container-Image Ihrer Instanz mit den folgenden Methoden aktualisieren, die von der Google Cloud CLI, Terraform oder der Notebooks API unterstützt werden.
gcloud
Sie können die Metadaten des benutzerdefinierten Container-Images für eine Vertex AI Workbench-Instanz mit dem folgenden Befehl aktualisieren:
gcloud workbench instances update INSTANCE_NAME \ --container-repository=CONTAINER_URI \ --container-tag=CONTAINER_TAG
Terraform
Sie können das Feld container_image
in der Terraform-Konfiguration ändern, um die Container-Payload zu aktualisieren.
Informationen zum Anwenden oder Entfernen einer Terraform-Konfiguration finden Sie unter Grundlegende Terraform-Befehle.
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" } } }
Notebooks API
Verwenden Sie die Methode instances.patch
mit Änderungen an gce_setup.container_image.repository
und gce_setup.container_image.tag
in der updateMask
.
Diagnosetool ausführen
Das Diagnosetool prüft und verifiziert den Status verschiedener Vertex AI Workbench-Dienste. Weitere Informationen finden Sie unter Vom Diagnosetool ausgeführte Aufgaben.
Wenn Sie eine Vertex AI Workbench-Instanz mit einem benutzerdefinierten Container erstellen, ist das Diagnosetool nicht als Skript in der Hostumgebung verfügbar, das Nutzer ausführen können. Stattdessen wird es in eine Binärdatei kompiliert und in einen Google-Laufzeitcontainer geladen, der für die Ausführung von Diagnosediensten in einer Container-Optimized OS-Umgebung entwickelt wurde. Weitere Informationen finden Sie unter Übersicht über Container-Optimized OS.
Führen Sie die folgenden Schritte aus, um das Diagnosetool auszuführen:
Weitere Informationen zu den Optionen des Diagnosetools finden Sie in der Dokumentation zum Überwachen des Integritätsstatus.
Informationen zum Ausführen des Diagnosetools über die REST API finden Sie in der REST API-Dokumentation.
Auf die Instanz zugreifen
Sie können über eine Proxy-URL auf Ihre Instanz zugreifen.
Nachdem die Instanz erstellt wurde und aktiv ist, können Sie den Proxy-URL mithilfe der gcloud CLI abrufen.
Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:
Führen Sie folgenden Befehl aus:
Linux, macOS oder 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
Der Befehl describe
gibt Ihre Proxy-URL zurück. Um auf Ihre Instanz zuzugreifen,
öffnen Sie die Proxy-URL in einem Webbrowser.
Weitere Informationen zum Befehl zum Beschreiben einer Instanz über die Befehlszeile siehe gcloud CLI Dokumentation.