使用自定义容器创建实例

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

概览

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

基础容器在主机虚拟机 (VM) 中配置了 Container-Optimized OS。基础容器提供预安装的数据科学包和特定配置，使您的实例能够与 Google Cloud 集成。

基础容器位于 gcr.io/deeplearning-platform-release/workbench-container:latest。

限制

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

• 自定义容器必须派生自 Google 提供的基础容器 (gcr.io/deeplearning-platform-release/workbench-container:latest)。使用未从基础容器派生的容器会增加出现兼容性问题的风险，并限制我们对您使用 Vertex AI Workbench 实例的支持。

• 不支持将多个容器与 Vertex AI Workbench 实例一起使用。

• 用户管理的笔记本和代管式笔记本中自定义容器的支持元数据在与 Vertex AI Workbench 实例搭配使用时可能会有不同的行为。

• 托管自定义容器的虚拟机运行的是 Container-Optimized OS，这会限制您与宿主机的互动方式。例如，Container-Optimized OS 不包含软件包管理器。这意味着，必须在具有挂载的容器上执行对主机操作的软件包。这会影响从托管的笔记本实例和用户托管的笔记本实例迁移的启动后脚本，其中宿主机包含的工具比 Container-Optimized OS 多得多。

• Vertex AI Workbench 实例使用 nerdctl（容器化 CLI）来运行自定义容器。这项设置是与图片流式传输服务兼容所必需的。使用元数据值添加的任何容器参数都需要遵循 nerdctl 支持的参数。

• Vertex AI Workbench 实例配置为从 Artifact Registry 或公共容器仓库拉取内容。如需将实例配置为从私有代码库中拉取代码，您必须手动配置 containerd 使用的凭据。

准备工作

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

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

   Go to project selector

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

4. Enable the Notebooks API.

   Enable the API

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

   Go to project selector

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

7. 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 实例搭配使用的自定义容器，请执行以下操作：

1. 创建派生容器，该容器派生自 Google 提供的基础容器映像 (gcr.io/deeplearning-platform-release/workbench-container:latest)。

2. 构建容器并将其推送到 Artifact Registry。创建 Vertex AI Workbench 实例时，您将使用容器的 URI。例如，该 URI 可能如下所示：gcr.io/PROJECT_ID/IMAGE_NAME。

创建实例

您可以使用 Google Cloud 控制台或 Google Cloud CLI 创建基于自定义容器的 Vertex AI Workbench 实例。

gcloud workbench instances create INSTANCE_NAME \
    --project=PROJECT_ID \
    --location=LOCATION \
    --container-repository=CUSTOM_CONTAINER_URL \
    --container-tag=latest \
    --metadata=METADATA

gcloud workbench instances create INSTANCE_NAME `
    --project=PROJECT_ID `
    --location=LOCATION `
    --container-repository=CUSTOM_CONTAINER_URL `
    --container-tag=latest `
    --metadata=METADATA

gcloud workbench instances create INSTANCE_NAME ^
    --project=PROJECT_ID ^
    --location=LOCATION ^
    --container-repository=CUSTOM_CONTAINER_URL ^
    --container-tag=latest ^
    --metadata=METADATA

网络配置选项

除了常规网络选项之外，使用自定义容器的 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 软件包的新内核。

1. 创建新的自定义容器：

   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

2. 将新容器添加到 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

3. 创建实例：

   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 目录中创建内核，请执行以下操作：

1. 创建 micromamba 环境：

   micromamba create -p /home/jupyter/ENVIRONMENT_NAME -c conda-forge python=3.11 -y
   micromamba activate ENVIRONMENT_NAME
   pip install ipykernel
   pip install -r ~/requirement.txt
   python -m ipykernel install --prefix "/home/jupyter/ENVIRONMENT_NAME" --display-name "Example Kernel"

2. 等待 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

# 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 实例的标准元数据列表之外，包含自定义容器的实例还包含以下用于管理载荷容器实例化的元数据：

升级自定义容器

如果您需要更新自定义容器，可以通过使用新的容器 URI 更新 custom-container-payload 元数据值来实现。容器每次重启都会尝试从存储在 custom-container-payload 的 URI 中拉取容器。

如果您使用 :latest 标记，则系统会在每次重启时更新基础容器。请参阅以下示例：

custom-container-payload = us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest

为避免更新基础容器，您可以指定版本。请参阅以下示例：

custom-container-payload = us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:20240920-2200-rc0

运行诊断工具

诊断工具可检查和验证各种 Vertex AI Workbench 服务的状态。如需了解详情，请参阅诊断工具执行的任务。

使用自定义容器创建 Vertex AI Workbench 实例时，诊断工具无法作为脚本在主机环境中供用户运行。而是编译为二进制文件，并加载到专为在 Container-Optimized OS 环境中运行诊断服务而构建的 Google 运行时容器上。请参阅 Container-Optimized OS 概览。

要运行诊断工具，请完成以下步骤：

1. 使用 ssh 连接到您的 Vertex AI Workbench 实例。

2. 在 SSH 终端中，运行以下命令：

   sudo docker exec diagnostic-service ./diagnostic_tool

3. 如需查看其他命令选项，请运行以下命令：

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

如需详细了解诊断工具的选项，请参阅监控运行状况文档。

如需使用 REST API 运行诊断工具，请参阅 REST API 文档。

访问您的实例

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

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

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

• INSTANCE_NAME：您的 Vertex AI Workbench 实例的名称
• PROJECT_ID：您的项目 ID
• LOCATION：实例所在的可用区

执行以下命令：

gcloud workbench instances describe INSTANCE_NAME \
--project=PROJECT_ID \
--location=LOCATION | grep proxy-url

gcloud workbench instances describe INSTANCE_NAME `
--project=PROJECT_ID `
--location=LOCATION | grep proxy-url

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 文档。