Vertex AI にモデルをインポートする

このガイドでは、モデルを Model Registry にインポートする方法について説明します。モデルをインポートすると、Model Registry に表示されます。Model Registry から、インポートしたモデルをエンドポイントにデプロイし、予測を実行できます。

必要なロール

モデルをインポートするために必要な権限を取得するには、管理者に連絡し、プロジェクトに対する Vertex AI ユーザー（roles/aiplatform.user）IAM ロールを付与してもらってください。ロールの付与の詳細については、アクセス権の管理に関する記事をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

ビルド済みコンテナまたはカスタムコンテナ

モデルをインポートするときに、Vertex AI が予測リクエストを実行するためにモデルをコンテナに関連付けます。Vertex AI が提供するビルド済みコンテナを使用することも、独自のカスタムコンテナをビルドして Artifact Registry に push することもできます。

モデルが次の要件を満たしている場合、ビルド済みコンテナを使用できます。

Python 3.7 以降でトレーニングされている
TensorFlow、PyTorch、scikit-learn、または XGBoost でトレーニングされている
ビルド済みの予測コンテナのフレームワーク固有の要件を満たすようにエクスポートされている

以前にエクスポートした表形式の AutoML モデルをインポートする場合は、Vertex AI が提供する特定のカスタムコンテナを使用する必要があります。

それ以外の場合は、新しいカスタムコンテナを作成するか、Artifact Registry 内の既存のカスタムコンテナを使用します。

モデルアーティファクトを Cloud Storage にアップロードする

モデルのアーティファクトは、使用しているリージョンエンドポイントと一致するリージョンの Cloud Storage バケットに保存する必要があります。

Cloud Storage バケットが別の Google Cloud プロジェクトにある場合、モデルアーティファクトを読み取るには、Vertex AI にアクセス権を付与する必要があります。

ビルド済みコンテナを使用する場合は、モデルアーティファクトのファイル名が次の例と完全に一致していることを確認します。

TensorFlow SavedModel: saved_model.pb
PyTorch: model.mar
scikit-learn: model.joblib または model.pkl
XGBoost: model.bst、model.joblib、model.pkl

詳しくは、予測に使用するモデルアーティファクトのエクスポートをご覧ください。

Google Cloud コンソールを使用してモデルをインポートする

Google Cloud コンソールを使用してモデルをインポートするには:

Google Cloud コンソールで、Vertex AI の [モデル] ページに移動します。

[モデル] ページに移動
[インポート] をクリックします。
新しいモデルをインポートするには、[新しいモデルとしてインポート] を選択します。
モデルを既存のモデルのバージョンとしてインポートするには、[新しいバージョンとしてインポート] を選択します。モデルのバージョニングの詳細については、モデルのバージョニングをご覧ください。
名前とリージョン: モデルの名前を入力します。バケットのリージョンと、使用している Vertex AI リージョンエンドポイントの両方に一致するリージョンを選択します。[続行] をクリックします。
[詳細オプション] を開くと、必要に応じて顧客管理の暗号鍵を追加できます。

使用しているコンテナの種類に応じて、該当するタブを選択してください。

ビルド済みコンテナ

[新しいビルド済みコンテナにモデルアーティファクトをインポートする] を選択します。
モデルのトレーニングに使用したモデルフレームワークとモデルフレームワークのバージョンを選択します。
GPU を使用して予測を行う場合は、[アクセラレータタイプ] を [GPU] に設定します。

GPU のタイプは、後でモデルをエンドポイントにデプロイするときに選択します。
モデルアーティファクトを含むディレクトリの Cloud Storage パスを指定します。

例: gs://BUCKET_NAME/models/
[予測スキマータ] は空白のままにします。
Vertex Explainable AI の設定を使用せずにモデルをインポートするには、[インポート] をクリックします。

インポートが完了すると、[モデル] ページにモデルが表示されます。

それ以外の場合は、[説明可能性] タブに説明可能性の設定を入力して、モデルの構成を続けます。詳細については、説明可能性の設定をご覧ください。

カスタムコンテナ

[既存のカスタムコンテナをインポート] を選択します。
コンテナイメージの URI を設定します。
コンテナイメージに加えてモデルアーティファクトも含める場合は、モデルアーティファクトが格納されたディレクトリの Cloud Storage パスを指定します。

例: gs://BUCKET_NAME/models/
その他のフィールドに値を指定します。

詳細については、省略可能なフィールドをご覧ください。
Vertex Explainable AI の設定を使用せずにモデルをインポートするには、[インポート] をクリックします。

インポートが完了すると、[モデル] ページにモデルが表示されます。

それ以外の場合は、[説明可能性] タブに説明可能性の設定を入力して、モデルの構成を続けます。詳細については、説明可能性の設定をご覧ください。

AutoML 表形式のコンテナ

[既存のカスタムコンテナをインポート] を選択します。
[コンテナイメージ] フィールドに「MULTI_REGION-docker.pkg.dev/vertex-ai/automl-tabular/prediction-server-v1:latest」と入力します。

MULTI_REGION を us、europe、または asia に置き換え、Docker イメージの取得元となる Docker リポジトリを選択します。各リポジトリは同じ Docker イメージを提供しますが、Docker を実行しているマシンに最も近い Artifact Registry マルチリージョンを選択すると、レイテンシが短縮される可能性があります。
[パッケージの場所] フィールドに、モデルアーティファクトが格納されているディレクトリの Cloud Storage パスを指定します。

パスは次の例のようになります。

gs://BUCKET_NAME/models-MODEL_ID/tf-saved-model/TIMESTAMP/
その他のフィールドは空欄のままにします。
[インポート] をクリックします。

インポートが完了すると、[モデル] ページにモデルが表示されます。このモデルは他の AutoML 表形式モデルと同じように使用できますが、インポートした AutoML 表形式モデルでは Vertex Explainable AI がサポートされません。

モデルをプログラムでインポートする

次の例は、さまざまなツールを使用してモデルをインポートする方法を示しています。

gcloud

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

gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY

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

LOCATION_ID: Vertex AI を使用するリージョン。
MODEL_NAME: Model の表示名。
IMAGE_URI: 予測に使用するコンテナイメージの URI。例: us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest。ビルド済みコンテナまたはカスタムコンテナを使用します。
PATH_TO_MODEL_ARTIFACT_DIRECTORY: モデルアーティファクトを含む Cloud Storage 内のディレクトリの Cloud Storage URI（gs:// で始まります）。

上の例は、ほとんどのモデルのインポートで必要になるフラグを示しています。ビルド済みコンテナを予測に使用しない場合は、Vertex AI がコンテナイメージを使用できるように、追加のオプションフラグの指定が必要になることがあります。これらのフラグは --container- で始まり、Model の containerSpec のフィールドに対応します。

REST

次のコードサンプルを使用して、model リソースの upload メソッドを使用してモデルをアップロードします。

リクエストのデータを使用する前に、次のように置き換えます。

LOCATION_ID: Vertex AI を使用するリージョン。
PROJECT_ID: 実際のプロジェクト ID。
MODEL_NAME: Model の表示名。
MODEL_DESCRIPTION: 省略可。モデルの説明。
IMAGE_URI: 予測に使用するコンテナイメージの URI。例: us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest。ビルド済みコンテナまたはカスタムコンテナを使用します。
PATH_TO_MODEL_ARTIFACT_DIRECTORY: モデルアーティファクトを含む Cloud Storage 内のディレクトリの Cloud Storage URI（gs:// で始まります）。カスタムコンテナを使用している場合、この変数と artifactUri フィールドは省略可能です。
labels: 省略可。モデルを整理するための任意の Key-Value ペアのセット。例:
- "env": "prod"
- "tier": "backend"
このトレーニングパイプラインに適用するラベルの LABEL_NAME と LABEL_VALUE を指定します。

HTTP メソッドと URL:

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/models:upload

リクエストの本文（JSON）:

{
  "model": {
    "displayName": "MODEL_NAME",
    "predictSchemata": {},
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "labels": {
      "LABEL_NAME_1": "LABEL_VALUE_1",
      "LABEL_NAME_2": "LABEL_VALUE_2"
    }
  }
}

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/models:upload"

PowerShell

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/models:upload" | Select-Object -Expand Content

レスポンス

{
"name": "projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.UploadModelOperationMetadata",
    "genericMetadata": {
      "createTime": "2020-11-10T23:44:21.777760Z",
      "updateTime": "2020-11-10T23:44:21.777760Z"
    }
  }
}

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 のリファレンスドキュメントをご覧ください。

/**
 * 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

Vertex AI SDK for 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

Vertex Explainable AI の設定を有効にしてモデルをインポートするには、Vertex Explainable AI モデルのインポート例をご覧ください。

オペレーションのステータスを取得する

一部のリクエストでは、完了までに長時間かかるオペレーションが実行されます。このようなリクエストではオペレーション名が返されます。そのオペレーション名を使用して、オペレーションのステータス確認やキャンセルを行うことができます。Vertex AI には、長時間実行オペレーションに対して呼び出しを行うためのヘルパーメソッドが用意されています。詳細については、長時間実行オペレーションによる作業をご覧ください。

制限事項

サポートされるモデルの最大サイズは 10 GiB です。

次のステップ

プログラムにより、または Google Cloud コンソールを使用して、エンドポイントにモデルをデプロイする。