使用執行器執行筆記本檔案

本文說明如何在 Vertex AI Workbench 代管型筆記本執行個體中使用執行器，以一次性執行作業和排程方式執行筆記本檔案。

總覽

執行器可讓您提交筆記本 (ipynb) 檔案，在 Vertex AI 自訂訓練中執行。您可以為每次執行筆記本檔案設定參數值。 您也可以排定筆記本檔案的執行時間，讓系統定期執行。執行完畢後，您可以查看執行結果並與他人分享。

將筆記本檔案提交至 Vertex AI 自訂訓練時，Vertex AI 會建立新的自訂訓練工作，並按照訓練工作生命週期執行筆記本檔案。

執行器執行的筆記本程式碼需求

編寫要在執行器中執行的筆記本程式碼時，請注意程式碼會在租戶專案中執行，與受管理筆記本執行個體的專案不同。本節說明這項變更對執行器中程式碼的影響。

確保執行者可安裝套件

如果筆記本依賴的套件安裝項目未包含在您使用的受管理筆記本核心中，請確保筆記本程式碼可透過下列其中一種方式，在執行器中使用套件：

  • 使用已安裝套件的自訂容器，然後在該自訂容器上執行筆記本。請參閱使用執行器搭配自訂容器的相關規定。

  • 在筆記本檔案的程式碼中安裝套件。 每次執行筆記本檔案時，系統都會安裝套件，但這可確保您執行筆記本時選取的容器中提供套件。

使用明確的專案選取方式

透過執行器執行的程式碼存取資源時，執行器可能無法連線至正確的Google Cloud 專案。如果發生權限錯誤，可能是連線到錯誤的專案。

發生這個問題的原因是，執行器不會直接在受管理筆記本執行個體的Google Cloud 專案中執行程式碼，而是由執行器在 Google 管理的租戶專案中，透過 Vertex AI 自訂訓練執行程式碼。因此，請勿嘗試從筆記本程式碼中的環境推斷專案 ID，而是明確指定專案 ID。

如不想在程式碼中硬式編碼專案 ID，可以參照 CLOUD_ML_PROJECT_ID 環境變數。 Vertex AI 會在每個自訂訓練容器中設定這個環境變數，其中包含您啟動自訂訓練的專案專案編號。許多 Google Cloud 工具接受專案 ID 的位置，也接受專案編號。

舉例來說，如果您想使用 Python Client for Google BigQuery 存取相同專案中的 BigQuery 資料表，請勿在筆記本程式碼中推斷專案：

隱含專案選取

from google.cloud import bigquery

client = bigquery.Client()

請改用明確選取專案的程式碼：

明確選取專案

import os

from google.cloud import bigquery

project_number = os.environ["CLOUD_ML_PROJECT_ID"]

client = bigquery.Client(project=project_number)

使用服務帳戶驗證存取權

根據預設，受管理筆記本執行個體可以存取相同專案中的資源。因此，手動執行筆記本檔案的程式碼時，這些資源不需要額外驗證。不過，由於執行器是在個別的租戶專案中執行，因此不具備相同的預設存取權。

此外，執行者無法使用使用者憑證驗證資源存取權，例如 gcloud auth login 指令。

如要解決這些問題，請在筆記本檔案的程式碼中，透過服務帳戶驗證資源存取權。

然後在建立執行作業或排程時，指定服務帳戶。

舉例來說，在建立執行作業時，請完成下列步驟：

  1. 在「Submit notebooks to Executor」(將筆記本提交至執行器) 對話方塊中，展開「Advanced options」(進階選項)。

  2. 在「身分及 API 存取權」部分，取消勾選「使用 Vertex AI Training 的預設服務帳戶」，然後輸入要使用的特定服務帳戶。

如需完整步驟，請參閱建立執行作業。

使用自訂容器時的規定

您可以使用執行器在自訂容器中執行筆記本程式碼。 自訂容器必須包含 nbexecutor 擴充功能，執行器才能將筆記本程式碼做為 Vertex AI 自訂訓練工作執行。如要確保自訂容器具有 nbexecutor 擴充功能，您可以修改其中一個深度學習容器容器映像檔，建立衍生容器映像檔。深度學習容器映像檔包含 nbexecutor 擴充功能。

事前準備

  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. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Notebooks and Vertex AI APIs.

    Enable the APIs

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

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Notebooks and Vertex AI APIs.

    Enable the APIs

    8.
  8. 如果您尚未建立代管型筆記本執行個體，請先完成這項作業。

    9. 必要的角色

    為確保執行個體的服務帳戶具備與 Vertex AI Workbench 執行器互動的必要權限，請要求管理員將專案的下列 IAM 角色授予執行個體的服務帳戶：

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

    管理員或許也能透過自訂角色或其他預先定義的角色，將必要權限授予執行個體的服務帳戶。

    開啟 JupyterLab

    如要開啟 JupyterLab 並準備要執行的筆記本檔案，請完成下列步驟。

    1. 開啟 JupyterLab。

    2. 上傳筆記本 (ipynb) 檔案、開啟現有檔案，或開啟新的筆記本檔案，然後將要執行的程式碼新增至筆記本。

    3. 確認筆記本檔案的程式碼符合使用執行器的規定。

    可建立執行作業

    如要建立執行作業來執行筆記本檔案，請完成下列步驟。這些步驟涵蓋排定執行作業和建立一次性執行作業。

    1. 在代管型筆記本執行個體的 JupyterLab 使用者介面中，開啟要執行的筆記本檔案。

    2. 按一下「執行」按鈕 。

    3. 在「Submit notebooks to Executor」(將筆記本提交至執行器) 對話方塊中，於「Execution name」(執行名稱) 欄位輸入執行名稱。

    4. 選取「Machine type」(機器類型)和「Accelerator type」(加速器類型)。

    5. 選取「環境」。

    6. 在「類型」欄位中，選取「一次性執行」，或選取「根據排程定期執行」，然後完成對話方塊，排定執行時間。

    7. 在「進階選項」中，選取要執行筆記本的「區域」。

    8. 在「Cloud Storage bucket」(Cloud Storage bucket) 欄位中，選取可用的 Cloud Storage bucket，或輸入新 bucket 的名稱，然後按一下「Create and select」(建立並選取)。 執行器會將筆記本輸出內容儲存在這個 Cloud Storage 值區中。

    9. 選用：在「Notebook parameterization」(筆記本參數化) 部分的「Input parameters」(輸入參數) 文字方塊中，新增以半形逗號分隔的筆記本參數，例如 optimizer="SGD",learning_rate=0.01。

      進一步瞭解如何使用筆記本參數。

    10. 選用：在「身分及 API 存取權」部分，選取「使用 Vertex AI Training 的預設服務帳戶」，或清除勾號並輸入要使用的特定服務帳戶。

    11. 選用步驟：在「網路」部分，指定虛擬私有雲網路。如要使用虛擬私有雲網路執行作業，必須建立私人服務存取權連線。

    12. 按一下「提交」。

      一次性執行作業會立即開始。 系統會按照您設定的時間表，自動執行排定的執行作業。

    在 Google Cloud 控制台的「Vertex AI Workbench」頁面中，您可以在「執行」分頁標籤中查看已完成的執行作業，並在「排程」分頁標籤中查看排程。

    查看、分享及匯入已執行的筆記本檔案

    透過代管型筆記本執行個體的 JupyterLab 使用者介面，您可以查看已執行的筆記本輸出內容、與他人分享結果，以及將已執行的筆記本檔案匯入 JupyterLab。

    查看筆記本執行的結果

    您可以在 Google Cloud 主控台 或 JupyterLab 使用者介面中查看筆記本執行結果。

    主控台

    1. 前往 Google Cloud 控制台的「Vertex AI Workbench」頁面，然後按一下「執行」分頁標籤。

      前往「執行」

    2. 選取包含結果的「Region」(區域)。

    3. 找出要查看的執行作業，然後按一下旁邊的「查看結果」。

      結果會在新瀏覽器分頁中開啟。

    JupyterLab

    1. 在 JupyterLab 的導覽選單中，按一下「Notebook Executor」(筆記本執行器) 按鈕。

    2. 按一下「執行」分頁標籤。

    3. 在要查看的執行作業下方，按一下「查看結果」。

      結果會在新瀏覽器分頁中開啟。

    分享筆記本執行結果

    如要共用執行結果，請提供含有筆記本執行的 Cloud Storage bucket 存取權。提供這項存取權時，也會授予使用者存取同一 Cloud Storage 值區中任何其他資源的權限。如要分享執行結果，請完成下列步驟。

    主控台

    1. 前往 Google Cloud 控制台的「Vertex AI Workbench」頁面，然後按一下「執行」分頁標籤。

      前往「執行」

    2. 選取包含執行的「Region」(區域)。

    3. 在要分享的執行作業旁邊，按一下「分享」按鈕。

    4. 按照對話方塊中的指示，授予使用者存取權，讓他們存取包含筆記本執行的 Cloud Storage 值區。

    JupyterLab

    1. 在代管型筆記本執行個體的 JupyterLab 使用者介面中，按一下導覽選單中的「Notebook Executor」按鈕。

    2. 按一下「執行」分頁標籤。

    3. 在要分享的執行作業旁邊，按一下 選單，然後選取「分享執行結果」。

    4. 按照對話方塊中的指示，授予使用者存取權，讓他們存取包含筆記本執行的 Cloud Storage 值區。

    將已執行的筆記本匯入 JupyterLab

    如要將已執行的筆記本匯入 JupyterLab，請完成下列步驟。

    1. 在代管型筆記本執行個體的 JupyterLab 使用者介面中，按一下導覽選單中的「Notebook Executor」按鈕。

    2. 按一下「執行」分頁標籤。

    3. 選取包含已執行筆記本的區域。

    4. 在要匯入的執行作業旁邊，按一下 選單，然後選取「匯入已執行的筆記本」。

    5. 選取要開啟筆記本的 Kernel。

      執行器會在 JupyterLab 中開啟已執行的筆記本檔案，並將這個筆記本檔案儲存在 JupyterLab 檔案瀏覽器的 imported_notebook_jobs 資料夾中。

    查看或刪除時間表

    您可以使用 Google Cloud 控制台或受管理筆記本執行個體的 JupyterLab 使用者介面，查看及刪除時間表。

    查看時間表

    查看排程，瞭解排程的頻率設定，或查看筆記本執行的結果。

    主控台

    1. 前往 Google Cloud 控制台的「Vertex AI Workbench」頁面，然後按一下「Schedules」分頁標籤。

      前往「時間表」

    2. 選取包含排程的區域。

    3. 按一下排程名稱，開啟「排程詳細資料」頁面。

    4. 按一下執行名稱旁的「查看結果」，即可開啟已執行的筆記本檔案。執行器會在新的瀏覽器分頁中開啟結果。

    JupyterLab

    1. 在代管型筆記本執行個體的 JupyterLab 使用者介面中，按一下導覽選單中的「Notebook Executor」按鈕。

    2. 按一下「時間表」分頁標籤。

    3. 如要查看最新執行作業，請在要查看的執行作業下方，按一下「查看最新執行結果」。 執行器會在新的瀏覽器分頁中開啟結果。

      如要查看所有執行作業，請按一下排程名稱。 執行者會在 Google Cloud 控制台中開啟「排程詳細資料」頁面。

    4. 按一下執行名稱旁的「查看結果」，即可開啟已執行的筆記本檔案。執行器會在新的瀏覽器分頁中開啟結果。

    刪除時間表

    刪除排程不會刪除從該排程產生的執行作業。

    主控台

    1. 前往 Google Cloud 控制台的「Vertex AI Workbench」頁面，然後按一下「Schedules」分頁標籤。

      前往「時間表」

    2. 選取包含排程的區域。

    3. 選取要刪除的時間表。

    4. 按一下「Delete」(刪除) 圖示 。

    JupyterLab

    1. 在代管型筆記本執行個體的 JupyterLab 使用者介面中，按一下導覽選單中的「Notebook Executor」按鈕。

    2. 按一下「時間表」分頁標籤。

    3. 按一下要刪除的排程名稱。 執行者會在 Google Cloud 控制台中開啟「排程詳細資料」頁面。

    4. 按一下「Delete」(刪除) 圖示 。

    Vertex AI 自訂訓練工作

    由於筆記本執行作業是在 Vertex AI 自訂訓練中執行，因此會以自訂訓練工作的形式顯示在 Vertex AI 中。您可以在 Google Cloud 控制台的「Vertex AI Training」頁面，查看「Custom jobs」分頁中的自訂訓練工作。進一步瞭解如何使用 Vertex AI 自訂訓練工作。

    後續步驟