予測用のカスタムコンテナの要件

カスタムコンテナを使用してカスタムトレーニングモデルから予測を提供するには、HTTP サーバーを実行する Docker コンテナイメージを Vertex AI に指定する必要があります。このドキュメントでは、Vertex AI と互換性を維持するためのコンテナイメージの要件について説明します。また、起動後に Vertex AI がカスタムコンテナを処理する方法についても説明します。このドキュメントでは、Vertex AI で使用するコンテナイメージを設計する際の注意点について説明します。

カスタムコンテナイメージを使用して予測を行う方法については、カスタムコンテナの使用をご覧ください。

コンテナイメージの要件

Docker コンテナイメージがコンテナとして実行される場合、コンテナで HTTP サーバーを実行する必要があります。具体的には、コンテナで実行チェック、ヘルスチェック、予測リクエストをリッスンして応答する必要があります。以下のサブセクションでは、これらの要件について詳しく説明します。

このセクションの要件を満たしている限り、任意の方法で、任意のプログラミング言語を使用して HTTP サーバーを実装できます。たとえば、Flask などのウェブフレームワークを使用してカスタム HTTP サーバーを作成できます。または TensorFlow Serving、TorchServe、KServe Python Server などの HTTP サーバーを実行する機械学習（ML）配信ソフトウェアを使用できます。

HTTP サーバーを実行する

HTTP サーバーを実行するには、コンテナイメージのビルドに使用する Dockerfile で ENTRYPOINT の手順、CMD の手順、またはその両方を使用します。CMD と ENTRYPOINT の間のやり取りを確認してください。

また、Model リソースの作成時に containerSpec.command フィールドと containerSpec.args フィールドを指定して、コンテナイメージの ENTRYPOINT と CMD をそれぞれオーバーライドできます。これらのフィールドのいずれかを指定すると、ENTRYPOINT または CMD と互換性がない（または存在しない）ために要件を満たしていないコンテナイメージを使用できるようになります。

ただし、コンテナの起動時に実行するコマンドを決めて、この ENTRYPOINT 命令を無期限で実行できるようにします。たとえば、バックグラウンドで HTTP サーバーを起動してから終了するコマンドを実行しないでください。このコマンドを実行すると、コンテナが起動後すぐに終了します。

HTTP サーバーで、任意のポートの 0.0.0.0 に対するリクエストをリッスンする必要があります。Model を作成する場合は、このポートを containerSpec.ports フィールドに指定します。コンテナでこの値にアクセスする方法については、このドキュメントの AIP_HTTP_PORT 環境変数のセクションをご覧ください。

実行チェック

Vertex AI では、コンテナの起動時に実行チェックを行い、サーバーが動作していることを確認します。カスタムトレーニングモデルを Endpoint リソースにデプロイすると、Vertex AI は TCP 実行プローブを使用して、構成済みのポートでコンテナとの TCP 接続の確立を試みます。このプローブは、接続の確立を最大 4 回試行します。失敗するたびに 10 秒間待機します。この時点でプローブが接続を確立していない場合、Vertex AI がコンテナを再起動します。

HTTP サーバーで、これらのチェックを処理するために特別な動作を行う必要はありません。構成されたポートでリクエストをリッスンしている限り、実行プローブで接続を確立できます。

ヘルスチェック

必要に応じて、startup_probe または health_probe を指定できます。

起動プローブは、コンテナアプリケーションが起動したかどうかを確認します。起動プローブが指定されていない場合、起動プローブは存在せず、ヘルスチェックが直ちに開始されます。起動プローブが指定されている場合、起動プローブが成功するまでヘルスチェックは実行されません。

最初の初期化で追加の起動時間が必要になる可能性のある以前のアプリケーションでは、起動プローブを構成する必要があります。たとえば、アプリケーションが外部ソースからモデルアーティファクトをコピーする必要がある場合は、初期化が完了したときに「成功」を返すように起動プローブを構成する必要があります。

ヘルスプローブは、コンテナがトラフィックを受け入れる準備ができているかどうかを確認します。ヘルスプローブが指定されていない場合、Vertex AI はデフォルトのヘルスチェックを使用します（デフォルトのヘルスチェックを参照）。

モデルが読み込まれてトラフィックの受け入れ準備ができたことを示す 200 OK を返さない以前のアプリケーションには、ヘルスプローブを構成する必要があります。たとえば、レスポンスの本文にある実際のモデルの読み込みステータスが、モデルが読み込まれておらず、トラフィックを受け入れる準備ができていない可能性があることを示している場合でも、アプリケーションは成功を示す 200 OK を返すことがあります。この場合、モデルが読み込まれてトラフィックを処理する準備ができた場合にのみ「成功」を返すように、ヘルスプローブを構成する必要があります。

プローブを実行するために、Vertex AI はターゲットコンテナで指定された exec コマンドを実行します。コマンドが成功すると 0 が返され、コンテナは稼働中で正常な状態であるとみなされます。

デフォルトのヘルスチェック

デフォルトでは、Vertex AI は HTTP サーバーでヘルスチェックを断続的に実行しながら、予測リクエストを処理する準備が整っていることを確認します。このサービスでは、ヘルスプローブを使用して、サーバー上の構成可能なヘルスチェックパスに HTTP GET リクエストを送信します。Model の作成時に、このパスを containerSpec.healthRoute フィールドに指定します。コンテナでこの値にアクセスする方法については、このドキュメントの AIP_HEALTH_ROUTE 環境変数のセクションをご覧ください。

HTTP サーバーは、次のように構成して各ヘルスチェックリクエストに応答するようにします。

サーバーで予測リクエストを処理する準備ができている場合、10 秒以内にヘルスチェックリクエストに対してステータスコード 200 OK を返します。レスポンス本文の内容は重要ではありません。Vertex AI では無視されます。

このレスポンスは、サーバーが正常であることを示しています。
サーバーが予測リクエストを処理する準備ができていない場合は、10 秒以内にヘルスチェックリクエストに応答しないか、200 OK 以外のステータスコードを返します。たとえば、ステータスコード 503 Service Unavailable で応答します。

このレスポンス（またはレスポンスがない場合）は、サーバーが異常であることを示しています。

ヘルスプローブでサーバーから異常レスポンスを受け取った場合は（10 秒以内にレスポンスがない場合を含む）、最大 3 回まで追加のヘルスチェックを 10 秒間隔で送信します。その間、Vertex AI ではサーバーが正常だと見なされます。プローブでいずれかのチェックへの正常性を示すレスポンスを受け取った場合、プローブはすぐに断続的なヘルスチェックのスケジュールに戻ります。ただし、プローブで 4 回連続して異常なレスポンスを受け取った場合、Vertex AI はコンテナへの予測トラフィックのルーティングを停止します（複数の予測ノードを使用するように DeployedModel リソースがスケーリングされている場合、Vertex AI は他の正常なコンテナに予測リクエストをルーティングします）。

Vertex AI はコンテナを再起動しません。代わりに、ヘルスプローブでは引き続き、断続的にヘルスチェックリクエストを異常なサーバーに送信します。正常なレスポンスを受信した場合、そのコンテナは正常とマークされ、予測トラフィックのルーティングが再開されます。

実践的なガイダンス

コンテナ内の HTTP サーバーで、ヘルスチェックに対して常にステータスコード 200 OK で応答するだけで十分な場合があります。サーバーの起動前にコンテナがリソースを読み込むと、起動中と HTTP サーバーで障害が発生したときに、コンテナが正常な状態でなくなります。それ以外の場合は、正常な状態としてレスポンスが返されます。

より高度な構成の場合は、特定の時間にヘルスチェックに異常ステータスで応答するように HTTP サーバーを設計することをおすすめします。たとえば、コンテナでメンテナンスを行えるように、ノードへの予測トラフィックを一定期間ブロックします。

予測リクエスト

クライアントが projects.locations.endpoints.predict リクエストを Vertex AI API に送信すると、Vertex AI は、このリクエストを構成可能な予測パスに HTTP POST リクエストとして転送します。Model の作成時に、このパスを containerSpec.predictRoute フィールドに指定します。コンテナでこの値にアクセスする方法については、このドキュメントの AIP_PREDICT_ROUTE 環境変数のセクションをご覧ください。

リクエストの要件

モデルがパブリックエンドポイントにデプロイされる場合、各予測リクエストは 1.5 MB 以下でなければなりません。HTTP サーバーは、次の形式の Content-Type: application/json HTTP ヘッダーと JSON 本文を持つ予測リクエストを受け入れる必要があります。

{
  "instances": INSTANCES,
  "parameters": PARAMETERS
}

これらのリクエストで:

INSTANCES は、任意の型の 1 つ以上の JSON 値の配列です。各値は、予測を提供するインスタンスを表します。
PARAMETERS は、インスタンスで予測を行うためにコンテナが必要とするパラメータを含む JSON オブジェクトです。Vertex AI は、parameters フィールドをオプションと見なすため、コンテナで必須にすることも、指定時にのみ使用することもできます。また、無視することもできます。

詳しくは、リクエスト本文の要件をご覧ください。

レスポンスの要件

モデルがパブリックエンドポイントにデプロイされる場合、各予測レスポンスは 1.5 MB 以下でなければなりません。HTTP サーバーは、次の形式の JSON 本文を含むレスポンスを送信する必要があります。

{
  "predictions": PREDICTIONS
}

これらのレスポンスで、PREDICTIONS は、対応するリクエストの INSTANCES ごとに、コンテナで生成された予測の JSON 値の配列で置き換えます。

HTTP サーバーがこのレスポンスを送信すると、Vertex AI はレスポンスを返す前に deployedModelId フィールドをレスポンスに追加します。このフィールドには、レスポンスを送信する Endpoint 上の DeployedModel を指定します。詳細については、レスポンスの本文の形式をご覧ください。

コンテナイメージの公開要件

コンテナイメージを Vertex AI で使用するには、対象のイメージを Artifact Registry に push する必要があります。コンテナイメージを Artifact Registry に push する方法を確認します。

特に、次のロケーションと権限の要件を満たすリポジトリにコンテナイメージを push する必要があります。

ロケーション

Artifact Registry を使用する場合、Model を作成するリージョンエンドポイントと一致するリージョンをリポジトリで使用する必要があります。たとえば、us-central1-aiplatform.googleapis.com エンドポイントに Model を作成する場合は、us-central1-docker.pkg.dev/ で始まるコンテナイメージの完全な名前を使用する必要があります。コンテナイメージにマルチリージョンリポジトリを使用しないでください。

権限

Model を作成する場合、Vertex AI にはコンテナイメージを pull できる権限が必要です。具体的には、プロジェクトの Vertex AI サービスエージェントには、コンテナイメージのリポジトリに対する Artifact Registry 読み取りロール（roles/artifactregistry.reader）の権限が必要です。

Vertex AI は、プロジェクトの Vertex AI サービスエージェントを使用して他の Google Cloud サービスとやり取りします。このサービスアカウントには、メールアドレス service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com が設定されています。ここで、PROJECT_NUMBER は実際の Vertex AI プロジェクトのプロジェクト番号に置き換えられます。

Vertex AI を使用しているのと同じ Google Cloud プロジェクトにコンテナイメージを push している場合は、権限を構成する必要はありません。Vertex AI サービスエージェントに付与されているデフォルトの権限で十分です。

一方、Vertex AI を使用しているプロジェクトとは別の Google Cloud プロジェクトにコンテナイメージを push した場合は、Vertex AI サービスエージェントに Artifact Registry リポジトリに対する Artifact Registry 読み取りロールを付与する必要があります。

モデルアーティファクトにアクセスする

カスタムコンテナなしで、カスタムトレーニングの Model を作成する場合は、artifactUri フィールドとしてモデルアーティファクトを使用して、Cloud Storage ディレクトリの URI を指定する必要があります。カスタムコンテナを使用して Model を作成する場合、Cloud Storage でのモデルアーティファクトの提供は任意です。

予測に必要なモデルアーティファクトがコンテナイメージに含まれている場合は、Cloud Storage からファイルを読み込む必要はありません。ただし、artifactUri フィールドを指定してモデルアーティファクトを提供する場合、コンテナで実行の開始時にそのアーティファクトを読み込む必要があります。Vertex AI がコンテナを起動すると、AIP_STORAGE_URI 環境変数が gs:// で始まる Cloud Storage URI に設定されます。コンテナの ENTRYPOINT 命令では、モデルアーティファクトにアクセスするために、この URI で指定されたディレクトリをダウンロードできます。

AIP_STORAGE_URI 環境変数の値は、Model の作成時に artifactUri フィールドに指定した Cloud Storage URI と同一ではありません。AIP_STORAGE_URI は、Vertex AI が管理する別の Cloud Storage バケットのモデルアーティファクトディレクトリのコピーを指します。Model を作成すると、Vertex AI がこのディレクトリを設定します。ディレクトリの内容は更新できません。新しいモデルアーティファクトを使用する場合は、新しい Model を作成する必要があります。

コンテナがデフォルトで使用するサービスアカウントには、この URI からの読み取りが許可されています。

一方、Model を Endpoint にデプロイするときに、カスタムサービスアカウントを指定すると、Vertex AI は、指定されたサービスアカウントに URI の Cloud Storage バケットに対するストレージオブジェクト閲覧者（roles/storage.objectViewer）ロールを付与します。

アプリケーションのデフォルト認証情報（ADC）がサポートされるライブラリを使用して、モデルアーティファクトを読み込みます。認証を明示的に構成する必要はありません。

コンテナで使用できる環境変数

実行中、コンテナの ENTRYPOINT 命令は、手動で構成した環境変数と、Vertex AI によって自動的に設定される環境変数を参照できます。このセクションでは、環境変数を設定する方法と、Vertex AI によって自動的に設定される変数について詳しく説明します。

コンテナイメージで設定される変数

ビルド時にコンテナイメージ内で環境変数を設定するには、Docker の ENV の手順を使用します。接頭辞 AIP_ で始まる環境変数は設定しないでください。

これらの環境変数はコンテナの ENTRYPOINT 命令で使用できますが、Model の API フィールドで参照することはできません。

Vertex AI によって設定される変数

Vertex AI がコンテナの実行を開始すると、コンテナ環境で次の環境変数が設定されます。変数は接頭辞 AIP_ で始まります。この接頭辞を使用する環境変数は手動で設定しないでください。

これらの変数には、コンテナの ENTRYPOINT 命令でアクセスできます。これらの変数を参照できる Vertex AI API フィールドについては、ModelContainerSpec の API リファレンスをご覧ください。

変数名	デフォルト値	値の構成方法	詳細
AIP_ACCELERATOR_TYPE	設定解除	`Model` を `DeployedModel` リソースとして `Endpoint` リソースにデプロイする場合は、`dedicatedResources.machineSpec.acceleratorType` フィールドを設定します。	この変数は、コンテナが動作している仮想マシン（VM）インスタンスによって使用されるアクセラレータのタイプを指定します。
AIP_DEPLOYED_MODEL_ID	このコンテナの `Model` がデプロイされている `DeployedModel` を識別する文字列。	構成不可	この値は、`DeployedModel` の `id` フィールドです。
AIP_ENDPOINT_ID	コンテナの `Model` がデプロイされている `Endpoint` を識別する文字列。	構成不可	この値は、`Endpoint` の `name` フィールドの最後のセグメントです（`endpoints/` の後）。
AIP_FRAMEWORK	`CUSTOM_CONTAINER`	構成不可
AIP_HEALTH_ROUTE	`/v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL` この文字列では、`ENDPOINT` を `AIP_ENDPOINT_ID` 変数の値に置き換え、`DEPLOYED_MODEL` を `AIP_DEPLOYED_MODEL_ID` 変数の値に置き換えます。	`Model` を作成するときに、`containerSpec.healthRoute` フィールドを設定します。	この変数は、Vertex AI でヘルスチェックを送信するコンテナの HTTP パスを指定します。
AIP_HTTP_PORT	`8080`	`Model` を作成するときに、`containerSpec.ports` フィールドを設定します。このフィールドの最初のエントリは、`AIP_HTTP_PORT` の値になります。	Vertex AI で、実行チェック、ヘルスチェック、予測リクエストがコンテナのこのポートに送信されます。コンテナの HTTP サーバーで、このポートでリクエストをリッスンする必要があります。
AIP_MACHINE_TYPE	デフォルトはありません。構成する必要があります	`Model` を `DeployedModel` リソースとして `Endpoint` リソースにデプロイする場合は、`dedicatedResources.machineSpec.machineType` フィールドを設定します。	この変数は、コンテナが実行されている VM のタイプを指定します。
AIP_MODE	`PREDICTION`	構成不可	この変数は、オンライン予測のために Vertex AI 上でコンテナが実行されていることを示します。この環境変数を使用すると、カスタムロジックをコンテナに追加して、複数のコンピューティング環境で実行できますが、特定のコードパスは Vertex AI で実行するときにだけ使用できます。
AIP_MODE_VERSION	`1.0.0`	構成不可	この変数は、Vertex AI がコンテナに想定するカスタムコンテナ要件（このドキュメント）のバージョンを示します。このドキュメントは、セマンティックバージョニングに従って更新されます。
AIP_MODEL_NAME	`AIP_ENDPOINT_ID` 変数の値。	構成不可	`AIP_ENDPOINT_ID` の行を確認します。この変数は互換性の理由から存在します。
AIP_PREDICT_ROUTE	`/v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict` この文字列では、`ENDPOINT` を `AIP_ENDPOINT_ID` 変数の値に置き換え、`DEPLOYED_MODEL` を `AIP_DEPLOYED_MODEL_ID` 変数の値に置き換えます。	`Model` を作成するときに、`containerSpec.predictRoute` フィールドを設定します。	この変数では、Vertex AI で予測リクエストを転送するコンテナの HTTP パスを指定します。
AIP_PROJECT_NUMBER	Vertex AI を使用している Google Cloud プロジェクトのプロジェクト番号	構成不可
AIP_STORAGE_URI	`Model` の作成時に `artifactUri` フィールドを設定しない場合: 空の文字列。 `Model` の作成時に `artifactUri` フィールドを設定する場合: Cloud Storage URI（`gs://` で始まる）。Vertex AI で管理されるバケット内のディレクトリを指定します。	構成不可	この変数では、モデルアーティファクトのコピーが含まれるディレクトリを指定します（該当する場合）。
AIP_VERSION_NAME	`AIP_DEPLOYED_MODEL_ID` 変数の値。	構成不可	`AIP_DEPLOYED_MODEL_ID` の行を確認します。この変数は互換性の理由から存在します。

`Model` リソースで設定された変数

Model を作成するときに、containerSpec.env フィールドに追加の環境変数を設定できます。

次のステップ

モデルのインポート時にコンテナ関連の API フィールドを指定する方法など、カスタムコンテナを使用して予測を行う方法を学習する。