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:

  • Terreno 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.
  • Ter fundamento nos 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 usada com a interface do usuário do widget de contexto do Google Maps.

A estrutura da 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 dos usuários. A resposta do lugar é baseada em uma lista de fontes, como avaliações de usuários.

Atributos

Um lugar ou uma fonte de avaliações de usuários 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 embasar uma resposta em dados públicos da Web usando a Pesquisa Google e 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 de 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())
        ],
    ),
)

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 de 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: "user"},
	}
	config := &genai.GenerateContentConfig{
		Tools: []*genai.Tool{
			{GoogleSearch: &genai.GoogleSearch{}},
		},
	}

	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
}

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

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

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

AVISO: por enquanto, essa interface de "fundamentação" não é compatível com o "modo de fragmentação" 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: