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

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

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

始める前に

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

  1. スタートガイドの手順に沿って開発環境を構成します。
  2. ガイドに従って、トレーニング アプリケーションのデータとファイルを保存できる Cloud Storage バケットを設定します。

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

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

  • gcloud ツールを使用する(推奨)、あるいは独自のソリューションをコーディングする。
  • 必要に応じてパッケージを手動で構築する。
  • 使用している Cloud ML Engine ランタイムによってインストールされていない追加の依存関係を含める方法。

    アプリケーションをその依存関係とともにパッケージングし、アップロードする最も簡単な方法は、gcloud ツールを使用することです。同じコマンド(gcloud ml-engine 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 ml-engine jobs submit training コマンドを示しています。

    gcloud ml-engine 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 バケットにアクセスできる必要があり、バケットはジョブを実行するのと同じリージョンにある必要があります。Cloud ML Engine サービスの利用可能なリージョンをご覧ください。ステージング バケットを指定しない場合、Cloud ML Engine は job-dir パラメータで指定された場所にパッケージをステージングします。

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

    • --package-path は、アプリケーションのルート ディレクトリへのローカルパスを指定します。推奨されるプロジェクトの構造をご覧ください。

    • --module-name は、パッケージの名前空間ドット表記を使用して、アプリケーションのメイン モジュールの名前を指定します。これは、アプリケーションを起動するために実行する Python ファイルです。たとえば、メイン モジュールが .../my_application/trainer/task.py推奨されるプロジェクト構造を参照)である場合、モジュール名は trainer.task です。

    • 構成ファイル(config.yaml)とコマンドライン フラグの両方でオプションが指定された場合、構成ファイルの値よりもコマンドラインの値が優先されます。
    • 空の -- フラグは、gcloud 固有のフラグの末尾、およびアプリケーションに渡す USER_ARGS の先頭を示します。
    • --module-name--runtime-version--job-dir などの Cloud ML Engine 固有のフラグは、空の -- フラグの前に指定する必要があります。Cloud ML Engine サービスが、これらのフラグを解釈します。
    • Cloud ML Engine は --job-dir を使用してパスを検証するため、--job-dir フラグを指定する場合は、空の -- フラグの前に指定する必要があります。
    • --job-dir フラグが指定されている場合、アプリケーションはこれも処理する必要があります。--job-dir フラグが空の -- の前に来ている場合でも、コマンドライン フラグとしてアプリケーションに渡されます。
    • USER_ARGS は必要な数だけ定義できます。Cloud ML Engine は、--user_first_arg--user_second_arg などをアプリケーションに渡します。

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

    依存関係の操作

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

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

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

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

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

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

    パッケージの標準依存関係を、setup.py スクリプトの一部として指定できます。Cloud ML Engine は、ジョブ用に割り当てたトレーニング インスタンス上に 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 の場所に存在している必要があります。Cloud ML Engine ではカスタム依存関係のインストールに pip install が使用されるので、カスタム依存関係が持っている標準依存関係を setup.py スクリプトの中に指定できます。

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

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

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

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

    以下の例では、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 \
        -- \
        --user_first_arg=first_arg_value \
        --user_second_arg=second_arg_value
    

    同様に、以下の例では、dep1.tar.gz および dep2.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 \
        -- \
        --user_first_arg=first_arg_value \
        --user_second_arg=second_arg_value
    

    Cloud ML Engine 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 を実行してパッケージを作成します。

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

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

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

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

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

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

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

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

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

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

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

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

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

    Python モジュール

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

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

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

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

    手動でパッケージを構築する場合は、gcloud ツールを使用してパッケージをアップロードできます。gcloud ml-engine jobs submit training コマンドを実行します。

    • --packages フラグに、パッケージングしたアプリケーションへのパスを設定します。

    • パッケージの名前空間ドット表記を使用して、アプリケーションのメイン モジュールの名前に --module-name フラグを設定します。これは、アプリケーションを起動するために実行する Python ファイルです。たとえば、メイン モジュールが .../my_application/trainer/task.py推奨されるプロジェクト構造を参照)である場合、モジュール名は trainer.task です。

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

    gcloud ml-engine 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 ml-engine jobs submit training コマンドを実行します。

    • --packages フラグに、パッケージングしたアプリケーションへのパスを設定します。

    • パッケージの名前空間ドット表記を使用して、アプリケーションのメイン モジュールの名前に --module-name フラグを設定します。これは、アプリケーションを起動するために実行する Python ファイルです。たとえば、メイン モジュールが .../my_application/trainer/task.py推奨されるプロジェクト構造を参照)である場合、モジュール名は trainer.task です。

    以下の例は、Cloud Storage バケットにある圧縮された tarball パッケージを使用する方法を示しています。

    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 \
        -- \
        --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
    

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

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

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

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

    次のステップ

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

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

TensorFlow 用 Cloud ML Engine