PAI SDK for Pythonを使用してトレーニングジョブを送信する - Platform For AI

Python用PAI SDKは、使いやすい高レベルのAPIを提供します。 SDKを使用して、トレーニングジョブをPlatform for AI (PAI) に送信し、クラウドでジョブを実行できます。このトピックでは、トレーニングジョブスクリプトを準備し、SDKを使用してトレーニングジョブを送信する方法について説明します。

課金

トレーニングジョブを送信すると、ジョブはDeep Learning Containers (DLC) リソースで実行され、リソースに対して課金されます。詳細については、「DLC課金」をご参照ください。

概要

pai SDK for PythonのPAI. Estimatorモジュールのestimatorクラスを使用して、トレーニングジョブを送信できます。トレーニングジョブを送信するには、次の手順を実行します。

Estimatorインスタンスを作成して、トレーニングジョブスクリプト、起動コマンド、ハイパーパラメータ、イメージ、コンピューティングリソースなどのトレーニングジョブを設定します。
Estimator.fit() メソッドを使用して、トレーニングデータを指定し、トレーニングジョブを送信します。

サンプルコード：

from pai.estimator import Estimator

# Create an Estimator instance to configure the training job. 
est = Estimator(
    command="<LaunchCommand>"
    source_dir="<SourceCodeDirectory>"
    image_uri="<TrainingImageUri>"
    instance_type="<TrainingInstanceType>",
    hyperparameters={
        "n_estimators": 500,
        "max_depth": 5,
    },
)

# Specify the training data and submit the training job. 
est.fit(
    inputs={
        "train_data": "oss://<YourOssBucket>/path/to/train/data/",
    }
)

# Obtain the path of the output model. 
print(est.model_data())

トレーニングジョブスクリプトと必要な依存関係を準備する

トレーニングジョブスクリプトを準備する
オンプレミス環境でトレーニングジョブスクリプトを作成し、そのスクリプトをPAIに送信できます。 PAIはクラウド環境を設定し、スクリプトを実行します。サンプルトレーニングジョブスクリプト:
```
import argparse
import os
import json

def train(hps, train_data, test_data):
    """Add your code for model training."""
    pass

def save_model(model):
    """Save the output model."""
    # Obtain the path where the output model is to be saved by using the PAI_OUTPUT_MODEL environment variable. Default path: /ml/output/model/. 
    output_model_path = os.environ.get("PAI_OUTPUT_MODEL")

    # Write the output model to the obtained path. 
    pass

def load_hyperparameters():
    """Read the hyperparameters."""
    # Obtain the path that contains the hyperparameters by using the PAI_CONFIG_DIR environment variable. Default path: /ml/input/config/. 
    hps_path = os.path.join(os.environ.get("PAI_CONFIG_DIR"), "hyperparameters.json")
    with open(hps_path, "r") as f:
        hyperparameters = json.load(f)
    return hyperparameters

def run():
    #1. Load the hyperparameters. 
    hps = load_hyperparameters()
    print("Hyperparameters: ", hps)

    #2. Load the input data. 
    # Call the est.fit() method to load the input data that is stored in Apsara File Storage NAS (NAS) or Object Storage Service (OSS) into a container. 
    # Obtain the path of the input data in the on-premises environment by using the PAI_INPUT_{CHANNEL_NAME} environment variable. 
    train_data = os.environ.get("PAI_INPUT_TRAIN")
    test_data = os.environ.get("PAI_INPUT_TEST")

    model = train(hps, train_data, test_data)

    #3. Add the training code. When the training is completed, the output model is saved to the specified path. 
    save_model(model)


if __name__ == "__main__":
    run()
```
トレーニングジョブスクリプトは、特定の標準に従って、ハイパーパラメータをロードし、入力データをロードし、出力モデルを保存する必要があります。次のセクションでは、要件について説明します。
- ハイパーパラメータの読み込み
  Estimatorインスタンスにhyperparametersパラメーターを設定すると、環境変数PAI_CONFIG_DIRで指定されたパスにhyperparameters.jsonという名前のハイパーパラメータファイルが生成されます。デフォルトのパスは /ml/input/config/ です。トレーニングジョブスクリプトでは、{PAI_CONFIG_DIR}/hyperparameters.jsonファイルを読み取ることで、ハイパーパラメーターを取得できます。
  たとえば、Estimatorインスタンスにhyperparameters={"batch_size": 32, "learning_rate": 0.01} を指定した場合、次のセクションに {PAI_CONFIG_DIR}/hyperparameters.jsonファイルの内容を示します。
```
{
  "batch_size": "32",
	"learning-rate": "0.01"
}
```
- 入力データの読み込み
  Estimator.fit() メソッドのinputパラメーターを使用して、入力データのパスを指定できます。キーと値のペア形式でパスを指定する必要があります。キーは入力データの名前 (ChannelNameとも呼ばれます) で、値は入力データのストレージパスです。サンプルコード：
```
estimator.fits(
  	inputs={
    		"train": "oss://<YourOssBucket>/train/data/train.csv",
    		"test": "oss://<YourOssBucket>/test/data/",
  	}
)
```
  入力データは /ml/input/data/{ChannelName} パスにマウントされます。トレーニングジョブスクリプトでは、PAI_INPUT_{ChannelName} 環境変数を使用して入力データのマウントパスを取得し、オンプレミスファイルを読み取るのと同じ方法でデータを読み取ることができます。上記の例では、PAI_INPUT_TRAINおよびPAI_INPUT_TEST環境変数を使用して、入力データのマウントパスを取得できます。
- 出力モデルの保存
  モデルを永続化するには、出力モデルを必要なパスに保存する必要があります。モデルを保存するパスを取得するには、環境変数PAI_OUTPUT_MODELを使用します。デフォルトのパスは /ml/output/modelです。
トレーニングジョブスクリプトで、使用するイメージに含まれていない追加のPythonパッケージの依存関係が必要な場合は、トレーニングジョブスクリプトが存在するディレクトリにrequirements.txtファイルを記述できます。スクリプトを実行する前に、サードパーティのライブラリの依存関係がジョブ環境にインストールされます。

トレーニングジョブスクリプトと関連する依存関係ファイルを特定のディレクトリに格納する必要があります。たとえば、トレーニングジョブスクリプトと依存関係ファイルは、オンプレミス環境で作成したtrain_srcディレクトリにあります。 Estimatorインスタンスを作成してパッケージ化し、train_srcディレクトリのコンテンツをPAIにアップロードするときに、source_dir="train_src" を指定します。

|-- train_src # The directory that contains the training job script. 
	|-- requirements.txt # The additional third-party dependencies of the training job script. 
	'-- train.py # The training job script. You can run the script by using the python train.py command.
	`-- utils.py

PAIイメージの取得

トレーニングジョブを送信するには、ジョブの実行に使用するイメージを指定します。イメージには、機械学習フレームワークやサードパーティのライブラリなど、トレーニングジョブスクリプトの依存関係が含まれている必要があります。 Container Registry (ACR) のカスタムイメージ、またはPAIのビルド済みイメージを使用できます。 PAIは、一般的な機械学習フレームワーク用のビルド済みイメージを提供します。 pai.image.retrieveメソッドを使用して、PAIイメージを取得できます。サンプルコード：

説明

PAIイメージにプリインストールされているサードパーティのPythonライブラリの詳細については、「パブリックイメージ」をご参照ください。

from pai.image import retrieve, list_images, ImageScope


# Obtain all PAI images for training with PyTorch. 
for image_info in list_images(framework_name="PyTorch"):
 print(image_info)

# Obtain the PAI image for training with TensorFlow 2.3 on CPUs. 
print(retrieve(framework_name="TensorFlow", framework_version="2.3"))

# Obtain the latest PAI image for training with TensorFlow on GPUs. 
# Specify framework_version="latest" to obtain the latest image. 
print(retrieve(framework_name="TensorFlow", framework_version="latest",
		accelerator_type="GPU"))

# Obtain the PAI image for training with PyTorch 1.12 on GPUs. 
print(retrieve(framework_name="PyTorch", framework_version="1.12",
 accelerator_type="GPU"))

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

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

PAIでトレーニングジョブを実行するには、Estimatorインスタンスを作成してトレーニングジョブを設定し、Estimator.fit() メソッドを呼び出してジョブを送信します。ジョブを送信した後、システムはジョブの詳細ページのURLを印刷し、ジョブのステータスが成功、失敗、または停止に変わるまでジョブログを印刷し続けます。印刷されたURLを使用して、ジョブ実行の詳細、ジョブログ、リソース使用量、およびトレーニング指標をPAIコンソールで表示できます。

デフォルトでは、ジョブが完了すると、Estimator.fit() メソッドは終了します。 estimator.mo del_data() メソッドを使用して、出力モデルのOSSパスを取得できます。

サンプルコード：

from pai.estimator import Estimator
from pai.image import retrieve

# Obtain the latest PAI image for training with PyTorch. 
torch_image_uri = retrieve("PyTorch", framework_version="1.12").image_uri

est = Estimator(
    # The startup command of the training job. 
    command="python train.py",
    # The path of the training job script. You can specify a relative or absolute path in the on-premises file system. You can also specify the OSS path of a TAR package. Example: oss://<YourOssBucket>/your-code-path-to/source.tar.gz. 
    # If the requirements.txt file exists in the directory that contains the training job script, the dependencies in the file are automatically installed before the script is run. 
    source_dir="./train_src/",
    # The image that you want to use for training. 
    image_uri=torch_image_uri,
    # The instance type that you want to use for training. 
    instance_type="ecs.c6.large",
    # The hyperparameters for training. 
    hyperparameters={
        "n_estimators": 500,
        "objective": "reg:squarederror",
        "max_depth": 5,
    },
    # The prefix of the training job name. The name is in the {base_job_name}_{submitted-datetime} format. 
    base_job_name="example_train_job",
)

# Submit the training job and print the URL of the job details page. By default, the Estimator.fit() method exits after the job status changes to successful, failed, or stopped. 
est.fit()

# Obtain the path of the output model. 
print(est.model_data())

オンプレミス環境でのトレーニングジョブの実行

クラウド環境ではデバッグは困難です。したがって、オンプレミス環境でトレーニングジョブを実行し、ジョブをデバッグできます。オンプレミス環境でトレーニングジョブを実行するには、Estimatorインスタンスの作成時にinstance_type="local" を指定します。このようにして、トレーニングジョブはdockerコンテナーで実行されます。

estimator = Estimator(
    image_uri=image_uri,
    entry_point="train.py",
    # Run a training job in the on-premises environment. 
    instance_type="local",
)

estimator.fit(
    inputs={
        # You can use OSS data. The data is downloaded and then mounted to the container. 
        "train": "oss://<BucketName>/path-to-data/",
        # You can also use data on the host machine. The data is mounted to the corresponding directory. 
        "test": "/data/to/test/data"
    }
)

# Obtain the path of the output model. 
print(estimator.model_data())

付録

トレーニングジョブのプリセット環境変数

トレーニングジョブをPAIに送信すると、ジョブに関する次の情報が環境変数として保存されます。ハイパーパラメータ、入力データのパス、出力モデルのパスです。事前定義された環境変数を使用して、トレーニングジョブスクリプトまたは起動コマンド (Estimator.command) を構成するときに情報を取得できます。

PAI_HPS_{HYPERPARAMETER_NAME}
この環境変数は、単一のハイパーパラメーターの値を指定します。環境変数には、英数字、アンダースコア (_) のみを使用できます。ハイパーパラメータの他の文字はアンダースコア (_) に置き換えられます。
たとえば、hyperparameters={"epochs": 10, "batch-size": 32, "train.learning_rate": 0.001} を指定した場合、次の環境変数が生成されます。
```
PAI_HPS_EPOCHS=10
PAI_HPS_BATCH_SIZE=32
PAI_HPS_TRAIN_LEARNING_RATE=0.001
```
これらの環境変数は, トレーニングジョブの起動コマンドで使用できます。サンプルコード：
```
est = Estimator(
 command="python train.py --epochs $PAI_HPS_EPOCHS --batch-size $PAI_HPS_BATCH_SZIE",
 hyperparameters={
 "epochs": 10,
 "batch-size": 32,
 },
 # more arguments for estimator..
)
```
トレーニングジョブスクリプト (train.py) では、argparseライブラリを使用してコマンドパラメーターを解析することで、ハイパーパラメーターを取得できます。
PAI_USER_ARGS
この環境変数は、--{hyperparameter_name} {hyperparameter_value} 形式のすべてのハイパーパラメーターの値を指定します。
たとえば、hyperparameters={"epochs": 10, "batch-size": 32, "learning-rate": 0.001} を指定した場合、次の環境変数が生成されます。
```
PAI_USER_ARGS="--epochs 10 --batch-size 32 --learning-rate 0.001"
```
この环境変数は、startupコマンドで使用できます。次の例では、実際のコマンドはpython train.py epochs 10 -- batch-size 32 -- learning-rate 0.001です。
```
est = Estimator(
    command="python train.py $PAI_USER_ARGS",
    hyperparameters={
        "epochs": 10,
        "learning-rate": 0.001
        "batch-size": 32,
    },
    # more arguments for estimator..
)
```
PAI_HPS
すべてのハイパーパラメータの値をJSON形式で指定します。
たとえば、hyperparameters={"epochs": 10, "batch-size": 32} を指定した場合、次の環境変数が生成されます。
```
PAI_HPS={"epochs": 10, "batch-size": 32}
```
PAI_INPUT_{channel_name}
ジョブの入力チャネルを指定します。各channel_nameは、OSSまたはNASに保存されている入力データのマウントパスに対応しています。
たとえば、est.fit(input={"train": "oss://<YourOssBucket>/path-to-data/", "test": "oss://<YourOssBucket>/path-to/data/test.csv"}) を指定すると、次の環境変数が生成されます。
```
PAI_INPUT_TRAIN=/ml/input/data/train/
PAI_INPUT_TEST=/ml/input/data/test/test.csv
```
マウントパスの入力データは、オンプレミスのファイルと同じ方法で読み取ることができます。
説明
スラッシュ () で終わるOSSパスを指定した場合、環境変数はディレクトリを指します。 ファイル名で終わるOSSパスを指定した場合、環境変数はファイルを指します。
PAI_OUTPUT_{channel_name}
ジョブの出力チャネルを指定します。デフォルトでは、MODELとCHECKPOINTSの出力チャネルが作成されます。MODELは出力モデルのパスを指定し、CHECKPOINTSはチェックポイントのパスを指定します。各channel_nameは、マウントパスとOSS URIに対応します。ファイルパスは、環境変数PAI_OUTPUT_{channel_name} を使用して取得できます。
```
PAI_OUTPUT_MODEL=/ml/output/model/
PAI_OUTPUT_CHECKPOINTS=/ml/output/checkpoints/
```
出力モデルまたはチェックポイントを必要なパスに保存すると、PAIはモデルまたはチェックポイントを対応するOSSパスに自動的にアップロードします。

ディレクトリ構造

PAIで実行されるトレーニングジョブのサンプルディレクトリ構造:

/ml
|-- usercode # The directory to which your code files are mounted. You can obtain the directory by using the PAI_WORKING_DIR environment variable.
|   |-- requirements.txt
|   `-- train.py
|-- input # The input data and configuration of the job. 
| '-- config # The directory that contains the configuration of the job. You can obtain the directory by using the PAI_CONFIG_DIR environment variable. 
| |-- hyperparameters.json # The hyperparameters of the training job. 
| '-- data # The input channels of the job. In this example, the job has two input channels: train_data and test_data. 
|       |-- test_data
|       |   `-- test.csv
|       `-- train_data
|           `-- train.csv
'-- output # The output channels of the job. By default, the MODEL and CHECKPOINTS channels are used. 
        '-- model # You can obtain the path of the output model by using the PAI_OUTPUT_{CHANNEL_NAME} environment variable. 
        `-- checkpoints

Platform For AI:トレーニングジョブを送信する

課金

概要