使用自定义容器创建实例

本页面介绍了如何基于自定义容器创建 Vertex AI Workbench 实例。

概览

Vertex AI Workbench 实例支持使用从 Google 提供的某个基础容器派生的自定义容器。您可以修改这些基础容器以创建自定义容器映像，并使用这些自定义容器创建 Vertex AI Workbench 实例。

基础容器在主机虚拟机 (VM) 中使用 Container-Optimized OS 进行配置。主机映像是基于 cos-stable 映像系列构建的。

限制

在规划项目时，请考虑以下限制：

自定义容器必须派生自 Google 提供的基础容器。使用不是从基础容器派生的容器会增加出现兼容性问题的风险，并限制我们为您使用 Vertex AI Workbench 实例提供支持的能力。
不支持将多个容器与 Vertex AI Workbench 实例一起使用。
用户管理的笔记本和托管式笔记本中自定义容器支持的元数据在与 Vertex AI Workbench 实例搭配使用时可能会有不同的行为。
托管自定义容器的虚拟机运行的是 Container-Optimized OS，这会限制您与宿主机的交互方式。例如，Container-Optimized OS 不包含软件包管理系统。这意味着，对主机执行操作的软件包必须通过装载在容器上执行。这会影响从托管式笔记本实例和用户管理的笔记本实例迁移的启动后脚本，在这种情况下，宿主机包含的工具比 Container-Optimized OS 多得多。
Vertex AI Workbench 实例使用 nerdctl（一种 containerd CLI）来运行自定义容器。这对于与映像流式传输服务的兼容性是必需的。使用元数据值添加的任何容器参数都需要遵循 nerdctl 支持的格式。
Vertex AI Workbench 实例配置为从 Artifact Registry 或公共容器仓库中进行拉取。如需将实例配置为从专用仓库中进行拉取，您必须手动配置 containerd 使用的凭据。

基础容器

标准基础容器

标准基础容器支持所有 Vertex AI Workbench 功能，并包含以下内容：

预安装的数据科学软件包。
类似于 Deep Learning Containers 的 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

精简型基础容器

精简型基础容器提供一组允许代理连接到实例的最低配置。其中不包含标准 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.

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 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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. 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 (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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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 控制台中，前往实例页面。

转到实例
点击新建。
在新建实例对话框中，点击高级选项。
在创建实例对话框的环境部分中，选择使用自定义容器。
对于 Docker 容器映像，请点击选择。
在选择容器映像对话框中，找到要使用的容器映像，然后点击选择。
可选。对于启动后脚本，请输入要使用的启动后脚本的路径。
可选。为实例添加元数据。如需了解详情，请参阅自定义容器元数据。
可选。在网络部分中，自定义网络设置。如需了解详情，请参阅网络配置选项。
完成实例创建对话框的其余部分，然后点击创建。

Vertex AI Workbench 会创建实例并自动启动该实例。当实例可供使用时，Vertex AI Workbench 会激活一个打开 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，您可以使用 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 控制台中激活一个打开 JupyterLab 链接。

网络配置选项

除了常规网络选项之外，具有自定义容器的 Vertex AI Workbench 实例还必须有权访问 Artifact Registry 服务。

如果您已为 VPC 关闭公共 IP 访问权限，请确保已启用专用 Google 访问通道。

启用映像流式传输

自定义容器主机预配为与 Google Kubernetes Engine (GKE) 中的映像流式传输交互，这样可更快地拉取容器，并可在大型容器缓存在 GKE 远程文件系统中后缩短其初始化时间。

如需查看启用映像流式传输的要求，请参阅要求。通常，您可以通过启用 Container File System API 来将映像流式传输与 Vertex AI Workbench 实例搭配使用。

启用 Container File System API

主机虚拟机如何运行自定义容器

主机虚拟机使用 Kubernetes 命名空间下的 nerdctl 来加载和运行自定义容器，而不是使用 Docker 运行容器。这样一来，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/REPOSITORY_NAME/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。我们的代理配置为将任何请求转发到端口 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 文档。

访问您的实例

您可以通过代理网址访问实例。

在创建并激活实例后，您可以使用 gcloud CLI 获取代理网址。

在使用下面的命令数据之前，请先进行以下替换：

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 命令会返回您的代理网址。要访问您的实例，请在网络浏览器中打开代理网址。

如需详细了解用于从命令行描述实例的命令，请参阅 gcloud CLI 文档。