予測にカスタム コンテナを使用する

Vertex AI がカスタム トレーニング モデルからオンライン予測を提供する方法をカスタマイズするには、Model リソースを作成するときに、事前にビルドされたコンテナではなくカスタム コンテナを指定します。カスタム コンテナを使用すると、Vertex AI は各予測ノードで任意の Docker コンテナを実行します。

次のような理由からカスタム コンテナの使用をおすすめします。

• ビルド済みコンテナ以外のフレームワークを使用してトレーニングされた ML モデルから予測を行う
• モデルから生成される予測リクエストの前処理または後処理を行う
• 任意のプログラミング言語で作成された予測サーバーを実行する
• 予測のカスタマイズに使用する依存関係をインストールする

このガイドでは、カスタム コンテナを使用する Model の作成方法について説明します。Docker コンテナ イメージの設計と作成の詳細な手順については説明しません。

コンテナ イメージを準備する

カスタム コンテナを使用する Model を作成するには、そのコンテナのベースとして Docker コンテナ イメージを指定する必要があります。このコンテナ イメージは、カスタム コンテナの要件にある要件を満たす必要があります。

信頼できる第三者によって作成された既存のコンテナ イメージを使用する場合は、次のセクションのいずれか、または両方を省略できる可能性があります。

コンテナ イメージを作成する

コンテナ イメージの要件を満たす Docker コンテナ イメージを設計してビルドします。

Docker コンテナ イメージの設計とビルドの基本については、Docker ドキュメントのクイックスタートをご覧ください。

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

コンテナ イメージを Artifact Registry リポジトリに push します。

コンテナ イメージを Artifact Registry に push する方法を確認します。

Model を作成する

カスタム コンテナを使用する Model を作成するには、次のいずれかを行います。

• カスタム トレーニング モデルをインポートする。

• CustomJob を実行し、結果のアーティファクトを Model としてインポートする TrainingPipeline を作成する。

以下のセクションでは、このような方法で Model を作成する際に、カスタム コンテナに関連する API フィールドを構成する方法について説明します。

コンテナ関連の API フィールド

Model を作成する場合は、事前にビルドされたコンテナではなく、カスタム コンテナの詳細を使用して containerSpec フィールドを構成してください。

Model.containerSpec フィールドには、ModelContainerSpec メッセージを指定する必要があります。このメッセージには次のサブフィールドを指定できます。

imageUri（必須）

コンテナ イメージの Artifact Registry URI。

gcloud ai models upload コマンドを使用している場合は、--container-image-uri フラグを使用してこのフィールドを指定できます。

command（オプション）

コンテナの ENTRYPOINT をオーバーライドする実行可能ファイルの配列と引数。このフィールドの形式を指定する方法と、args フィールドの操作方法の詳細については、ModelContainerSpec の API リファレンスをご覧ください。

gcloud ai models upload コマンドを使用している場合は、--container-command フラグを使用してこのフィールドを指定できます。

args（オプション）

コンテナの CMD をオーバーライドする実行可能ファイルの配列と引数。このフィールドの形式を指定する方法と、command フィールドの操作方法の詳細については、ModelContainerSpec の API リファレンスをご覧ください。

gcloud ai models upload コマンドを使用している場合は、--container-args フラグを使用してこのフィールドを指定できます。

ports（オプション）

ポートの配列。Vertex AI では、リストの最初のポート上のコンテナ、またはデフォルトでは 8080 に実行チェック、ヘルスチェック、予測リクエストが送信されます。追加のポートを指定しても影響はありません。

gcloud ai models upload コマンドを使用している場合は、--container-ports フラグを使用してこのフィールドを指定できます。

env（オプション）

コンテナのエントリポイント コマンド、command フォールドと args フィールドで参照できる環境変数の配列。他のフィールドでこれらの環境変数を参照する方法について詳しくは、ModelContainerSpec の API リファレンスをご覧ください。

gcloud ai models upload コマンドを使用している場合は、--container-env-vars フラグを使用してこのフィールドを指定できます。

healthRoute（オプション）

Vertex AI でヘルスチェックを送信するコンテナの HTTP サーバーのパス。

このフィールドを指定しない場合、Model を DeployedModel として Endpoint リソースにデプロイすると、デフォルトで /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL になります。ここで、ENDPOINT は Endpoint の name フィールド（endpoints/ の後）の最後のセグメントに置き換えられます。また、DEPLOYED_MODEL は DeployedModel の id フィールドに置き換えられます。

gcloud ai models upload コマンドを使用している場合は、--container-health-route フラグを使用してこのフィールドを指定できます。

predictRoute（オプション）

Vertex AI で予測リクエストを転送するコンテナの HTTP サーバーのパス。

このフィールドを指定しない場合、Model を DeployedModel として Endpoint リソースにデプロイすると、デフォルトで /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict になります。ここで、ENDPOINT は Endpoint の name フィールド（endpoints/ の後）の最後のセグメントに置き換えられます。また、DEPLOYED_MODEL は DeployedModel の id フィールドに置き換えられます。

gcloud ai models upload コマンドを使用している場合は、--container-predict-route フラグを使用してこのフィールドを指定できます。

sharedMemorySizeMb（オプション）

モデルの共有メモリ ボリュームで予約する VM メモリの量（MB 単位）。

共有メモリは、複数のプロセスがメモリの共通ブロックにアクセスして操作できるようにするプロセス間通信（IPC）のメカニズムです。必要な共有メモリの量は、コンテナとモデルの実装の詳細によって異なります。ガイドラインについては、モデルサーバーのドキュメントをご覧ください。

gcloud ai models upload コマンドを使用している場合は、--container-shared-memory-size-mb フラグを使用してこのフィールドを指定できます。

startupProbe（オプション）

コンテナ アプリケーションが起動したかどうかを確認するプローブの仕様。

gcloud ai models upload コマンドを使用している場合は、--container-startup-probe-exec, --container-startup-probe-period-seconds, --container-startup-probe-timeout-seconds フラグを使用してこのフィールドを指定できます。

healthProbe（オプション）

コンテナがトラフィックを受け入れる準備ができているかどうかを確認するプローブの仕様。

gcloud ai models upload コマンドを使用している場合は、--container-health-probe-exec, --container-health-probe-period-seconds, --container-health-probe-timeout-seconds フラグを使用してこのフィールドを指定できます。

Vertex AI では、Model.containerSpec.env フィールドで設定する変数に加えて、構成に基づいていくつかの変数が設定されます。詳細については、これらのフィールドとコンテナのエントリポイント コマンドでの環境変数の使用をご覧ください。

モデルのインポートの例

次の例は、モデルをインポートするときにコンテナ関連の API フィールドを指定する方法を示しています。

注: TrainingPipeline を使用して Model を作成する場合は、これらのフィールドを別のコンテキストで指定する必要があります。Google Cloud CLI を使用して TrainingPipeline を作成することはできません。カスタム TrainingPipeline リソースの作成に関する詳細をご覧ください。

gcloud

次の例では、gcloud ai models upload コマンドを使用します。

gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --container-command=COMMAND \
  --container-args=ARGS \
  --container-ports=PORTS \
  --container-env-vars=ENV \
  --container-health-route=HEALTH_ROUTE \
  --container-predict-route=PREDICT_ROUTE \
  --container-shared-memory-size-mb=SHARED_MEMORY_SIZE \
  --container-startup-probe-exec=STARTUP_PROBE_EXEC \
  --container-startup-probe-period-seconds=STARTUP_PROBE_PERIOD \
  --container-startup-probe-timeout-seconds=STARTUP_PROBE_TIMEOUT \
  --container-health-probe-exec=HEALTH_PROBE_EXEC \
  --container-health-probe-period-seconds=HEALTH_PROBE_PERIOD \
  --container-health-probe-timeout-seconds=HEALTH_PROBE_TIMEOUT \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY

--container-image-uri フラグは必須です。--container- で始まる他のすべてのフラグは省略可能です。フィールドの値の詳細については、このガイドの前のセクションをご覧ください。

Java

このサンプルを試す前に、Vertex AI クイックスタート: クライアント ライブラリの使用にある Java の設定手順を完了してください。詳細については、Vertex AI Java API のリファレンス ドキュメントをご覧ください。

Vertex AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。

import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.aiplatform.v1.LocationName;
import com.google.cloud.aiplatform.v1.Model;
import com.google.cloud.aiplatform.v1.ModelContainerSpec;
import com.google.cloud.aiplatform.v1.ModelServiceClient;
import com.google.cloud.aiplatform.v1.ModelServiceSettings;
import com.google.cloud.aiplatform.v1.UploadModelOperationMetadata;
import com.google.cloud.aiplatform.v1.UploadModelResponse;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class UploadModelSample {
  public static void main(String[] args)
      throws InterruptedException, ExecutionException, TimeoutException, IOException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String modelDisplayName = "YOUR_MODEL_DISPLAY_NAME";
    String metadataSchemaUri =
        "gs://google-cloud-aiplatform/schema/trainingjob/definition/custom_task_1.0.0.yaml";
    String imageUri = "YOUR_IMAGE_URI";
    String artifactUri = "gs://your-gcs-bucket/artifact_path";
    uploadModel(project, modelDisplayName, metadataSchemaUri, imageUri, artifactUri);
  }

  static void uploadModel(
      String project,
      String modelDisplayName,
      String metadataSchemaUri,
      String imageUri,
      String artifactUri)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    ModelServiceSettings modelServiceSettings =
        ModelServiceSettings.newBuilder()
            .setEndpoint("us-central1-aiplatform.googleapis.com:443")
            .build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (ModelServiceClient modelServiceClient = ModelServiceClient.create(modelServiceSettings)) {
      String location = "us-central1";
      LocationName locationName = LocationName.of(project, location);

      ModelContainerSpec modelContainerSpec =
          ModelContainerSpec.newBuilder().setImageUri(imageUri).build();

      Model model =
          Model.newBuilder()
              .setDisplayName(modelDisplayName)
              .setMetadataSchemaUri(metadataSchemaUri)
              .setArtifactUri(artifactUri)
              .setContainerSpec(modelContainerSpec)
              .build();

      OperationFuture<UploadModelResponse, UploadModelOperationMetadata> uploadModelResponseFuture =
          modelServiceClient.uploadModelAsync(locationName, model);
      System.out.format(
          "Operation name: %s\n", uploadModelResponseFuture.getInitialFuture().get().getName());
      System.out.println("Waiting for operation to finish...");
      UploadModelResponse uploadModelResponse = uploadModelResponseFuture.get(5, TimeUnit.MINUTES);

      System.out.println("Upload Model Response");
      System.out.format("Model: %s\n", uploadModelResponse.getModel());
    }
  }
}

Node.js

このサンプルを試す前に、Vertex AI クイックスタート: クライアント ライブラリの使用にある Node.js の設定手順を完了してください。詳細については、Vertex AI Node.js API のリファレンス ドキュメントをご覧ください。

Vertex AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。

/**
 * TODO(developer): Uncomment these variables before running the sample.\
 */

// const modelDisplayName = 'YOUR_MODEL_DISPLAY_NAME';
// const metadataSchemaUri = 'YOUR_METADATA_SCHEMA_URI';
// const imageUri = 'YOUR_IMAGE_URI';
// const artifactUri = 'YOUR_ARTIFACT_URI';
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';

// Imports the Google Cloud Model Service Client library
const {ModelServiceClient} = require('@google-cloud/aiplatform');

// Specifies the location of the api endpoint
const clientOptions = {
  apiEndpoint: 'us-central1-aiplatform.googleapis.com',
};

// Instantiates a client
const modelServiceClient = new ModelServiceClient(clientOptions);

async function uploadModel() {
  // Configure the parent resources
  const parent = `projects/${project}/locations/${location}`;
  // Configure the model resources
  const model = {
    displayName: modelDisplayName,
    metadataSchemaUri: '',
    artifactUri: artifactUri,
    containerSpec: {
      imageUri: imageUri,
      command: [],
      args: [],
      env: [],
      ports: [],
      predictRoute: '',
      healthRoute: '',
    },
  };
  const request = {
    parent,
    model,
  };

  console.log('PARENT AND MODEL');
  console.log(parent, model);
  // Upload Model request
  const [response] = await modelServiceClient.uploadModel(request);
  console.log(`Long running operation : ${response.name}`);

  // Wait for operation to complete
  await response.promise();
  const result = response.result;

  console.log('Upload model response ');
  console.log(`\tModel : ${result.model}`);
}
uploadModel();

Python

Python をインストールまたは更新する方法については、Vertex AI SDK for Python をインストールするをご覧ください。詳細については、Python API リファレンス ドキュメントをご覧ください。

def upload_model_sample(
    project: str,
    location: str,
    display_name: str,
    serving_container_image_uri: str,
    artifact_uri: Optional[str] = None,
    serving_container_predict_route: Optional[str] = None,
    serving_container_health_route: Optional[str] = None,
    description: Optional[str] = None,
    serving_container_command: Optional[Sequence[str]] = None,
    serving_container_args: Optional[Sequence[str]] = None,
    serving_container_environment_variables: Optional[Dict[str, str]] = None,
    serving_container_ports: Optional[Sequence[int]] = None,
    instance_schema_uri: Optional[str] = None,
    parameters_schema_uri: Optional[str] = None,
    prediction_schema_uri: Optional[str] = None,
    explanation_metadata: Optional[explain.ExplanationMetadata] = None,
    explanation_parameters: Optional[explain.ExplanationParameters] = None,
    sync: bool = True,
):

    aiplatform.init(project=project, location=location)

    model = aiplatform.Model.upload(
        display_name=display_name,
        artifact_uri=artifact_uri,
        serving_container_image_uri=serving_container_image_uri,
        serving_container_predict_route=serving_container_predict_route,
        serving_container_health_route=serving_container_health_route,
        instance_schema_uri=instance_schema_uri,
        parameters_schema_uri=parameters_schema_uri,
        prediction_schema_uri=prediction_schema_uri,
        description=description,
        serving_container_command=serving_container_command,
        serving_container_args=serving_container_args,
        serving_container_environment_variables=serving_container_environment_variables,
        serving_container_ports=serving_container_ports,
        explanation_metadata=explanation_metadata,
        explanation_parameters=explanation_parameters,
        sync=sync,
    )

    model.wait()

    print(model.display_name)
    print(model.resource_name)
    return model

詳細については、モデルのインポート ガイドをご覧ください。

予測リクエストを送信する

オンライン予測リクエストを Model に送信するには、カスタム トレーニング モデルから予測を取得するの説明に従って操作します。このプロセスは、カスタム コンテナを使うかどうかに関係なく、同じように機能します。

詳細については、カスタム コンテナの予測リクエストとレスポンスの要件をご覧ください。

次のステップ

• カスタム コンテナの要件で、Vertex AI で使用するカスタム コンテナを設計する際に考慮すべき事項を確認する。