AI Platform Training でトレーニング アプリケーションを実行するには、Google Cloud プロジェクトがアクセスできる Cloud Storage バケットにコードとすべての依存関係をアップロードする必要があります。このページでは、アプリケーションをクラウドにパッケージングしてステージングする方法を示します。
クラウドにアップロードする前にトレーニング アプリケーションをローカルでテストすれば、最適な結果を得ることができます。AI Platform Training を使用したトレーニングでは、使用するリソースに対し、アカウントに課金されます。
始める前に
トレーニング アプリケーションをクラウドに移行する前に、次の手順を実行する必要があります。
- スタートガイドの説明に従って開発環境を構成します。
AI Platform Training のホスト型機械学習フレームワークである TensorFlow、scikit-learn、または XGBoost のうちの 1 つでトレーニング アプリケーションを開発します。トレーニング アプリケーションの環境をカスタマイズするには、カスタム コンテナを作成します。これにより、AI Platform Training のホスト型フレームワーク以外の機械学習フレームワークを使用できます。
トレーニング後にトレーニング済みモデルを AI Platform Prediction にデプロイする場合は、予測に使用するモデルのエクスポート ガイドに従って、AI Platform Prediction で使用できるモデル アーティファクトがトレーニング パッケージによってエクスポートされるようにします。
ガイドに従って、トレーニング アプリケーションのデータとファイルを保存できる Cloud Storage バケットを設定します。
トレーニング アプリケーションが依存するすべての Python ライブラリを(カスタム パッケージであるか、PyPI を介して自由に利用できるライブラリであるかにかかわらず)把握します。
このドキュメントでは、アプリケーションをパッケージングして Cloud Storage にアップロードする方法に影響する次の要因について説明します。
- gcloud CLI を使用するか(推奨)、独自のソリューションをコーディングする。
- 必要に応じてパッケージを手動で構築する。
- 使用している AI Platform Training ランタイムによってインストールされない追加の依存関係を組み込む方法。
gcloud
を使用してアプリケーションをパッケージングしてアップロードする(推奨)
アプリケーションをパッケージングし、その依存関係とともにアップロードする最も簡単な方法は、gcloud CLI を使用することです。単一のコマンド(gcloud ai-platform jobs submit training
)でアプリケーションをパッケージングしてアップロードし、最初のトレーニング ジョブを送信します。
便宜上、構成値をシェル変数として定義すると便利です。
PACKAGE_PATH='LOCAL_PACKAGE_PATH'
MODULE_NAME='MODULE_NAME'
STAGING_BUCKET='BUCKET_NAME'
JOB_NAME='JOB_NAME'
JOB_DIR='JOB_OUTPUT_PATH'
REGION='REGION'
次のように置き換えます。
LOCAL_PACKAGE_PATH
: ローカル環境内の Python パッケージのディレクトリへのパスMODULE_NAME
: トレーニング モジュールの完全修飾名BUCKET_NAME
: Cloud Storage バケットの名前JOB_NAME
: トレーニング ジョブの名前JOB_OUTPUT_PATH
: トレーニング ジョブの出力を保存する Cloud Storage ディレクトリの URIREGION
: トレーニング ジョブを実行するリージョン
次のコマンドの実行後に、これらの値の要件に関する詳細をご覧ください。
次の例は、アプリケーションのパッケージングとトレーニング ジョブの送信を行う gcloud ai-platform jobs submit training
コマンドを示しています。
gcloud ai-platform jobs submit training $JOB_NAME \
--staging-bucket=$STAGING_BUCKET \
--job-dir=$JOB_DIR \
--package-path=$PACKAGE_PATH \
--module-name=$MODULE_NAME \
--region=$REGION \
-- \
--user_first_arg=first_arg_value \
--user_second_arg=second_arg_value
--staging-bucket
では、トレーニング パッケージと依存関係パッケージをステージングする Cloud Storage バケットを指定します。Google Cloud プロジェクトでこの Cloud Storage バケットにアクセスできる必要があり、バケットがジョブを実行するリージョンと同じリージョンに存在している必要があります。AI Platform Training サービスに利用可能なリージョンをご覧ください。ステージング バケットを指定しない場合、AI Platform Training では、job-dir
パラメータで指定されたロケーションにパッケージがステージングされます。--job-dir
には、トレーニング ジョブの出力ファイルに使用する Cloud Storage のロケーションを指定します。Google Cloud プロジェクトはこの Cloud Storage バケットにアクセスできる必要があり、バケットはジョブを実行するリージョンと同じリージョンに存在する必要があります。AI Platform Training サービスに利用可能なリージョンをご覧ください。--package-path
には、アプリケーションのディレクトリへのローカルパスを指定します。gcloud CLI は、--package-path
によって指定されたいずれかの親ディレクトリのsetup.py
ファイルに基づいて、コードから.tar.gz
配布パッケージを構築します。次に、この.tar.gz
ファイルを Cloud Storage にアップロードしてトレーニング ジョブを実行します。想定したロケーションに
setup.py
ファイルがない場合、gcloud CLI はシンプルなsetup.py
を一時的に作成します。作成された.tar.gz
ファイルには、--package-path
で指定されたディレクトリのみが含まれます。--module-name
には、パッケージの名前空間ドット表記を使用して、アプリケーションのメイン モジュールの名前を指定します。これは、アプリケーションを起動するために実行する Python ファイルです。たとえば、メイン モジュールが.../my_application/trainer/task.py
の場合(推奨されるプロジェクト構造を参照)、モジュール名はtrainer.task
です。
- 構成ファイル(
config.yaml
)とコマンドライン フラグの両方でオプションを指定した場合、構成ファイルの値よりもコマンドラインの値が優先されます。 - 空の
--
フラグは、gcloud
固有のフラグの末尾、およびアプリケーションに渡すUSER_ARGS
の先頭を示します。 --module-name
、--runtime-version
、--job-dir
などの AI Platform Training 固有のフラグは、空の--
フラグの前に指定する必要があります。AI Platform Training サービスがこれらのフラグを解釈します。- AI Platform Training はパスの検証に
--job-dir
を使用するため、--job-dir
フラグを指定する場合は、空の--
フラグの前に指定する必要があります。 --job-dir
フラグが指定されている場合、アプリケーションはこれも処理する必要があります。--job-dir
フラグは、空の--
の前に指定されている場合でも、コマンドライン フラグとしてアプリケーションに渡されます。USER_ARGS
は必要な数だけ定義できます。AI Platform Training は、--user_first_arg
、--user_second_arg
などをアプリケーションに渡します。
ジョブ送信フラグの詳細については、トレーニング ジョブの実行ガイドをご覧ください。
依存関係の操作
依存関係は、コード内に import
するパッケージです。アプリケーションは、機能させる必要がある多くの依存関係を持つ場合があります。
AI Platform Training でトレーニング ジョブを実行すると、そのジョブは、多くの一般的な Python パッケージがすでにインストールされているトレーニング インスタンス(特別に構成された仮想マシン)で実行されます。トレーニングに使用するランタイム バージョンに含まれているパッケージをチェックし、まだインストールされていない依存関係に注意します。
追加する必要のある依存関係には 2 つの種類があります。
- 標準依存関係。PyPI で利用可能な一般的な Python パッケージです。
- カスタム パッケージ。独自に開発したパッケージや組織内で使用しているパッケージなどです。
以下のセクションでは、種類ごとの手順について説明します。
標準(PyPI)依存関係の追加
パッケージの標準依存関係は、setup.py
スクリプトの一部として指定できます。AI Platform Training は、ジョブ用に割り当てたトレーニング インスタンス上に pip
を使用してパッケージをインストールします。pip install
コマンドは、構成済みの依存関係を見つけてインストールします。
アプリケーションのルート ディレクトリ(推奨パターンに従っている場合は trainer
ディレクトリの 1 つ上のディレクトリ)に setup.py
という名前のファイルを作成します。
独自の値を挿入して、setup.py
に次のスクリプトを入力します。
from setuptools import find_packages
from setuptools import setup
REQUIRED_PACKAGES = ['some_PyPI_package>=1.0']
setup(
name='trainer',
version='0.1',
install_requires=REQUIRED_PACKAGES,
packages=find_packages(),
include_package_data=True,
description='My training application package.'
)
Google Cloud CLI を使用してトレーニング ジョブを送信している場合は、setup.py
ファイルが自動的に使用され、パッケージが作成されます。
gcloud
を使用せずにトレーニング ジョブを送信する場合は、次のコマンドを使用してスクリプトを実行します。
python setup.py sdist
詳細は、トレーニング アプリケーションの手動パッケージ化に関するセクションをご覧ください。
カスタム依存関係の追加
アプリケーションのカスタム依存関係を指定するには、そのパスをジョブ構成の一部として渡します。それぞれの依存関係のパッケージへの URI が必要です。カスタム依存関係は Cloud Storage のロケーションに存在している必要があります。AI Platform Training ではカスタム依存関係のインストールに pip install
が使用されるので、setup.py
スクリプトに独自の標準依存関係を指定しておくことができます。
gcloud CLI を使用してトレーニング ジョブを実行する場合、Cloud Storage だけでなく、ローカルマシン上の依存関係も指定できます。この依存関係はツールによってクラウドにステージングされます。依存関係は、gcloud ai-platform jobs submit training
コマンドの実行時に、カンマ区切りリストとして --packages
フラグに指定します。
指定する URI は配布パッケージのパスで、tarball(.tar.gz
)または wheel(.whl
)の形式にします。AI Platform Training は、pip install
を使用して、トレーニング ジョブ用に割り当てたすべての仮想マシンに各パッケージをインストールします。
以下の例では、dep1.tar.gz
および dep2.whl
(サポートされている各パッケージ タイプ 1 つずつ)という名前のパッケージ依存関係と、アプリケーションのソースへのパスを指定しています。
gcloud ai-platform jobs submit training $JOB_NAME \
--staging-bucket $PACKAGE_STAGING_PATH \
--package-path /Users/mluser/models/faces/trainer \
--module-name $MODULE_NAME \
--packages dep1.tar.gz,dep2.whl \
--region us-central1 \
-- \
--user_first_arg=first_arg_value \
--user_second_arg=second_arg_value
同様に、以下の例では、dep1.tar.gz
および dep2.whl
(サポートされている各パッケージ タイプ 1 つずつ)という名前のパッケージ依存関係を指定していますが、ビルドされたトレーニング アプリケーションを使用しています。
gcloud ai-platform jobs submit training $JOB_NAME \
--staging-bucket $PACKAGE_STAGING_PATH \
--module-name $MODULE_NAME \
--packages trainer-0.0.1.tar.gz,dep1.tar.gz,dep2.whl
--region us-central1 \
-- \
--user_first_arg=first_arg_value \
--user_second_arg=second_arg_value
AI Platform トレーニングと Prediction API を使用してトレーニング ジョブを直接実行する場合は、Cloud Storage のロケーションに依存関係パッケージをステージングし、そのロケーションのパッケージへのパスを使用する必要があります。
パッケージを手動で構築する
Python コードのパッケージングは、このドキュメントの範囲をはるかに超える広範なトピックです。便宜上、このセクションではパッケージを構築するための Setuptools の使用の概要について説明します。他にもこの操作に使用できるライブラリがあります。
アプリケーション パッケージのインストール時になんらかのセットアップ オペレーションを実行する必要がある場合でも、必ずしもパッケージを手動で構築する必要はありません。代わりに、パッケージのルート ディレクトリにカスタムの__init__.py
ファイルを配置し、Google Cloud CLI でパッケージの作成とアップロードを行うことができます。gcloud ai-platform jobs submit
コマンドの実行時に --package-path
を指定すると、使用する __init__.py
ファイルが自動的に検索されます。パッケージを手動で構築するには、次の手順に従います。
アプリケーション パッケージの各ディレクトリに
__init__.py
という名前のファイルを置きます。このファイルは空でもかまいません。また、パッケージ(そのディレクトリ内の任意のモジュール)がインポートされたときに実行されるコードを格納することもできます。.tar.gz
配布パッケージに含めるすべてのコードの親ディレクトリ(推奨パターンに従っている場合はtrainer
ディレクトリの 1 つ上のディレクトリ)に、次のものを含むsetup.py
という名前の Setuptools ファイルを配置します。setuptools.find_packages
とsetuptools.setup
のインポート ステートメント。(少なくとも)以下のパラメータが設定された
setuptools.setup
の呼び出し。_name
_ をパッケージ名前空間の名前に設定する。_version
_ をパッケージのこのビルドのバージョン番号に設定する。_install_requires
_ をアプリケーションで必要となるパッケージのリストに設定する('docutils>=0.3'
のようにバージョン要件を含む)。_packages
_ をfind_packages()
に設定する。これにより、Setuptools は、インポート パッケージ(from trainer import util
などのステートメントで、これらのモジュールを Python にインポートする)として、__init__.py
ファイルを含む親ディレクトリのすべてのサブディレクトリを配布パッケージ(すべてのコードを含む .tar.gz ファイル)に追加します。_include_package_data
_ をTrue
に設定する。
python setup.py sdist
を実行して.tar.gz
配布パッケージを作成します。
推奨されるプロジェクト構造
トレーニング アプリケーションは好きなように構造化できます。ただし、AI Platform Training のサンプルでは、次の構造が一般的に使用されています。プロジェクトの構成がサンプルと似ていると、サンプルを追跡しやすくなります。
メイン プロジェクトのディレクトリに
setup.py
ファイルを格納します。setup.py
ファイルにsetuptools
のfind_packages()
関数を使用して、構築する.tar.gz
配布パッケージにすべてのサブディレクトリを含めます。trainer
という名前のサブディレクトリにメイン アプリケーション モジュールを格納します。メイン アプリケーション モジュールに
task.py
という名前を付けます。メイン プロジェクトのディレクトリに、アプリケーションの実装に必要な他のサブディレクトリをすべて作成します。
すべてのサブディレクトリに
__init__.py
ファイルを作成します。これらのファイルは、パッケージングするコードを含むディレクトリを識別するために Setuptools によって使用されます。ファイルは空でもかまいません。
AI Platform Training のサンプルでは、trainer
ディレクトリには通常、次のソースファイルが含まれています。
task.py
には、トレーニング ジョブを管理するアプリケーション ロジックが含まれています。model.py
には、モデルのロジックが含まれています。util.py
(存在する場合)には、トレーニング アプリケーションを実行するためのコードが含まれています。
gcloud ai-platform jobs submit training
の実行時に、--package-path
を trainer
に設定します。これにより、gcloud CLI がメイン プロジェクト ディレクトリ trainer
の親にある setup.py
ファイルを検索します。
Python モジュール
アプリケーション パッケージには、複数のモジュール(Python ファイル)を入れることができます。その場合、どのモジュールの中にアプリケーションのエントリ ポイントがあるかを指定する必要があります。トレーニング サービスは、デベロッパーがローカルで行う場合と同様に、Python を起動してそのモジュールを実行します。
たとえば、前のセクションの推奨構造に従っている場合、メイン モジュールは task.py
です。これは trainer
という名前のインポート パッケージ内にあるため(__init__.py
ファイルがあるディレクトリ)、このモジュールの完全修飾名は trainer.task
です。したがって、gcloud ai-platform jobs submit training
を使用してジョブを送信する場合は、--module-name
フラグを trainer.task
に設定します。
モジュールの詳細については、パッケージに関する Python ガイドをご覧ください。
gcloud CLI を使用して既存のパッケージをアップロードする
手動でパッケージを構築する場合、gcloud CLI でパッケージをアップロードできます。gcloud ai-platform jobs submit training
コマンドを実行します。
--packages
フラグに、パッケージングしたアプリケーションへのパスを設定します。パッケージの名前空間ドット表記を使用して、
--module-name
フラグにアプリケーションのメイン モジュールの名前を設定します。これは、アプリケーションを起動するために実行する Python ファイルです。たとえば、メイン モジュールが.../my_application/trainer/task.py
の場合(推奨されるプロジェクト構造を参照)、モジュール名はtrainer.task
です。
以下の例は、コマンドを実行するのと同じディレクトリにある圧縮された tarball パッケージ(ここでは trainer-0.0.1.tar.gz
)を使用する方法を示しています。メイン関数は task.py:
というモジュールにあります。
gcloud ai-platform jobs submit training $JOB_NAME \
--staging-bucket $PACKAGE_STAGING_PATH \
--job-dir $JOB_DIR \
--packages trainer-0.0.1.tar.gz \
--module-name $MODULE_NAME \
--region us-central1 \
-- \
--user_first_arg=first_arg_value \
--user_second_arg=second_arg_value
gcloud CLI を使用してクラウドにある既存のパッケージを使用する
手動でパッケージを構築して Cloud Storage のロケーションにアップロードする場合は、gcloud
を使用してアップロードできます。gcloud ai-platform jobs submit training
コマンドを実行します。
--packages
フラグに、パッケージングしたアプリケーションへのパスを設定します。パッケージの名前空間ドット表記を使用して、
--module-name
フラグにアプリケーションのメイン モジュールの名前を設定します。これは、アプリケーションを起動するために実行する Python ファイルです。たとえば、メイン モジュールが.../my_application/trainer/task.py
の場合(推奨されるプロジェクト構造を参照)、モジュール名はtrainer.task
です。
以下の例は、Cloud Storage バケットにある圧縮された tarball パッケージを使用する方法を示しています。
gcloud ai-platform jobs submit training $JOB_NAME \
--job-dir $JOB_DIR \
--packages $PATH_TO_PACKAGED_TRAINER \
--module-name $MODULE_NAME \
--region us-central1 \
-- \
--user_first_arg=first_arg_value \
--user_second_arg=second_arg_value
$PATH_TO_PACKAGED_TRAINER
は、クラウドに存在する既存パッケージのパスを表す環境変数です。たとえば、パスは、trainer-0.0.1.tar.gz
と呼ばれる圧縮された tarball パッケージを含む次の Cloud Storage のロケーションを参照します。
PATH_TO_PACKAGED_TRAINER=gs://$CLOUD_STORAGE_BUCKET_NAME/trainer-0.0.0.tar.gz
手動でパッケージをアップロードする
必要に応じて、パッケージを手動でアップロードできます。一般的には、AI Platform トレーニングと Prediction API を直接呼び出してトレーニング ジョブを開始する場合にこれを行います。パッケージとカスタム依存関係を Cloud Storage バケットに手動でアップロードする場合、gcloud storage
コマンドツールを使用するのが最も簡単な方法です。
gcloud storage cp /local/path/to/package.tar.gz gs://bucket/path/
ただし、この操作にコマンドラインを使用できる場合は、gcloud ai-platform jobs submit training
を使用するだけで、トレーニング ジョブの設定時にパッケージをアップロードできます。コマンドラインを使用できない場合は、Cloud Storage クライアント ライブラリを使用してプログラムでアップロードします。
次のステップ
- トレーニング ジョブを構成して実行する。
- 実行中のトレーニング ジョブをモニタリングする。
- トレーニングの仕組みについて詳しく学ぶ。