从代管式笔记本迁移到 Vertex AI Workbench 实例

从代管式笔记本迁移到 Vertex AI Workbench 实例

Vertex AI Workbench 托管式笔记本已弃用。自 2025 年 1 月 30 日起，我们将终止对托管式笔记本的支持，并且将不再支持创建托管式笔记本实例。现有实例将继续运行，但补丁、更新和升级不再提供。如需继续使用 Vertex AI Workbench，请完成本页面上的步骤，将托管式笔记本实例迁移到 Vertex AI Workbench 实例。

本页面介绍了如何从代管式笔记本实例迁移到 Vertex AI Workbench 实例。您可以使用 Vertex AI Workbench 迁移工具进行迁移，也可以手动迁移实例的数据和文件。

迁移工具概览

Vertex AI Workbench 提供用于从代管式笔记本实例迁移到 Vertex AI Workbench 实例的迁移工具。

迁移工具会创建 Vertex AI Workbench 实例，其配置与您要迁移的代管式笔记本实例类似。例如，迁移工具会创建一个具有相同或类似机器类型、网络配置、空闲关停设置和其他规范的实例。然后，代管式笔记本实例的数据磁盘上的文件会复制到 Vertex AI Workbench 实例。

Vertex AI Workbench 不会删除或更改代管式笔记本实例，因此在迁移后，您可以继续使用该实例。如果您不再需要代管式笔记本实例，请将其删除以避免该实例产生更多费用。

结算

如果代管式笔记本实例使用极端永久性磁盘，则迁移会产生 I/O 操作的费用。请参阅磁盘价格的永久性磁盘和 Hyperdisk 价格部分中的“极端预配的 IOPS”。

迁移后，代管式笔记本实例仍然存在，并像以前一样产生费用。如果您不再需要代管式笔记本实例，请将其删除以避免该实例产生更多费用。

默认迁移工具行为

Vertex AI Workbench 迁移工具会尝试将代管式笔记本实例迁移到具有匹配规范的 Vertex AI Workbench 实例。如果代管式笔记本实例中的规范在 Vertex AI Workbench 实例中不可用，则 Vertex AI Workbench 会尽可能使用默认规范。如果迁移工具无法迁移代管式笔记本实例的规范，则不会迁移该实例。

下表列出了迁移工具的一些关键默认迁移行为。

Category	代管式笔记本规范	迁移结果
操作系统	任何 Ubuntu 版本	Debian 11
	任何 Debian 版本	Debian 11
框架	任何 CUDA 版本	CUDA 11.3
	任何 Python 版本	Python 3.10
	任何 PyTorch 版本	PyTorch 1.13
	任何 TensorFlow 版本	TensorFlow 2.11
	任何 R 版本	未迁移；请参阅添加 conda 环境
	任何本地 PySpark 版本	未迁移；请参阅添加 conda 环境
	任何 XGBoost 版本	未迁移；请参阅添加 conda 环境
	任何 Kaggle Python 版本	未迁移；请参阅添加 conda 环境
	任何 Jax 版本	未迁移；请参阅添加 conda 环境
	任何 Apache Beam 版本	未迁移；请参阅添加 conda 环境
机器类型	支持的机器类型	相同的机器类型
	不受支持的机器类型	e2-standard-4
加速器	支持的加速器	相同的加速器
	不受支持的加速器	迁移不包含加速器
设置	空闲机器关停	已迁移
	删除至回收站	已迁移
	nbconvert	已迁移
	文件下载	已迁移
	终端访问权限	已迁移
其他	Identity and Access Management 权限	已迁移，但使用 Vertex AI Workbench 实例可能需要新权限
	访问模式	已迁移；使用单用户 JupyterLab 访问模式的实例必须指定 serviceAccount 选项
	网络	已迁移；使用 Google 管理的 Virtual Private Cloud 的实例必须指定 network 和 subnet 选项
	启动后脚本	使用 Google Cloud 控制台时，无需启动后脚本即可迁移实例；如需使用启动后脚本迁移实例，请使用 Google Cloud CLI 或 REST API 指定 PostStartupScriptOption 选项
	Dataproc 中心	未迁移；必须手动迁移

指定选项

以下部分介绍了在将代管式笔记本实例迁移到 Vertex AI Workbench 实例时需要指定选项的情况。

使用单用户访问模式的实例

使用单用户访问模式的代管式笔记本实例必须迁移到指定了 serviceAccount 选项的实例。您要迁移的 Vertex AI Workbench 实例仅限单个用户访问 JupyterLab，但它使用服务账号与 Google Cloud 服务和 API 进行交互。

使用 Google 管理的 VPC 的实例

使用 Google 管理的 VPC 的代管式笔记本实例必须迁移到指定了 network 和 subnet 选项的实例。Vertex AI Workbench 实例不支持使用 Google 管理的 VPC 的选项，因此必须指定其他网络。

使用启动后脚本的实例

使用启动后脚本的代管式笔记本实例必须迁移到指定了 PostStartupScriptOption 选项的实例。使用此选项可指示是要在新的 Vertex AI Workbench 实例中跳过还是重新运行启动后脚本。

Google Cloud 控制台不支持指定 PostStartupScriptOption 选项。如需在迁移托管式笔记本实例时指定 PostStartupScriptOption 选项，您必须使用 Google Cloud CLI 或 REST API。

准备工作

1. 登录您的 Google Cloud 账号。如果您是 Google Cloud 新手，请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

2. 在 Google Cloud Console 中的项目选择器页面上，选择或创建一个 Google Cloud 项目。

   注意：如果您不打算保留在此过程中创建的资源，请创建新的项目，而不要选择现有的项目。完成本教程介绍的步骤后，您可以删除所创建的项目，并移除与该项目关联的所有资源。

   转到“项目选择器”

3. 确保您的 Google Cloud 项目已启用结算功能。

4. 启用 Notebooks API。

   启用 API

5. 在 Google Cloud Console 中的项目选择器页面上，选择或创建一个 Google Cloud 项目。

   注意：如果您不打算保留在此过程中创建的资源，请创建新的项目，而不要选择现有的项目。完成本教程介绍的步骤后，您可以删除所创建的项目，并移除与该项目关联的所有资源。

   转到“项目选择器”

6. 确保您的 Google Cloud 项目已启用结算功能。

7. 启用 Notebooks API。

   启用 API

8. 创建代管式笔记本实例（如果您尚未创建）。

所需的角色

如需确保用户账号拥有将代管式笔记本实例迁移到 Vertex AI Workbench 实例所需的权限，请让您的管理员为用户账号授予项目的 Notebooks Runner (roles/notebooks.runner) IAM 角色。如需详细了解如何授予角色，请参阅管理访问权限。

此预定义角色可提供将代管式笔记本实例迁移到 Vertex AI Workbench 实例所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

将代管式笔记本实例迁移到 Vertex AI Workbench 实例需要以下权限：

• notebooks.runtimes.create
• notebooks.runtimes.get

您的管理员也可以使用自定义角色或其他预定义角色为用户账号授予这些权限。

迁移前检查

在迁移之前，通过列出实例并检查输出是否存在任何迁移警告或错误来检查代管式笔记本实例的迁移资格。

列出实例

如需列出尚未迁移的托管式笔记本实例，请使用带有过滤条件 migrated:false 的 projects.locations.runtimes.list 方法。您可以使用 gcloud CLI 或 REST API 列出它们：

gcloud

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

• PROJECT_ID：您的项目 ID
• LOCATION：托管式笔记本实例所在的区域，或使用 - 列出所有区域中的实例

执行以下命令：

Linux、macOS 或 Cloud Shell

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

gcloud notebooks runtimes list --project=PROJECT_ID \
    --location=LOCATION --filter=migrated:false --format=default

Windows (PowerShell)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

gcloud notebooks runtimes list --project=PROJECT_ID `
    --location=LOCATION --filter=migrated:false --format=default

Windows (cmd.exe)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

gcloud notebooks runtimes list --project=PROJECT_ID ^
    --location=LOCATION --filter=migrated:false --format=default

REST

在使用任何请求数据之前，请先进行以下替换：

• PROJECT_ID：您的项目 ID
• LOCATION：托管式笔记本实例所在的区域，或使用 - 列出所有区域中的实例

HTTP 方法和网址：

GET https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/runtimes?filter=migrated:false

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/runtimes?filter=migrated:false"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/runtimes?filter=migrated:false" | Select-Object -Expand Content

检查输出是否存在警告或错误

如果检测到迁移警告或错误，则 projects.locations.runtimes.list 方法的输出会包含此信息。

如果代管式笔记本实例的配置中的特定组件不会迁移到 Vertex AI Workbench 实例中的相同规范，则系统会显示警告。例如，如果代管式笔记本实例使用不受支持的加速器，则输出中会显示警告。在这种情况下，实例会在没有任何加速器的情况下进行迁移。您可以在迁移后挂接加速器。查看输出中的警告，考虑迁移工具的默认行为，并评估迁移工具是否适合迁移。

输出中的一个或多个错误意味着您无法使用迁移工具迁移代管式笔记本实例。 您必须手动迁移实例。

如需详细了解迁移警告和错误，请参阅 RuntimeMigrationEligibility 文档中的警告和错误。

使用迁移工具进行迁移

您可以使用 Google Cloud 控制台、gcloud CLI 或 REST API 迁移代管式笔记本实例。

控制台

1. 在 Google Cloud 控制台中，前往代管式笔记本页面。

   前往“代管式笔记本”

2. 点击迁移按钮。 系统会打开将托管式笔记本迁移到实例页面。

3. 如需迁移不需要指定选项的实例，请点击准备就绪标签页，选择要迁移的实例，然后点击迁移。

4. 如需迁移需要指定选项的实例，请点击需要输入标签页，选择要迁移的实例，然后点击迁移。

   1. 在为迁移提供输入对话框中，指定要用于您选择的新 Vertex AI Workbench 实例的网络和服务账号。

   2. 点击提交。

5. 迁移完成后，进入实例页面以查看新的 Vertex AI Workbench 实例。

   转到实例

gcloud

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

• PROJECT_ID：您的项目 ID
• LOCATION：代管式笔记本实例所在的区域
• RUNTIME_ID：代管式笔记本实例的 ID
• NETWORK（可选）：您要将实例迁移到的网络
• SUBNET（可选）：您要将实例迁移到的子网
• SERVICE_ACCOUNT（可选）：您要使用的服务账号的电子邮件地址
• POST_STARTUP_SCRIPT_OPTION（可选）：启动后脚本选项之一

执行以下命令：

Linux、macOS 或 Cloud Shell

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

gcloud notebooks runtimes migrate RUNTIME_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --network=NETWORK \
    --subnet=SUBNET \
    --service-account=SERVICE_ACCOUNT \
    --post-startup-script-option=POST_STARTUP_SCRIPT_OPTION

Windows (PowerShell)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

gcloud notebooks runtimes migrate RUNTIME_ID `
    --project=PROJECT_ID `
    --location=LOCATION `
    --network=NETWORK `
    --subnet=SUBNET `
    --service-account=SERVICE_ACCOUNT `
    --post-startup-script-option=POST_STARTUP_SCRIPT_OPTION

Windows (cmd.exe)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

gcloud notebooks runtimes migrate RUNTIME_ID ^
    --project=PROJECT_ID ^
    --location=LOCATION ^
    --network=NETWORK ^
    --subnet=SUBNET ^
    --service-account=SERVICE_ACCOUNT ^
    --post-startup-script-option=POST_STARTUP_SCRIPT_OPTION

REST

在使用任何请求数据之前，请先进行以下替换：

• PROJECT_ID：您的项目 ID
• LOCATION：代管式笔记本实例所在的区域
• RUNTIME_ID：代管式笔记本实例的 ID
• NETWORK（可选）：您要将实例迁移到的网络
• SUBNET（可选）：您要将实例迁移到的子网
• SERVICE_ACCOUNT（可选）：您要使用的服务账号的电子邮件地址
• POST_STARTUP_SCRIPT_OPTION（可选）：启动后脚本选项之一

HTTP 方法和网址：

POST https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/runtimes/RUNTIME_ID:migrate

请求 JSON 正文：

{
  "network": NETWORK,
  "subnet": SUBNET,
  "serviceAccount": SERVICE_ACCOUNT_EMAIL_ADDRESS,
  "postStartupScriptOption": (POST_STARTUP_SCRIPT_OPTION)
}

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/runtimes/RUNTIME_ID:migrate"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/runtimes/RUNTIME_ID:migrate" | Select-Object -Expand Content

手动迁移

如需手动将实例迁移到 Vertex AI Workbench 实例，请考虑使用以下方法：

• 使用 Cloud Storage 和终端：使用终端将数据和文件复制到 Cloud Storage，然后复制到另一个实例。

• 使用 GitHub：使用 JupyterLab 的 Git 扩展程序将数据和文件复制到 GitHub 代码库。

本指南介绍如何使用 Cloud Storage 和终端迁移数据和文件。

使用要求

您必须具有代管式笔记本实例的终端访问权限。终端访问权限是在创建实例时手动设置的。实例创建后，终端访问权限设置便无法更改。

使用 Cloud Storage 和终端手动迁移

如需使用 Cloud Storage 和终端将数据和文件迁移到新的 Vertex AI Workbench 实例，请执行以下操作。

1. 在代管式笔记本实例所在的项目中创建 Cloud Storage 存储桶。

2. 在同一项目中，创建 Vertex AI Workbench 实例以将数据迁移到其中。创建此实例时：

   • 启用终端访问权限。
   • 指定机器类型、网络和其他特性以符合您的需求。

3. 在代管式笔记本实例的 JupyterLab 界面中，选择文件 > 新建 > 终端，以打开终端窗口。

4. 使用 gsutil tool 将您的用户数据复制到 Cloud Storage 存储桶。以下示例命令会将实例 /home/jupyter/ 目录中的所有文件复制到 Cloud Storage 存储桶中的目录。

   gsutil cp -R /home/jupyter/* gs://BUCKET_NAMEPATH
   

   替换以下内容：

   • BUCKET_NAME：Cloud Storage 存储桶的名称
   • PATH：您要将文件复制到的目录的路径，例如 /copy/jupyter/

5. 在新的 Vertex AI Workbench 实例的 JupyterLab 界面中，选择 文件 > 新建 > 终端，以打开终端窗口。

6. 使用 gsutil tool 将数据复制到新实例。以下示例命令会将 Cloud Storage 目录中的所有文件复制到新实例的 /home/jupyter/ 目录中。

   gsutil cp gs://BUCKET_NAMEPATH* /home/jupyter/
   

确认迁移

迁移后，原始代管式笔记本实例会继续像以前一样工作。在删除原始实例之前，确认迁移成功。

删除代管式笔记本实例

如果您不需要从中迁移的代管式笔记本实例，请将其删除以避免该实例产生更多费用。

1. 在 Google Cloud 控制台中，前往代管式笔记本页面。

   前往“代管式笔记本”

2. 选择要删除的实例。

3. 点击 删除。（您可能需要点开 选项菜单才能看到删除按钮，具体取决于您的窗口大小。）

4. 请点击删除来确认操作。

问题排查

如需查找诊断和解决迁移问题的方法，请参阅排查 Vertex AI Workbench 问题。

后续步骤

• 详细了解 Vertex AI Workbench 实例。