ビルド済みコンテナ用の Python トレーニングアプリケーションを作成する

ビルド済みコンテナでカスタムトレーニングを実行するには、事前に Python ソース配布を作成し、Google Cloud プロジェクトがアクセスできる Cloud Storage バケットにアップロードする必要があります。

ソース配布を作成する別の方法

このガイドでは、ソース配布を手動で作成し、Cloud Storage にアップロードする手順を説明します。ガイドに進む前に、次のような代替ワークフローを検討してください。こちらのほうが便利な場合もあります。

ローカルコンピュータ上のコードを使用してトレーニングを行い、手動でのパッケージ化をできるだけ簡単に行いたい場合は、Google Cloud CLI の自動パッケージ化機能の使用をおすすめします。この機能を使用すると、Docker コンテナイメージのビルド、Container Registry への push、コンテナイメージに基づく CustomJob リソースの作成をすべて 1 つのコマンドで行うことができます。詳しくは、CustomJob の作成ガイドをご覧ください。

自動パッケージ化を使用するには、ローカルコンピュータに Docker をインストールする必要があります。このオプションで作成できるのは CustomJob だけです。TrainingPipeline リソースや HyperparameterTuningJob リソースを作成することはできません（カスタムトレーニングリソースの違いをご覧ください）。
Vertex AI で実行する前にコンテナイメージをさらにカスタマイズし、ローカルのコンテナ内で実行する場合は、gcloud CLI の local-run コマンドを使用して、ローカルでコードをコンテナ化して実行できます。その後、Artifact Registry または Container Registry にイメージを手動で push できます。

local-run コマンドを使用するには、ローカルコンピュータに Docker をインストールする必要があります。
単一の Python スクリプトでトレーニングコードを作成できる場合は、Vertex AI SDK for Python の CustomJob クラスを使用してカスタムジョブまたは CustomTrainingJob クラスを作成し、カスタム TrainingPipelineを作成できます。トレーニングコードは、ソースディストリビューションとして自動的にパッケージ化され、Cloud Storage にアップロードされます。
柔軟性を最大限に高めるには、カスタムコンテナイメージを手動で作成し、Artifact Registry または Container Registry に push します。

上記のオプションがユースケースに合わない場合や、トレーニングアプリケーションをソース配布として手動でパッケージ化する場合は、このガイドの説明に従ってください。

始める前に

トレーニングアプリケーションをクラウドで実行する準備をする前に、次の手順を行います。

Vertex AI のトレーニング用ビルド済みコンテナにある機械学習（ML）フレームワークを使用して、トレーニングアプリケーションを開発します。トレーニングアプリケーションがトレーニングコードの要件を満たしていることを確認します。

トレーニングアプリケーションをゼロから作成する場合は、このドキュメントの次のセクションで説明するアプリケーション構造に沿ってコードを整理することをおすすめします。
Vertex AI を使用する予定の Google Cloud プロジェクトで Cloud Storage バケットを作成します。このバケットにトレーニングアプリケーションを保存します（別の Google Cloud バケットを使用することも可能ですが、その場合、このガイドの対象外となる構成が必要になります）。

最高のパフォーマンスを得るには、Cloud Storage バケットが Vertex AI を使用する予定のロケーションに存在する必要があります。
トレーニングアプリケーションが依存するすべての Python ライブラリを確認します。カスタム依存関係か、PyPI を介して自由に利用できるライブラリかどうかにかかわらず確認します。

アプリケーションの構造

ビルド済みコンテナを使用してカスタムトレーニングを実行するには、次の要件に従ってトレーニングコードを指定する必要があります。

コードを 1 つ以上の Python ソース配布として提供します。

Vertex AI API を使用してカスタムトレーニングを開始する場合は、このソース配布を packageUris フィールドに指定します。
これらのソース配布に、トレーニングのエントリポイントとして機能するモジュールを作成します。

Vertex AI API を使用してカスタムトレーニングを開始する場合は、これを pythonModule フィールドに指定します。

これらの要件を満たしている限り、任意の方法でトレーニングアプリケーションを構造化できます。ただし、次の構造（Vertex AI のサンプルで頻繁に使用します）でコードを編成し、単一の Python ソース配布を作成することをおすすめします。

メインプロジェクトのディレクトリに setup.py ファイルを格納します。このファイルのコンテンツのガイダンスについては、次のセクションをご覧ください。
メインプロジェクトディレクトリ内に trainer/ というサブディレクトリを作成し、トレーニングコードのメインパッケージとして使用します。
trainer/ 内に、トレーニングコードのエントリポイントとして機能するモジュールを task.py という名前で作成します。
trainer/task.py をサポートするため、trainer/ パッケージに追加の Python モジュールを作成し、メインプロジェクトディレクトリに必要な追加コードのサブディレクトリを作成します。
各サブディレクトリに __init__.py ファイルを作成し、パッケージにします。

このガイドの以降の内容は、この構造に従ってコードが整理されていることを前提としています。

ソース配布を作成する

Python ソース配布の作成は、このドキュメントの範囲をはるかに超える広範なトピックです。このセクションでは、Vertex AI で使用するソース配布の作成に Setuptools を使用する方法について説明します。他にもこの操作に使用できるライブラリがあります。

setup.py ファイルを作成して、Setuptools にソース配布の作成方法を指定します。基本的な setup.py には次のものが含まれます。
- setuptools.find_packages と setuptools.setup のインポートステートメント。
- 少なくとも次のパラメータが設定された setuptools.setup の呼び出し。
  - name は、ソース配布の名前に設定します。
  - version は、ソース配布のこのビルドのバージョン番号に設定します。
  - install_requires は、アプリケーションに必要な依存関係のリスト（'docutils>=0.3' など）に設定します。
  - packages は find_packages() に設定します。これにより、パッケージとして __init__.py ファイルを含む親ディレクトリのすべてのサブディレクトリが含まることを Setuptools に通知します。
  - include_package_data は True に設定します。
次の例は、トレーニングアプリケーションの基本的な setup.py ファイルを示しています。
```
from setuptools import find_packages
from setuptools import setup

setup(
    name='trainer',
    version='0.1',
    packages=find_packages(),
    include_package_data=True,
    description='My training application.'
)
```
次のコマンドを実行して、ソース配布 dist/trainer-0.1.tar.gz を作成します。
```
python setup.py sdist --formats=gztar
```

Python アプリケーションの依存関係

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

カスタムトレーニングジョブのレプリカでは、一般的な Python 依存関係がすでにインストールされているコンテナでコードが実行されます。トレーニングに使用予定のビルド済みコンテナにある依存関係を確認し、インストールされていない依存関係をメモしておきます。次の手順は、ビルド済みコンテナにインストールされていない依存関係にのみ行います。

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

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

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

標準（PyPI）依存関係

アプリケーションの標準依存関係は、アプリケーションの setup.py スクリプトの一部として指定できます。Vertex AI は、pip を使用して、ジョブ用に割り当てたレプリカにトレーニングアプリケーションをインストールします。pip install コマンドは、構成済みの依存関係を見つけてインストールします。

次の例は、前のセクションと同様の setup.py を示しています。ただし、この setup.py は、トレーニングアプリケーションのインストール時に some_PyPI_package をインストールするように Vertex AI に指示します。

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.'
)

カスタム依存関係

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

指定する URI はソース配布のパスで、tarball（.tar.gz）または wheel（.whl）の形式にします。Vertex AI は、pip install を使用して、トレーニングジョブ用に割り当てた各レプリカに依存関係をインストールします。

Vertex AI API を使用してカスタムトレーニングを開始する場合は、これらの依存関係の Cloud Storage URI とトレーニングアプリケーションを packageUris フィールドに指定します。

Python モジュール

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

たとえば、前のセクションの推奨構造に従っている場合、メインモジュールは task.py です。これは trainer という名前のインポートパッケージ（__init__.py ファイルがあるディレクトリ）内にあるため、このモジュールの完全修飾名は trainer.task になります。Vertex AI API を使用してカスタムトレーニングを開始する場合は、moduleName フィールドを trainer.task に設定します。

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

ソース配布を Cloud Storage にアップロードする

gsutil ツールを使用して、ソース配布とカスタム依存関係を Cloud Storage バケットにアップロードできます。例:

gsutil cp dist/trainer-0.1.tar.gz CLOUD_STORAGE_DIRECTORY

CLOUD_STORAGE_DIRECTORY は、Google Cloud プロジェクトからアクセスできるバケット内の Cloud Storage ディレクトリの URI（gs:// で始まり、/ で終わるもの）に置き換えます。

ソース配布を Cloud Storage にアップロードする方法については、Cloud Storage ドキュメントのオブジェクトのアップロードをご覧ください。

次のステップ

カスタムトレーニングに関するその他のトレーニングコード要件を確認する。
カスタムトレーニングジョブの作成方法、またはトレーニングアプリケーションを使用するカスタムトレーニングパイプラインを作成する方法を学習する。