エグゼキュータでノートブック ファイルを実行する
このページでは、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 コマンドなど）を使用してリソースへのアクセスを認証できません。
この問題を解決するには、ノートブック ファイルのコードでサービス アカウントを使用して、リソースへのアクセスを認証します。
実行またはスケジュールを作成するときにもサービス アカウントを指定します。
たとえば、実行を作成するときに、次の手順を行います。
[Submit notebooks to Executor] ダイアログで、[Advanced options] を開きます。
[Identity and API access] セクションで、[Use Vertex AI Training's default service account] の横にあるチェックマークをオフにし、使用するサービス アカウントを入力します。
詳しくは、実行の作成手順をご覧ください。
カスタム コンテナを使用する場合の要件
エグゼキュータを使用して、カスタム コンテナでノートブック コードを実行できます。カスタム コンテナには nbexecutor 拡張機能を含める必要があります。これにより、エグゼキュータはノートブック コードを Vertex AI カスタム トレーニング ジョブとして実行できます。カスタム コンテナに nbexecutor 拡張機能を含めるには、Deep Learning Containers コンテナ イメージの 1 つを変更して、派生コンテナ イメージを作成します。Deep Learning Containers イメージには nbexecutor 拡張機能が含まれています。
始める前に
- 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.
-
Google Cloud Console の [プロジェクト セレクタ] ページで、Google Cloud プロジェクトを選択または作成します。
-
Notebooks and Vertex AI API を有効にします。
-
Google Cloud Console の [プロジェクト セレクタ] ページで、Google Cloud プロジェクトを選択または作成します。
-
Notebooks and Vertex AI API を有効にします。
- まだ作成していない場合は、マネージド ノートブック インスタンスを作成します。
必要なロール
インスタンスのサービス アカウントに Vertex AI Workbench エグゼキュータの操作に必要な権限を付与するには、プロジェクトに対する次の IAM ロールをインスタンスのサービス アカウントに付与するよう管理者に依頼してください。
- Notebooks 閲覧者（
roles/notebooks.viewer） - Vertex AI ユーザー（
roles/aiplatform.user） - ストレージ管理者（
roles/storage.admin）
ロールの付与の詳細については、アクセスの管理をご覧ください。
管理者は、インスタンスのサービス アカウントに、カスタムロールや他の事前定義ロールを使用して必要な権限を付与することもできます。
JupyterLab を開く
JupyterLab を開き、実行するノートブック ファイルを準備するには、次の手順を行います。
ノートブック（ipynb）ファイルをアップロードするか、既存のファイルを開きます。あるいは、新しいノートブック ファイルを開いて、実行するコードをノートブックに追加します。
ノートブック ファイルのコードがエグゼキュータの使用要件を満たしていることを確認してください。
実行の作成
ノートブック ファイルの実行を作成するには、次の手順を行います。この手順は、実行のスケジューリングと 1 回限りの実行の両方を対象としています。
マネージド ノートブック インスタンスの JupyterLab ユーザー インターフェースで、実行するノートブック ファイルを開きます。
[Execute] ボタンをクリックします。
[Submit notebooks to Executor] ダイアログの [Execution name] フィールドに、実行の名前を入力します。
マシンタイプとアクセラレータ タイプを選択します。
環境を選択します。
[Type] フィールドで [One-time execution] を選択します。あるいは、[Schedule-based recurring executions] を選択して、ダイアログで実行スケジュールを設定します。
[Advanced options] で、ノートブックを実行するリージョンを選択します。
[Cloud Storage bucket] フィールドで、使用可能な Cloud Storage バケットを選択するか、新しいバケットの名前を入力して [Create and select] をクリックします。エグゼキュータは、この Cloud Storage バケットにノートブックの出力を保存します。
省略可: [Notebook parameterization] セクションの [Input parameters] テキスト ボックスに、ノートブック パラメータをカンマ区切りで追加します（例:
optimizer="SGD",learning_rate=0.01）。詳細については、ノートブック パラメータの使用方法をご覧ください。
省略可: [Identity and API access] セクションで、[Use Vertex AI Training's default service account] を選択するか、チェックマークをオフにして使用するサービス アカウントを入力します。
省略可: [Networking] セクションで Virtual Private Cloud ネットワークを指定します。実行に VPC ネットワークを使用する場合は、プライベート サービス アクセス接続が必要です。
[Submit] をクリックします。
1 回限りの実行は直ちに開始されます。スケジュールされた実行は、設定したスケジュールに従って自動的に実行されます。
Execute] ボタンをクリックします。完了した実行は、Google Cloud コンソールの [Vertex AI Workbench] ページの [実行] タブで確認できます。また、[スケジュール] タブでスケジュールを確認できます。
実行されたノートブック ファイルの表示、共有、インポート
マネージド ノートブック インスタンスの JupyterLab ユーザー インターフェースを使用すると、実行されたノートブックの出力を表示して、結果を他のユーザーと共有できます。また、実行されたノートブック ファイルを JupyterLab にインポートすることもできます。
ノートブックの実行結果を表示する
ノートブックの実行結果は、Google Cloud コンソールまたは JupyterLab ユーザー インターフェースで確認できます。
コンソール
Google Cloud コンソールで [Vertex AI Workbench] ページに移動し、[実行] タブをクリックします。
結果が含まれているリージョンを選択します。
表示する実行結果の横にある [結果を表示] をクリックします。
ブラウザの新しいタブに結果が表示されます。
JupyterLab
JupyterLab のナビゲーション メニューで [Notebook Executor] ボタンをクリックします。
[Executions] タブをクリックします。
表示する実行条件の下にある [View result] をクリックします。
ブラウザの新しいタブに結果が表示されます。
ノートブックの実行結果を共有する
実行結果を共有するには、ノートブックの実行を含む Cloud Storage バケットへのアクセスを許可します。このアクセス権を付与すると、同じ Cloud Storage バケット内の他のリソースにもアクセスできるようになります。実行結果を共有するには、次の手順を行います。
コンソール
Google Cloud コンソールで [Vertex AI Workbench] ページに移動し、[実行] タブをクリックします。
実行が含まれているリージョンを選択します。
共有する実行の横にある [共有] ボタンをクリックします。
ダイアログの指示に沿って、ノートブックの実行を含む Cloud Storage バケットへのアクセス権をユーザーに付与します。
JupyterLab
マネージド ノートブック インスタンスの JupyterLab ユーザー インターフェースで、ナビゲーション メニューで [Notebook Executor] ボタンをクリックします。
[Executions] タブをクリックします。
共有する実行の横にあるオプション メニューをクリックして、[Share execution result] を選択します。
ダイアログの指示に沿って、ノートブックの実行を含む Cloud Storage バケットへのアクセス権をユーザーに付与します。
実行したノートブックを JupyterLab にインポートする
実行したノートブックを JupyterLab にインポートするには、次の手順を行います。
マネージド ノートブック インスタンスの JupyterLab ユーザー インターフェースで、ナビゲーション メニューで [Notebook Executor] ボタンをクリックします。
[Executions] タブをクリックします。
実行したノートブックが含まれているリージョンを選択します。
インポートする実行の横にあるオプション メニューをクリックし、[Import executed notebook] を選択します。
ノートブックを開くカーネルを選択します。
エグゼキュータは、実行されたノートブック ファイルを JupyterLab で開きます。JupyterLab ファイル ブラウザで、このノートブック ファイルは imported_notebook_jobs フォルダに保存されています。
スケジュールを表示または削除する
スケジュールを表示および削除するには、Google Cloud コンソールまたはマネージド ノートブック インスタンスの JupyterLab ユーザー インターフェースを使用します。
スケジュールを表示する
スケジュールを表示して、スケジュールの頻度設定やノートブックの実行結果を確認します。
コンソール
Google Cloud コンソールで [Vertex AI Workbench] ページに移動し、[スケジュール] タブをクリックします。
スケジュールが含まれているリージョンを選択します。
スケジュール名をクリックして、[スケジュールの詳細] ページを開きます。
実行名の横の [結果を表示] をクリックして、実行されたノートブック ファイルを開きます。エグゼキュータが新しいブラウザタブに結果を表示します。
JupyterLab
マネージド ノートブック インスタンスの JupyterLab ユーザー インターフェースで、ナビゲーション メニューで [Notebook Executor] ボタンをクリックします。
[Schedules] タブをクリックします。
最新の実行を表示するには、表示する実行の下で [View latest execution result] をクリックします。エグゼキュータが新しいブラウザタブに結果を表示します。
すべての実行を確認するには、スケジュールの名前をクリックします。エグゼキュータが Google Cloud コンソールで [スケジュールの詳細] ページを開きます。
実行名の横の [結果を表示] をクリックして、実行されたノートブック ファイルを開きます。エグゼキュータが新しいブラウザタブに結果を表示します。
スケジュールを削除する
スケジュールを削除しても、そのスケジュールから生成された実行は削除されません。
コンソール
Google Cloud コンソールで [Vertex AI Workbench] ページに移動し、[スケジュール] タブをクリックします。
スケジュールが含まれているリージョンを選択します。
削除するスケジュールを選択します。
[削除] をクリックします。
JupyterLab
マネージド ノートブック インスタンスの JupyterLab ユーザー インターフェースで、ナビゲーション メニューで [Notebook Executor] ボタンをクリックします。
[Schedules] タブをクリックします。
削除するスケジュールの名前をクリックします。エグゼキュータが Google Cloud コンソールで [スケジュールの詳細] ページを開きます。
[削除] をクリックします。
Vertex AI カスタム トレーニング ジョブ
ノートブックの実行は Vertex AI カスタム トレーニングで実行されます。このため、ノートブックは、Vertex AI でカスタム トレーニング ジョブとして公開されます。これらのカスタム トレーニング ジョブは、Google Cloud コンソールの [Vertex AI Training] ページの [カスタムジョブ] タブで確認できます。詳細については、Vertex AI カスタム トレーニング ジョブの操作方法をご覧ください。
次のステップ
パラメータを使用したノートブックの実行方法を学習する。
Vertex AI カスタム トレーニングの詳細をご覧ください。