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

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

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

始める前に

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

  1. スタートガイドの説明に従って開発環境を構成します。
  2. scikit-learn または XGBoost を使用してトレーニング アプリケーションを開発します。
  3. ガイドに従って、トレーニング アプリケーションのデータとファイルを保存できる Cloud Storage バケットを設定します。

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

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

  • gcloud ツールを使用する(推奨)、あるいは独自のソリューションをコーディングする。
  • 必要に応じてパッケージを手動で構築する。
  • 使用している AI Platform ランタイムによってインストールされない追加の依存関係を組み込む方法。
  • トレーニング ジョブを実行した後の、オンライン予測用のモデルファイルの命名方法の検討。

オンライン予測で使用するモデルファイルの命名

トレーニング後に AI Platform を使用してオンライン予測を取得する場合は、モデルファイルのエクスポートに使用するライブラリに応じて、モデルファイルに名前を付ける必要があります。モデルファイルの命名規則の詳細については、以下をご覧ください。

トレーニング アプリケーションをパッケージングしてトレーニング ジョブを AI Platform に送信する前に、メインのトレーニング コード内でモデルファイルの名前を設定します。

scikit-learn

モデルをエクスポートするには、下記のように joblib または Python pickle ライブラリを使用します。

joblib

# Export the model to a file
joblib.dump(pipeline, 'model.joblib')

pickle

# Export the model to a file
with open('model.pkl', 'wb') as model_file:
  pickle.dump(pipeline, model_file)

XGBoost

モデルをエクスポートするには、Booster オブジェクトの save_model メソッドまたは Python pickle ライブラリを使用します。

# load data into DMatrix object
dtrain = xgb.DMatrix(train_features, train_labels)
dtest = xgb.DMatrix(test_features)

# train XGBoost model
bst = xgb.train({}, dtrain, 20)
bst.save_model('./model.bst')

モデルファイルの命名規則

Cloud Storage にアップロードする保存済みモデルのファイル名は、使用したライブラリに応じて、model.pklmodel.joblibmodel.bst のいずれかにする必要があります。この制限により、AI Platform はエクスポート時と同じパターンを使用して、インポート時にモデルを再構築できます。

カスタム予測ルーチン(ベータ版)を作成する場合、この要件は適用されません。

scikit-learn

モデルのエクスポートに使用するライブラリ 正しいモデル名
pickle model.pkl
joblib model.joblib

XGBoost

モデルのエクスポートに使用するライブラリ 正しいモデル名
pickle model.pkl
joblib model.joblib
xgboost.Booster model.bst

モデルを今後繰り返し利用する場合は、新しいモデルのそれぞれに専用のディレクトリが存在するように Cloud Storage バケットを整理してください。

アプリケーションをその依存関係とともにパッケージングし、アップロードする最も簡単な方法は、gcloud ツールを使用することです。アプリケーションをパッケージングしてアップロードする場合、最初のトレーニング ジョブを送信する場合、どちらの場合も同じコマンド(gcloud ai-platform jobs submit training)を使用します。

便宜上、環境変数として構成値を定義すると便利です。次の変数には、アプリケーション パッケージのステージングに使用される値が含まれます。

TRAINER_PACKAGE_PATH="/path/to/your/application/sources"
MAIN_TRAINER_MODULE="trainer.task"
PACKAGE_STAGING_PATH="gs://your/chosen/staging/path"

さらに、次の変数は、ジョブの実行時に使用される値を定義します。

now=$(date +"%Y%m%d_%H%M%S")
JOB_NAME="your_name_$now"
JOB_DIR="gs://your/chosen/job/output/path"
REGION="us-east1"

次の例では、gcloud ai-platform jobs submit training コマンドを使用してアプリケーションのパッケージングとトレーニング ジョブの送信を行います。

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --job-dir $JOB_DIR  \
    --package-path $TRAINER_PACKAGE_PATH \
    --module-name $MAIN_TRAINER_MODULE \
    --region $REGION \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value
  • --staging-bucket には、トレーニング パッケージと依存関係パッケージをステージングする Cloud Storage の場所を指定します。GCP プロジェクトはこの Cloud Storage バケットにアクセスできる必要があり、バケットはジョブを実行するリージョンと同じリージョンに存在する必要があります。詳しくは、AI Platform サービスで利用可能なリージョンをご覧ください。ステージング バケットを指定しなかった場合、AI Platform は、job-dir パラメータで指定されたロケーションにパッケージをステージングします。

  • --job-dir には、トレーニング ジョブの出力ファイルに使用する Cloud Storage の場所を指定します。GCP プロジェクトはこの Cloud Storage バケットにアクセスできる必要があり、バケットはジョブを実行するリージョンと同じリージョンに存在する必要があります。詳しくは、AI Platform サービスで利用可能なリージョンをご覧ください。

  • --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 固有のフラグは、空の -- フラグの前に指定する必要があります。AI Platform サービスがこれらのフラグを解釈します。
  • AI Platform はパスの検証に --job-dir を使用するため、--job-dir フラグを指定する場合は、空の -- フラグの前に指定する必要があります。
  • --job-dir フラグが指定されている場合、アプリケーションはこれも処理する必要があります。--job-dir フラグが空の -- の前に来ている場合でも、コマンドライン フラグとしてアプリケーションに渡されます。
  • USER_ARGS は必要な数だけ定義できます。AI Platform は、--user_first_arg--user_second_arg などをアプリケーションに渡します。

ジョブ送信フラグの詳細については、トレーニング ジョブの実行ガイドをご覧ください。

依存関係の操作

依存関係は、コード内で import するパッケージです。アプリケーションは、機能させる必要がある多くの依存関係を持つ場合があります。

AI Platform でトレーニング ジョブを実行すると、そのジョブは、多くの一般的な Python パッケージがすでにインストールされているトレーニング インスタンス(特別に構成された仮想マシン)で実行されます。トレーニングに使用するランタイム バージョンに含まれているパッケージをチェックし、まだインストールされていない依存関係に注意します。

追加する必要のある依存関係には次の 2 つの種類があります。

  • 標準的な依存関係。PyPI で利用可能な一般的な Python パッケージです。
  • 独自に開発したパッケージや組織内で使用しているパッケージなどのカスタム パッケージ。

以下のセクションでは、種類ごとの手順について説明します。

標準(PyPI)依存関係の追加

パッケージの標準依存関係を、setup.py スクリプトの一部として指定できます。AI Platform は、ジョブ用に割り当てたトレーニング インスタンス上に 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.'
)

gcloud コマンドライン ツールを使用してトレーニング ジョブを送信する場合は、自動的に setup.py ファイルを使用してパッケージを作成します。

gcloud を使用せずにトレーニング ジョブを送信する場合は、次のコマンドを使用してスクリプトを実行します。

python setup.py sdist

詳細は、トレーニング アプリケーションの手動パッケージ化に関するセクションをご覧ください。

カスタム依存関係の追加

アプリケーションのカスタム依存関係を指定するには、そのパスをジョブ構成の一部として渡します。それぞれの依存関係のパッケージへの URI が必要です。カスタム依存関係は Cloud Storage の場所に存在している必要があります。AI Platform ではカスタム依存関係のインストールに pip install が使用されるので、カスタム依存関係の独自の標準依存関係を setup.py スクリプトの中で指定しておくことができます。

gcloud ツールを使用してトレーニング ジョブを実行する場合、ローカル ディレクトリを指定できるので、ツールが自動的にクラウド内にそれらをステージングします。gcloud ai-platform jobs submit training コマンドを次のように実行します。

  • package-path フラグを設定して、トレーニング アプリケーションを、ソースコードが格納されているディレクトリへのパスまたはビルドされたパッケージへのパスとして指定します。

  • --packages フラグを設定して、依存関係をカンマ区切りリストで指定します。

この中で指定する URI はそれぞれ、パッケージへのパスであり、パッケージの形式は tarball(*.tar.gz)または wheel です。AI Platform は pip install を使用して、トレーニング ジョブ用に割り当てたすべての仮想マシンに各パッケージをインストールします。

以下の例では、dep1.tar.gzdep2.whl(サポートされている各パッケージタイプ 1 つずつ)という名前のパッケージ依存関係と、アプリケーションのソースへのパスを指定しています。

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --package-path /Users/mluser/models/faces/trainer \
    --module-name $MAIN_TRAINER_MODULE \
    --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 $MAIN_TRAINER_MODULE \
    --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. パッケージのルート ディレクトリ(推奨パターンに従っている場合は、trainer ディレクトリの 1 つ上のディレクトリ)に、次の要素を含む setup.py という名前の Setuptools ファイルを格納します。

    • setuptools.find_packagessetuptools.setup のインポート ステートメント。

    • (少なくとも)以下のパラメータが設定された setuptools.setup の呼び出し。

      • パッケージ名前空間の名前に設定された _name_。

      • パッケージのこのビルドのバージョン番号に設定された _version_。

      • ‘docutils>=0.3' などのバージョン要件を含む、アプリケーションによって必要とされるパッケージのリストに設定された _install_requires_。

      • find_packages() に設定された _packages_。

      • True に設定された _include_package_data_。

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

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

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

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

  • メイン アプリケーション モジュールを格納する trainer という名前のサブディレクトリを使用します。

  • メイン アプリケーション モジュールに task.py という名前を付けます。

  • メイン プロジェクトのディレクトリに、アプリケーションの実装に必要な他のサブディレクトリをすべて作成します。

  • すべてのサブディレクトリに __init__.py ファイルを作成します。これらのファイルは、パッケージングするコードを含むディレクトリを識別するために Setuptools によって使用されます。ファイルは空でもかまいません。

AI Platform のサンプルでは、trainer ディレクトリには通常、次のソースファイルが含まれています。

  • task.py には、トレーニング ジョブを管理するアプリケーション ロジックが含まれています。

  • model.py には、モデルのロジックである scikit-learn および XGBoost のグラフコードが含まれています。

  • util.py(存在する場合)には、トレーニング アプリケーションを実行するためのコードが含まれています。

トレーニング アプリケーション プロジェクトの推奨される構造

gcloud ツールを使用してアプリケーションをパッケージングする場合は、setup.py ファイルまたは __init__.py ファイルを作成する必要はありません。gcloud ai-platform jobs submit training を実行する場合は、メイン プロジェクト ディレクトリのパスに --package_path フラグを設定できます。あるいは、そのディレクトリからツールを実行してフラグをすべて省略できます。

Python モジュール

アプリケーション パッケージには、複数のモジュール(Python ファイル)を入れることができます。その場合、どのモジュールの中にアプリケーションのエントリ ポイントがあるかを指定する必要があります。トレーニング サービスは Python を起動し、デベロッパーがローカルで実行する場合と同様にそのモジュールを実行します。

アプリケーションを Python のパッケージにするときに、名前空間を作成します。たとえば、作成するパッケージの名前が trainer で、メイン モジュールの名前が task.py である場合、そのパッケージには trainer.task という名前を指定します。したがって、gcloud ai-platform jobs submit training を実行する際は、--module-name フラグを trainer.task に設定します。

モジュールの詳細については、パッケージに関する Python ガイドをご覧ください。

gcloud ツールを使用して既存のパッケージをアップロードする

手動でパッケージを構築する場合、gcloud ツールでパッケージをアップロードできます。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 $MAIN_TRAINER_MODULE \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

gcloud ツールを使用してクラウドにある既存のパッケージを使用する

手動でパッケージを構築して 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 $MAIN_TRAINER_MODULE \
    --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 バケットに手動でアップロードするための特に簡単な方法は、gsutil ツールを使用することです。

gsutil cp /local/path/to/package.tar.gz  gs://bucket/path/

ただし、このオペレーションにコマンドラインを使用できる場合は、gcloud ai-platform jobs submit training を使用するだけで、トレーニング ジョブの設定の一環としてパッケージをアップロードできます。コマンドラインを使用できない場合は、Cloud Storage クライアント ライブラリを使用してプログラムでアップロードできます。

次のステップ

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

scikit-learn と XGBoost の AI Platform