Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

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

本頁說明如何根據自訂容器，建立 Gemini Enterprise Agent Platform Workbench 執行個體。

總覽

Agent Platform Workbench 執行個體支援使用根據 Google 基礎容器建立的自訂容器。您可以修改這些基礎容器，建立自訂容器映像檔，並使用這些自訂容器來建立 Agent Platform Workbench 執行個體。

基礎容器是設定為在採用 Container-Optimized OS 的主機虛擬機器 (VM) 上執行。主機映像檔是從 cos-stable 映像檔系列建構而成。

限制

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

自訂容器必須衍生自 Google 提供的基礎容器。如果使用的容器並非衍生自基礎容器，相容性問題的風險會增加，我們也無法支援您使用 Agent Platform Workbench 執行個體。
不支援在 Agent Platform Workbench 執行個體中使用多個容器。
託管自訂容器的 VM 是在 Container-Optimized OS 上執行，這會限制您與主機機器的互動方式。舉例來說，Container-Optimized OS 不含套件管理工具。也就是說，在主機上執行的套件必須在具有掛接點的容器上執行。
Agent Platform Workbench 執行個體會使用 nerdctl (containerd CLI) 執行自訂容器。必須這麼做，才能與映像檔串流服務相容。使用中繼資料值新增的任何容器參數，都必須符合 nerdctl 支援的格式。
Agent Platform Workbench 執行個體會設為從 Artifact Registry 或公開容器存放區提取。如要設定執行個體從私人存放區提取，您必須手動設定 containerd 使用的憑證。

基礎容器

Agent Platform Workbench 提供兩種 Google 建構的基礎容器映像檔：標準版和精簡版。每個變化版本都包含 Python 3.10 (預設) 或 Python 3.12。編寫衍生容器的 FROM 陳述式時，請使用與所需 Python 版本相符的 URI。

標準基礎容器

標準基本容器支援所有 Agent Platform Workbench 功能，並包含下列項目：

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

規格

標準基礎容器的規格如下：

基本映像檔：nvidia/cuda:12.6.1-cudnn-devel-ubuntu24.04
映像檔大小：約 22 GB
URI (Python 3.10，預設)： us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest
URI (Python 3.12)： us-docker.pkg.dev/workbench-images/gcr.io/workbench-container-2606:latest

Slim 基本容器

精簡基本容器提供一組最少的設定，允許 Proxy 連線至執行個體。不含標準 Agent Platform Workbench 功能和套件，但下列項目除外：

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

其他套件或 JupyterLab 擴充功能必須獨立安裝及管理。

規格

精簡基本容器的規格如下：

基本映像檔：marketplace.gcr.io/google/ubuntu24.04
映像檔大小：約 2 GB
URI (Python 3.10，預設)： us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container-slim:latest
URI (Python 3.12)： us-docker.pkg.dev/workbench-images/gcr.io/workbench-container-slim-2606:latest

事前準備

登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

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 role (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 Notebooks API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

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 role (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 Notebooks API, if it is not already enabled.

Roles required to enable APIs

Enable the API

必要的角色

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

使用者帳戶的 Notebooks 執行者 (roles/notebooks.runner)
如要從 Artifact Registry 存放區提取映像檔：服務帳戶的 Artifact Registry 讀取者 (roles/artifactregistry.reader) 角色

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

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

建立自訂容器

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

建立衍生容器，衍生自 Google 提供的基本容器映像檔。
建構容器並推送至 Artifact Registry。建立 Agent Platform Workbench 執行個體時，您會使用容器的 URI。例如，URI 可能如下所示：gcr.io/PROJECT_ID/IMAGE_NAME。

建立執行個體

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

控制台

如要根據自訂容器建立 Agent Platform Workbench 執行個體，請按照下列步驟操作：

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

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

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

gcloud

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

INSTANCE_NAME：Agent Platform 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 說明文件。

Agent Platform Workbench 會建立執行個體，並自動啟動。執行個體可供使用時，Agent Platform Workbench 會在 Google Cloud 控制台啟用「Open JupyterLab」(開啟 JupyterLab) 連結。

網路設定選項

除了一般網路選項之外，具有自訂容器的 Agent Platform Workbench 執行個體也必須能存取 Artifact Registry 服務。

如果您已關閉虛擬私有雲的公開 IP 存取權，請務必啟用 Private Google Access。

啟用映像檔串流

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

如要查看啟用映像檔串流的需求條件，請參閱「需求條件」。一般來說，只要啟用 Container 檔案系統 API，即可搭配 Agent Platform Workbench 執行個體使用映像檔串流功能。

啟用 Container File System API

主機 VM 如何執行自訂容器

主機 VM 不會使用 Docker 執行自訂容器，而是使用 Kubernetes 命名空間下的 nerdctl 載入及執行容器。這樣 Agent Platform 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/REPOSITORY_NAME/IMAGE_NAME \
    --container-tag=latest

自訂容器的永久核心

Agent Platform 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 分鐘，讓核心重新整理。

更新基本容器的啟動作業

Agent Platform 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
```

自訂容器中繼資料

除了可套用至 Gemini Enterprise Agent Platform 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

您可以使用下列指令，更新 Agent Platform 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。

執行診斷工具

診斷工具會檢查並驗證各項 Agent Platform Workbench 服務的狀態。詳情請參閱「診斷工具執行的工作」。

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

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

使用 SSH 連線至 Agent Platform 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 網址。

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

INSTANCE_NAME：Agent Platform 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 說明文件。

使用自訂容器建立執行個體 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽

限制

基礎容器

標準基礎容器

規格

Slim 基本容器

規格

事前準備

必要的角色

建立自訂容器

建立執行個體

控制台

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

網路設定選項

啟用映像檔串流

主機 VM 如何執行自訂容器

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

自訂容器的永久核心

更新基本容器的啟動作業

更新基礎容器中的 JupyterLab 設定

自訂容器中繼資料

升級自訂容器

gcloud

Terraform

Notebooks API

執行診斷工具

存取執行個體

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

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