API Grounding

Na IA generativa, embasamento é a capacidade de conectar a saída do modelo a fontes de informações verificáveis. Se você fornecer aos modelos acesso a fontes de dados específicas, o embasamento da saída deles a esses dados reduz as chances de inventar conteúdo.

Com a Vertex AI, é possível embasar as saídas do modelo das seguintes maneiras:

  • Embasamento com a Pesquisa Google: basear um modelo com dados da Web disponíveis publicamente.
  • Embasamento com o Google Maps: basear um modelo com dados geoespaciais do Google Maps.
  • Embasamento com seus dados: basear um modelo com seus dados da Vertex AI para Pesquisa como um repositório de dados.

Para mais informações sobre embasamento, consulte Visão geral de embasamento.

Modelos compatíveis

Lista de parâmetros

Confira exemplos para detalhes de implementação.

googleSearch

Baseie a resposta com dados da Web disponíveis publicamente da Pesquisa Google.

googleMaps

Baseie a resposta com dados geoespaciais disponíveis publicamente do Google Maps.

A entrada da API inclui o seguinte parâmetro:

Parâmetro de entrada

enable_widget

Obrigatório: boolean

Flag que pode ser definida como true ou false. Um valor de true retorna um token usando a resposta da API que pode ser usado com a interface do widget de contexto do Google Maps.

A estrutura de resposta da API inclui o seguinte parâmetro:

Parâmetro de resposta

grounding_metadata

Obrigatório: Object

O campo principal que contém informações de embasamento.
  • grounding_support: um subcampo que indica o nível de suporte de embasamento.
  • grounding_chunks.maps: um subcampo que contém as fontes de lugares usadas para gerar a resposta embasada.
    • place_answer_sources.review_snippets: Um subcampo em grounding_chunks.maps que aparece quando uma resposta de lugar é usada para responder a uma consulta. As respostas de lugar fornecem informações contextuais mais detalhadas sobre um lugar específico usando dados, como avaliações de usuários. A resposta de lugar é apoiada por uma lista de fontes, como avaliações de usuários reviews.

Atributos

Uma fonte de avaliação de lugar ou usuário tem os seguintes atributos:

Atributos

title

Obrigatório: Object

O título da fonte.

uri

Obrigatório: string

Um URI que vincula à fonte.

place_id

Obrigatório: string

Um identificador exclusivo do lugar.

review_id

Obrigatório: string

Um identificador exclusivo da avaliação.

retrieval

Baseie a resposta com dados particulares da Vertex AI para Pesquisa como um repositório de dados. Define uma ferramenta de recuperação que o modelo pode chamar para acessar conhecimento externo.

Parâmetros

vertexAiSearch

Obrigatório: VertexAISearch

Informações básicas sobre as fontes de dados da Vertex AI para Pesquisa.

VertexAISearch

Parâmetros

datastore

Obrigatório: string

ID do recurso de repositório de dados totalmente qualificado da Vertex AI para Pesquisa, no seguinte formato: projects/{project}/locations/{location}/collections/default_collection/dataStores/{datastore}

Exemplos

Esta seção fornece exemplos de como basear uma resposta em dados públicos da Web usando a Pesquisa Google e como basear uma resposta em dados particulares usando a Vertex AI para Pesquisa.

Resposta empírica em dados públicos da Web usando a Pesquisa Google

Baseie a resposta com dados públicos da Pesquisa Google. Inclua a ferramenta google_search_retrieval na solicitação. Nenhum parâmetro adicional é necessário.

Python

Instalar

pip install --upgrade google-genai

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK da IA generativa com a Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

from google import genai
from google.genai.types import (
    GenerateContentConfig,
    GoogleSearch,
    HttpOptions,
    Tool,
)

client = genai.Client(http_options=HttpOptions(api_version="v1"))

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="When is the next total solar eclipse in the United States?",
    config=GenerateContentConfig(
        tools=[
            # Use Google Search Tool
            Tool(
                google_search=GoogleSearch(
                    # Optional: Domains to exclude from results
                    exclude_domains=["domain.com", "domain2.com"]
                )
            )
        ],
    ),
)

print(response.text)
# Example response:
# 'The next total solar eclipse in the United States will occur on ...'

Go

Saiba como instalar ou atualizar o Go.

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK da IA generativa com a Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithGoogleSearch shows how to generate text using Google Search.
func generateWithGoogleSearch(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	modelName := "gemini-2.5-flash"
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: "When is the next total solar eclipse in the United States?"},
		},
			Role: genai.RoleUser},
	}
	config := &genai.GenerateContentConfig{
		Tools: []*genai.Tool{
			{GoogleSearch: &genai.GoogleSearch{ExcludeDomains: []string{"example.com", "example.org"}}},
		},
	}

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// The next total solar eclipse in the United States will occur on March 30, 2033, but it will only ...

	return nil
}

Java

Saiba como instalar ou atualizar o Java.

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK da IA generativa com a Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 


import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.GoogleSearch;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.Tool;

public class ToolsGoogleSearchWithText {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-2.5-flash";
    generateContent(modelId);
  }

  // Generates content with Google Search tool
  public static String generateContent(String modelId) {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      // Create a GenerateContentConfig and set Google Search tool
      GenerateContentConfig contentConfig =
          GenerateContentConfig.builder()
              .tools(Tool.builder().googleSearch(GoogleSearch.builder().build()).build())
              .build();

      GenerateContentResponse response =
          client.models.generateContent(
              modelId, "When is the next total solar eclipse in the United States?", contentConfig);

      System.out.print(response.text());
      // Example response:
      // The next total solar eclipse in the United States will occur on...
      return response.text();
    }
  }
}

Node.js

Instalar

npm install @google/genai

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK da IA generativa com a Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateGoogleSearch(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: 'When is the next total solar eclipse in the United States?',
    config: {
      tools: [
        {
          googleSearch: {},
        },
      ],
    },
  });

  console.log(response.text);

  // Example response:
  //    'The next total solar eclipse in United States will occur on ...'

  return response.text;
}

Resposta em base em dados particulares usando a Vertex AI para Pesquisa

Baseie a resposta com dados de um repositório de dados da Vertex AI para Pesquisa. Para mais informações, consulte Vertex AI para Pesquisa.

Antes de fundamentar uma resposta com dados particulares, crie um repositório de dados e um app de pesquisa.

AVISO: no momento, essa interface de "embasamento" não oferece suporte ao "modo de bloco" da Vertex AI para Pesquisa.

SDK da IA generativa para Python

from google import genai
from google.genai.types import (
    GenerateContentConfig,
    HttpOptions,
    Retrieval,
    Tool,
    VertexAISearch,
)

client = genai.Client(http_options=HttpOptions(api_version="v1"))

# Load Data Store ID from Vertex AI Search
# datastore = "projects/111111111111/locations/global/collections/default_collection/dataStores/data-store-id"

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="How do I make an appointment to renew my driver's license?",
    config=GenerateContentConfig(
        tools=[
            # Use Vertex AI Search Tool
            Tool(
                retrieval=Retrieval(
                    vertex_ai_search=VertexAISearch(
                        datastore=datastore,
                    )
                )
            )
        ],
    ),
)

print(response.text)
# Example response:
# 'The process for making an appointment to renew your driver's license varies depending on your location. To provide you with the most accurate instructions...'

A seguir

Para consultar a documentação detalhada, acesse: