Model Garden と Vertex AI TPU 対応エンドポイントを使用して Gemma をデプロイして推論する


このチュートリアルでは、Model Garden を使用して、TPU をベースとする Vertex AI エンドポイントに Gemma 2B オープンモデルをデプロイします。オンライン予測用にモデルを配信する前に、モデルをエンドポイントにデプロイする必要があります。モデルのデプロイでは、少ないレイテンシでオンライン予測を提供できるように、モデルに物理リソースを関連付けます。

Gemma 2B モデルをデプロイしたら、PredictionServiceClient を使用してトレーニング済みモデルを推論し、オンライン予測を取得します。オンライン予測は、エンドポイントにデプロイされたモデルに対して行われる同期リクエストです。

目標

このチュートリアルでは、次のタスクを行う方法について説明します。

  • Model Garden を使用して、Gemma 2B オープンモデルを TPU ベースのエンドポイントにデプロイする
  • PredictionServiceClient を使用してオンライン予測を取得する

費用

このドキュメントでは、Google Cloud の次の課金対象のコンポーネントを使用します。

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。 新しい Google Cloud ユーザーは無料トライアルをご利用いただける場合があります。

このドキュメントに記載されているタスクの完了後、作成したリソースを削除すると、それ以上の請求は発生しません。詳細については、クリーンアップをご覧ください。

始める前に

このチュートリアルでは、次の作業が必要です。

  • Google Cloud プロジェクトを設定して Vertex AI API を有効にする
  • ローカルマシンで以下を行います。
    • Google Cloud CLI をインストール、初期化、認証する
    • 言語の SDK をインストールする

Google Cloud プロジェクトを設定する

Google Cloud プロジェクトを設定し、Vertex AI API を有効にします。

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI API.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI API.

    Enable the API

Google Cloud CLI を設定する

ローカルマシンで Google Cloud CLI を設定します。

  1. Google Cloud CLI をインストールして初期化する

  2. すでに gcloud CLI をインストールしている場合は、このコマンドを実行して gcloud コンポーネントが更新されていることを確認します。

    gcloud components update
  3. gcloud CLI で認証するには、次のコマンドを実行してローカルのアプリケーションのデフォルト認証情報(ADC)ファイルを生成します。コマンドで起動されたウェブフローを使用して、ユーザー認証情報を提供します。

    gcloud auth application-default login

    詳細については、gcloud CLI 認証構成と ADC 構成をご覧ください。

プログラミング言語の SDK を設定する

このチュートリアルで使用する環境を設定するには、使用する言語の Vertex AI SDK とプロトコル バッファ ライブラリをインストールします。コードサンプルでは、プロトコル バッファ ライブラリの関数を使用して、入力ディクショナリを API が想定する JSON 形式に変換します。

ローカルマシンで、次のいずれかのタブをクリックして、プログラミング言語の SDK をインストールします。

Python

ローカルマシンで、次のいずれかのタブをクリックして、プログラミング言語の SDK をインストールします。

  • 次のコマンドを実行して、Vertex AI SDK for Python をインストールして更新します。

    pip3 install --upgrade "google-cloud-aiplatform>=1.64"
  • 次のコマンドを実行して、Python 用のプロトコル バッファ ライブラリをインストールします。

    pip3 install --upgrade "protobuf>=5.28"

Node.js

次のコマンドを実行して、Node.js 用の aiplatform SDK をインストールまたは更新します。

npm install @google-cloud/aiplatform

Java

google-cloud-aiplatform を依存関係として追加するには、環境に適したコードを追加します。

BOM ありの Maven

pom.xml に次の HTML を追加します。

<dependencyManagement>
<dependencies>
  <dependency>
    <artifactId>libraries-bom</artifactId>
    <groupId>com.google.cloud</groupId>
    <scope>import</scope>
    <type>pom</type>
    <version>26.34.0</version>
  </dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-aiplatform</artifactId>
</dependency>
<dependency>
  <groupId>com.google.protobuf</groupId>
  <artifactId>protobuf-java-util</artifactId>
</dependency>
<dependency>
  <groupId>com.google.code.gson</groupId>
  <artifactId>gson</artifactId>
</dependency>
</dependencies>

BOM なしの Maven

pom.xml に次の行を追加します。

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-aiplatform</artifactId>
  <version>1.1.0</version>
</dependency>
<dependency>
  <groupId>com.google.protobuf</groupId>
  <artifactId>protobuf-java-util</artifactId>
  <version>5.28</version>
</dependency>
<dependency>
  <groupId>com.google.code.gson</groupId>
  <artifactId>gson</artifactId>
  <version>2.11.0</version>
</dependency>

BOM なしの Gradle

build.gradle に次の行を追加します。

implementation 'com.google.cloud:google-cloud-aiplatform:1.1.0'

Go

次のコマンドを実行して、これらの Go パッケージをインストールします。

go get cloud.google.com/go/aiplatform
go get google.golang.org/protobuf
go get github.com/googleapis/gax-go/v2

Model Garden を使用して Gemma をデプロイする

Gemma 2B モデルを、小規模から中規模のトレーニング用に最適化された ct5lp-hightpu-1t Compute Engine マシンタイプにデプロイします。このマシンには 1 つの TPU v5e アクセラレータがあります。TPU を使用してモデルをトレーニングする方法の詳細については、Cloud TPU v5e トレーニングをご覧ください。

このチュートリアルでは、Model Garden のモデルカードを使用して、命令でチューニングされた Gemma 2B オープンモデルをデプロイします。具体的なモデル バージョンは gemma2-2b-it です。-it指示のチューニング済みを表します。

Gemma 2B モデルのパラメータ サイズは小さいため、リソース要件が少なく、デプロイの柔軟性が高まります。

  1. Google Cloud コンソールで、[Model Garden] ページに移動します。

    Model Garden に移動

  2. [Gemma 2] モデルカードをクリックします。

    Gemma 2 に移動

  3. [デプロイ] をクリックして、[モデルのデプロイ] ペインを開きます。

  4. [モデルのデプロイ] ペインで、次の詳細を指定します。

    1. [デプロイ環境] で [Vertex AI] をクリックします。

    2. [モデルをデプロイする] セクションで、次の操作を行います。

      1. [リソース ID] に gemma-2b-it を選択します。

      2. [モデル名] と [エンドポイント名] のデフォルト値を使用します。例:

        • モデル名: gemma2-2b-it-1234567891234
        • エンドポイント名: gemma2-2b-it-mg-one-click-deploy

        エンドポイント名をメモします。コードサンプルで使用されているエンドポイント ID を確認するために必要になります。

    3. [デプロイの設定] セクションで、次の操作を行います。

      1. [基本] 設定はデフォルト オプションのままにします。

      2. [リージョン] では、デフォルト値のままにするか、リストからリージョンを選択します。リージョンをメモします。コードサンプルに必要になります。

      3. [マシン仕様] で、TPU を使用するインスタンス ct5lp-hightpu-1t (1 TPU_V5_LITEPOD; ct5lp-hightpu-1t) を選択します。

  5. [デプロイ] をクリックします。デプロイが完了すると、新しいエンドポイントの詳細が記載されたメールが届きます。[オンライン予測] > [エンドポイント] をクリックしてリージョンを選択して、エンドポイントの詳細を確認することもできます。

    エンドポイントに移動

PredictionServiceClient で Gemma 2B を推論する

Gemma 2B をデプロイしたら、PredictionServiceClient を使用して「空はなぜ青いの?」というプロンプトのオンライン予測を取得します。

コード パラメータ

PredictionServiceClient コードサンプルでは、以下を更新する必要があります。

  • PROJECT_ID: プロジェクト ID を確認する手順は次のとおりです。

    1. Google Cloud コンソールの [ようこそ] ページに移動します。

      [ようこそ] に移動

    2. ページ上部のプロジェクト選択ツールで、自分のプロジェクトを選択します。

      プロジェクト名、プロジェクト番号、プロジェクト ID は [ようこそ] の見出しの後に表示されます。

  • ENDPOINT_REGION: エンドポイントをデプロイしたリージョンです。

  • ENDPOINT_ID: エンドポイント ID を確認するには、コンソールで確認するか、gcloud ai endpoints list コマンドを実行します。[モデルをデプロイ] ペインからエンドポイント名とリージョンを取得します。

    コンソール

    [オンライン予測] > [エンドポイント] をクリックしてリージョンを選択すると、エンドポイントの詳細を確認できます。ID 列に表示される番号をメモします。

    エンドポイントに移動

    gcloud

    エンドポイントの詳細を表示するには、gcloud ai endpoints list コマンドを実行します。

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

    出力は次のようになります。

    Using endpoint [https://us-central1-aiplatform.googleapis.com/]
    ENDPOINT_ID: 1234567891234567891
    DISPLAY_NAME: gemma2-2b-it-mg-one-click-deploy
    

サンプルコード

言語のサンプルコードで、PROJECT_IDENDPOINT_REGIONENDPOINT_ID を更新します。次に、コードを実行します。

Python

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

"""
Sample to run inference on a Gemma2 model deployed to a Vertex AI endpoint with TPU accellerators.
"""

from google.cloud import aiplatform
from google.protobuf import json_format
from google.protobuf.struct_pb2 import Value

# TODO(developer): Update & uncomment lines below
# PROJECT_ID = "your-project-id"
# ENDPOINT_REGION = "your-vertex-endpoint-region"
# ENDPOINT_ID = "your-vertex-endpoint-id"

# Default configuration
config = {"max_tokens": 1024, "temperature": 0.9, "top_p": 1.0, "top_k": 1}

# Prompt used in the prediction
prompt = "Why is the sky blue?"

# Encapsulate the prompt in a correct format for TPUs
# Example format: [{'prompt': 'Why is the sky blue?', 'temperature': 0.9}]
input = {"prompt": prompt}
input.update(config)

# Convert input message to a list of GAPIC instances for model input
instances = [json_format.ParseDict(input, Value())]

# Create a client
api_endpoint = f"{ENDPOINT_REGION}-aiplatform.googleapis.com"
client = aiplatform.gapic.PredictionServiceClient(
    client_options={"api_endpoint": api_endpoint}
)

# Call the Gemma2 endpoint
gemma2_end_point = (
    f"projects/{PROJECT_ID}/locations/{ENDPOINT_REGION}/endpoints/{ENDPOINT_ID}"
)
response = client.predict(
    endpoint=gemma2_end_point,
    instances=instances,
)
text_responses = response.predictions
print(text_responses[0])

Node.js

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

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

// Imports the Google Cloud Prediction Service Client library
const {
  // TODO(developer): Uncomment PredictionServiceClient before running the sample.
  // PredictionServiceClient,
  helpers,
} = require('@google-cloud/aiplatform');
/**
 * TODO(developer): Update these variables before running the sample.
 */
const projectId = 'your-project-id';
const endpointRegion = 'your-vertex-endpoint-region';
const endpointId = 'your-vertex-endpoint-id';

// Prompt used in the prediction
const prompt = 'Why is the sky blue?';

// Encapsulate the prompt in a correct format for TPUs
// Example format: [{prompt: 'Why is the sky blue?', temperature: 0.9}]
const input = {
  prompt,
  // Parameters for default configuration
  maxOutputTokens: 1024,
  temperature: 0.9,
  topP: 1.0,
  topK: 1,
};

// Convert input message to a list of GAPIC instances for model input
const instances = [helpers.toValue(input)];

// TODO(developer): Uncomment apiEndpoint and predictionServiceClient before running the sample.
// const apiEndpoint = `${endpointRegion}-aiplatform.googleapis.com`;

// Create a client
// predictionServiceClient = new PredictionServiceClient({apiEndpoint});

// Call the Gemma2 endpoint
const gemma2Endpoint = `projects/${projectId}/locations/${endpointRegion}/endpoints/${endpointId}`;

const [response] = await predictionServiceClient.predict({
  endpoint: gemma2Endpoint,
  instances,
});

const predictions = response.predictions;
const text = predictions[0].stringValue;

console.log('Predictions:', text);

Java

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

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


import com.google.cloud.aiplatform.v1.EndpointName;
import com.google.cloud.aiplatform.v1.PredictResponse;
import com.google.cloud.aiplatform.v1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1.PredictionServiceSettings;
import com.google.gson.Gson;
import com.google.protobuf.InvalidProtocolBufferException;
import com.google.protobuf.Value;
import com.google.protobuf.util.JsonFormat;
import java.io.IOException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class Gemma2PredictTpu {
  private final PredictionServiceClient predictionServiceClient;

  // Constructor to inject the PredictionServiceClient
  public Gemma2PredictTpu(PredictionServiceClient predictionServiceClient) {
    this.predictionServiceClient = predictionServiceClient;
  }

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "YOUR_PROJECT_ID";
    String endpointRegion = "us-west1";
    String endpointId = "YOUR_ENDPOINT_ID";

    PredictionServiceSettings predictionServiceSettings =
        PredictionServiceSettings.newBuilder()
            .setEndpoint(String.format("%s-aiplatform.googleapis.com:443", endpointRegion))
            .build();
    PredictionServiceClient predictionServiceClient =
        PredictionServiceClient.create(predictionServiceSettings);
    Gemma2PredictTpu creator = new Gemma2PredictTpu(predictionServiceClient);

    creator.gemma2PredictTpu(projectId, endpointRegion, endpointId);
  }

  // Demonstrates how to run inference on a Gemma2 model
  // deployed to a Vertex AI endpoint with TPU accelerators.
  public String gemma2PredictTpu(String projectId, String region,
           String endpointId) throws IOException {
    Map<String, Object> paramsMap = new HashMap<>();
    paramsMap.put("temperature", 0.9);
    paramsMap.put("maxOutputTokens", 1024);
    paramsMap.put("topP", 1.0);
    paramsMap.put("topK", 1);
    Value parameters = mapToValue(paramsMap);
    // Prompt used in the prediction
    String instance = "{ \"prompt\": \"Why is the sky blue?\"}";
    Value.Builder instanceValue = Value.newBuilder();
    JsonFormat.parser().merge(instance, instanceValue);
    // Encapsulate the prompt in a correct format for TPUs
    // Example format: [{'prompt': 'Why is the sky blue?', 'temperature': 0.9}]
    List<Value> instances = new ArrayList<>();
    instances.add(instanceValue.build());

    EndpointName endpointName = EndpointName.of(projectId, region, endpointId);

    PredictResponse predictResponse = this.predictionServiceClient
        .predict(endpointName, instances, parameters);
    String textResponse = predictResponse.getPredictions(0).getStringValue();
    System.out.println(textResponse);
    return textResponse;
  }

  private static Value mapToValue(Map<String, Object> map) throws InvalidProtocolBufferException {
    Gson gson = new Gson();
    String json = gson.toJson(map);
    Value.Builder builder = Value.newBuilder();
    JsonFormat.parser().merge(json, builder);
    return builder.build();
  }
}

Go

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

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

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/aiplatform/apiv1/aiplatformpb"

	"google.golang.org/protobuf/types/known/structpb"
)

// predictTPU demonstrates how to run interference on a Gemma2 model deployed to a Vertex AI endpoint with TPU accelerators.
func predictTPU(w io.Writer, client PredictionsClient, projectID, location, endpointID string) error {
	ctx := context.Background()

	// Note: client can be initialized in the following way:
	// apiEndpoint := fmt.Sprintf("%s-aiplatform.googleapis.com:443", location)
	// client, err := aiplatform.NewPredictionClient(ctx, option.WithEndpoint(apiEndpoint))
	// if err != nil {
	// 	return fmt.Errorf("unable to create prediction client: %v", err)
	// }
	// defer client.Close()

	gemma2Endpoint := fmt.Sprintf("projects/%s/locations/%s/endpoints/%s", projectID, location, endpointID)
	prompt := "Why is the sky blue?"
	parameters := map[string]interface{}{
		"temperature":     0.9,
		"maxOutputTokens": 1024,
		"topP":            1.0,
		"topK":            1,
	}

	// Encapsulate the prompt in a correct format for TPUs.
	// Example format: [{'prompt': 'Why is the sky blue?', 'temperature': 0.9}]
	promptValue, err := structpb.NewValue(map[string]interface{}{
		"prompt":     prompt,
		"parameters": parameters,
	})
	if err != nil {
		fmt.Fprintf(w, "unable to convert prompt to Value: %v", err)
		return err
	}

	req := &aiplatformpb.PredictRequest{
		Endpoint:  gemma2Endpoint,
		Instances: []*structpb.Value{promptValue},
	}

	resp, err := client.Predict(ctx, req)
	if err != nil {
		return err
	}

	prediction := resp.GetPredictions()
	value := prediction[0].GetStringValue()
	fmt.Fprintf(w, "%v", value)

	return nil
}

クリーンアップ

このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。

プロジェクトを削除する

  1. In the Google Cloud console, go to the Manage resources page.

    Go to Manage resources

  2. In the project list, select the project that you want to delete, and then click Delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.

リソースを個別に削除する

プロジェクトを保持する場合は、このチュートリアルで使用したリソースを削除します。

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

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

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

コンソール

  1. Google Cloud コンソールで、[オンライン予測]、[エンドポイント] の順にクリックします。

    [エンドポイント] ページに移動

  2. [リージョン] プルダウン リストで、エンドポイントをデプロイしたリージョンを選択します。

  3. エンドポイント名をクリックして詳細ページを開きます。例: gemma2-2b-it-mg-one-click-deploy

  4. Gemma 2 (Version 1) モデルの行で、 [アクション] をクリックして、次に [エンドポイントからモデルのデプロイを解除] をクリックします。

  5. [エンドポイントからモデルのデプロイを解除] ダイアログで [デプロイ解除] をクリックします。

  6. [戻る] ボタンをクリックして [エンドポイント] ページに戻ります。

    [エンドポイント] ページに移動

  7. gemma2-2b-it-mg-one-click-deploy 行の末尾にある [アクション] をクリックし、[エンドポイントを削除] を選択します。

  8. 確認プロンプトで [確認] をクリックします。

gcloud

Google Cloud CLI を使用してモデルのデプロイを解除し、エンドポイントを削除する手順は次のとおりです。

これらのコマンドでは、次のように置き換えます。

  • PROJECT_ID は、プロジェクト名に置き換えます。
  • LOCATION_ID は、モデルとエンドポイントをデプロイしたリージョンに置き換えます。
  • ENDPOINT_ID は、エンドポイント ID に置き換えます。
  • DEPLOYED_MODEL_NAME はモデルの表示名に置き換えます。
  • DEPLOYED_MODEL_ID はモデル ID に置き換えます。
  1. gcloud ai endpoints list コマンドを実行してエンドポイント ID を取得します。このコマンドを使用すると、プロジェクト内のすべてのエンドポイントのエンドポイント ID が一覧表示されます。このチュートリアルで使用するエンドポイントの ID をメモします。

    gcloud ai endpoints list \
        --project=PROJECT_ID \
        --region=LOCATION_ID
    

    出力は次のようになります。出力では、ID は ENDPOINT_ID と呼ばれます。

    Using endpoint [https://us-central1-aiplatform.googleapis.com/]
    ENDPOINT_ID: 1234567891234567891
    DISPLAY_NAME: gemma2-2b-it-mg-one-click-deploy
    
  2. gcloud ai models describe コマンドを実行してモデル ID を取得します。このチュートリアルでデプロイしたモデルの ID をメモします。

    gcloud ai models describe DEPLOYED_MODEL_NAME \
        --project=PROJECT_ID \
        --region=LOCATION_ID
    

    省略した出力は次のようになります。出力では、ID は deployedModelId と呼ばれます。

    Using endpoint [https://us-central1-aiplatform.googleapis.com/]
    artifactUri: [URI removed]
    baseModelSource:
      modelGardenSource:
        publicModelName: publishers/google/models/gemma2
    ...
    deployedModels:
    - deployedModelId: '1234567891234567891'
      endpoint: projects/12345678912/locations/us-central1/endpoints/12345678912345
    displayName: gemma2-2b-it-12345678912345
    etag: [ETag removed]
    modelSourceInfo:
      sourceType: MODEL_GARDEN
    name: projects/123456789123/locations/us-central1/models/gemma2-2b-it-12345678912345
    ...
    
  3. エンドポイントからモデルのデプロイを解除します。前のコマンドからエンドポイント ID とモデル ID が必要です。

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

    このコマンドは出力を生成しません。

  4. gcloud ai endpoints delete コマンドを実行して、エンドポイントを削除します。

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

    プロンプトが表示されたら、「y」と入力して確定します。このコマンドは出力を生成しません。

モデルを削除する

コンソール

  1. Google Cloud コンソールの Vertex AI セクションから [Model Registry] ページに移動します。

    [Model Registry] ページに移動

  2. [リージョン] プルダウン リストで、モデルをデプロイしたリージョンを選択します。

  3. gemma2-2b-it-1234567891234 行の末尾にある [アクション] をクリックします。

  4. [モデルを削除] を選択します。

    モデルを削除すると、関連するすべてのモデル バージョンと評価が Google Cloud プロジェクトから削除されます。

  5. 確認プロンプトで [削除] をクリックします。

gcloud

Google Cloud CLI を使用してモデルを削除するには、モデルの表示名とリージョンを gcloud ai models delete コマンドに指定します。

gcloud ai models delete DEPLOYED_MODEL_NAME \
    --project=PROJECT_ID \
    --region=LOCATION_ID

DEPLOYED_MODEL_NAME は、モデルの表示名に置き換えます。PROJECT_ID は、プロジェクト名に置き換えます。LOCATION_ID は、モデルをデプロイしたリージョンに置き換えます。

次のステップ