本頁面由 Cloud Translation API 翻譯而成。

使用自訂容器建立執行個體

本頁說明如何根據自訂容器建立 Vertex AI Workbench 執行個體。

總覽

Vertex AI Workbench 執行個體支援使用自訂容器，該容器衍生自 Google 提供的其中一個基本容器。您可以修改這些基本容器，製作自訂容器映像檔，並使用這些自訂容器建立 Vertex AI Workbench 執行個體。

主機虛擬機器 (VM) 中的基礎容器會設定為使用容器最佳化作業系統。主機映像檔是從 cos-stable 映像檔系列建立。

限制

規劃專案時，請考量下列限制：

自訂容器必須衍生自 Google 提供的基本容器。使用非基底容器衍生的容器，會增加相容性問題的風險，並限制我們支援您使用 Vertex AI Workbench 執行個體的能力。
不支援在 Vertex AI Workbench 執行個體中使用多個容器。
使用者自管筆記本和代管筆記本的自訂容器支援的結構描述，在與 Vertex AI Workbench 執行個體搭配使用時，可能會出現不同的行為。
託管自訂容器的 VM 會透過 Container-Optimized OS 執行，這會限制您與主機機器互動的做法。舉例來說，Container-Optimized OS 不包含套件管理員。也就是說，在主機上執行的套件必須在具有掛載點的容器上執行。這會影響從受管理的 Notebook 執行個體和使用者管理的 Notebook 執行個體遷移的啟動後指令碼，因為主機機器包含的工具比 Container-Optimized OS 多出許多。
Vertex AI Workbench 執行個體會使用 nerdctl (containerd CLI) 執行自訂容器。這項屬性是與圖片串流服務相容的必要條件。使用中繼資料值新增的任何容器參數都必須遵循 nerdctl 支援的內容。
Vertex AI Workbench 執行個體會設為從 Artifact Registry 或公開容器存放區提取資料。如要設定執行個體，以便從私人存放區提取，您必須手動設定 containerd 使用的憑證。

基本容器

標準容器

標準基礎容器支援所有 Vertex AI Workbench 功能，並包含下列項目：

預先安裝的數據科學套件。
CUDA 程式庫 (類似深度學習容器)。
Google Cloud JupyterLab 整合，例如 Dataproc 和 BigQuery 整合。
常見的系統套件，例如 curl 或 git。
以中繼資料為基礎的 JupyterLab 設定。
以 Micromamba 為基礎的核心管理。

規格

標準底座容器的規格如下：

基本映像檔：nvidia/cuda:12.6.1-cudnn-devel-ubuntu24.04
圖片大小：約 22 GB
URI：us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest

纖薄底座容器

精簡版基本容器提供最少的設定組合，可允許與執行個體建立 Proxy 連線。除了下列項目外，標準 Vertex AI Workbench 功能和套件均未納入：

JupyterLab
以中繼資料為基礎的 JupyterLab 設定
以 Micromamba 為基礎的核心管理

您必須個別安裝及管理其他套件或 JupyterLab 擴充功能。

規格

窄型底座容器的規格如下：

基本映像檔：marketplace.gcr.io/google/ubuntu24.04
圖片大小：約 2 GB
URI：us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container-slim:latest

事前準備

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.

Go to project selector

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

Enable the Notebooks API.

Enable the API

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

Go to project selector

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

Enable the Notebooks API.

Enable the API

必要的角色

如要取得使用自訂容器建立 Vertex AI Workbench 執行個體所需的權限，請要求管理員授予您下列 IAM 角色：

使用者帳戶中的Notebooks Runner (roles/notebooks.runner)
如要從 Artifact Registry 存放區提取映像檔，請執行下列操作： Artifact Registry Reader (roles/artifactregistry.reader) 服務帳戶上的權限

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

建立自訂容器

如要建立自訂容器，以便與 Vertex AI Workbench 執行個體搭配使用，請按照下列步驟操作：

建立衍生容器，該容器衍生自 Google 提供的基本容器映像檔。
建構容器並推送至 Artifact Registry。建立 Vertex AI Workbench 執行個體時，您會使用容器的 URI。舉例來說，URI 可能會像這樣：gcr.io/PROJECT_ID/IMAGE_NAME。

建立執行個體

您可以使用 Google Cloud 控制台或 Google Cloud CLI，根據自訂容器建立 Vertex AI Workbench 執行個體。

主控台

如要根據自訂容器建立 Vertex AI Workbench 執行個體，請執行下列操作：

前往 Google Cloud 控制台的「Instances」(執行個體) 頁面。

前往「Instances」(執行個體)
按一下「建立新項目」。
在「New instance」對話方塊中，按一下「Advanced options」。
在「Create instance」對話方塊的「Environment」部分，選取「Use custom container」。
針對「Docker 容器映像檔」，按一下「選取」。
在「Select container image」對話方塊中，瀏覽至要使用的容器映像檔，然後按一下「Select」。
(選用步驟) 針對「開機後指令碼」，請輸入要使用的開機後指令碼路徑。
(選用步驟) 為執行個體新增中繼資料。詳情請參閱「自訂容器中繼資料」。
(選用步驟) 在「Networking」部分中，自訂網路設定。詳情請參閱「網路設定選項」。
完成執行個體建立對話方塊的其餘部分，然後按一下「建立」。

Vertex AI Workbench 會建立執行個體並自動啟動。執行個體可供使用時，Vertex AI Workbench 會啟用「Open JupyterLab」(開啟 JupyterLab) 連結。

gcloud

使用下列任何指令資料之前，請先替換以下項目：

INSTANCE_NAME：Vertex AI Workbench 執行個體的名稱；開頭須為英文字母，後面最多可接 62 個小寫英文字母、數字或連字號 (-)，但結尾不得為連字號
PROJECT_ID：您的專案 ID
LOCATION：您要將執行個體放置的位置
CUSTOM_CONTAINER_PATH：容器映像檔存放區的路徑，例如：gcr.io/PROJECT_ID/IMAGE_NAME
METADATA：要套用至此執行個體的自訂中繼資料；舉例來說，如要指定啟動後指令碼，您可以使用 post-startup-script 中繼資料標記，格式如下： "--metadata=post-startup-script=gs://BUCKET_NAME/hello.sh"

執行下列指令：

Linux、macOS 或 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

如要進一步瞭解透過指令列建立執行個體的指令，請參閱 gcloud CLI 說明文件。

Vertex AI Workbench 會建立執行個體並自動啟動。執行個體可供使用時，Vertex AI Workbench 會在 Google Cloud 控制台中啟用「Open JupyterLab」連結。

網路設定選項

除了一般網路選項，含有自訂容器的 Vertex AI Workbench 執行個體也必須能存取 Artifact Registry 服務。

如果您已關閉 VPC 的公開 IP 存取權，請確認您已啟用私人 Google 存取權。

啟用圖片串流

自訂容器主機會佈建為與 Google Kubernetes Engine (GKE) 中的映像串流互動，這樣一來，當大型容器快取到 GKE 遠端檔案系統時，就能加快提取容器的速度，並縮短初始化時間。

如要查看啟用圖片串流功能的相關規定，請參閱「規定」。通常，只要啟用容器檔案系統 API，即可搭配 Vertex AI Workbench 執行個體使用映像檔串流。

啟用 Container File System API

主機 VM 如何執行自訂容器

主機 VM 不會使用 Docker 執行自訂容器，而是會使用 Kubernetes 命名空間下的 nerdctl 載入及執行容器。這可讓 Vertex AI Workbench 為自訂容器使用映像檔串流。

# Runs the custom container.
sudo /var/lib/google/nerdctl/nerdctl --snapshotter=gcfs -n k8s.io run --name payload-container

安裝範例：自訂容器搭配自訂預設核心

以下範例說明如何使用預先安裝的 pip 套件建立新的核心。

建立新的自訂容器：

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"

將新容器新增至 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

建立執行個體：

gcloud workbench instances create INSTANCE_NAME  \
    --project=PROJECT_ID \
    --location=ZONE \
    --container-repository=REGION-docker.pkg.dev/PROJECT_ID/IMAGE_NAME \
    --container-tag=latest

自訂容器的持久性核心

Vertex AI Workbench 自訂容器只會將資料磁碟掛載至每個容器內的 /home/USER 目錄，其中 jupyter 是預設使用者。這表示 /home/USER 以外的任何變更都是暫時性的，在重新啟動後就會消失。如果您需要為特定核心保留已安裝的套件，可以在 /home/USER 目錄中建立核心。

如要在 /home/USER 目錄中建立核心，請按照下列步驟操作：

建立 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"

更改下列內容：

USER：使用者目錄名稱，預設為 jupyter
ENVIRONMENT_NAME：環境名稱
PYTHON_VERSION：Python 版本，例如 3.11

等待 30 秒至 1 分鐘，讓核心重新整理。

更新基本容器的啟動程序

Vertex AI Workbench 執行個體 (us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest) 的基本容器會透過執行 /run_jupyter.sh 啟動 JupyterLab。

如果您在衍生容器中修改容器的啟動作業，必須附加 /run_jupyter.sh 才能執行 JupyterLab 的預設設定。

以下是 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

更新基礎容器中的 JupyterLab 設定

如果您需要修改基礎容器上的 JupyterLab 設定，請務必執行下列操作：

請確認 JupyterLab 已設為使用通訊埠 8080。我們的 Proxy 服務已設定為將任何要求轉送至 8080 通訊埠，如果 Jupyter 伺服器未監聽正確的通訊埠，執行個體就會遇到佈建問題。
在 jupyterlab micromamba 環境下修改 JupyterLab 套件。我們提供獨立的套件環境，用於執行 JupyterLab 及其外掛程式，確保不會與核心環境發生任何依附元件衝突。如果您想安裝其他 JupyterLab 擴充功能，必須在 jupyterlab 環境中安裝。例如：
```
# DockerFile
FROM us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest
RUN micromamba activate jupyterlab && \
  jupyter nbextension install nbdime
```

自訂容器中繼資料

除了可套用至 Vertex AI Workbench 執行個體的標準中繼資料清單外，含有自訂容器的執行個體還包含下列中繼資料，用於管理酬載容器的例項化：

功能	說明	中繼資料鍵	接受的值和預設值
在容器映像檔上啟用 Cloud Storage FUSE	將 `/dev/fuse` 掛接到容器，並啟用 `gcsfuse` 以便在容器上使用。	`container-allow-fuse`	`true`：啟用 Cloud Storage FUSE。 `false` (預設)：不啟用 Cloud Storage FUSE。
其他容器執行參數	將其他容器參數附加至 `nerdctl run`，其中 `nerdctl` 是 Containerd CLI。	`container-custom-params`	容器執行參數的字串。範例：`--v /mnt/disk1:/mnt/disk1`。
其他容器環境標記	將環境變數儲存至 `/mnt/stateful_partition/workbench/container_env` 底下的旗標，並附加至 `nerdctl run`。	`container-env-file`	容器環境變數的字串。範例：`CONTAINER_NAME=derivative-container`。

升級自訂容器

執行個體第一次啟動時，會從 custom-container-payload 中繼資料中儲存的 URI 提取容器映像檔。如果您使用 :latest 標記，容器會在每次重新啟動時更新。custom-container-payload 中繼資料值是受保護的中繼資料鍵，因此無法直接修改。

如要更新執行個體的自訂容器映像檔，您可以使用 Google Cloud CLI、Terraform 或 Notebooks API 支援的下列方法。

gcloud

您可以使用下列指令，在 Vertex AI Workbench 執行個體上更新自訂容器映像檔中繼資料：

gcloud workbench instances update INSTANCE_NAME \
    --container-repository=CONTAINER_URI \
    --container-tag=CONTAINER_TAG

Terraform

您可以變更 Terraform 設定中的 container_image 欄位，以更新容器酬載。

如要瞭解如何套用或移除 Terraform 設定，請參閱「基本 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"
    }
  }
}

Notebooks API

使用 instances.patch 方法，並變更 updateMask 中的 gce_setup.container_image.repository 和 gce_setup.container_image.tag。

執行診斷工具

診斷工具會檢查及驗證各種 Vertex AI Workbench 服務的狀態。詳情請參閱「診斷工具執行的工作」。

使用自訂容器建立 Vertex AI Workbench 執行個體時，診斷工具不會以可供使用者執行的指令碼形式出現在主機環境中。而是編譯成二進位檔，並載入至 Google 執行階段容器，該容器是為了在 Container-Optimized OS 環境中執行診斷服務而建構。請參閱「Container-Optimized OS 總覽」。

如要執行診斷工具，請完成下列步驟：

使用 ssh 連線至 Vertex AI Workbench 執行個體。

在 SSH 終端機中執行下列指令：

sudo docker exec diagnostic-service ./diagnostic_tool

如要查看其他指令選項，請執行下列指令：

sudo docker exec diagnostic-service ./diagnostic_tool --help

如要進一步瞭解診斷工具的選項，請參閱監控健康狀態說明文件。

如要使用 REST API 執行診斷工具，請參閱 REST API 說明文件。

存取執行個體

您可以透過 Proxy 網址存取執行個體。

建立並啟用執行個體後，您可以使用 gcloud CLI 取得 Proxy URL。

使用下列任何指令資料之前，請先替換以下項目：

INSTANCE_NAME：Vertex AI Workbench 執行個體的名稱
PROJECT_ID：您的專案 ID
LOCATION：執行個體所在的區域

執行下列指令：

Linux、macOS 或 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

describe 指令會傳回 Proxy 網址。如要存取執行個體，請在網路瀏覽器中開啟 Proxy 網址。

如要進一步瞭解透過指令列描述執行個體的指令，請參閱 gcloud CLI 說明文件。