Grounding with Vertex AI Search

This guide shows you how to ground Gemini model responses to your own data by using Vertex AI Search. When you ground a model, you connect it to your own data sources, such as website content or documents. This technique, also known as retrieval-augmented generation (RAG), helps the model provide more accurate and relevant responses by reducing hallucinations.

This guide covers the following topics:

• Prerequisites: Set up your environment by enabling APIs and configuring permissions.
• Create a data store: Learn how to create a data store from either website content or documents.
• Generate grounded responses: Use the API or Vertex AI Studio to get model responses grounded to your data.
• Understand your response: Interpret the output, including grounding metadata and confidence scores.

You can ground a model with up to 10 Vertex AI Search data sources. This can also be combined with Grounding with Google Search.

The following diagram summarizes the overall workflow:

Supported models

This section lists the models that support grounding with your data.

• Gemini 2.5 Flash-Lite
• Gemini 2.5 Flash with Live API native audio
  previewPreview
• Gemini 2.0 Flash with Live API
  previewPreview
• Gemini 2.5 Pro
• Gemini 2.5 Flash
• Gemini 2.0 Flash

Prerequisites

Before you ground model responses with your data, complete the following setup steps:

1. Configure permissions: In the Google Cloud console, go to the IAM page and make sure that your project has the discoveryengine.servingConfigs.search permission. This permission is required for the grounding service to work.

   Go to IAM

2. Enable the API: Enable AI Applications and activate the API.

3. Create a data store: Create a AI Applications data store to hold your grounding data.

For more information, see the Introduction to Vertex AI Search.

Enable AI Applications

1. In the Google Cloud console, go to the AI Applications page.

   AI Applications

2. Read and agree to the terms of service, then click Continue and activate the API.

AI Applications is available in the global location, or the eu and us multi-region. To learn more, see AI Applications locations.

Create a data store

To create a data store in AI Applications, you can use either website data or documents from Cloud Storage.

Generate grounded responses with your data store

You can ground a model with your data by using up to 10 data stores. The following instructions show you how to generate a grounded response.

If you don't know your data store ID, follow these steps:

1. In the Google Cloud console, go to the AI Applications page and in the navigation menu, click Data stores.

   Go to the Data stores page

2. Click the name of your data store.

3. On the Data page for your data store, get the data store ID.

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

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent

{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "TEXT"
    }]
  }],
  "tools": [{
    "retrieval": {
      "vertexAiSearch": {
        "datastore": projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID
      }
    }
  }],
  "model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "You can make an appointment on the website https://dmv.gov/"
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        "..."
      ],
      "groundingMetadata": {
        "retrievalQueries": [
          "How to make appointment to renew driving license?"
        ],
        "groundingChunks": [
          {
            "retrievedContext": {
              "uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AXiHM.....QTN92V5ePQ==",
              "title": "dmv"
            }
          }
        ],
        "groundingSupport": [
          {
            "segment": {
              "startIndex": 25,
              "endIndex": 147
            },
            "segment_text": "ipsum lorem ...",
            "supportChunkIndices": [1, 2],
            "confidenceScore": [0.9541752, 0.97726375]
          },
          {
            "segment": {
              "startIndex": 294,
              "endIndex": 439
            },
            "segment_text": "ipsum lorem ...",
            "supportChunkIndices": [1],
            "confidenceScore": [0.9541752, 0.9325467]
          }
        ]
      }
    }
  ],
  "usageMetadata": {
    "..."
  }
}

Understand your response

The API response includes the LLM-generated text and, if grounding is successful, grounding metadata. Grounding metadata identifies which parts of the response were derived from your data source.

Grounding metadata might not be provided if the source has low relevance or if the information in the model's response is incomplete.

The response contains the following fields:

• Role: Indicates the sender of the answer. For a grounded response, the role is always model.
• Text: The grounded answer generated by the LLM.
• Grounding metadata: Contains information about the grounding source. This object includes the following:
  • Grounding chunks: A list of results from your data store that support the answer.
  • Grounding supports: Information about a specific claim within the answer that can be used for citations. This includes:
    • Segment: The part of the model's answer that is substantiated by a grounding chunk.
    • Grounding chunk index: The index of the grounding chunk in the grounding_chunks list that corresponds to this claim.
    • Confidence scores: A value from 0 to 1 that indicates how grounded the claim is in the provided grounding chunks. This is not available for Gemini 2.5 and later.

What's next

• To learn how to send chat prompt requests, see Multiturn chat.
• To learn about responsible AI best practices and Vertex AI's safety filters, see Safety best practices.