API de fundamentación

En la IA generativa, los fundamentos son la capacidad de conectar el resultado del modelo con fuentes de información verificables. Si proporcionas modelos con acceso a fuentes de datos específicas, los fundamentos conectan su resultado a estos datos y reducen las posibilidades de inventar contenido.

Con Vertex AI, puedes fundamentar los resultados del modelo de las siguientes maneras:

  • Fundamenta con la Búsqueda de Google: Fundamenta un modelo con datos web disponibles públicamente.
  • Fundamenta con Google Maps: Fundamenta un modelo con datos geoespaciales de Google Maps.
  • Fundamenta con tus datos: Fundamenta un modelo con tus datos de Agent Search como almacén de datos.

Para obtener más información sobre la fundamentación, consulta Descripción general de los fundamentos.

Modelos compatibles

Lista de parámetros

Consulta ejemplos para obtener detalles sobre la implementación.

googleSearch

Fundamenta la respuesta con datos web disponibles públicamente de la Búsqueda de Google.

googleMaps

Fundamenta la respuesta con datos geoespaciales disponibles públicamente de Google Maps.

La entrada de la API incluye el siguiente parámetro:

Parámetro de entrada

enable_widget

Obligatorio: boolean

Es una marca que se puede establecer en true o false. Un valor de true muestra un token con la respuesta de la API que puedes usar con la interfaz de usuario del widget de contexto de Google Maps.

La estructura de respuesta de la API incluye el siguiente parámetro:

Parámetro de respuesta

grounding_metadata

Obligatorio: Object

Es el campo principal que contiene información de fundamentación.
  • grounding_support: Es un subcampo que indica el nivel de compatibilidad con la fundamentación.
  • grounding_chunks.maps: Es un subcampo que contiene las fuentes de lugares que se usan para generar la respuesta fundamentada.
    • place_answer_sources.review_snippets: Es un subcampo dentro de grounding_chunks.maps que aparece cuando se usa una respuesta de lugar para responder una consulta. Las respuestas de lugar proporcionan información contextual más detallada sobre un lugar específico con datos, como las opiniones de los usuarios. La respuesta de lugar se basa en una lista de fuentes, como las opiniones de los usuarios.

Atributos

Una fuente de opinión de lugar o de usuario tiene los siguientes atributos:

Atributos

title

Obligatorio: Object

Es el título de la fuente.

uri

Obligatorio: string

Es un URI que vincula a la fuente.

place_id

Obligatorio: string

Es un identificador único del lugar.

review_id

Obligatorio: string

Es un identificador único de la opinión.

retrieval

Fundamenta la respuesta con datos privados de Agent Search como almacén de datos. Define una herramienta de recuperación que el modelo puede llamar para acceder a conocimientos externos.

Parámetros

vertexAiSearch

Obligatorio: VertexAISearch

Fundamenta con fuentes de datos de Agent Search.

VertexAISearch

Parámetros

datastore

Obligatorio: string

Es el ID del recurso del almacén de datos completamente calificado de Agent Search, en el siguiente formato: projects/{project}/locations/{location}/collections/default_collection/dataStores/{datastore}

Ejemplos

En esta sección, se proporcionan ejemplos para fundamentar una respuesta sobre datos web públicos con la Búsqueda de Google y fundamentar una respuesta sobre datos privados con Agent Search.

Fundamenta la respuesta sobre datos web públicos con la Búsqueda de Google

Fundamenta la respuesta con datos públicos de la Búsqueda de Google. Incluye la herramienta google_search_retrieval en la solicitud. No se requieren parámetros adicionales.

Python

Instalar

pip install --upgrade google-genai

Para obtener más información, consulta la documentación de referencia del SDK.

Configura las variables de entorno para usar el SDK de IA generativa con 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

Obtén información para instalar o actualizar Go.

Para obtener más información, consulta la documentación de referencia del SDK.

Configura las variables de entorno para usar el SDK de IA generativa con 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

Obtén información para instalar o actualizar Java.

Para obtener más información, consulta la documentación de referencia del SDK.

Configura las variables de entorno para usar el SDK de IA generativa con 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 obtener más información, consulta la documentación de referencia del SDK.

Configura las variables de entorno para usar el SDK de IA generativa con 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;
}

Fundamenta la respuesta sobre datos privados con Agent Search

Fundamenta la respuesta con datos de un almacén de datos de Agent Search. Para obtener más información, consulta Agent Search.

Antes de fundamentar una respuesta con datos privados, crea un almacén de datos y una app de búsqueda.

ADVERTENCIA: Por el momento, esta interfaz de "fundamentación" no admite el "modo de fragmentos" de Agent Search.

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

¿Qué sigue?

Para obtener documentación detallada, consulta lo siguiente: