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, then grounding tethers their output to these data and reduces the chances of inventing content.
With Vertex AI, you can ground model outputs in the following ways:
- Ground with Google Search - ground a model with publicly available web data.
- Ground to your own data - ground a model with your own data from Vertex AI Search as a data store (Preview).
For more information about grounding, see Grounding overview.
Supported models
Model | Version |
---|---|
Gemini 1.5 Pro with only text input | gemini-1.5-pro-002 gemini-1.5-pro-001 |
Gemini 1.5 Flash with only text input | gemini-1.5-flash-002 gemini-1.5-flash-001 |
Gemini 1.0 Pro with only text input | gemini-1.0-pro-001 gemini-1.0-pro-002 |
Limitations
Grounding is available only for text requests.
Example syntax
This example shows the syntax for how to ground a model and to specify the supported language. For language support, see Languages.
Specify values for the following variables:
- PROMPT_TEXT: Your text request that you submit to a language model to receive a response back.
- SYSTEM_INSTRUCTION: A set of instructions that tells the model how to behave and respond to prompts.
- FACT_TEXT_1: Verified information used by the model to generate a response.
- TITLE_1: The name of your verified source of information.
- URI_1: A string that uniquely identifies a location of your verified source of information.
- AUTHOR_1: The provider of the verified information used by the model to generate a response.
- FACT_TEXT_2: Verified information used by the model to generate a response.
- TITLE_2: The name of your verified source of information.
- URI_2: A string that uniquely identifies a location of your verified source of information.
- FACT_TEXT_3: Verified information used by the model to generate a response.
- TITLE_3: The name of your verified source of information.
- URI_3: A string that uniquely identifies a location of your verified source of information.
- PROJECT_NUMBER: Uniquely identifies your Google Cloud project, which contains your resources.
- APP_ID_1: An application that interacts with the model.
- APP_ID_2: An application that interacts with the model.
- MODEL_ID: Identifies the model that your application interacts with.
- LANGUAGE_CODE: Identifies the language used in generating a grounded response.
curl
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global:generateGroundedContent" \ -d ' { "contents": [ { "role": "user", "parts": [ { "text": "PROMPT_TEXT" } ] } ], "systemInstruction": { "parts": { "text": "SYSTEM_INSTRUCTION" } }, "groundingSpec": { "groundingSources": [ { "inlineSource": { "groundingFacts": [ { "factText": "FACT_TEXT_1", "attributes": { "title": "TITLE_1", "uri": "URI_1", "author": "AUTHOR_1" } } ] } }, { "inlineSource": { "groundingFacts": [ { "factText": "FACT_TEXT_2", "attributes": { "title": "TITLE_2", "uri": "URI_2" } }, { "factText": "FACT_TEXT_3", "attributes": { "title": "TITLE_3", "uri": "URI_3" } } ] } }, { "searchSource": { "servingConfig": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID_1/servingConfigs/default_search" } }, { "searchSource": { "servingConfig": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID_2/servingConfigs/default_search" } } ] }, "generationSpec": { "modelId": "MODEL_ID", "temperature": TEMPERATURE, "topP": TOP_P, "topK": TOP_K, }, "user_context": { "languageCode: "LANGUAGE_CODE" "latLng": { "latitude": 46.7, "longitude": 8.9 }, }'
Parameter list
See examples for implementation details.
GoogleSearchRetrieval
Ground the response with public data.
Parameters | |
---|---|
|
Required: Ground with publicly available web data. |
Retrieval
Ground the response with private data from Vertex AI Search as a data store. Defines a retrieval tool that the model can call to access external knowledge.
Parameters | |
---|---|
|
Required: Ground with Vertex AI Search data sources. |
VertexAISearch
Parameters | |
---|---|
|
Required: Fully-qualified data store resource ID from Vertex AI Search, in the
following format: |
Examples
Ground response on public web data using Google Search
Ground the response with Google Search public data. Include the google_search_retrieval
tool in the request. No additional parameters are required.
REST
Before using any of the request data, make the following replacements:
- LOCATION: The region to process the request.
- PROJECT_ID: Your project ID.
- MODEL_ID: The model ID of the multimodal model.
- TEXT: The text instructions to include in the prompt.
- DYNAMIC_THRESHOLD: An optional field to set the threshold
to invoke the dynamic retrieval configuration. It is a floating point
value in the range [0,1]. If you don't set the
dynamicThreshold
field, the threshold value defaults to 0.7.
HTTP method and URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent
Request JSON body:
{ "contents": [{ "role": "user", "parts": [{ "text": "TEXT" }] }], "tools": [{ "googleSearchRetrieval": { "dynamicRetrievalConfig": { "mode": "MODE_DYNAMIC", "dynamicThreshold": DYNAMIC_THRESHOLD } } }], "model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID" }
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "candidates": [ { "content": { "role": "model", "parts": [ { "text": "Chicago weather changes rapidly, so layers let you adjust easily. Consider a base layer, a warm mid-layer (sweater-fleece), and a weatherproof outer layer." } ] }, "finishReason": "STOP", "safetyRatings":[ "..." ], "groundingMetadata": { "webSearchQueries": [ "What's the weather in Chicago this weekend?" ], "searchEntryPoint": { "renderedContent": "....................." } "groundingSupports": [ { "segment": { "startIndex": 0, "endIndex": 65, "text": "Chicago weather changes rapidly, so layers let you adjust easily." }, "groundingChunkIndices": [ 0 ], "confidenceScores": [ 0.99 ] }, ] "retrievalMetadata": { "webDynamicRetrievalScore": 0.96879 } } } ], "usageMetadata": { "..." } }
Python
NodeJS
Java
Ground response on private data using Vertex AI Search
Ground the response with data from a Vertex AI Search data store. For more information, see Vertex AI Agent Builder.
Before you ground a response with private data, create a data store and a search app.
WARNING: For the time being, this "grounding" interface does not support Vertex AI Search "chunk mode".
REST
Before using any of the request data, make the following replacements:
- LOCATION: The region to process the request.
- PROJECT_ID: Your project ID.
- MODEL_ID: The model ID of the multimodal model.
- TEXT: The text instructions to include in the prompt.
HTTP method and URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent
Request JSON body:
{ "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" }
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "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": { "..." } }
Python
NodeJS
Java
What's next
For detailed documentation, see the following: