エグゼキュータでノートブック ファイルを実行する

エグゼキュータでノートブック ファイルを実行する

Vertex AI Workbench マネージド ノートブックは非推奨になりました。2025 年 1 月 30 日にマネージド ノートブックのサポートが終了し、マネージド ノートブック インスタンスを作成する機能が削除されます。既存のインスタンスは引き続き機能しますが、パッチ、更新、アップグレードは利用できなくなります。Vertex AI Workbench を引き続き使用するには、マネージド ノートブック インスタンスを Vertex AI Workbench インスタンスに移行することをおすすめします。

このページでは、Vertex AI Workbench マネージド ノートブック インスタンスでエグゼキュータを使用し、1 回限りの実行またはスケジュールに従ってノートブック ファイルを実行する方法について説明します。

概要

エグゼキュータを使用すると、Vertex AI カスタム トレーニングで実行するノートブック（ipynb）ファイルを送信できます。ノートブック ファイルを実行するたびに、パラメータ値を設定できます。ノートブック ファイルを定期的に実行することもできます。実行が完了したら、実行結果を表示して他のユーザーと共有できます。

ノートブック ファイルが Vertex AI カスタム トレーニングに送信されると、Vertex AI はトレーニング ジョブのライフサイクルに従って、ノートブック ファイルを実行する新しいカスタム トレーニング ジョブを作成します。

エグゼキュータが実行するノートブック コードの要件

エグゼキュータで実行するノートブック コードは、マネージド ノートブック インスタンスのプロジェクトではなく、別のテナント プロジェクトで実行されます。コードを作成する場合は、この点に注意してください。このセクションでは、エグゼキュータでコードを実行する場合、この違いがコードにどのように影響するのかについて説明します。

エグゼキュータでパッケージをインストールできることを確認する

ノートブックが、使用しているマネージド ノートブック カーネルにまだ含まれていないパッケージのインストールに依存している場合は、次のいずれかの方法を行い、エグゼキュータのノートブック コードでパッケージを利用できるかどうか確認してください。

• すでにパッケージがインストールされているカスタム コンテナでノートブックを実行する。エグゼキュータでカスタム コンテナを使用する場合の要件をご覧ください。

• ノートブック ファイルのコード内にパッケージをインストールする。パッケージは、ノートブック ファイルが実行されるたびにインストールされます。これにより、ノートブックの実行時に選択したコンテナでパッケージを使用できます。

プロジェクトを明示的に選択する

エグゼキュータによって実行されるコードからリソースにアクセスする場合、エグゼキュータが正しい Google Cloud プロジェクトに接続できない場合があります。権限エラーが発生した場合は、間違ったプロジェクトに接続している可能性があります。

この問題は、エグゼキュータがマネージド ノートブック インスタンスの Google Cloud プロジェクトでコードを直接実行しないために発生します。エグゼキュータは、Google 管理のテナント プロジェクトで Vertex AI カスタム トレーニングのコードを実行します。そのため、ノートブック コードの環境のプロジェクト ID を推測させるのではなく、プロジェクト ID を明示的に指定する必要があります。

コード内にプロジェクト ID をハードコードしない場合は、CLOUD_ML_PROJECT_ID 環境変数を使用します。Vertex AI では、この環境変数をすべてのカスタム トレーニング コンテナに設定し、カスタム トレーニングを開始したプロジェクトのプロジェクト番号を格納します。Google Cloud ツールの多くは、プロジェクト ID を受け取ると、プロジェクト番号を受け入れることができます。

たとえば、Google BigQuery 用 Python クライアントを使用して同じプロジェクト内の 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. [Identity and API access] セクションで、[Use Vertex AI Training's default service account] の横にあるチェックマークをオフにし、使用するサービス アカウントを入力します。

詳しくは、実行の作成手順をご覧ください。

カスタム コンテナを使用する場合の要件

エグゼキュータを使用して、カスタム コンテナでノートブック コードを実行できます。カスタム コンテナには nbexecutor 拡張機能を含める必要があります。これにより、エグゼキュータはノートブック コードを Vertex AI カスタム トレーニング ジョブとして実行できます。カスタム コンテナに nbexecutor 拡張機能を含めるには、Deep Learning Containers コンテナ イメージの 1 つを変更して、派生コンテナ イメージを作成します。Deep Learning Containers イメージには 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.

   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

3. Make sure 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.

   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

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

7. Enable the Notebooks and Vertex AI APIs.

   Enable the APIs

8. まだ作成していない場合は、マネージド ノートブック インスタンスを作成します。

必要なロール

インスタンスのサービス アカウントに Vertex AI Workbench エグゼキュータの操作に必要な権限を付与するには、プロジェクトに対する次の IAM ロールをインスタンスのサービス アカウントに付与するよう管理者に依頼してください。

• Notebooks 閲覧者（roles/notebooks.viewer）
• Vertex AI ユーザー（roles/aiplatform.user）
• ストレージ管理者（roles/storage.admin）

ロールの付与の詳細については、アクセスの管理をご覧ください。

管理者は、インスタンスのサービス アカウントに、カスタムロールや他の事前定義ロールを使用して必要な権限を付与することもできます。

JupyterLab を開く

JupyterLab を開き、実行するノートブック ファイルを準備するには、次の手順を行います。

1. JupyterLab を開きます。

2. ノートブック（ipynb）ファイルをアップロードするか、既存のファイルを開きます。あるいは、新しいノートブック ファイルを開いて、実行するコードをノートブックに追加します。

3. ノートブック ファイルのコードがエグゼキュータの使用要件を満たしていることを確認してください。

実行の作成

ノートブック ファイルの実行を作成するには、次の手順を行います。この手順は、実行のスケジューリングと 1 回限りの実行の両方を対象としています。

1. マネージド ノートブック インスタンスの JupyterLab ユーザー インターフェースで、実行するノートブック ファイルを開きます。

2. [Execute] ボタンをクリックします。

3. [Submit notebooks to Executor] ダイアログの [Execution name] フィールドに、実行の名前を入力します。

4. マシンタイプとアクセラレータ タイプを選択します。

5. 環境を選択します。

6. [Type] フィールドで [One-time execution] を選択します。あるいは、[Schedule-based recurring executions] を選択して、ダイアログで実行スケジュールを設定します。

7. [Advanced options] で、ノートブックを実行するリージョンを選択します。

8. [Cloud Storage bucket] フィールドで、使用可能な Cloud Storage バケットを選択するか、新しいバケットの名前を入力して [Create and select] をクリックします。エグゼキュータは、この Cloud Storage バケットにノートブックの出力を保存します。

9. 省略可: [Notebook parameterization] セクションの [Input parameters] テキスト ボックスに、ノートブック パラメータをカンマ区切りで追加します（例: optimizer="SGD",learning_rate=0.01）。

   詳細については、ノートブック パラメータの使用方法をご覧ください。

10. 省略可: [Identity and API access] セクションで、[Use Vertex AI Training's default service account] を選択するか、チェックマークをオフにして使用するサービス アカウントを入力します。

    注: ノートブック ファイルのコードが、エンドユーザーの認証情報またはマネージド ノートブック インスタンス プロジェクトのデフォルトのアクセス権でサービスへのアクセスを認証する場合は、エグゼキュータが実行するノートブック コードの要件を参照して、サービス アカウントを指定することを検討してください。

11. 省略可: [Networking] セクションで Virtual Private Cloud ネットワークを指定します。実行に VPC ネットワークを使用する場合は、プライベート サービス アクセス接続が必要です。

12. [Submit] をクリックします。

    1 回限りの実行は直ちに開始されます。スケジュールされた実行は、設定したスケジュールに従って自動的に実行されます。

    注: マネージド ノートブック インスタンスがシャットダウンされても、エグゼキュータはスケジュールに従ってノートブック ファイルを実行します。

完了した実行は、Google Cloud コンソールの [Vertex AI Workbench] ページの [実行] タブで確認できます。また、[スケジュール] タブでスケジュールを確認できます。

実行されたノートブック ファイルの表示、共有、インポート

マネージド ノートブック インスタンスの JupyterLab ユーザー インターフェースを使用すると、実行されたノートブックの出力を表示して、結果を他のユーザーと共有できます。また、実行されたノートブック ファイルを JupyterLab にインポートすることもできます。

ノートブックの実行結果を表示する

ノートブックの実行結果は、Google Cloud コンソールまたは JupyterLab ユーザー インターフェースで確認できます。

コンソール

1. Google Cloud コンソールで [Vertex AI Workbench] ページに移動し、[実行] タブをクリックします。

   [実行] に移動

2. 結果が含まれているリージョンを選択します。

3. 表示する実行結果の横にある [結果を表示] をクリックします。

   ブラウザの新しいタブに結果が表示されます。

JupyterLab

1. JupyterLab のナビゲーション メニューで [Notebook Executor] ボタンをクリックします。

2. [Executions] タブをクリックします。

3. 表示する実行条件の下にある [View result] をクリックします。

   ブラウザの新しいタブに結果が表示されます。

ノートブックの実行結果を共有する

実行結果を共有するには、ノートブックの実行を含む Cloud Storage バケットへのアクセスを許可します。このアクセス権を付与すると、同じ Cloud Storage バケット内の他のリソースにもアクセスできるようになります。実行結果を共有するには、次の手順を行います。

コンソール

1. Google Cloud コンソールで [Vertex AI Workbench] ページに移動し、[実行] タブをクリックします。

   [実行] に移動

2. 実行が含まれているリージョンを選択します。

3. 共有する実行の横にある [共有] ボタンをクリックします。

4. ダイアログの指示に沿って、ノートブックの実行を含む Cloud Storage バケットへのアクセス権をユーザーに付与します。

JupyterLab

1. マネージド ノートブック インスタンスの JupyterLab ユーザー インターフェースで、ナビゲーション メニューで [Notebook Executor] ボタンをクリックします。

2. [Executions] タブをクリックします。

3. 共有する実行の横にあるオプション メニューをクリックして、[Share execution result] を選択します。

4. ダイアログの指示に沿って、ノートブックの実行を含む Cloud Storage バケットへのアクセス権をユーザーに付与します。

実行したノートブックを JupyterLab にインポートする

実行したノートブックを JupyterLab にインポートするには、次の手順を行います。

1. マネージド ノートブック インスタンスの JupyterLab ユーザー インターフェースで、ナビゲーション メニューで [Notebook Executor] ボタンをクリックします。

2. [Executions] タブをクリックします。

3. 実行したノートブックが含まれているリージョンを選択します。

4. インポートする実行の横にあるオプション メニューをクリックし、[Import executed notebook] を選択します。

5. ノートブックを開くカーネルを選択します。

   エグゼキュータは、実行されたノートブック ファイルを JupyterLab で開きます。JupyterLab ファイル ブラウザで、このノートブック ファイルは imported_notebook_jobs フォルダに保存されています。

スケジュールを表示または削除する

スケジュールを表示および削除するには、Google Cloud コンソールまたはマネージド ノートブック インスタンスの JupyterLab ユーザー インターフェースを使用します。

スケジュールを表示する

スケジュールを表示して、スケジュールの頻度設定やノートブックの実行結果を確認します。

コンソール

1. Google Cloud コンソールで [Vertex AI Workbench] ページに移動し、[スケジュール] タブをクリックします。

   [スケジュール] に移動

2. スケジュールが含まれているリージョンを選択します。

3. スケジュール名をクリックして、[スケジュールの詳細] ページを開きます。

4. 実行名の横の [結果を表示] をクリックして、実行されたノートブック ファイルを開きます。エグゼキュータが新しいブラウザタブに結果を表示します。

JupyterLab

1. マネージド ノートブック インスタンスの JupyterLab ユーザー インターフェースで、ナビゲーション メニューで [Notebook Executor] ボタンをクリックします。

2. [Schedules] タブをクリックします。

3. 最新の実行を表示するには、表示する実行の下で [View latest execution result] をクリックします。エグゼキュータが新しいブラウザタブに結果を表示します。

   すべての実行を確認するには、スケジュールの名前をクリックします。エグゼキュータが Google Cloud コンソールで [スケジュールの詳細] ページを開きます。

4. 実行名の横の [結果を表示] をクリックして、実行されたノートブック ファイルを開きます。エグゼキュータが新しいブラウザタブに結果を表示します。

スケジュールを削除する

スケジュールを削除しても、そのスケジュールから生成された実行は削除されません。

コンソール

1. Google Cloud コンソールで [Vertex AI Workbench] ページに移動し、[スケジュール] タブをクリックします。

   [スケジュール] に移動

2. スケジュールが含まれているリージョンを選択します。

3. 削除するスケジュールを選択します。

4. [削除] をクリックします。

JupyterLab

1. マネージド ノートブック インスタンスの JupyterLab ユーザー インターフェースで、ナビゲーション メニューで [Notebook Executor] ボタンをクリックします。

2. [Schedules] タブをクリックします。

3. 削除するスケジュールの名前をクリックします。エグゼキュータが Google Cloud コンソールで [スケジュールの詳細] ページを開きます。

4. [削除] をクリックします。

Vertex AI カスタム トレーニング ジョブ

ノートブックの実行は Vertex AI カスタム トレーニングで実行されます。このため、ノートブックは、Vertex AI でカスタム トレーニング ジョブとして公開されます。これらのカスタム トレーニング ジョブは、Google Cloud コンソールの [Vertex AI Training] ページの [カスタムジョブ] タブで確認できます。詳細については、Vertex AI カスタム トレーニング ジョブの操作方法をご覧ください。

次のステップ

• パラメータを使用したノートブックの実行方法を学習する。

• Vertex AI カスタム トレーニングの詳細をご覧ください。