Grounding

In generative AI, grounding is the ability to connect model output to verifiable sources of information. If you provide models with access to specific data sources, grounding tethers their output to this data and reduces the chances of inventing content.

This document shows you how to ground model outputs by using either public or private data and covers the following topics:

Choose a grounding method

Vertex AI offers two methods for grounding model responses. The following table helps you choose the best option for your use case.

Method Description Data Source Use Case
Google Search Grounds the model with publicly available web data. Public web When you need the model to answer questions about current events or general knowledge that can be found on the internet.
Vertex AI Search (Preview) Grounds the model with your own data from a Vertex AI Search data store. Private data When you need the model to answer questions based on your own documents, such as internal knowledge bases or proprietary information.

For more information about grounding, see Grounding overview.

Supported models

Grounding parameters

When you make a request, you specify the tools the model can use for grounding. For implementation details, see Examples.

  • To ground with public data, include the GoogleSearchRetrieval tool in your request.

    • google_search_retrieval: An empty object ({}) that tells the model to use Google Search to ground the response.

  • To ground with private data, include the Retrieval tool in your request. This tool defines how the model accesses external knowledge from a Vertex AI Search data store.

    • retrieval: Contains the VertexAISearch object as its source.
      • vertex_ai_search: Specifies the data store to use for grounding.
        • datastore: The fully-qualified Vertex AI Search data store resource ID. Specify the ID in the following format: projects/{project}/locations/{location}/collections/default_collection/dataStores/{datastore}.

Examples

Ground response on public web data using Google Search

To ground the response with Google Search public data, include the google_search_retrieval tool in the request. No additional parameters are required.

Python

Install

pip install --upgrade google-genai

To learn more, see the SDK reference documentation.

Set environment variables to use the Gen AI SDK with 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

Learn how to install or update the Go.

To learn more, see the SDK reference documentation.

Set environment variables to use the Gen AI SDK with 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
}

Ground response on private data using Vertex AI Search

You can ground the response with data from a Vertex AI Search data store. For more information, see AI Applications.

Before you ground a response with private data, you must create a data store and a search app.

Gen AI SDK for 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...'

What's next

For detailed documentation, see the following: