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

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

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

    高度なユースケースでは、独自の Dockerfile を作成することもできます。

  • コンテナ イメージでは、Python トレーニング アプリケーションまたは Bash スクリプトを実行できます。

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

  • コンテナをローカルで実行する場合、Vertex AI で実行する場合と類似した方法でトレーニング コードを実行できます。

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

始める前に

  1. Vertex AI 開発環境を設定します。

  2. Docker Engine をインストールします。

  3. 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 の要件を満たすイメージ名を使用することをおすすめします。（また、後で別の名前でイメージにタグを付けることもできます）。

    --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 コマンドの動作をカスタマイズする際に使用できる追加オプションについて説明します。

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

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

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

次のいずれかのセクションで説明されている手順を行って、追加の 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 でどのように機能するかをテストする際に役立ちます。手順は次のとおりです。

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

  2. 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 認証情報を使用する場合は、次のようにします。

  1. トレーニング コードにアクセスを許可するサービス アカウントを作成または選択します。

  2. このサービス アカウントのサービス アカウント キーをローカル コンピュータにダウンロードします。

  3. 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 カスタム コード サービス エージェントとして認証することはできませんが、同様の権限を持つサービス アカウントを作成してローカルで使用することは可能です。

次のステップ