トレーニング アプリケーションのパッケージング

AI Platform Training でトレーニング アプリケーションを実行するには、Google Cloud プロジェクトがアクセスできる Cloud Storage バケットにコードとすべての依存関係をアップロードする必要があります。このページでは、アプリケーションをクラウドにパッケージングしてステージングする方法を示します。

クラウドにアップロードする前にトレーニング アプリケーションをローカルでテストすれば、最適な結果を得ることができます。AI Platform Training を使用したトレーニングでは、使用するリソースに対し、アカウントに課金されます。

始める前に

トレーニング アプリケーションをクラウドに移行する前に、次の手順を実行する必要があります。

  1. スタートガイドの説明に従って開発環境を構成します。
  2. AI Platform Training のホスト型機械学習フレームワークである TensorFlow、scikit-learn、または XGBoost のうちの 1 つでトレーニング アプリケーションを開発します。トレーニング アプリケーションの環境をカスタマイズするには、カスタム コンテナを作成します。これにより、AI Platform Training のホスト型フレームワーク以外の機械学習フレームワークを使用できます。

    トレーニング後にトレーニング済みモデルを AI Platform Prediction にデプロイする場合は、予測に使用するモデルのエクスポート ガイドに従って、AI Platform Prediction で使用できるモデル アーティファクトがトレーニング パッケージによってエクスポートされるようにします。

  3. ガイドに従って、トレーニング アプリケーションのデータとファイルを保存できる Cloud Storage バケットを設定します。

  4. トレーニング アプリケーションが依存するすべての Python ライブラリを(カスタム パッケージであるか、PyPI を介して自由に利用できるライブラリであるかにかかわらず)把握します。

このドキュメントでは、アプリケーションをパッケージングして Cloud Storage にアップロードする方法に影響する次の要因について説明します。

  • gcloud CLI を使用するか(推奨)、独自のソリューションをコーディングする。
  • 必要に応じてパッケージを手動で構築する。
  • 使用している AI Platform Training ランタイムによってインストールされない追加の依存関係を組み込む方法。

アプリケーションをパッケージングし、その依存関係とともにアップロードする最も簡単な方法は、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 ディレクトリの URI
  • REGION: トレーニング ジョブを実行するリージョン

次のコマンドの実行後に、これらの値の要件に関する詳細をご覧ください。

次の例は、アプリケーションのパッケージングとトレーニング ジョブの送信を行う 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 の使用の概要について説明します。他にもこの操作に使用できるライブラリがあります。

パッケージを手動で構築するには、次の手順に従います。

  1. アプリケーション パッケージの各ディレクトリに __init__.py という名前のファイルを置きます。このファイルは空でもかまいません。また、パッケージ(そのディレクトリ内の任意のモジュール)がインポートされたときに実行されるコードを格納することもできます。

  2. .tar.gz 配布パッケージに含めるすべてのコードの親ディレクトリ(推奨パターンに従っている場合は trainer ディレクトリの 1 つ上のディレクトリ)に、次のものを含む setup.py という名前の Setuptools ファイルを配置します。

    • setuptools.find_packagessetuptools.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 に設定する。

  3. python setup.py sdist を実行して .tar.gz 配布パッケージを作成します。

推奨されるプロジェクト構造

トレーニング アプリケーションは好きなように構造化できます。ただし、AI Platform Training のサンプルでは、次の構造が一般的に使用されています。プロジェクトの構成がサンプルと似ていると、サンプルを追跡しやすくなります。

  • メイン プロジェクトのディレクトリに setup.py ファイルを格納します。

    setup.py ファイルに setuptoolsfind_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-pathtrainer に設定します。これにより、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 クライアント ライブラリを使用してプログラムでアップロードします。

次のステップ