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

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

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

コンテナ イメージの要件

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

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

HTTP サーバーを実行する

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

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

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

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

実行チェック

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

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

ヘルスチェック

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 または Container Registry にイメージを push する必要があります。詳しくは、コンテナ イメージを Artifact Registry に push する方法またはコンテナ イメージを Container Registry に push する方法をご覧ください。

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

ロケーション

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

Container Registry を使用する場合、リポジトリは任意の Container Registry ホスト名を使用できます。

権限

Model を作成する場合、Vertex AI にはコンテナ イメージを pull できる権限が必要です。特に、以下の点に注意してください。

プロジェクトの Vertex AI サービス エージェントは、Google が管理するサービス アカウントで、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 読み取りロールを付与するか、Vertex AI サービス エージェントに Container Registry が使用する Cloud Storage バケットに対するストレージ オブジェクト閲覧者ロールを付与する必要があります。

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

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

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

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

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

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

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

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

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

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

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

これらの環境変数はコンテナのエントリポイント コマンドで使用できますが、Model の API フィールドでは参照できません。

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

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

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

変数名 デフォルト値 値の構成方法 詳細
AIP_ACCELERATOR_TYPE 設定解除 ModelDeployedModel リソースとして Endpoint リソースにデプロイする場合は、dedicatedResources.machineSpec.acceleratorType フィールドを設定します。 この変数は、コンテナが動作している仮想マシン(VM)インスタンスによって使用されるアクセラレータのタイプを指定します。
AIP_DEPLOYED_MODEL_ID このコンテナの Model がデプロイされている DeployedModel を識別する文字列。 構成不可 この値は、DeployedModelid フィールドです。
AIP_ENDPOINT_ID コンテナの Model がデプロイされている Endpoint を識別する文字列。 構成不可 この値は、Endpointname フィールドの最後のセグメントです(endpoints/ の後)。
AIP_FRAMEWORK CUSTOM_CONTAINER 構成不可
AIP_HEALTH_ROUTE /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL

この文字列では、ENDPOINTAIP_ENDPOINT_ID 変数の値に置き換え、DEPLOYED_MODELAIP_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 デフォルトはありません。構成する必要があります ModelDeployedModel リソースとして 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

この文字列では、ENDPOINTAIP_ENDPOINT_ID 変数の値に置き換え、DEPLOYED_MODELAIP_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 フィールドに追加の環境変数を設定できます。

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

次のステップ