從代管型筆記本遷移至 Vertex AI Workbench 執行個體

從代管型筆記本遷移至 Vertex AI Workbench 執行個體

Vertex AI Workbench 代管型筆記本已淘汰。 我們將於 2025 年 4 月 14 日停止支援代管筆記本，並移除建立這類執行個體的功能。現有執行個體仍可繼續運作，但無法使用修補程式、更新和升級。如要繼續使用 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 不會刪除或變更代管筆記本執行個體，因此遷移後您可以繼續使用。如果不再需要受管理筆記本執行個體，請刪除該執行個體，以免產生進一步費用。

帳單

如果受管理 Notebooks 執行個體使用 Extreme 永久磁碟，遷移作業會產生 I/O 作業費用。請參閱磁碟定價的「永久磁碟和 Hyperdisk 定價」部分，瞭解「極端佈建 IOPS」。

遷移後，代管型筆記本執行個體仍會存在，並照常產生費用。如果不再需要受管理筆記本執行個體，請刪除該執行個體，以免產生進一步費用。

預設遷移工具行為

Vertex AI Workbench 遷移工具會嘗試將代管型筆記本執行個體遷移至規格相符的 Vertex AI Workbench 執行個體。如果代管型筆記本執行個體中的規格無法在 Vertex AI Workbench 執行個體中使用，Vertex AI Workbench 會盡可能使用預設規格。如果遷移工具無法遷移代管 Notebooks 執行個體的規格，就不會遷移該執行個體。

下表列出遷移工具的一些主要預設遷移行為。

類別	代管筆記本規格	遷移結果
作業系統	任何 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	已遷移
	下載檔案	已遷移
	終端機存取權	已遷移
其他	身分與存取權管理權限	已遷移，但可能需要新權限才能使用 Vertex AI Workbench 執行個體
	存取模式	已遷移；使用單一使用者 JupyterLab 存取模式的執行個體必須指定 serviceAccount 選項
	網路	已遷移；使用 Google 管理的虛擬私有雲的執行個體必須指定 network 和 subnet 選項
	開機後指令碼	使用 Google Cloud 控制台時，系統會遷移執行個體，但不會遷移開機後指令碼；如要遷移執行個體和開機後指令碼，請使用 Google Cloud CLI 或 REST API 指定 PostStartupScriptOption 選項。
	Dataproc Hub	尚未遷移，必須手動遷移

指定選項

以下各節說明將代管型筆記本執行個體遷移至 Vertex AI Workbench 執行個體時，必須指定選項的情況。

使用單一使用者存取模式的執行個體

使用單一使用者存取模式的代管筆記本執行個體，必須遷移至指定 serviceAccount 選項的執行個體。您要遷移的 Vertex AI Workbench 執行個體會限制單一使用者存取 JupyterLab，但會使用服務帳戶與 Google Cloud 服務和 API 互動。

使用 Google 代管虛擬私有雲的執行個體

使用 Google 管理的 VPC 的代管筆記本執行個體，必須遷移至指定 network 和 subnet 選項的執行個體。Vertex AI Workbench 執行個體不支援使用 Google 管理的虛擬私有雲，因此必須指定其他網路。

使用執行後開機指令碼的執行個體

使用開機後指令碼的代管筆記本執行個體必須遷移至指定 PostStartupScriptOption 選項的執行個體。使用這個選項，指出是否要在新的 Vertex AI Workbench 執行個體中略過或重新執行啟動後指令碼。

Google Cloud 控制台不支援指定 PostStartupScriptOption 選項。如要在遷移受管理筆記本執行個體時指定 PostStartupScriptOption 選項，請使用 Google Cloud CLI 或 REST API。

事前準備

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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 執行個體所需的權限，請要求管理員授予您專案的 Notebooks Runner (roles/notebooks.runner) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備將代管型筆記本執行個體遷移至 Vertex AI Workbench 執行個體所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要將代管型筆記本執行個體遷移至 Vertex AI Workbench 執行個體，您必須具備下列權限：

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

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

遷移前檢查

遷移前，請先列出執行個體，並檢查輸出內容是否有任何遷移警告或錯誤，確認受管理筆記本執行個體是否符合遷移資格。

列出執行個體

如要列出尚未遷移的受管理 Notebooks 執行個體，請使用 projects.locations.runtimes.list 方法和 migrated:false 篩選器。您可以使用 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。您可以執行 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 執行個體中的相同規格，系統就會顯示警告。舉例來說，如果受管理筆記本執行個體使用不支援的加速器，輸出內容中會顯示警告。在這種情況下，系統會遷移執行個體，但不會遷移任何加速器。遷移完成後，您就可以連結加速器。查看輸出內容中的警告，考量遷移工具的預設行為，並評估遷移工具是否適合您的遷移作業。

如果輸出內容中有一或多個錯誤，表示您無法使用遷移工具遷移受管理 Notebooks 執行個體。您必須手動遷移執行個體。

如要進一步瞭解遷移警告和錯誤，請參閱 RuntimeMigrationEligibility 說明文件中的警告和錯誤。

使用遷移工具進行遷移

您可以使用 Google Cloud 控制台、gcloud CLI 或 REST API 遷移受管理筆記本執行個體。

控制台

1. 前往 Google Cloud 控制台的「受管理 Notebook」頁面。

   前往代管型筆記本

2. 按一下「遷移」按鈕。「將代管的筆記本遷移至執行個體」頁面隨即開啟。

3. 如要遷移不需要指定選項的執行個體，請按一下「Ready」(就緒) 分頁標籤，選取要遷移的執行個體，然後按一下「Migrate」(遷移)。

4. 如要遷移需要指定選項的執行個體，請按一下「需要輸入」分頁，選取要遷移的執行個體，然後按一下「遷移」。

   1. 在「提供遷移輸入內容」對話方塊中，指定要用於所選新 Vertex AI Workbench 執行個體的網路和服務帳戶。

   2. 按一下「提交」。

5. 遷移完成後，請前往「執行個體」頁面，查看新的 Vertex AI Workbench 執行個體。

   前往「Instances」(執行個體)

gcloud

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

• PROJECT_ID：專案 ID
• LOCATION：代管筆記本執行個體所在的區域
• RUNTIME_ID：代管筆記本執行個體的 ID
• NETWORK：要將執行個體遷移至的網路
• SUBNET：要將執行個體遷移至的子網路
• SUBNET_REGION：子網路的區域
• 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 \
    --subnet-region=SUBNET_REGION \
    --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 `
    --subnet-region=SUBNET_REGION `
    --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 ^
    --subnet-region=SUBNET_REGION ^
    --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。您可以執行 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 bucket。

2. 在同一個專案中，建立 Vertex AI Workbench 執行個體，以便將資料遷移至該執行個體。建立這個執行個體時：

   • 啟用終端機存取權。
   • 指定機器類型、網路和其他特徵，以符合您的需求。

3. 在受管理筆記本執行個體的 JupyterLab 介面中，依序選取「File」(檔案)>「New」(新增)>「Terminal」(終端機)，開啟終端機視窗。

4. 使用 gcloud CLI 將使用者資料複製到 Cloud Storage bucket。以下範例指令會將執行個體 /home/jupyter/ 目錄中的所有檔案，複製到 Cloud Storage bucket 的目錄。

   gcloud storage cp /home/jupyter/* gs://BUCKET_NAMEPATH --recursive

   更改下列內容：

   • BUCKET_NAME：Cloud Storage bucket 的名稱
   • PATH：要複製檔案的目錄路徑，例如：/copy/jupyter/

5. 在新的 Vertex AI Workbench 執行個體 JupyterLab 介面中，依序選取「File」>「New」>「Terminal」，開啟終端機視窗。

6. 使用 gcloud CLI 將資料複製到新執行個體。 以下範例指令會將 Cloud Storage 目錄中的所有檔案，複製到新執行個體的 /home/jupyter/ 目錄。

   gcloud storage cp gs://BUCKET_NAMEPATH* /home/jupyter/ --recursive

確認遷移

遷移後，原始受管理筆記本執行個體會照常運作。刪除原始執行個體前，請先確認遷移作業是否成功。

刪除代管型筆記本執行個體

如果您不需要從中移轉的受管理 Notebooks 執行個體，請將其刪除，以免該執行個體產生後續費用。

1. 前往 Google Cloud 控制台的「受管理 Notebook」頁面。

   前往代管型筆記本

2. 選取要刪除的執行個體。

3. 按一下 「Delete」(刪除) (依視窗大小而定，「Delete」(刪除) 按鈕可能位於 選項選單中)。

4. 按一下「Delete」(刪除) 確認操作。

疑難排解

如要瞭解如何診斷及解決遷移問題，請參閱「疑難排解 Vertex AI Workbench」。

後續步驟

• 進一步瞭解 Vertex AI Workbench 執行個體。