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

Cloud Machine Learning Engine でトレーナー アプリケーションを実行する前に、Google Cloud Platform プロジェクトでアクセスできる Google Cloud Storage の場所に、コードとその依存関係を配置する必要があります。このページでは、コードをパッケージングしてクラウド内にステージングする手順を示します。Cloud ML Engine のパッケージング要件の詳細な説明については、トレーニングのコンセプト ページを参照してください。

始める前に

トレーナー コードのパッケージングは、モデル トレーニング プロセスの 1 ステップです。アプリケーションをクラウドに移行する前に、次の手順を完了しておく必要があります。

  1. TensorFlow で、トレーナー アプリケーションを開発します。

さらに、次の場合に最善の結果が得られます。

  • カスタム Python ライブラリか、または PyPI から自由に利用できる Python ライブラリかに関わらず、トレーナーが依存するすべての Python ライブラリについて知ります。

  • トレーナーをローカルでテストします。Cloud ML Engine を使用したトレーニングでは、使用するリソースに対し、アカウントに課金されます。

コードと依存関係のパッケージングとアップロード

トレーニング アプリケーションを目的の Google Cloud Storage の場所に格納する方法は、次の要因によって異なります。

  • gcloud ツールを使用する(推奨)か、独自のソリューションをコーディングするか。

  • 手動でパッケージを作成する必要があるか。

  • 使用している Cloud ML Engine のランタイムに含まれていない追加の依存関係があるか。

必要な情報の収集

トレーナーをパッケージングするには、以下の情報を収集する必要があります。

パッケージのパス
gcloud コマンドライン ツールを使用してトレーナーをパッケージングする場合は、トレーナー ソース コードにローカルパスを含める必要があります。詳細は、推奨されるトレーナー プロジェクトの構造を参照してください。
ジョブ ディレクトリ
これは、ジョブの出力用のルート ディレクトリです。プロジェクトが書き込みアクセス権を持つ場所への Cloud Storage パスである必要があります。
依存関係パス
カスタム依存関係がある場合は、それぞれのパッケージへの URI が必要です。gcloud ツールを使用してトレーニング ジョブを実行する場合、ローカル ディレクトリを指定できるので、ツールが自動的にクラウド内にそれらをステージングします。Cloud ML Engine API を使用してトレーニング ジョブを直接実行する場合は、手動で Cloud Storage の場所に依存関係パッケージをステージングし、そこでそれらへのパスを使用する必要があります。
モジュール名
トレーナーのメイン モジュールの名前。これはトレーナーを起動するために実行する Python ファイルです。この名前は、パッケージの名前空間表記を使用する必要があります。推奨されるトレーナー プロジェクト構造を使用する場合、モジュール名は trainer.task になります。
ステージング バケット
トレーニング サービスがジョブを実行するために必要なトレーニング インスタンスにコピーできるように、トレーナーがステージングされる Google Cloud Storage の場所。手動でパッケージングしてステージングする場合は、使用するトレーナー パッケージをここにコピーして、トレーニング ジョブを開始するときに、そのパスを覚えておくだけです。gcloud ツールを使用してトレーナーをパッケージングする場合は、この値を指定すると、ツールによって自動的にパッケージがコピーされます。gcloud ツールの場合、ジョブ ディレクトリを指定して、ツールにステージング用の出力ディレクトリを使用させる場合は、この値を省略できます。

トレーナーをその依存関係とともにパッケージングし、アップロードする最も簡単な方法は、gcloud ツールを使用することです。

  • gcloud ml-engine jobs submit training コマンドの一部として:

    1. --package-path フラグにトレーナー アプリケーションのルート ディレクトリへのパスを設定します。

    2. --module-name フラグに、パッケージの名前空間ドット表記を使用して、アプリケーションのメイン モジュールの名前を設定します(たとえば、メイン モジュールが .../my_application/trainer/task.py である推奨されるケースの場合、モジュール名は trainer.task です)。

    3. --staging-bucket フラグに、ツールでトレーニングと依存関係のパッケージのステージングに使用する Cloud Storage の場所を設定します。

環境変数として設定値を定義すると便利な場合があります。

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

下記のトレーニング ジョブ送信コマンドの例では、先ほど定義した環境変数を使用してトレーナー アプリケーションをパッケージングしています。これらについては、トレーニング ジョブの開始に関する方法のページで詳しく説明しています。

ジョブ名

プロジェクト内でユニークでなければならないジョブの名前。わかりやすいユニークなジョブ名を確保するための一般的なアプローチは、現在の日時をモデル名に追加することです。BASH での例を次に示します。

now=$(date +"%Y%m%d_%H%M%S")
JOB_NAME="census_$now"
ジョブ ディレクトリ

トレーニング出力に使用する Cloud Storage の場所。ジョブを実行する同じリージョン内のバケットの場所を使用するようにしてください。Cloud ML Engine サービスの利用可能なリージョンを参照してください。

JOB_DIR="gs://your/chosen/job/output/path"

次にコマンド例を示します。

gcloud ml-engine jobs submit training $JOB_NAME \
    --job-dir $JOB_DIR  \
    --package-path $TRAINER_PACKAGE_PATH \
    --module-name $MAIN_TRAINER_MODULE \
    --region us-central1 \
    -- \
    --trainer_arg_1 value_1 \
    ...
    --trainer_arg_n value_n

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

手動でパッケージを構築する場合は、gcloud ツールを使用してパッケージをアップロードできます。

  • gcloud ml-engine jobs submit training コマンドの一部として:

    1. --packages 引数に、パッケージングしたトレーナー アプリケーションへのパスを設定します。

    2. --module-name 引数に、パッケージの名前空間ドット表記を使用して、アプリケーションのメイン モジュールの名前を設定します。

このコマンド例では、コマンドを実行する同じディレクトリにある圧縮された tarball パッケージ(ここでは trainer-0.0.1.tar.gz と呼ばれる)を使用する方法を示しています。メイン関数は task.py: というモジュールにあります。

gcloud ml-engine jobs submit training $JOB_NAME \
    --job-dir $JOB_DIR \
    --packages trainer-0.0.1.tar.gz \
    --module-name $MAIN_TRAINER_MODULE \
    --region us-central1 \
    -- \
    --trainer_arg_1 value_1 \
    ...
    --trainer_arg_n value_n

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

手動でパッケージを構築し、Cloud Storage の場所にアップロードする場合は、gcloud ツールを使用してアップロードできます。

  • gcloud ml-engine jobs submit training コマンドの一部として:

    1. --packages 引数に、パッケージングしたトレーナー アプリケーションへのパスを設定します。

    2. --module-name 引数に、パッケージの名前空間ドット表記を使用して、アプリケーションのメイン モジュールの名前を設定します。

このコマンドでは、Cloud Storage バケットに存在する tarball 圧縮パッケージ(ここでは trainer-0.0.1.tar.gz)の使用方法を示しています。メイン関数は task.py: というモジュールにあります。

gcloud ml-engine jobs submit training $JOB_NAME \
    --job-dir $JOB_DIR \
    --packages $PATH_TO_PACKAGED_TRAINER \
    --module-name $MAIN_TRAINER_MODULE \
    --region us-central1 \
    -- \
    --trainer_arg_1 value_1 \
    ...
    --trainer_arg_n value_n

$PATH_TO_PACKAGED_TRAINER は、クラウドに存在する既存パッケージのパスを表す環境変数です。たとえば、Cloud Storage の次のような場所を参照します。

PATH_TO_PACKAGED_TRAINER=gs://$CLOUD_STORAGE_BUCKET_NAME/trainer-0.0.0.tar.gz

依存関係の操作

トレーナーは、機能させる必要がある多くの依存関係(コードに import するパッケージ)を持つ場合があります。トレーニング ジョブは、多くの一般的な Python パッケージがすでにインストールされているトレーニング インスタンス(特別に構成された仮想マシン)で実行します。トレーニングに使用するランタイム バージョンに含まれているパッケージをチェックし、まだインストールされていない依存関係に注意します。

特別な依存関係には、PyPI で使用可能な一般的な Python パッケージとカスタム パッケージ(独自に開発したパッケージや組織の内部のパッケージなど)の 2 つのタイプがあります。タイプごとに手順が異なります。

追加の PyPI 依存関係を含める

トレーナーがトレーニング インスタンス イメージに含まれていない一般的な Python パッケージに依存している場合は、それらをトレーナー パッケージの依存関係として含めることができます。Cloud ML Engine は pip を使用してパッケージをインストールしますが、構成された依存関係を探してそれらをインストールします。

トレーナー アプリケーションのルート ディレクトリ(推奨パターンに従っている場合は、trainer ディレクトリの 1 つ上のディレクトリ)に 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 trainer application package.'
)

gcloud コマンドライン ツールを使用してトレーニング ジョブを送信すると、自動的に setup.py ファイルが使用され、パッケージが作成されます。ツールを使用せずにトレーニング ジョブを送信する場合は、次のコマンドを使用してこのスクリプトを手動で実行する必要があります。

python setup.py sdist

詳細については、このページのトレーナーの手動パッケージングに関するセクションを参照してください。

パッケージにカスタム依存関係を含める

使用しているランタイム バージョンのトレーニング インスタンスに含まれていないライブラリをアプリケーションで使用している場合は、それらをアプリケーション パッケージとともにアップロードできます。

  • gcloud ml-engine jobs submit training コマンドの一部として:

    1. トレーニング アプリケーションを、ソースコードが格納されているディレクトリへのパスまたは構築済みパッケージへのパスとして指定します。

    2. --packages 引数を設定して、カンマ区切りのリストに各依存関係を含めます。

このトレーニング ジョブ送信コマンドの例では、アプリケーションのソースへのパスを使用し、dep1.tar.gzdep2.whl というパッケージングされた依存関係(サポートされるパッケージ タイプ 1 つずつ)を含めています。

gcloud ml-engine jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --package-path /Users/mlguy/models/faces/trainer \
    --module-name $MAIN_TRAINER_MODULE \
    --packages dep1.tar.gz,dep2.whl \
    --region us-central1 \
    -- \
    --trainer_arg_1 value_1 \
    ...
    --trainer_arg_n value_n

このトレーニング ジョブ送信コマンドの例では、ビルドされたトレーニング アプリケーションを使用し、dep1.tar.gzdep2.whl というパッケージングされた依存関係(サポートされるパッケージ タイプ 1 つずつ)を含めています。

gcloud ml-engine 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 \
    -- \
    --trainer_arg_1 value_1 \
    ...
    --trainer_arg_n value_n

トレーナー パッケージの手動での構築

Python コードのパッケージングは、このドキュメントの範囲をはるかに超える広範なトピックです。便宜上、このセクションでは Setuptools の使用の概要について説明しますが、同じことを行うために他のライブラリを使用することもできます。

パッケージングのステップ

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

  2. パッケージのルート ディレクトリに、次を含む setup.py という名前の Setuptools ファイルを格納します。

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

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

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

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

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

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

      • True に設定された _include_package_data_。

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

トレーニング アプリケーションは、好きなように構造化できます。ただし、次の構造は、Cloud ML Engine のサンプルで一般的に使われており、プロジェクトの構成をサンプルに似たようなものにすると従いやすくなります。

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

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

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

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

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

サンプルでは、trainer ディレクトリには通常、task.py: model.pyutil.py に加えて 2 つのソース ファイルが格納されています。コードの内訳は次のとおりです。

  • task.py には、ジョブを管理するトレーナー ロジックが含まれています。

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

  • util.py(存在する場合)には、トレーナーを実行するためのコードが含まれています。

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

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

手動でパッケージをアップロードする

理由があれば、パッケージを手動でアップロードできます。最も一般的な理由は、Cloud ML Engine API を直接呼び出してトレーニング ジョブを開始することです。パッケージとカスタム依存関係を Google Cloud Storage バケットに手動でアップロードする最も簡単な方法は、gsutil ツールを使用することです。

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

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

ここでも、gcloud ツールを使用して、すでにクラウドにあるトレーニング アプリケーション パッケージでトレーニングを行なうことができます。

次のステップ

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

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

Cloud Machine Learning Engine(Cloud ML Engine)