トレーニングコードをコンテナ化してローカルで実行する

gcloud ai custom-jobs local-run コマンドを使用すると、トレーニングコードに基づいて Docker コンテナイメージをビルドし、イメージをローカルコンピュータのコンテナとして実行できます。この機能には次のようなメリットがあります。

Docker の知識がなくてもコンテナイメージを作成できます。独自の Dockerfile を記述する必要がありません。このイメージを後で Artifact Registry に push し、カスタムコンテナトレーニングに使用できます。

高度なユースケースでは、独自の Dockerfile を作成することもできます。
コンテナイメージでは、Python トレーニングアプリケーションまたは Bash スクリプトを実行できます。

Bash スクリプトを使用すると、別のプログラミング言語で記述されたトレーニングコードを実行できます（ただし、その言語をサポートするベースコンテナイメージを指定する必要があります）。
コンテナをローカルで実行する場合、Vertex AI で実行する場合と類似した方法でトレーニングコードを実行できます。

コードをローカルで実行すると、Vertex AI でカスタムトレーニングを行う前に、コードの問題をデバッグできます。

始める前に

Vertex AI 開発環境を設定します。
Docker Engine をインストールします。
Linux を使用している場合は、sudo なしで実行できるように Docker を構成します。

Docker を使用する場合、local-run コマンドを実行するためにこの構成が必要になります。

`local-run` コマンドを使用する

次のコマンドを実行して、トレーニングコードに基づいてコンテナイメージをビルドし、コンテナをローカルで実行します。

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME

次のように置き換えます。

BASE_IMAGE_URI: コンテナのベースとして使用する Docker イメージの URI。トレーニングコードに必要な依存関係を含むベースイメージを選択します。

この URI を使用すると、事前にビルドされたトレーニングコンテナイメージや、Dockerfile FROM の命令に有効なその他の値を使用できます。たとえば、アクセス可能な一般公開の Docker イメージや、Artifact Registry 内の Docker イメージなどを使用できます。
WORKING_DIRECTORY: トレーニングに使用する必要があるすべてのトレーニングコードとローカル依存関係を含む、ファイルシステムの最下位のディレクトリ。

デフォルトでは、このコマンドは --script フラグ（次のリスト項目を参照）で指定されたファイルの親ディレクトリのみをコピーします。Docker イメージには、WORKING_DIRECTORY 内のすべてのファイルが含まれているとは限りません。含まれるファイルをカスタマイズする方法については、このドキュメントの依存関係をインクルードするをご覧ください。

--local-package-path フラグ（とこのプレースホルダ）を省略すると、local-run コマンドは、この値に現在の作業ディレクトリを使用します。
SCRIPT_PATH: ローカルファイルシステム上の WORKING_DIRECTORY の相対パス。トレーニングコードのエントリポイントとなるスクリプトへの相対パスになります。これは、Python スクリプト（.py で終わるもの）または Bash スクリプトです。

たとえば、/hello-world/trainer/task.py を実行し、WORKING_DIRECTORY が /hello-world の場合は、この値に trainer/task.py を使用します。

Python スクリプトを指定する場合は、ベースイメージに Python がインストールされている必要があります。bash スクリプトを指定する場合は、ベースイメージに Bash がインストールされている必要があります（すべてのビルド済みトレーニングコンテナと、多くの公開されているその他の Docker イメージには、両方の依存関係が含まれます）。

--script ではなく --python-module を使用する

--script フラグ（および SCRIPT_PATH）を省略した場合は、代わりに --python-module フラグを使用して、トレーニングのエントリポイントとして実行する WORKING_DIRECTORY モジュール内の Python モジュールの名前を指定する必要があります。たとえば、--script=trainer/task.py の代わりに --python-module=trainer.task を指定できます。

この場合、作成された Docker コンテナはスクリプトではなく、モジュールとしてコードを読み込みます。エントリポイントスクリプトが WORKING_DIRECTORY 内の他の Python モジュールをインポートする場合は、このオプションを使用できます。
OUTPUT_IMAGE_NAME: コマンドによってビルドされた Docker イメージの名前。docker build の -t フラグによって受け入れられる任意の値を使用できます。

後でイメージを Artifact Registry に push する場合は、Artifact Registry の要件を満たすイメージ名を使用することをおすすめします。後でイメージを Container Registry に push する場合は、Container Registry の要件を満たすイメージ名を使用します（また、後で別の名前でイメージにタグを付けることもできます）。

--output-image-uri フラグ（とこのプレースホルダ）を省略すると、local-run コマンドは、現在の時刻とエントリポイントスクリプトのファイル名に基づいてイメージをタグ付けします。

このコマンドにより、構成に基づいて Docker コンテナイメージがビルドされます。イメージをビルドした後、このコマンドは次のものを出力します。

A training image is built.
Starting to run ...

このコマンドは、このコンテナイメージをすぐに使用してローカルコンピュータ上でコンテナを実行します。コンテナが終了すると、コマンドは次のものを出力します。

A local run is finished successfully using custom image: OUTPUT_IMAGE_NAME

その他のオプション

以降のセクションでは、local-run コマンドの動作をカスタマイズする際に使用できる追加オプションについて説明します。

依存関係をインストールする

トレーニングコードは、ベースイメージにインストールされている依存関係に依存する場合があります（たとえば、事前にビルド済みのトレーニングコンテナのイメージには、ML 用の多くの Python ライブラリが含まれています）。また、local-run コマンドによって作成された Docker イメージに含まれる任意のファイルに依存することもあります。

--script フラグまたは --python-module フラグを使用してスクリプトを指定すると、スクリプトの親ディレクトリ（とそのサブディレクトリ）が Docker イメージにコピーされます。たとえば、--local-package-path=/hello-world と --script=trainer/task.py を指定すると、/hello-world/trainer/ が Docker イメージにコピーされます。

次のいずれかのセクションで説明されている手順を行って、追加の Python 依存関係やファイルシステムの任意のファイルを含めることもできます。

Python 依存関係に requirements.txt ファイルを使用する
Python 依存関係に setup.py ファイルを使用する
個々の PyPI 依存関係を指定する
ローカルの Python 依存関係を指定する
その他のファイルをインクルードする

追加の Python 依存関係をインストールする

Docker イメージに別の Python 依存関係を追加するには、次のような方法があります。

`requirements.txt` ファイルを使用する

作業ディレクトリに requirements.txt という名前のファイルがある場合、local-run コマンドはこれを pip 要件ファイルとして扱い、これにより、Docker イメージ内に Python 依存関係をインストールします。

`setup.py` ファイルを使用する

作業ディレクトリに setup.py というファイルがある場合、local-run コマンドはそれを Python setup.py ファイルとして扱い、Docker イメージにコピーします。さらに、このファイルを含む Docker イメージ内のディレクトリで pip install を実行します。

たとえば、Docker イメージに Python 依存関係をインストールするには、setup.py に install_requires 引数を追加できます。

個々の PyPI 依存関係を指定する

Docker イメージの PyPI から特定の依存関係をインストールするには、--requirements フラグを使用します。次に例を示します。

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --requirements=REQUIREMENTS

REQUIREMENTS は、Python 要件指定子のカンマ区切りリストに置き換えます。

追加のローカル Python 依存関係を指定する

特定のローカル Python 依存関係をインストールするには、--extra-packages フラグを使用します。これらの Python 依存関係は作業ディレクトリにあります。各依存関係は、pip install でサポートされている形式にする必要があります（例: wheel ファイル、Python ソース配布など）。

次に例を示します。

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --extra-packages=LOCAL_DEPENDENCIES

LOCAL_DEPENDENCIES は、ローカルファイルパスのカンマ区切りのリスト（作業ディレクトリを基準とする相対パス）に置き換えます。

他のファイルを含める

追加のディレクトリを Python の依存関係としてインストールせずに Docker イメージにコピーするには、--extra-dirs フラグを使用します。ディレクトリは作業ディレクトリの下にのみ指定できます。次に例を示します。

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --extra-dirs=EXTRA_DIRECTORIES

EXTRA_DIRECTORIES は、作業ディレクトリを基準にした、カンマ区切りのローカルディレクトリのリストに置き換えます。

トレーニングアプリケーションの引数

トレーニングアプリケーションで、エントリポイントスクリプトにコマンドライン引数が渡されることを前提としている場合は、local-run コマンドを実行するときに指定できます。これらの引数は Docker イメージに保存されません。イメージがコンテナとして実行されたときに、引数として渡されます。

エントリポイントスクリプトに引数を渡すには、すべてのコマンドの他のフラグの後に、スクリプト引数が続く -- 引数を指定して、local-run コマンドに渡します。

たとえば、次のコマンドを使用して、スクリプトをローカルで実行するとします。

python /hello-world/trainer/task.py \
  --learning_rate=0.1 \
  --input_data=gs://BUCKET/small-dataset/

local-run コマンドを使用する場合は、次のフラグを指定すると、同じ引数を使用してコンテナ内でスクリプトを実行できます。

gcloud ai custom-jobs local-run \\
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=/hello-world \
  --script=/trainer/task.py \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  -- \
  --learning_rate=0.1 \
  --input_data=gs://BUCKET/small-dataset/

GPU を使用してモデルトレーニングを加速する

local-run コマンドで作成した Docker イメージを最終的に Vertex AI にデプロイし、トレーニングに GPU を使用する場合は、GPU を活用するトレーニングコードを作成して、--executor-image-uri フラグの値に GPU 対応の Docker イメージを使用します。たとえば、GPU をサポートするビルド済みのトレーニングコンテナイメージを使用できます。

ローカルコンピュータで Linux が実行され、GPU が搭載されている場合は、ローカルでコンテナを実行するときに GPU を使用するように local-run コマンドを構成することもできます。これはオプションですが、トレーニングコードが GPU でどのように機能するかをテストする際に役立ちます。手順は次のとおりです。

ローカルコンピュータに NVIDIA Container Toolkit（nvidia-docker）がインストールされていない場合は、インストールします。

local-run コマンドを実行するときに、--gpu フラグを指定します。次に例を示します。

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --gpu

カスタムサービスアカウントを指定する

デフォルトでは、local-run コマンドは、ローカルコンテナ内でトレーニングコードを実行し、アプリケーションのデフォルト認証情報（ADC）を使用して、ローカル環境で利用可能な Google Cloud 認証情報をマウントします。これにより、トレーニングコードで同じ認証情報を使用して、ADC による認証を行うことができます。つまり、local-run コマンドを実行するときに、ローカルシェルの ADC で使用可能な認証情報をコードで使用できるようになります。

gcloud auth application-default login コマンドを使用して、ADC のユーザーアカウントを使用できます。また、シェルの環境変数を設定して、ADC にサービスアカウントを使用することもできます。

コンテナを実行するときに、ローカルシェルの ADC で使用可能な認証情報以外の Google Cloud 認証情報を使用する場合は、次のようにします。

トレーニングコードにアクセスを許可するサービスアカウントを作成または選択します。
このサービスアカウントのサービスアカウントキーをローカルコンピュータにダウンロードします。
local-run コマンドを実行するときに、--service-account-key-file フラグを指定します。次に例を示します。
```
gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --service-account-key-file=KEY_PATH
```
KEY_PATH は、ローカルファイルシステムのサービスアカウントキーのパスで置き換えます。これは、--local-package-path フラグで指定したディレクトリの相対パスではなく、シェルの現在の作業ディレクトリの絶対パスまたは相対パスにする必要があります。

作成されたコンテナで、トレーニングコードは ADC を使用し、指定されたサービスアカウントの認証情報で認証を行うことができます。

Vertex AI でのトレーニングとの比較

デフォルトでは、Vertex AI 上でカスタムトレーニングを実行するときに、Vertex AI はプロジェクトの AI カスタムコードサービスエージェントを使用してコードを実行します。カスタムトレーニング用に別のサービスアカウントを接続することもできます。

local-run コマンドを使用する場合、Vertex AI カスタムコードサービスエージェントとして認証することはできませんが、同様の権限を持つサービスアカウントを作成してローカルで使用することは可能です。

次のステップ

トレーニングコードの要件について学習する。
Docker イメージを Artifact Registry に push し、カスタムコンテナとして使用して Vertex AI でトレーニングを行う方法を学習する。

トレーニング コードをコンテナ化してローカルで実行する

始める前に

local-run コマンドを使用する

--script ではなく --python-module を使用する