API Grounding

Na IA generativa, a fundamentação é a capacidade de associar o resultado do modelo a fontes de informações verificáveis. Se fornecer aos modelos acesso a origens de dados específicas, a fundamentação restringe a respetiva saída a estes dados e reduz as probabilidades de inventar conteúdo.

Com o Vertex AI, pode fundamentar os resultados do modelo das seguintes formas:

  • Fundamentar com a Pesquisa Google: fundamentar um modelo com dados da Web disponíveis publicamente.
  • Fundamente com o Google Maps: fundamente um modelo com dados geoespaciais do Google Maps.
  • Fundamente o modelo com os seus dados do Vertex AI Search como um repositório de dados.

Para mais informações sobre a fundamentação, consulte o artigo Vista geral da fundamentação.

Modelos suportados

Lista de parâmetros

Consulte exemplos para ver detalhes de implementação.

googleSearch

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

googleMaps

Fundamentar 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

Sinalizador que pode ser definido como true ou false. Um valor de true devolve um token através da resposta da API que pode usar com a interface do utilizador 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 fundamentação.
  • grounding_support: um subcampo que indica o nível de apoio técnico de base.
  • grounding_chunks.maps: um subcampo que contém as fontes de locais usadas para gerar a resposta fundamentada.
    • place_answer_sources.review_snippets: um subcampo em grounding_chunks.maps que aparece quando uma resposta de local é usada para responder a uma consulta. As respostas de locais fornecem informações contextuais mais detalhadas sobre um local específico através de dados, como críticas de utilizadores. A resposta sobre o local é apoiada por uma lista de fontes, como críticas de utilizadores.

Atributos

Uma origem de críticas de um local ou de um utilizador tem os seguintes atributos:

Atributos

title

Obrigatório: Object

O título da fonte.

uri

Obrigatório: string

Um URI com um link para a origem.

place_id

Obrigatório: string

Um identificador exclusivo do local.

review_id

Obrigatório: string

Um identificador exclusivo da crítica.

retrieval

Fundamente a resposta com dados privados da Vertex AI Search como um repositório de dados. Define uma ferramenta de obtenção que o modelo pode chamar para aceder a conhecimentos externos.

Parâmetros

vertexAiSearch

Obrigatório: VertexAISearch

Fundamente com origens de dados do Vertex AI Search.

VertexAISearch

Parâmetros

datastore

Obrigatório: string

ID do recurso do armazém de dados totalmente qualificado do Vertex AI Search, no seguinte formato: projects/{project}/locations/{location}/collections/default_collection/dataStores/{datastore}

Exemplos

Esta secção fornece exemplos de fundamentação de uma resposta em dados da Web públicos através da Pesquisa Google e de fundamentação de uma resposta em dados privados através da Vertex AI Search.

Fundamente a resposta em dados da Web pública através da Pesquisa Google

Fundamentar a resposta com dados públicos da Pesquisa Google. Inclua a ferramenta google_search_retrieval no pedido. Não são necessários parâmetros adicionais.

Python

Instalação

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

Fundamente as respostas em dados privados através da Vertex AI Search

Fundamentar a resposta com dados de um repositório de dados do Vertex AI Search. Para mais informações, consulte o artigo Aplicações de IA.

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

AVISO: por agora, esta interface de "fundamentação" não suporta o "modo de fragmentos" do Vertex AI Search.

SDK de IA gen 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...'

O que se segue?

Para ver documentação detalhada, consulte o seguinte: