エンドポイントにモデルをデプロイする

オンライン予測用にモデルを配信する前に、モデルをエンドポイントにデプロイする必要があります。モデルのデプロイでは、少ないレイテンシでオンライン予測を提供できるように、モデルに物理リソースを関連付けます。

デプロイ可能なモデルは、Vertex AI Model Registry に表示されている必要があります。モデルのアーティファクトをインポートする方法や、Model Registry で直接作成する方法など、Model Registry の詳細については、Vertex AI Model Registry の概要をご覧ください。

1 つのエンドポイントに複数のモデルをデプロイすることも、複数のエンドポイントに同じモデルをデプロイすることもできます。モデルのデプロイにおけるオプションとユースケースの詳細については、同じエンドポイントに複数のモデルをデプロイする理由をご覧ください。

エンドポイントにモデルをデプロイする

モデルをデプロイするには、次のいずれかの方法を使用します。

Google Cloud コンソール

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

[モデル] ページに移動
デプロイするモデルの名前とバージョン ID をクリックして、詳細ページを開きます。
[デプロイとテスト] タブを選択します。

モデルがいずれかのエンドポイントにデプロイされている場合は、[モデルのデプロイ] セクションに一覧表示されます。
[エンドポイントへのデプロイ] をクリックします。
新しいエンドポイントにモデルをデプロイするには、[新しいエンドポイントを作成する] を選択し、新しいエンドポイントの名前を指定します。モデルを既存のエンドポイントにデプロイするには、[既存のエンドポイントに追加] を選択して、プルダウンリストからエンドポイントを選択します。

1 つのエンドポイントに複数のモデルをデプロイすることも、複数のエンドポイントに同じモデルをデプロイすることもできます。
1 つ以上のモデルがデプロイされている既存のエンドポイントにモデルをデプロイする場合は、すべての割合の合計が 100% になるように、デプロイするモデルとデプロイ済みのモデルのトラフィック分割の割合を更新する必要があります。
モデルを新しいエンドポイントにデプロイする場合は、トラフィック分割を 100 にします。それ以外の場合は、合計が 100 になるように、エンドポイントにあるすべてのモデルのトラフィック分割値を調整します。
モデルのコンピューティングノードの最小数を入力します。

これは、モデルで常に使用できる必要のあるノードの数です。

予測負荷を処理しているか、スタンバイ状態かに関係なく、使用されているノードに対して料金が発生します（予測トラフィックがない場合でも課金されます）。料金ページをご覧ください。

予測トラフィックを処理するために、必要に応じてコンピューティングノードの数を増やすことができますが、ノードの最大数を超えることはありません。
自動スケーリングを使用するには、Vertex AI でスケールアップするコンピューティングノードの最大数を入力します。
マシンタイプを選択します。

マシンリソースのサイズが大きいほど、予測パフォーマンスが向上しますが、コストも増加します。使用可能なマシンタイプを比較します。
アクセラレータタイプとアクセラレータ数を選択します。

モデルをインポートまたは作成したときにアクセラレータの使用を有効にした場合に、このオプションが表示されます。

アクセラレータ数については、GPU テーブルを参照して、各 CPU マシンタイプで使用できる有効な GPU の数を確認してください。アクセラレータ数は、デプロイメント内のアクセラレータの合計数ではなく、ノードあたりのアクセラレータの数を指します。
デプロイにカスタムサービスアカウントを使用する場合は、[サービスアカウント] プルダウンボックスでサービスアカウントを選択します。
予測ロギングのデフォルト設定を変更する方法をご確認ください。
モデルの [完了] をクリックします。すべてのトラフィック分割の割合が正しい場合は、[続行] をクリックします。
モデルがデプロイされるリージョンが表示されます。これは、モデルを作成したリージョンにする必要があります。
[デプロイ] をクリックして、エンドポイントにモデルをデプロイします。

API

Vertex AI API を使用してモデルをデプロイする場合は、次の手順を行います。

エンドポイントを Create します（必要に応じて）。
エンドポイント ID を Get します。
モデルをエンドポイントに Deploy します。

エンドポイントを作成する

既存のエンドポイントにモデルをデプロイする場合は、この手順をスキップして、エンドポイント ID を取得するに進みます。専用エンドポイントのプレビューを試すには、専用エンドポイントを作成するに進みます。

gcloud

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

gcloud ai endpoints create \
  --region=LOCATION_ID \
  --display-name=ENDPOINT_NAME

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

LOCATION_ID: Vertex AI を使用するリージョン。
ENDPOINT_NAME: エンドポイントの表示名。

Google Cloud CLI ツールがエンドポイントを作成するまでに数秒かかる場合があります。

REST

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

LOCATION_ID: 使用するリージョン。
PROJECT_ID: 実際のプロジェクト ID。
ENDPOINT_NAME: エンドポイントの表示名。

HTTP メソッドと URL:

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

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

{
  "display_name": "ENDPOINT_NAME"
}

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

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、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/endpoints"

PowerShell（Windows）

注: 次のコマンドは、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/endpoints" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/endpoints/ENDPOINT_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreateEndpointOperationMetadata",
    "genericMetadata": {
      "createTime": "2020-11-05T17:45:42.812656Z",
      "updateTime": "2020-11-05T17:45:42.812656Z"
    }
  }
}

レスポンスに

"done":
true

が含まれるまで、オペレーションのステータスをポーリングできます。

Terraform

次のサンプルでは、google_vertex_ai_endpoint Terraform リソースを使用してエンドポイントを作成します。

Terraform 構成を適用または削除する方法については、基本的な Terraform コマンドをご覧ください。

# Endpoint name must be unique for the project
resource "random_id" "endpoint_id" {
  byte_length = 4
}

resource "google_vertex_ai_endpoint" "default" {
  name         = substr(random_id.endpoint_id.dec, 0, 10)
  display_name = "sample-endpoint"
  description  = "A sample Vertex AI endpoint"
  location     = "us-central1"
  labels = {
    label-one = "value-one"
  }
}

Java

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

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


import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.aiplatform.v1.CreateEndpointOperationMetadata;
import com.google.cloud.aiplatform.v1.Endpoint;
import com.google.cloud.aiplatform.v1.EndpointServiceClient;
import com.google.cloud.aiplatform.v1.EndpointServiceSettings;
import com.google.cloud.aiplatform.v1.LocationName;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class CreateEndpointSample {

  public static void main(String[] args)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String endpointDisplayName = "YOUR_ENDPOINT_DISPLAY_NAME";
    createEndpointSample(project, endpointDisplayName);
  }

  static void createEndpointSample(String project, String endpointDisplayName)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    EndpointServiceSettings endpointServiceSettings =
        EndpointServiceSettings.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 (EndpointServiceClient endpointServiceClient =
        EndpointServiceClient.create(endpointServiceSettings)) {
      String location = "us-central1";
      LocationName locationName = LocationName.of(project, location);
      Endpoint endpoint = Endpoint.newBuilder().setDisplayName(endpointDisplayName).build();

      OperationFuture<Endpoint, CreateEndpointOperationMetadata> endpointFuture =
          endpointServiceClient.createEndpointAsync(locationName, endpoint);
      System.out.format("Operation name: %s\n", endpointFuture.getInitialFuture().get().getName());
      System.out.println("Waiting for operation to finish...");
      Endpoint endpointResponse = endpointFuture.get(300, TimeUnit.SECONDS);

      System.out.println("Create Endpoint Response");
      System.out.format("Name: %s\n", endpointResponse.getName());
      System.out.format("Display Name: %s\n", endpointResponse.getDisplayName());
      System.out.format("Description: %s\n", endpointResponse.getDescription());
      System.out.format("Labels: %s\n", endpointResponse.getLabelsMap());
      System.out.format("Create Time: %s\n", endpointResponse.getCreateTime());
      System.out.format("Update Time: %s\n", endpointResponse.getUpdateTime());
    }
  }
}

Node.js

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

/**
 * TODO(developer): Uncomment these variables before running the sample.\
 * (Not necessary if passing values as arguments)
 */

// const endpointDisplayName = 'YOUR_ENDPOINT_DISPLAY_NAME';
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';

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

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

// Instantiates a client
const endpointServiceClient = new EndpointServiceClient(clientOptions);

async function createEndpoint() {
  // Configure the parent resource
  const parent = `projects/${project}/locations/${location}`;
  const endpoint = {
    displayName: endpointDisplayName,
  };
  const request = {
    parent,
    endpoint,
  };

  // Get and print out a list of all the endpoints for this resource
  const [response] = await endpointServiceClient.createEndpoint(request);
  console.log(`Long running operation : ${response.name}`);

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

  console.log('Create endpoint response');
  console.log(`\tName : ${result.name}`);
  console.log(`\tDisplay name : ${result.displayName}`);
  console.log(`\tDescription : ${result.description}`);
  console.log(`\tLabels : ${JSON.stringify(result.labels)}`);
  console.log(`\tCreate time : ${JSON.stringify(result.createTime)}`);
  console.log(`\tUpdate time : ${JSON.stringify(result.updateTime)}`);
}
createEndpoint();

Python

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

def create_endpoint_sample(
    project: str,
    display_name: str,
    location: str,
):
    aiplatform.init(project=project, location=location)

    endpoint = aiplatform.Endpoint.create(
        display_name=display_name,
        project=project,
        location=location,
    )

    print(endpoint.display_name)
    print(endpoint.resource_name)
    return endpoint

専用エンドポイントを作成する

既存のエンドポイントにモデルをデプロイする場合は、この手順をスキップできます。

専用エンドポイントは、より高速で安定したエンドポイントであり、より大きなペイロードサイズと長いリクエストタイムアウトをサポートしています。

プレビュー版で専用エンドポイントを使用するには、明示的に有効にする必要があります。

REST

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"display_name": "ENDPOINT_NAME", "dedicatedEndpointEnabled": true}' \
https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints

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

ENDPOINT_NAME: エンドポイントの表示名。
LOCATION_ID: Vertex AI を使用するリージョン。
PROJECT_ID: Google Cloud プロジェクトのプロジェクト ID。

Python

endpoint = aiplatform.Endpoint.create(
  display_name="ENDPOINT_NAME",
  dedicated_endpoint_enabled=True,
)

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

ENDPOINT_NAME: エンドポイントの表示名。

エンドポイント ID を取得する

モデルをデプロイするには、エンドポイント ID が必要です。

gcloud

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

gcloud ai endpoints list \
  --region=LOCATION_ID \
  --filter=display_name=ENDPOINT_NAME

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

LOCATION_ID: Vertex AI を使用するリージョン。
ENDPOINT_NAME: エンドポイントの表示名。

ENDPOINT_ID 列に表示される番号をメモします。この ID は次の手順で使用します。

REST

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

LOCATION_ID: Vertex AI を使用するリージョン。
PROJECT_ID: 実際のプロジェクト ID。
ENDPOINT_NAME: エンドポイントの表示名。

HTTP メソッドと URL:

GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints?filter=display_name=ENDPOINT_NAME

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

curl（Linux、macOS、Cloud Shell）

次のコマンドを実行します。

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints?filter=display_name=ENDPOINT_NAME"

PowerShell（Windows）

次のコマンドを実行します。

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints?filter=display_name=ENDPOINT_NAME" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "endpoints": [
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/endpoints/ENDPOINT_ID",
      "displayName": "ENDPOINT_NAME",
      "etag": "AMEw9yPz5pf4PwBHbRWOGh0PcAxUdjbdX2Jm3QO_amguy3DbZGP5Oi_YUKRywIE-BtLx",
      "createTime": "2020-04-17T18:31:11.585169Z",
      "updateTime": "2020-04-17T18:35:08.568959Z"
    }
  ]
}

ENDPOINT_ID に注意してください。

モデルをデプロイする

お使いの言語または環境に応じて、以下のタブを選択してください。

gcloud

次の例では、gcloud ai endpoints deploy-model コマンドを使用しています。

次の例では、予測処理を高速化するために GPU を使用せずに Model を Endpoint にデプロイし、複数の DeployedModel リソース間でトラフィックを分割しません。

後述のコマンドデータを使用する前に、次のように置き換えます。

ENDPOINT_ID: エンドポイントの ID。
LOCATION_ID: Vertex AI を使用するリージョン。
MODEL_ID: デプロイするモデルの ID。
DEPLOYED_MODEL_NAME: DeployedModel の名前。DeployedModel の Model の表示名を使用することもできます。
MIN_REPLICA_COUNT: このデプロイの最小ノード数。ノード数は、予測負荷に応じてノードの最大数まで増減できますが、この数より少なくすることはできません。
MAX_REPLICA_COUNT: このデプロイの最大ノード数。ノード数は、予測負荷に応じてこのノード数まで増減に応じて増減できますが、最大値を超えることはできません。--max-replica-count フラグを省略した場合、最大ノード数は --min-replica-count の値に設定されます。

gcloud ai endpoints deploy-model コマンドを実行します。

Linux、macOS、Cloud Shell

gcloud ai endpoints deploy-model ENDPOINT_ID\
  --region=LOCATION_ID \
  --model=MODEL_ID \
  --display-name=DEPLOYED_MODEL_NAME \
  --min-replica-count=MIN_REPLICA_COUNT \
  --max-replica-count=MAX_REPLICA_COUNT \
  --traffic-split=0=100

Windows（PowerShell）

gcloud ai endpoints deploy-model ENDPOINT_ID`
  --region=LOCATION_ID `
  --model=MODEL_ID `
  --display-name=DEPLOYED_MODEL_NAME `
  --min-replica-count=MIN_REPLICA_COUNT `
  --max-replica-count=MAX_REPLICA_COUNT `
  --traffic-split=0=100

Windows（cmd.exe）

gcloud ai endpoints deploy-model ENDPOINT_ID^
  --region=LOCATION_ID ^
  --model=MODEL_ID ^
  --display-name=DEPLOYED_MODEL_NAME ^
  --min-replica-count=MIN_REPLICA_COUNT ^
  --max-replica-count=MAX_REPLICA_COUNT ^
  --traffic-split=0=100

トラフィックの分割

上記の例の --traffic-split=0=100 フラグでは、Endpoint が受信する新しい予測トラフィックの 100% を新しい DeployedModel に送信します。これは、一時的な ID 0 で表されます。Endpoint にすでに他の DeployedModel リソースがある場合は、新しい DeployedModel と古いリソースとの間でトラフィックを分割できます。たとえば、トラフィックの 20% を新しい DeployedModel に、80% を古いリソースに送信するには、次のコマンドを実行します。

後述のコマンドデータを使用する前に、次のように置き換えます。

OLD_DEPLOYED_MODEL_ID: 既存の DeployedModel の ID。

gcloud ai endpoints deploy-model コマンドを実行します。

Linux、macOS、Cloud Shell

gcloud ai endpoints deploy-model ENDPOINT_ID\
  --region=LOCATION_ID \
  --model=MODEL_ID \
  --display-name=DEPLOYED_MODEL_NAME \ 
  --min-replica-count=MIN_REPLICA_COUNT \
  --max-replica-count=MAX_REPLICA_COUNT \
  --traffic-split=0=20,OLD_DEPLOYED_MODEL_ID=80

Windows（PowerShell）

gcloud ai endpoints deploy-model ENDPOINT_ID`
  --region=LOCATION_ID `
  --model=MODEL_ID `
  --display-name=DEPLOYED_MODEL_NAME \ 
  --min-replica-count=MIN_REPLICA_COUNT `
  --max-replica-count=MAX_REPLICA_COUNT `
  --traffic-split=0=20,OLD_DEPLOYED_MODEL_ID=80

Windows（cmd.exe）

gcloud ai endpoints deploy-model ENDPOINT_ID^
  --region=LOCATION_ID ^
  --model=MODEL_ID ^
  --display-name=DEPLOYED_MODEL_NAME \ 
  --min-replica-count=MIN_REPLICA_COUNT ^
  --max-replica-count=MAX_REPLICA_COUNT ^
  --traffic-split=0=20,OLD_DEPLOYED_MODEL_ID=80

REST

モデルをデプロイします。

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

LOCATION_ID: Vertex AI を使用するリージョン。
PROJECT_ID: 実際のプロジェクト ID。
ENDPOINT_ID: エンドポイントの ID。
MODEL_ID: デプロイするモデルの ID。
DEPLOYED_MODEL_NAME: DeployedModel の名前。DeployedModel の Model の表示名を使用することもできます。
MACHINE_TYPE: 省略可。このデプロイの各ノードで使用するマシンリソース。デフォルトの設定は n1-standard-2 です。マシンタイプの詳細をご覧ください。
ACCELERATOR_TYPE: マシンに接続するアクセラレータのタイプ。ACCELERATOR_COUNT が指定されていない場合、またはゼロの場合は省略できます。AutoML モデルや、GPU 以外のイメージを使用するカスタムトレーニングモデルでは、推奨されません。詳細。
ACCELERATOR_COUNT: 各レプリカで使用するアクセラレータの数。省略可。GPU 以外のイメージを使用する AutoML モデルまたはカスタムトレーニングモデルの場合、0 を指定するか何も指定しないかのどちらかにしてください。
MIN_REPLICA_COUNT: このデプロイの最小ノード数。ノード数は、予測負荷に応じてノードの最大数まで増減できますが、この数より少なくすることはできません。1 以上の値を指定してください。
MAX_REPLICA_COUNT: このデプロイの最大ノード数。ノード数は、予測負荷に応じてこのノード数まで増減に応じて増減できますが、最大値を超えることはできません。
TRAFFIC_SPLIT_THIS_MODEL: このオペレーションでデプロイするモデルにルーティングされる、このエンドポイントへの予測トラフィックの割合。デフォルトは 100 です。すべてのトラフィックの割合の合計は 100 になる必要があります。トラフィック分割の詳細
DEPLOYED_MODEL_ID_N: 省略可。他のモデルがこのエンドポイントにデプロイされている場合は、すべての割合の合計が 100 になるように、トラフィック分割の割合を更新する必要があります。
TRAFFIC_SPLIT_MODEL_N: デプロイされたモデル ID キーのトラフィック分割の割合値。
PROJECT_NUMBER: プロジェクトに自動生成されたプロジェクト番号

HTTP メソッドと URL:

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:deployModel

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

{
  "deployedModel": {
    "model": "projects/PROJECT/locations/us-central1/models/MODEL_ID",
    "displayName": "DEPLOYED_MODEL_NAME",
    "dedicatedResources": {
       "machineSpec": {
         "machineType": "MACHINE_TYPE",
         "acceleratorType": "ACCELERATOR_TYPE",
         "acceleratorCount": "ACCELERATOR_COUNT"
       },
       "minReplicaCount": MIN_REPLICA_COUNT,
       "maxReplicaCount": MAX_REPLICA_COUNT
     },
  },
  "trafficSplit": {
    "0": TRAFFIC_SPLIT_THIS_MODEL,
    "DEPLOYED_MODEL_ID_1": TRAFFIC_SPLIT_MODEL_1,
    "DEPLOYED_MODEL_ID_2": TRAFFIC_SPLIT_MODEL_2
  },
}

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

curl（Linux、macOS、Cloud Shell）

リクエスト本文を 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/endpoints/ENDPOINT_ID:deployModel"

PowerShell（Windows）

リクエスト本文を 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/endpoints/ENDPOINT_ID:deployModel" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "name": "projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeployModelOperationMetadata",
    "genericMetadata": {
      "createTime": "2020-10-19T17:53:16.502088Z",
      "updateTime": "2020-10-19T17:53:16.502088Z"
    }
  }
}

Java

import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.aiplatform.v1.DedicatedResources;
import com.google.cloud.aiplatform.v1.DeployModelOperationMetadata;
import com.google.cloud.aiplatform.v1.DeployModelResponse;
import com.google.cloud.aiplatform.v1.DeployedModel;
import com.google.cloud.aiplatform.v1.EndpointName;
import com.google.cloud.aiplatform.v1.EndpointServiceClient;
import com.google.cloud.aiplatform.v1.EndpointServiceSettings;
import com.google.cloud.aiplatform.v1.MachineSpec;
import com.google.cloud.aiplatform.v1.ModelName;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.ExecutionException;

public class DeployModelCustomTrainedModelSample {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "PROJECT";
    String endpointId = "ENDPOINT_ID";
    String modelName = "MODEL_NAME";
    String deployedModelDisplayName = "DEPLOYED_MODEL_DISPLAY_NAME";
    deployModelCustomTrainedModelSample(project, endpointId, modelName, deployedModelDisplayName);
  }

  static void deployModelCustomTrainedModelSample(
      String project, String endpointId, String model, String deployedModelDisplayName)
      throws IOException, ExecutionException, InterruptedException {
    EndpointServiceSettings settings =
        EndpointServiceSettings.newBuilder()
            .setEndpoint("us-central1-aiplatform.googleapis.com:443")
            .build();
    String location = "us-central1";

    // 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 (EndpointServiceClient client = EndpointServiceClient.create(settings)) {
      MachineSpec machineSpec = MachineSpec.newBuilder().setMachineType("n1-standard-2").build();
      DedicatedResources dedicatedResources =
          DedicatedResources.newBuilder().setMinReplicaCount(1).setMachineSpec(machineSpec).build();

      String modelName = ModelName.of(project, location, model).toString();
      DeployedModel deployedModel =
          DeployedModel.newBuilder()
              .setModel(modelName)
              .setDisplayName(deployedModelDisplayName)
              // `dedicated_resources` must be used for non-AutoML models
              .setDedicatedResources(dedicatedResources)
              .build();
      // key '0' assigns traffic for the newly deployed model
      // Traffic percentage values must add up to 100
      // Leave dictionary empty if endpoint should not accept any traffic
      Map<String, Integer> trafficSplit = new HashMap<>();
      trafficSplit.put("0", 100);
      EndpointName endpoint = EndpointName.of(project, location, endpointId);
      OperationFuture<DeployModelResponse, DeployModelOperationMetadata> response =
          client.deployModelAsync(endpoint, deployedModel, trafficSplit);

      // You can use OperationFuture.getInitialFuture to get a future representing the initial
      // response to the request, which contains information while the operation is in progress.
      System.out.format("Operation name: %s\n", response.getInitialFuture().get().getName());

      // OperationFuture.get() will block until the operation is finished.
      DeployModelResponse deployModelResponse = response.get();
      System.out.format("deployModelResponse: %s\n", deployModelResponse);
    }
  }
}

Python

def deploy_model_with_dedicated_resources_sample(
    project,
    location,
    model_name: str,
    machine_type: str,
    endpoint: Optional[aiplatform.Endpoint] = None,
    deployed_model_display_name: Optional[str] = None,
    traffic_percentage: Optional[int] = 0,
    traffic_split: Optional[Dict[str, int]] = None,
    min_replica_count: int = 1,
    max_replica_count: int = 1,
    accelerator_type: Optional[str] = None,
    accelerator_count: Optional[int] = None,
    explanation_metadata: Optional[explain.ExplanationMetadata] = None,
    explanation_parameters: Optional[explain.ExplanationParameters] = None,
    metadata: Optional[Sequence[Tuple[str, str]]] = (),
    sync: bool = True,
):
    """
    model_name: A fully-qualified model resource name or model ID.
          Example: "projects/123/locations/us-central1/models/456" or
          "456" when project and location are initialized or passed.
    """

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

    model = aiplatform.Model(model_name=model_name)

    # The explanation_metadata and explanation_parameters should only be
    # provided for a custom trained model and not an AutoML model.
    model.deploy(
        endpoint=endpoint,
        deployed_model_display_name=deployed_model_display_name,
        traffic_percentage=traffic_percentage,
        traffic_split=traffic_split,
        machine_type=machine_type,
        min_replica_count=min_replica_count,
        max_replica_count=max_replica_count,
        accelerator_type=accelerator_type,
        accelerator_count=accelerator_count,
        explanation_metadata=explanation_metadata,
        explanation_parameters=explanation_parameters,
        metadata=metadata,
        sync=sync,
    )

    model.wait()

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

Node.js

const automl = require('@google-cloud/automl');
const client = new automl.v1beta1.AutoMlClient();

/**
 * Demonstrates using the AutoML client to create a model.
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = '[PROJECT_ID]' e.g., "my-gcloud-project";
// const computeRegion = '[REGION_NAME]' e.g., "us-central1";
// const datasetId = '[DATASET_ID]' e.g., "TBL2246891593778855936";
// const tableId = '[TABLE_ID]' e.g., "1991013247762825216";
// const columnId = '[COLUMN_ID]' e.g., "773141392279994368";
// const modelName = '[MODEL_NAME]' e.g., "testModel";
// const trainBudget = '[TRAIN_BUDGET]' e.g., "1000",
// `Train budget in milli node hours`;

// A resource that represents Google Cloud Platform location.
const projectLocation = client.locationPath(projectId, computeRegion);

// Get the full path of the column.
const columnSpecId = client.columnSpecPath(
  projectId,
  computeRegion,
  datasetId,
  tableId,
  columnId
);

// Set target column to train the model.
const targetColumnSpec = {name: columnSpecId};

// Set tables model metadata.
const tablesModelMetadata = {
  targetColumnSpec: targetColumnSpec,
  trainBudgetMilliNodeHours: trainBudget,
};

// Set datasetId, model name and model metadata for the dataset.
const myModel = {
  datasetId: datasetId,
  displayName: modelName,
  tablesModelMetadata: tablesModelMetadata,
};

// Create a model with the model metadata in the region.
client
  .createModel({parent: projectLocation, model: myModel})
  .then(responses => {
    const initialApiResponse = responses[1];
    console.log(`Training operation name: ${initialApiResponse.name}`);
    console.log('Training started...');
  })
  .catch(err => {
    console.error(err);
  });

予測ロギングのデフォルト設定を変更する方法をご確認ください。

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

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

制限事項

VPC Service Controls が有効になっている場合、デプロイされたモデルのコンテナはインターネットにアクセスできません。

モデルのデプロイメントを構成する

モデルのデプロイ時に、オンライン予測の実行について次の重要な決定を行います。

作成するリソース	リソース作成時に指定する設定
エンドポイント	予測を実行するロケーション
モデル	使用するコンテナ（`ModelContainerSpec`）
DeployedModel	オンライン予測に使用するマシン

これらの設定をモデルまたはエンドポイントの作成後に更新することはできません。また、オンライン予測リクエストでオーバーライドすることもできません。これらの設定を変更する必要がある場合は、モデルを再デプロイする必要があります。

モデルのデプロイによる影響

エンドポイントにモデルをデプロイする際は、物理（マシン）リソースを対象のモデルに関連付けて、オンライン予測を提供できるようにします。オンライン予測では、低レイテンシが求められます。事前にリソースをモデルに提供することで、レイテンシを削減できます

モデルのトレーニングタイプ（AutoML またはカスタム）と（AutoML）データ型によって、モデルで使用可能な物理リソースの種類が決まります。モデルのデプロイ後、新しいデプロイを作成せずに、これらのリソースの一部を mutate できます。

エンドポイントリソースによって、予測をリクエストするために使用するサービスエンドポイント（URL）が提供されます。次に例を示します。

https://us-central1-aiplatform.googleapis.com/v1/projects/{project}/locations/{location}/endpoints/{endpoint}:predict

同じエンドポイントに複数のモデルをデプロイする理由

2 つのモデルを同じエンドポイントにデプロイすると、1 つのモデルを段階的に別のモデルに置き換えることができます。たとえば、モデルを使用しており、新しいトレーニングデータでモデルの精度を向上させる方法を見つけたとします。ただし、新しいエンドポイント URL を指すようにアプリケーションを更新する必要がなく、アプリケーションを急に変更することを避ける必要があります。新しいモデルを同じエンドポイントに追加すると、トラフィックのごく一部を処理できます。新しいモデルへのトラフィック分割は、すべてのトラフィックがトラフィックを処理するまで、段階的に増やしていくことになります。

リソースは、エンドポイントではなくモデルに関連付けられているため、さまざまなタイプのモデルを同じエンドポイントにデプロイできます。ただし、特定の種類のモデル（AutoML 表形式、カスタムトレーニングなど）をエンドポイントにデプロイすることをおすすめします。この構成は管理が簡単です。

複数のエンドポイントにモデルをデプロイする理由

テスト環境や本番環境などのアプリケーション環境ごとに異なるリソースを使用してモデルをデプロイすることが必要になるかもしれません。また、予測リクエストでさまざまな SLO をサポートする必要がある場合もあります。おそらく、アプリケーションの中には他のアプリケーションよりもパフォーマンスニーズがはるかに高いものがあります。この場合、より多くのマシンリソースを持つ高パフォーマンスエンドポイントにこのモデルをデプロイできます。コストを最適化するために、マシンリソースが少ない低パフォーマンスのエンドポイントにモデルをデプロイすることもできます。

スケーリング動作

オンライン予測用のモデルを DeployedModel としてデプロイすると、予測ノードを自動スケーリングするよう構成できます。これを行うには、dedicatedResources.maxReplicaCount を dedicatedResources.minReplicaCount より大きい値に設定します。

DeployedModel を構成する場合は、dedicatedResources.minReplicaCount を 1 以上に設定する必要があります。つまり、使用されていない DeployedModel を 0 個の予測ノードにスケーリングするように構成することはできません。

ターゲット使用率と構成

デフォルトでは、専用の GPU リソースなしでモデルをデプロイすると、Vertex AI は CPU 使用率がデフォルトの 60% のターゲット値と一致するように、レプリカの数を自動的にスケールアップまたはスケールダウンします。

デフォルトでは、専用の GPU リソースを使用してモデルをデプロイすると（machineSpec.accelerator_count が 0 より大きい場合）、CPU 使用率または GPU 使用率のいずれか高い方がデフォルトの 60% のターゲット値と一致するように、Vertex AI は自動的にレプリカ数をスケールアップまたはスケールダウンします。そのため、予測スループットで GPU 使用率が高くても CPU 使用率が高くない場合、Vertex AI がスケールアップを行い、CPU 使用率は非常に低くなります。これは、モニタリングで確認できます。逆に、カスタムコンテナの GPU 使用率が低いものの、CPU 使用率が 60% を超える原因となる関連性のないプロセスが存在する場合は、QPS とレイテンシの目標を達成するために必要でない場合でも、Vertex AI はスケールアップを行います。

デフォルトのしきい値指標とターゲットは、autoscalingMetricSpecs を指定してオーバーライドできます。CPU 使用率のみに基づいてスケーリングするようにデプロイが構成されている場合、GPU 使用率が高い状態でも、スケールアップは行われません。

リソース使用量を管理する

エンドポイントをモニタリングして、CPU とアクセラレータの使用率、リクエスト数、レイテンシ、レプリカの現在の数とターゲット数などの指標を追跡できます。この情報は、エンドポイントのリソース使用量とスケーリング動作の理解に活用できます。

各レプリカではコンテナが 1 つしか実行されないことに注意してください。つまり、予測コンテナが選択されたコンピューティングリソース（マルチコアマシンのシングルスレッドコードなど）や、予測の一環として別のサービスを呼び出すカスタムモデルを十分に利用できない場合は、ノードがスケールアップされない可能性があります。

たとえば、FastAPI、またはワーカー数やスレッド数が構成可能なモデルサーバーを使用する場合は、リソース使用率を引き上げることができる複数のワーカーが存在すると、サービスがレプリカ数を自動的にスケーリングするための機能が改善されるケースが多数存在します。

通常は、コアごとに 1 つのワーカーまたはスレッドから始めることをおすすめします。CPU 使用率が低い場合（特に負荷が高い状況下で）、または CPU 使用率が低いためにモデルがスケールアップされない場合は、ワーカー数を引き上げる必要があります。一方、使用率が過剰に高く、負荷が生じた状態でレイテンシが予想以上に増加した場合は、使用するワーカーの数を削減してみてください。すでに 1 つのワーカーのみを使用している場合は、より小さなマシンタイプを使用してみてください。

スケーリングの動作とラグ

Vertex AI は、過去 5 分間のデータを使用して 15 秒ごとにレプリカの数を調整します。15 秒サイクルごとに、サーバー使用率が測定され、次の式に基づいてレプリカのターゲット数が生成されます。

target # of replicas = Ceil(current # of replicas * (current utilization / target utilization))

たとえば、2 つのレプリカが 100% 使用されている場合、ターゲットは以下のとおり 4 になります。

4 = Ceil(3.33) = Ceil(2 * (100% / 60%))

別の例として、10 個のレプリカがあり、使用率が 1% に低下した場合、ターゲットは以下のとおり 1 になります。

1 = Ceil(.167) = Ceil(10 * (1% / 60%))

15 秒の各サイクルの終了時に、過去 5 分間の最大ターゲット値に一致するようにレプリカの数を調整します。最大ターゲット値が選択されているため、全体の使用率が非常に低い場合でも、該当する 5 分間に使用率が急増しても、エンドポイントはスケールダウンされません。一方、システムをスケールアップする必要がある場合は、平均ではなく最大ターゲット値が選択されるため、15 秒以内にスケーリングが行われます。

Vertex AI がレプリカの数を調整しても、レプリカの起動または停止には時間を要することに注意してください。このため、エンドポイントがトラフィックに調整されるまでに、さらに遅延が発生します。この時間の原因となる主な要因は次のとおりです。

Compute Engine VM のプロビジョニングと起動に要する時間
レジストリからコンテナをダウンロードするために必要な時間
ストレージからモデルを読み込むために必要な時間

モデルの実際のスケーリング動作を理解する最善の方法は、負荷テストを実施し、モデルとユースケースにとって重要な特性を最適化することです。オートスケーラーのスケールアップ速度がアプリケーションに対して十分でない場合は、予想されるベースライントラフィックを処理するのに十分な min_replicas をプロビジョニングします。

スケーリング構成を更新する

モデルのデプロイ時に DedicatedResources または AutomaticResources を指定した場合は、mutateDeployedModel を呼び出してモデルを再デプロイすることなくスケーリングの構成を更新できます。

たとえば、次のリクエストでは max_replica と autoscaling_metric_specs が更新され、コンテナロギングが無効に設定されます。

{
  "deployedModel": {
    "id": "2464520679043629056",
    "dedicatedResources": {
      "maxReplicaCount": 9,
      "autoscalingMetricSpecs": [
        {
          "metricName": "aiplatform.googleapis.com/prediction/online/cpu/utilization",
          "target": 50
        }
      ]
    },
    "disableContainerLogging": true
  },
  "update_mask": {
    "paths": [
      "dedicated_resources.max_replica_count",
      "dedicated_resources.autoscaling_metric_specs",
      "disable_container_logging"
    ]
  }
}

使用上の注意:

マシンタイプの変更や、DedicatedResources から AutomaticResources（またはその逆）への切り替えはできません。変更できるスケーリング構成フィールドは、min_replica、max_replica、AutoscalingMetricSpec（DedicatedResources のみ）のみです。
更新するフィールドはすべて updateMask にリストする必要があります。リストにないフィールドは無視されます。
DeployedModel は DEPLOYED 状態である必要があります。デプロイされたモデルごとに、存在できるアクティブな変更オペレーションは 1 つのみです。
mutateDeployedModel を使用すると、コンテナロギングを有効または無効にすることもできます。詳細については、オンライン予測のロギングをご覧ください。

モデルのデプロイを解除してエンドポイントを削除する

次のいずれかの方法でモデルのデプロイを解除し、エンドポイントを削除します。

Google Cloud コンソール

次のようにモデルのデプロイを解除します。
1. Google Cloud コンソールの Vertex AI セクションで、[エンドポイント] ページに移動します。
  
  [エンドポイント] ページに移動
2. デプロイ解除するモデルの名前とバージョン ID をクリックして、詳細ページを開きます。
3. モデルの行で、（アクション）をクリックし、[エンドポイントからモデルのデプロイを解除] をクリックします。
4. [エンドポイントからモデルのデプロイを解除] ダイアログで [デプロイ解除] をクリックします。
5. 他のモデルを削除するには、上記の手順を繰り返します。
省略可: 次のようにオンライン予測エンドポイントを削除します。
1. Google Cloud コンソールの [Vertex AI] セクションで、[オンライン予測] ページに移動します。
  
  [オンライン予測] に移動
2. エンドポイントを選択します。
3. エンドポイントを削除するには、（アクション）をクリックしてから、[エンドポイントを削除] をクリックします。

gcloud

プロジェクト内のすべてのエンドポイントのエンドポイント ID を一覧取得します。
```
gcloud ai endpoints list \
    --project=PROJECT_ID \
    --region=LOCATION_ID
```
PROJECT_ID はプロジェクト名に置き換え、LOCATION_ID は Vertex AI を使用しているリージョンに置き換えます。
エンドポイントにデプロイされているモデルのモデル ID を一覧取得します。
```
gcloud ai endpoints describe ENDPOINT_ID \
    --project=PROJECT_ID \
    --region=LOCATION_ID
```
ENDPOINT_ID は、エンドポイント ID に置き換えます。

エンドポイントからモデルのデプロイを解除します。

gcloud ai endpoints undeploy-model ENDPOINT_ID \
    --project=PROJECT_ID \
    --region=LOCATION_ID \
    --deployed-model-id=DEPLOYED_MODEL_ID

DEPLOYED_MODEL_ID はモデル ID に置き換えます。

省略可: オンライン予測エンドポイントを削除します。

gcloud ai endpoints delete ENDPOINT_ID \
    --project=PROJECT_ID \
    --region=LOCATION_ID

次のステップ

オンライン予測を取得する方法を確認する。
プライベートエンドポイントについて確認する。