この古いバージョンの AI Platform Training は非推奨になりました。2025 年 1 月 31 日を過ぎると Google Cloud で使用できなくなります。リソースを Vertex AI カスタムトレーニングに移行することで、AI Platform にはない新しい機械学習機能を利用できます。

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

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 ディレクトリの 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 の使用の概要について説明します。他にもこの操作に使用できるライブラリがあります。

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

アプリケーションパッケージの各ディレクトリに __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 にインポートimportする）として、__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 クライアントライブラリを使用してプログラムでアップロードします。

次のステップ

トレーニングジョブの実行

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