feat (provider/google): Add support for search grounding. (#4067)

Author: shaper

.changeset/wicked-suns-sing.md

@@ -0,0 +1,6 @@
+---
+'@ai-sdk/google-vertex': patch
+'@ai-sdk/google': patch
+---
+
+feat (provider/google): Add support for search grounding.

content/providers/01-ai-sdk-providers/10-google-generative-ai.mdx

@@ -226,6 +226,127 @@ const { text: meatLasangaRecipe } = await generateText({
 });
 ```
 
+### Search Grounding
+
+With [search grounding](https://ai.google.dev/gemini-api/docs/grounding),
+the model has access to the latest information using Google search.
+Search grounding can be used to provide answers around current events:
+
+```ts highlight="7,14-20"
+import { google } from '@ai-sdk/google';
+import { GoogleGenerativeAIProviderMetadata } from '@ai-sdk/google';
+import { generateText } from 'ai';
+
+const { text, experimental_providerMetadata } = await generateText({
+  model: google('gemini-1.5-pro', {
+    useSearchGrounding: true,
+  }),
+  prompt:
+    'List the top 5 San Francisco news from the past week.' +
+    'You must include the date of each article.',
+});
+
+// access the grounding metadata. Casting to the provider metadata type
+// is optional but provides autocomplete and type safety.
+const metadata = experimental_providerMetadata?.google as
+  | GoogleGenerativeAIProviderMetadata
+  | undefined;
+const groundingMetadata = metadata?.groundingMetadata;
+const safetyRatings = metadata?.safetyRatings;
+```
+
+The grounding metadata includes detailed information about how search results were used to ground the model's response. Here are the available fields:
+
+- **`webSearchQueries`** (`string[] | null`)
+
+  - Array of search queries used to retrieve information
+  - Example: `["What's the weather in Chicago this weekend?"]`
+
+- **`searchEntryPoint`** (`{ renderedContent: string } | null`)
+
+  - Contains the main search result content used as an entry point
+  - The `renderedContent` field contains the formatted content
+
+- **`groundingSupports`** (Array of support objects | null)
+  - Contains details about how specific response parts are supported by search results
+  - Each support object includes:
+    - **`segment`**: Information about the grounded text segment
+      - `text`: The actual text segment
+      - `startIndex`: Starting position in the response
+      - `endIndex`: Ending position in the response
+    - **`groundingChunkIndices`**: References to supporting search result chunks
+    - **`confidenceScores`**: Confidence scores (0-1) for each supporting chunk
+
+Example response:
+
+```json
+{
+  "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]
+      }
+    ]
+  }
+}
+```
+
+The safety ratings provide insight into how the model's response was grounded to search results. See [Google AI documentation on safety settings](https://ai.google.dev/gemini-api/docs/safety-settings).
+
+Example response excerpt:
+
+```json
+{
+  "safetyRatings": [
+    {
+      "category": "HARM_CATEGORY_HATE_SPEECH",
+      "probability": "NEGLIGIBLE",
+      "probabilityScore": 0.11027937,
+      "severity": "HARM_SEVERITY_LOW",
+      "severityScore": 0.28487435
+    },
+    {
+      "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
+      "probability": "HIGH",
+      "blocked": true,
+      "probabilityScore": 0.95422274,
+      "severity": "HARM_SEVERITY_MEDIUM",
+      "severityScore": 0.43398145
+    },
+    {
+      "category": "HARM_CATEGORY_HARASSMENT",
+      "probability": "NEGLIGIBLE",
+      "probabilityScore": 0.11085559,
+      "severity": "HARM_SEVERITY_NEGLIGIBLE",
+      "severityScore": 0.19027223
+    },
+    {
+      "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
+      "probability": "NEGLIGIBLE",
+      "probabilityScore": 0.22901751,
+      "severity": "HARM_SEVERITY_NEGLIGIBLE",
+      "severityScore": 0.09089675
+    }
+  ]
+}
+```
+
+<Note>
+  The Google Generative AI provider does not yet support [dynamic retrieval mode
+  and
+  threshold](https://ai.google.dev/gemini-api/docs/grounding?lang=rest#dynamic-retrieval).
+</Note>
+
 ### Troubleshooting
 
 #### Schema Limitations

content/providers/01-ai-sdk-providers/11-google-vertex.mdx

@@ -402,7 +402,7 @@ Example response excerpt:
 ```json
 {
   "groundingMetadata": {
-    "webSearchQueries": ["What's the weather in Chicago this weekend?"],
+    "retrievalQueries": ["What's the weather in Chicago this weekend?"],
     "searchEntryPoint": {
       "renderedContent": "..."
     },
@@ -461,6 +461,11 @@ Example response excerpt:
 }
 ```
 
+<Note>
+  The Google Vertex provider does not yet support [dynamic retrieval mode and
+  threshold](https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/ground-gemini#dynamic-retrieval).
+</Note>
+
 For more details, see the [Google Vertex AI documentation on grounding with Google Search](https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/ground-gemini#ground-to-search).
 
 ### Troubleshooting

examples/ai-core/src/e2e/google.test.ts

@@ -1,6 +1,9 @@
 import 'dotenv/config';
 import { describe, it, expect, vi } from 'vitest';
-import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import {
+  createGoogleGenerativeAI,
+  GoogleGenerativeAIProviderMetadata,
+} from '@ai-sdk/google';
 import { z } from 'zod';
 import {
   generateText,
@@ -67,6 +70,44 @@ describe('Google E2E Tests', () => {
       expect(result.usage?.totalTokens).toBeGreaterThan(0);
     });
 
+    it('should generate text with search grounding metadata in response when search grounding is enabled', async () => {
+      const model = provider(modelId, {
+        useSearchGrounding: true,
+      });
+
+      const result = await generateText({
+        model,
+        prompt: 'What is the current population of Tokyo?',
+      });
+
+      expect(result.text).toBeTruthy();
+      expect(result.text.toLowerCase()).toContain('tokyo');
+      expect(result.usage?.totalTokens).toBeGreaterThan(0);
+
+      // Verify specific grounding metadata fields
+      const metadata = result.experimental_providerMetadata?.google as
+        | GoogleGenerativeAIProviderMetadata
+        | undefined;
+      const groundingMetadata = metadata?.groundingMetadata;
+      expect(Array.isArray(groundingMetadata?.webSearchQueries)).toBe(true);
+      expect(groundingMetadata?.webSearchQueries?.length).toBeGreaterThan(0);
+
+      // Verify search entry point exists
+      expect(
+        groundingMetadata?.searchEntryPoint?.renderedContent,
+      ).toBeDefined();
+
+      // Verify grounding supports
+      expect(Array.isArray(groundingMetadata?.groundingSupports)).toBe(true);
+      const support = groundingMetadata?.groundingSupports?.[0];
+      expect(support?.segment).toBeDefined();
+      expect(Array.isArray(support?.groundingChunkIndices)).toBe(true);
+      expect(Array.isArray(support?.confidenceScores)).toBe(true);
+
+      // Basic response checks
+      expect(result.text).toBeTruthy();
+      expect(result.usage?.totalTokens).toBeGreaterThan(0);
+    });
     it('should generate text with PDF input', async () => {
       const model = provider(modelId);
       const result = await generateText({
@@ -166,6 +207,53 @@ describe('Google E2E Tests', () => {
       expect((await result.usage)?.totalTokens).toBeGreaterThan(0);
     });
 
+    it('should stream text with search grounding metadata when search grounding is enabled', async () => {
+      const model = provider(modelId, {
+        useSearchGrounding: true,
+      });
+
+      const result = streamText({
+        model,
+        prompt: 'What is the current population of Tokyo?',
+      });
+
+      const chunks: string[] = [];
+      for await (const chunk of result.textStream) {
+        chunks.push(chunk);
+      }
+
+      // Get the complete response metadata
+      const metadata = (await result.experimental_providerMetadata)?.google as
+        | GoogleGenerativeAIProviderMetadata
+        | undefined;
+      const groundingMetadata = metadata?.groundingMetadata;
+
+      const completeText = chunks.join('');
+      expect(completeText).toBeTruthy();
+      expect(completeText.toLowerCase()).toContain('tokyo');
+      expect((await result.usage)?.totalTokens).toBeGreaterThan(0);
+
+      // Verify specific grounding metadata fields
+      expect(Array.isArray(groundingMetadata?.webSearchQueries)).toBe(true);
+      expect(groundingMetadata?.webSearchQueries?.length).toBeGreaterThan(0);
+
+      // Verify search entry point exists
+      expect(
+        groundingMetadata?.searchEntryPoint?.renderedContent,
+      ).toBeDefined();
+
+      // Verify grounding supports
+      expect(Array.isArray(groundingMetadata?.groundingSupports)).toBe(true);
+      const support = groundingMetadata?.groundingSupports?.[0];
+      expect(support?.segment).toBeDefined();
+      expect(Array.isArray(support?.groundingChunkIndices)).toBe(true);
+      expect(Array.isArray(support?.confidenceScores)).toBe(true);
+
+      // Basic response checks
+      expect(chunks.join('')).toBeTruthy();
+      expect((await result.usage)?.totalTokens).toBeGreaterThan(0);
+    });
+
     it('should stream object', async () => {
       const model = provider(modelId);
       const result = streamObject({