Implantar e fazer inferência no Gemma usando o Model Garden e os endpoints com suporte de GPU da Vertex AI

Neste tutorial, você vai usar o Model Garden para implantar o modelo aberto Gemma 2B em um endpoint da Vertex AI com suporte a GPU. Implante um modelo em um endpoint antes de ele ser usado para exibir previsões on-line. A implantação de um modelo associa recursos físicos ao modelo para que ele possa exibir previsões on-line com baixa latência.

Depois de implantar o modelo Gemma 2B, você infere o modelo treinado usando o PredictionServiceClient para receber previsões on-line. As previsões on-line são solicitações síncronas feitas em um modelo implantado em um endpoint.

Objetivos

Este tutorial mostra como fazer as seguintes tarefas:

  • Implante o modelo aberto Gemma 2B em um endpoint com suporte a GPU usando o Model Garden
  • Usar o PredictionServiceClient para receber previsões on-line

Custos

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.

Antes de começar

Para este tutorial, você precisa:

  • Configurar um projeto do Google Cloud e ativar a API Vertex AI
  • Na máquina local:
    • Instalar, inicializar e autenticar com a Google Cloud CLI
    • Instalar o SDK para seu idioma

Configurar um Google Cloud projeto

Configure o Google Cloud projeto e ative a API Vertex AI.

  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.

  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

    8.

Configure a Google Cloud CLI

Na máquina local, configure a CLI do Google Cloud.

  1. Instale e inicialize a Google Cloud CLI.

  2. Se você já instalou a CLI gcloud, execute este comando para garantir que os componentes gcloud estejam atualizados.

    gcloud components update

  3. Para fazer a autenticação com a CLI gcloud, gere um arquivo local de credenciais padrão do aplicativo (ADC, na sigla em inglês) executando este comando. O fluxo da Web iniciado pelo comando é usado para fornecer suas credenciais de usuário.

    gcloud auth application-default login

    Para mais informações, consulte Configuração de autenticação da gcloud CLI e configuração do ADC.

Configurar o SDK para sua linguagem de programação

Para configurar o ambiente usado neste tutorial, instale o SDK da Vertex AI para sua linguagem e a biblioteca Protocol Buffers. Os exemplos de código usam funções da biblioteca Protocol Buffers para converter o dicionário de entrada no formato JSON esperado pela API.

Na máquina local, clique em uma das guias a seguir para instalar o SDK para sua linguagem de programação.

Python

Na máquina local, clique em uma das guias a seguir para instalar o SDK da sua linguagem de programação.

  • Instale e atualize o SDK da Vertex AI para Python executando este comando.

    pip3 install --upgrade "google-cloud-aiplatform>=1.64"

  • Instale a biblioteca Protocol Buffers para Python executando este comando.

    pip3 install --upgrade "protobuf>=5.28"

Node.js

Instale ou atualize o SDK aiplatform para Node.js executando o seguinte comando.

npm install @google-cloud/aiplatform

Java

Para adicionar google-cloud-aiplatform como uma dependência, adicione o código apropriado para seu ambiente.

Maven com BoM

Adicione o seguinte HTML ao pom.xml:

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

Maven sem BOM

Adicione o seguinte ao 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>

Gradle sem BoM

Adicione o seguinte ao seu build.gradle:

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

Go

Instale esses pacotes Go executando os seguintes comandos.

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

Implantar o Gemma usando o Model Garden

Você implanta o modelo Gemma 2B em um tipo de máquina otimizado para acelerador do Compute Engine g2-standard-12. Essa máquina tem um acelerador de GPU NVIDIA L4 anexado a ela.

Neste tutorial, você implanta o modelo aberto do Gemma 2B ajustado por instrução usando o card de modelo no Model Garden. A versão específica do modelo é gemma2-2b-it. -it significa ajuste de instruções.

O modelo Gemma 2B tem um tamanho de parâmetro menor, o que significa requisitos de recursos menores e mais flexibilidade de implantação.

  1. No Console do Google Cloud, acesse a página Model Garden.

    Acessar o Model Garden

  2. Clique no card de modelo Gemma 2.

    Acessar o Gemma 2

  3. Clique em Implantar para abrir o painel Implantar modelo.

  4. No painel Implantar modelo, especifique estes detalhes.

    1. Em Ambiente de implantação, clique em Vertex AI.

    2. Na seção Implantar modelo:

      1. Em ID do recurso, escolha gemma-2b-it.

      2. Para Nome do modelo e Nome do endpoint, aceite os valores padrão. Exemplo:

        • Nome do modelo: gemma2-2b-it-1234567891234
        • Nome do endpoint: gemma2-2b-it-mg-one-click-deploy

        Anote o nome do endpoint. Você vai precisar dela para encontrar o ID do endpoint usado nos exemplos de código.

    3. Na seção Configurações de implantação:

      1. Aceite a opção padrão para as configurações Básico.

      2. Em Região, aceite o valor padrão ou escolha uma região na lista. Anote a região. Você vai precisar dele para os exemplos de código.

      3. Em Especificação da máquina, escolha a instância com suporte a GPU: 1 NVIDIA_L4 g2-standard-12.

  5. Clique em Implantar. Quando a implantação for concluída, você vai receber um e-mail com detalhes sobre o novo endpoint. Também é possível conferir os detalhes do endpoint clicando em Previsão on-line > Endpoints e selecionando sua região.

    Acessar o Endpoints

Inferir o Gemma 2B com o PredictionServiceClient

Depois de implantar o Gemma 2B, use o PredictionServiceClient para receber previsões on-line para a instrução: "Por que o céu é azul?"

Parâmetros de código

Os exemplos de código PredictionServiceClient exigem que você atualize o seguinte:

  • PROJECT_ID: para encontrar o ID do projeto, siga estas etapas.

    1. Acesse a página Welcome no console do Google Cloud.

      Acesse a página "Bem-vindo"

    2. No seletor de projetos na parte de cima da página, selecione seu projeto.

      O nome, o número e o ID do projeto aparecem após o título Welcome.

  • ENDPOINT_REGION: é a região em que você implantou o endpoint.

  • ENDPOINT_ID: para encontrar o ID do endpoint, confira no console ou execute o comando gcloud ai endpoints list. Você vai precisar do nome e da região do endpoint no painel Deploy model.

    Console

    Para conferir os detalhes do endpoint, clique em Previsão on-line > Endpoints e selecione sua região. Anote o número que aparece na coluna ID.

    Acessar o Endpoints

    gcloud

    Para conferir os detalhes do endpoint, execute o comando gcloud ai endpoints list.

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

    A saída é semelhante a esta.

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

Código de amostra

No exemplo de código para sua linguagem, atualize o PROJECT_ID, ENDPOINT_REGION e ENDPOINT_ID. Em seguida, execute o código.

SDK da Vertex AI para Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Saiba mais na documentação de referência da API SDK da Vertex AI para Python. 

"""
Sample to run inference on a Gemma2 model deployed to a Vertex AI endpoint with GPU 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 GPUs
# Example format: [{'inputs': 'Why is the sky blue?', 'parameters': {'temperature': 0.9}}]
input = {"inputs": prompt, "parameters": 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

Antes de testar esse exemplo, siga as instruções de configuração para Node.js no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Node.js.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

async function gemma2PredictGpu(predictionServiceClient) {
  // 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';

  // Default configuration
  const config = {maxOutputTokens: 1024, temperature: 0.9, topP: 1.0, topK: 1};
  // Prompt used in the prediction
  const prompt = 'Why is the sky blue?';

  // Encapsulate the prompt in a correct format for GPUs
  // Example format: [{inputs: 'Why is the sky blue?', parameters: {temperature: 0.9}}]
  const input = {
    inputs: prompt,
    parameters: config,
  };

  // 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);
  return text;
}

module.exports = gemma2PredictGpu;

// TODO(developer): Uncomment below lines before running the sample.
// gemma2PredictGpu(...process.argv.slice(2)).catch(err => {
//   console.error(err.message);
//   process.exitCode = 1;
// });

Java

Antes de testar esse exemplo, siga as instruções de configuração para Java no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Java.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 


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 Gemma2PredictGpu {

  private final PredictionServiceClient predictionServiceClient;

  // Constructor to inject the PredictionServiceClient
  public Gemma2PredictGpu(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-east4";
    String endpointId = "YOUR_ENDPOINT_ID";

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

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

  // Demonstrates how to run inference on a Gemma2 model
  // deployed to a Vertex AI endpoint with GPU accelerators.
  public String gemma2PredictGpu(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 = "{ \"inputs\": \"Why is the sky blue?\"}";
    Value.Builder instanceValue = Value.newBuilder();
    JsonFormat.parser().merge(instance, instanceValue);
    // Encapsulate the prompt in a correct format for GPUs
    // Example format: [{'inputs': 'Why is the sky blue?', 'parameters': {'temperature': 0.8}}]
    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

Antes de testar esse exemplo, siga as instruções de configuração para Go no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Go.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

import (
	"context"
	"fmt"
	"io"

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

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

// predictGPU demonstrates how to run interference on a Gemma2 model deployed to a Vertex AI endpoint with GPU accelerators.
func predictGPU(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.
	// Pay attention that prompt should be set in "inputs" field.
	// Example format: [{'inputs': 'Why is the sky blue?', 'parameters': {'temperature': 0.9}}]
	promptValue, err := structpb.NewValue(map[string]interface{}{
		"inputs":     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
}

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

Excluir o projeto

  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.

Excluir recursos individuais

Se você quiser manter seu projeto, exclua os recursos usados neste tutorial:

  • Desfazer a implantação do modelo e excluir o endpoint
  • Excluir o modelo do Model Registry

Desfazer a implantação do modelo e excluir o endpoint

Use um dos métodos a seguir para desimplantar um modelo e excluir o endpoint.

Console

  1. No console do Google Cloud, clique em Previsão on-line e em Endpoints.

    Acessar a página do Endpoints

  2. Na lista suspensa Região, escolha a região em que você implantou o endpoint.

  3. Clique no nome do endpoint para abrir a página de detalhes. Por exemplo: gemma2-2b-it-mg-one-click-deploy.

  4. Na linha do modelo Gemma 2 (Version 1), clique em Ações e, em seguida, em Cancelar a implantação do modelo no endpoint.

  5. Na caixa de diálogo Cancelar a implantação do modelo do endpoint, clique em Cancelar a implantação.

  6. Clique no botão Voltar para retornar à página Endpoints.

    Acessar a página do Endpoints

  7. No final da linha gemma2-2b-it-mg-one-click-deploy, clique em Ações e selecione Excluir endpoint.

  8. No prompt de confirmação, clique em Confirmar.

gcloud

Para desimplantar o modelo e excluir o endpoint usando a CLI do Google Cloud, siga estas etapas.

Nesses comandos, substitua:

  • PROJECT_ID pelo nome do projeto;
  • LOCATION_ID pela região em que você implantou o modelo e o endpoint
  • ENDPOINT_ID com o ID do endpoint
  • DEPLOYED_MODEL_NAME com o nome de exibição do modelo
  • DEPLOYED_MODEL_ID pelo ID do modelo

  1. Para receber o ID do endpoint, execute o comando gcloud ai endpoints list. Esse comando lista os IDs de todos os endpoints no seu projeto. Anote o ID do endpoint usado neste tutorial.

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

    A saída é semelhante a esta. Na saída, o ID é chamado de ENDPOINT_ID.

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

  2. Para receber o ID do modelo, execute o comando gcloud ai models describe. Anote o ID do modelo implantado neste tutorial.

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

    A saída abreviada é assim. Na saída, o ID é chamado de 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. Desimplante o modelo do endpoint. Você vai precisar do ID do endpoint e do ID do modelo dos comandos anteriores.

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

    Esse comando não produz saída.

  4. Execute o comando gcloud ai endpoints delete para excluir o endpoint.

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

    Quando solicitado, digite y para confirmar. Esse comando não produz saída.

Excluir o modelo

Console

  1. Acesse a página Registro do modelo na seção "Vertex AI" do Console do Google Cloud.

    Acessar a página "Modelo de registro"

  2. Na lista suspensa Região, escolha a região em que você implantou o modelo.

  3. No final da linha gemma2-2b-it-1234567891234, clique em Ações.

  4. Selecione Excluir modelo.

    Quando você exclui o modelo, todas as versões e avaliações de modelo associadas são excluídas do projeto Google Cloud .

  5. No aviso de confirmação, clique em Excluir.

gcloud

Para excluir o modelo usando a CLI do Google Cloud, forneça o nome de exibição e a região do modelo ao comando gcloud ai models delete.

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

Substitua DEPLOYED_MODEL_NAME pelo nome de exibição do modelo. Substitua PROJECT_ID pelo nome do projeto. Substitua LOCATION_ID pela região em que você implantou o modelo.

A seguir