この古いバージョンの AI Platform Prediction は非推奨になりました。2025 年 1 月 31 日を過ぎると Google Cloud で使用できなくなります。2025 年 1 月 31 日以降、すべてのモデル、関連するメタデータ、デプロイが削除されます。リソースを Vertex AI に移行することで、AI Platform にはない新しい機械学習機能を利用できます。

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

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

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

始める前に

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.

Google Cloud Console の [プロジェクトセレクタ] ページで、Google Cloud プロジェクトを選択または作成します。

プロジェクトセレクタに移動

Google Cloud プロジェクトで課金が有効になっていることを確認します。

AI Platform Training & Prediction and Artifact Registry API API を有効にします。

API を有効にする

Google Cloud Console の [プロジェクトセレクタ] ページで、Google Cloud プロジェクトを選択または作成します。

プロジェクトセレクタに移動

Google Cloud プロジェクトで課金が有効になっていることを確認します。

AI Platform Training & Prediction and Artifact Registry API API を有効にします。

API を有効にする

Google Cloud コンソールで、「Cloud Shell をアクティブにする」をクリックします。

Cloud Shell をアクティブにする

Google Cloud コンソールの下部で Cloud Shell セッションが開始し、コマンドラインプロンプトが表示されます。Cloud Shell はシェル環境です。Google Cloud CLI がすでにインストールされており、現在のプロジェクトの値もすでに設定されています。セッションが初期化されるまで数秒かかることがあります。

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

Google Cloud CLI をインストールします。
gcloud CLI を初期化するには:
```
gcloud init
```

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 イメージのいずれかからコンテナイメージを取得することで、ビルドプロセスを迅速に進めることが可能です。

モデルアーティファクトを含むディレクトリ内で、次のコマンドをシェルで実行して、新しい 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 命令をオーバーライドすることが重要です。
新しい 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 で使用する前に、ローカル環境でコンテナとして実行し、サーバーが想定どおりに動作することを確認できます。

コンテナイメージをコンテナとしてローカルで実行するには、シェルで次のコマンドを実行します。
```
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 を使用するように構成されます）。
コンテナのサーバーにヘルスチェックを送信するには、シェルで次のコマンドを実行します。
```
curl localhost:8080/ping
```
成功すると、サーバーは次のレスポンスを返します。
```
{
  "status": "Healthy"
}
```
コンテナのサーバーに予測リクエストを送信するには、シェルで次のコマンドを実行します。
```
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]}
```
コンテナを停止するには、シェルで次のコマンドを実行します。
```
docker stop local_mnist
```

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

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

ローカルの Docker インストール権限を選択したリージョンの Artifact Registry に push するには、シェルで次のコマンドを実行します。
```
gcloud auth configure-docker REGION-docker.pkg.dev
```
REGION は、前のセクションでリポジトリを作成したリージョンに置き換えます。
ビルドしたコンテナイメージを 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 リソースを削除します。

モデルバージョンを削除するには、シェルで次のコマンドを実行します。
```
gcloud ai-platform versions delete v1 \
  --region=REGION \
  --model=getting_started_pytorch \
  --quiet
```
REGION は、前のセクションでモデルを作成したリージョンに置き換えます。
モデルを削除するには、シェルで次のコマンドを実行します。
```
gcloud ai-platform models delete getting_started_pytorch \
  --region=REGION \
  --quiet
```
REGION は、前のセクションでモデルを作成したリージョンに置き換えます。
Artifact Registry リポジトリとその中のコンテナイメージを削除するには、シェルで次のコマンドを実行します。
```
gcloud beta artifacts repositories delete getting-started-pytorch \
  --location=REGION \
  --quiet
```
REGION は、前のセクションで Artifact Registry リポジトリを作成したリージョンに置き換えます。

次のステップ

独自のコンテナイメージを最初から、または既存のサードパーティコンテナイメージから取得して設計する場合は、カスタムコンテナの要件をご覧ください。
他の AI Platform Prediction 機能との互換性や、デプロイ時にコンテナに指定できる構成オプションなどの詳細は、予測にカスタムコンテナを使用するをご覧ください。