スタートガイド: カスタム コンテナを使用した PyTorch 予測の提供

プレビュー

この機能には、サービス固有の利用規約の「一般的なサービス規約」の「pre-GA サービス規約」が適用されます。 pre-GA の機能は「現状有姿」で利用できますが、サポートが制限される場合があります。 詳しくは、リリース ステージの説明をご覧ください。

このチュートリアルでは、カスタム コンテナを使用してオンライン予測を提供する PyTorch 機械学習（ML）モデルをデプロイする方法について説明します。

このチュートリアルでは、MNIST データセットで事前トレーニング済みである TorchServe によって提供された数字認識モデルからの予測を提供するために、PyTorch の TorchServe ツールを実行するコンテナをデプロイします。その後、AI Platform Prediction を使用して数字の画像の分類ができます。

始める前に

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the AI Platform Training & Prediction and Artifact Registry API APIs.

   Enable the APIs

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the AI Platform Training & Prediction and Artifact Registry API APIs.

   Enable the APIs

8. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

このチュートリアル全体を通して、Cloud Shell を使用して Google Cloud とやり取りすることをおすすめします。Cloud Shell の代わりに別の Bash シェルを使用する場合は、次の追加の構成を行います。

1. Install the Google Cloud CLI.

2. To initialize the gcloud CLI, run the following command:

   gcloud init

3. Artifact Registry のドキュメントに従って、Docker をインストールします。

コンテナ イメージのビルドと push

カスタム コンテナを使用するには、カスタム コンテナの要件を満たす Docker コンテナ イメージを指定する必要があります。このセクションでは、コンテナ イメージを作成して Artifact Registry に push する方法について説明します。

モデル アーティファクトをダウンロードする

モデル アーティファクトとは、予測の提供に使用できる ML トレーニングによって作成されたファイルです。これには、少なくとも、トレーニング済み ML モデルの構造と重みが含まれます。モデル アーティファクトの形式は、トレーニングに使用する ML フレームワークによって異なります。

このチュートリアルの場合は、トレーニングをゼロから行うのではなく、TorchServe によって提供されるサンプル モデル アーティファクトをダウンロードします。

TorchServe リポジトリのクローンを作成して、モデル アーティファクトのあるディレクトリに移動するには、シェルで次のコマンドを実行します。

git clone https://github.com/pytorch/serve.git \
  --branch=v0.3.0 \
  --depth=1

cd serve/examples/image_classifier/mnist

このディレクトリには、コンテナ イメージに組み込む重要なファイルが 3 つあります。

• mnist.py: トレーニング済みのニューラル ネットワークの構造を定義します。
• mnist_cnn.pt: 特徴の重みとトレーニングからのその他の出力を含む state_dict を含みます。
• mnist_handler.py: TorchServe が予測リクエストを処理する方法を拡張します。

Artifact Registry リポジトリを作成する

Artifact Registry リポジトリを作成して、次のセクションで作成するコンテナ イメージを保存します。シェルで次のコマンドを実行します。

gcloud beta artifacts repositories create getting-started-pytorch \
 --repository-format=docker \
 --location=REGION

REGION は、コンテナ イメージを保存する Artifact Registry があるリージョンに置き換えます。後で、このリージョンと一致するリージョン エンドポイントに AI Platform Prediction モデルリソースを作成する必要があります。そのため、AI Platform Prediction にリージョン エンドポイントがあるリージョンを選択してください（例: us-central1）。

このオペレーションが完了すると、このコマンドによって次の入力が出力されます。

Created repository [getting-started-pytorch].

コンテナ イメージをビルドする

TorchServe は、TorchServe を実行するコンテナ イメージをビルドするための Dockerfile を提供しています。ただし、この Dockerfile を使用してすべての TorchServe の依存関係をインストールする代わりに、コンテナ イメージを TorchServe チームにより Docker Hub へ push された TorchServe イメージのいずれかからコンテナ イメージを取得することで、ビルドプロセスを迅速に進めることが可能です。

1. モデル アーティファクトを含むディレクトリ内で、次のコマンドをシェルで実行して、新しい Dockerfile を作成します。

   cat > Dockerfile <<END
   FROM pytorch/torchserve:0.3.0-cpu
   
   COPY mnist.py mnist_cnn.pt mnist_handler.py /home/model-server/
   
   USER root
   RUN printf "\nservice_envelope=json" >> /home/model-server/config.properties
   USER model-server
   
   RUN torch-model-archiver \
     --model-name=mnist \
     --version=1.0 \
     --model-file=/home/model-server/mnist.py \
     --serialized-file=/home/model-server/mnist_cnn.pt \
     --handler=/home/model-server/mnist_handler.py \
     --export-path=/home/model-server/model-store
   
   CMD ["torchserve", \
        "--start", \
        "--ts-config=/home/model-server/config.properties", \
        "--models", \
        "mnist=mnist.mar"]
   END
   

   これらの Docker の命令では、次の処理が行われます。

   • FROM 命令は、既存の TorchServe イメージから現在のコンテナ イメージを取得します。

   • COPY 命令は、ローカル ディレクトリからモデル アーティファクトと予測ハンドラをコンテナ イメージの /home/model-server/ ディレクトリにコピーします。

   • 最初の RUN 命令は、親イメージの構成ファイルを編集して、AI Platform Prediction の予測の優先入力形式をサポートします。

     具体的には、この命令は TorchServe が予測リクエストに対する JSON サービス エンベロープを想定するように構成します。

     この構成ファイルを編集するには、親イメージ内に作成された model-server ユーザーが持っていない権限が必要です。この手順では、その構成ファイルを編集するために root ユーザーとして実行するように Docker に指示します。その後も model-server ユーザーを引き続き使用します。

   • 2 番目の RUN 命令は、コンテナ イメージにすでにインストールされている Torch モデル アーカイブ ツールを使用して、イメージ内にコピーしたファイルからモデルのアーカイブを作成します。このモデル アーカイブを mnist.mar というファイル名で、/home/model-server/model-store/ ディレクトリに保存します

     （たとえば、リクエスト ハンドラでカスタムの前処理や後処理を行う場合など、コンテナ イメージを変更する場合は、追加の RUN 命令を使用して依存関係をインストールできます）。

   • CMD 命令により、TorchServe HTTP サーバーが開始されます。親イメージから構成ファイルを参照し、mnist という名前の 1 つのモデルの提供を可能にします。このモデルは、RUN 命令で作成された mnist.mar ファイルを読み込みます。

     この命令は、親イメージの CMD 命令をオーバーライドします。親イメージの ENTRYPOINT スクリプトは CMD で渡されたコマンドを実行し、Docker が終了しないようにするためのロジックを追加するため、ENTRYPOINT 命令ではなく CMD 命令をオーバーライドすることが重要です。

2. 新しい Dockerfile に基づいてコンテナ イメージをビルドし、Artifact Registry リポジトリと互換性のある名前を使用してタグ付けするには、シェルで次のコマンドを実行します。

   docker build \
     --tag=REGION-docker.pkg.dev/PROJECT_ID/getting-started-pytorch/serve-mnist \
     .
   

   次のように置き換えます。

   • REGION: 前のセクションで指定した Artifact Registry リポジトリのリージョン
   • PROJECT_ID: Google Cloud プロジェクトの ID

   このコマンドの実行には、数分間かかる場合があります。

コンテナをローカルで実行する（省略可）

コンテナ イメージを Artifact Registry に push して AI Platform Prediction で使用する前に、ローカル環境でコンテナとして実行し、サーバーが想定どおりに動作することを確認できます。

1. コンテナ イメージをコンテナとしてローカルで実行するには、次のコマンドを実行します。

   docker run -d -p 8080:8080 --name=local_mnist \
     REGION-docker.pkg.dev/PROJECT_ID/getting-started-pytorch/serve-mnist
   

   前のセクションと同様に、次のよう置き換えます。

   • REGION: 前のセクションで指定した Artifact Registry リポジトリのリージョン
   • PROJECT_ID: Google Cloud プロジェクトの ID

   このコマンドは分離モードでコンテナを実行し、コンテナのポート 8080 をローカル環境のポート 8080 にマッピングします（コンテナ イメージを取得した親イメージによって、TorchServe はポート 8080 を使用するように構成されます）。

2. コンテナのサーバーにヘルスチェックを送信するには、シェルで次のコマンドを実行します。

   curl localhost:8080/ping
   

   成功すると、サーバーは次のレスポンスを返します。

   {
     "status": "Healthy"
   }
   

3. コンテナのサーバーに予測リクエストを送信するには、シェルで次のコマンドを実行します。

   cat > instances.json <<END
   {
     "instances": [
       {
         "data": {
           "b64": "$(base64 --wrap=0 test_data/3.png)"
         }
       }
     ]
   }
   END
   
   curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @instances.json \
     localhost:8080/predictions/mnist
   

   このリクエストでは、TorchServe サンプルに含まれるテストイメージのいずれかが使用されます。

   成功すると、サーバーは次の予測を返します。

   {"predictions": [3]}
   

4. コンテナを停止するには、シェルで次のコマンドを実行します。

   docker stop local_mnist
   

コンテナ イメージを Artifact Registry に push する

Artifact Registry にアクセスできるように Docker を構成します。次に、コンテナ イメージを Artifact Registry リポジトリに push します。

1. ローカルの Docker インストール権限を選択したリージョンの Artifact Registry に push するには、シェルで次のコマンドを実行します。

   gcloud auth configure-docker REGION-docker.pkg.dev
   

   REGION は、前のセクションでリポジトリを作成したリージョンに置き換えます。

2. ビルドしたコンテナ イメージを Artifact Registry に push するには、シェルで次のコマンドを実行します。

   docker push REGION-docker.pkg.dev/PROJECT_ID/getting-started-pytorch/serve-mnist
   

   前のセクションと同様に、次のよう置き換えます。

   • REGION: 前のセクションで指定した Artifact Registry リポジトリのリージョン
   • PROJECT_ID: Google Cloud プロジェクトの ID

コンテナをデプロイする

このセクションでは、予測を提供するために AI Platform Prediction でモデルとモデル バージョンを作成する手順について説明します。モデル バージョンでは、予測を提供するために、コンテナ イメージをコンテナとして実行します。

このチュートリアルでは、モデルとモデル バージョンを作成するときに使用する特定の構成オプションについて説明します。さまざまな構成オプションの詳細については、モデルのデプロイをご覧ください。

モデルの作成

モデルリソースを作成するには、シェルで次のコマンドを実行します。

gcloud beta ai-platform models create getting_started_pytorch \
  --region=REGION \
  --enable-logging \
  --enable-console-logging

REGION は、前のセクションで Artifact Registry リポジトリを作成したリージョンと同じリージョンに置き換えます。

モデル バージョンの作成

モデル バージョンのリソースを作成するには、シェルで次のコマンドを実行します。

gcloud beta ai-platform versions create v1 \
  --region=REGION \
  --model=getting_started_pytorch \
  --machine-type=n1-standard-4 \
  --image=REGION-docker.pkg.dev/PROJECT_ID/getting-started-pytorch/serve-mnist \
  --ports=8080 \
  --health-route=/ping \
  --predict-route=/predictions/mnist

次のように置き換えます。

• REGION: 前のセクションで Artifact Registry リポジトリと AI Platform Prediction モデルを作成したリージョン。
• PROJECT_ID: Google Cloud プロジェクトの ID

このコマンドのコンテナ関連フラグは次のとおりです。

• --image: コンテナ イメージの URI。

• --ports: コンテナの HTTP サーバーがリクエストをリッスンするポート。コンテナ イメージを取得した親イメージによって、TorchServe はポート 8080 を使用するように構成されます。

• --health-route: コンテナの HTTP サーバーがヘルスチェックをリッスンするパス。TorchServe は常に /ping パスでヘルスチェックをリッスンします。

• --predict-route: コンテナの HTTP サーバーが予測リクエストをリッスンするパス。TorchServe は常に /predictions/MODEL パスで予測リクエストをリッスンします。

  MODEL は、TorchServe の起動時に指定したモデルの名前です。このケースでは、名前は mnist です。これは、前のセクションのこの Docker 命令で設定されたものです。

  CMD ["torchserve", \
    "--start", \
    "--ts-config=/home/model-server/config.properties", \
    "--models", \
    "mnist=mnist.mar"]
  

予測の取得

前のセクションでダウンロードした TorchServe のサンプル ファイルには、テストイメージが含まれています。コンテナの TorchServe 構成では、予測リクエストを JSON 形式で受信し、各インスタンスの data.b64 フィールドにイメージが base64 エンコードの文字列で設定されていること前提としています。

たとえば、test_data/3.png を分類するには、シェルで次のコマンドを実行します。

cat > instances.json <<END
{
 "instances": [
   {
     "data": {
       "b64": "$(base64 --wrap=0 test_data/3.png)"
     }
   }
 ]
}
END

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d @instances.json \
  https://REGION-ml.googleapis.com/v1/projects/PROJECT_ID/models/getting_started_pytorch/versions/v1:predict

次のように置き換えます。

• REGION: 前のセクションで AI Platform Prediction モデルを作成したリージョン。
• PROJECT_ID: Google Cloud プロジェクトの ID

正常に実行されると、モデル バージョンは次の予測を返します。

{"predictions": [3]}

クリーンアップ

今後 AI Platform Prediction の料金と Artifact Registry の料金が発生しないようにするには、このチュートリアルで作成した Google Cloud リソースを削除します。

1. モデル バージョンを削除するには、シェルで次のコマンドを実行します。

   gcloud ai-platform versions delete v1 \
     --region=REGION \
     --model=getting_started_pytorch \
     --quiet
   

   REGION は、前のセクションでモデルを作成したリージョンに置き換えます。

2. モデルを削除するには、シェルで次のコマンドを実行します。

   gcloud ai-platform models delete getting_started_pytorch \
     --region=REGION \
     --quiet
   

   REGION は、前のセクションでモデルを作成したリージョンに置き換えます。

3. Artifact Registry リポジトリとその中のコンテナ イメージを削除するには、シェルで次のコマンドを実行します。

   gcloud beta artifacts repositories delete getting-started-pytorch \
     --location=REGION \
     --quiet
   

   REGION は、前のセクションで Artifact Registry リポジトリを作成したリージョンに置き換えます。

次のステップ

• 独自のコンテナ イメージを最初から、または既存のサードパーティ コンテナ イメージから取得して設計する場合は、カスタム コンテナの要件をご覧ください。

• 他の AI Platform Prediction 機能との互換性や、デプロイ時にコンテナに指定できる構成オプションなどの詳細は、予測にカスタム コンテナを使用するをご覧ください。