gcloud ai custom-jobs local-run
コマンドを使用すると、トレーニング コードに基づいて Docker コンテナ イメージをビルドし、イメージをローカル コンピュータのコンテナとして実行できます。この機能には次のようなメリットがあります。
Docker の知識がなくてもコンテナ イメージを作成できます。独自の Dockerfile を記述する必要がありません。このイメージを後で Artifact Registry に push し、カスタム コンテナ トレーニングに使用できます。
高度なユースケースでは、独自の Dockerfile を作成することもできます。
コンテナ イメージでは、Python トレーニング アプリケーションまたは Bash スクリプトを実行できます。
Bash スクリプトを使用すると、別のプログラミング言語で記述されたトレーニング コードを実行できます(ただし、その言語をサポートするベース コンテナ イメージを指定する必要があります)。
コンテナをローカルで実行する場合、Vertex AI で実行する場合と類似した方法でトレーニング コードを実行できます。
コードをローカルで実行すると、Vertex AI でカスタム トレーニングを行う前に、コードの問題をデバッグできます。
始める前に
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
コマンドの動作をカスタマイズする際に使用できる追加オプションについて説明します。
依存関係をインストールする
トレーニング コードは、ベースイメージにインストールされている依存関係に依存する場合があります(たとえば、事前にビルド済みのトレーニング コンテナのイメージには、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 でトレーニングを行う方法を学習する。