Grounding API

ב-AI גנרטיבי, 'הארקה' היא היכולת לקשר בין פלט של מודל לבין מקורות מידע שאפשר לאמת. אם מספקים למודלים גישה למקורות נתונים ספציפיים, ההארקה מקשרת את הפלט שלהם לנתונים האלה ומפחיתה את הסיכויים להמצאת תוכן.

בעזרת Vertex AI, אפשר להצמיד את הפלט של המודל לקרקע בדרכים הבאות:

• הארקה באמצעות חיפוש Google – הארקה של מודל באמצעות נתונים שזמינים לציבור באינטרנט.
• עיגון בעזרת מפות Google – עיגון מודל בעזרת נתונים גיאו-מרחביים ממפות Google.
• הצמדת המודל לנתונים – הצמדת מודל לנתונים מחיפוש מבוסס-Vertex AI בתור מאגר נתונים.

מידע נוסף על הארקה זמין במאמר סקירה כללית על הארקה.

מודלים נתמכים

רשימת פרמטרים

פרטים על ההטמעה מופיעים בדוגמאות.

googleSearch

תבסס את התשובה על נתונים שזמינים לציבור באינטרנט מחיפוש Google.

googleMaps

תבסס את התשובה על נתונים גיאו-מרחביים שגלויים לכולם ממפות Google.

קלט ה-API כולל את הפרמטר הבא:

פרמטר קלט
enable_widget	חובה: boolean דגל שאפשר להגדיר לערך true או false. הערך true מחזיר טוקן באמצעות תגובה מה-API שאפשר להשתמש בה עם ממשק המשתמש של הווידג'ט של הקשר ב-מפות Google.

מבנה התגובה של ה-API כולל את הפרמטר הבא:

פרמטר של תגובה
grounding_metadata	חובה: Object השדה הראשי שמכיל מידע על ההארקה.	‫grounding_support: שדה משנה שמציין את רמת התמיכה בהצגת מידע מבוסס. ‫grounding_chunks.maps: שדה משנה שמכיל את המקורות של המקומות ששימשו ליצירת התשובה המבוססת על מידע. ‫place_answer_sources.review_snippets: שדה משנה בתוך grounding_chunks.maps שמופיע כשמשתמשים בתשובה לגבי מקום כדי לענות על שאילתה. תשובות לגבי מקומות מספקות מידע הקשרי מעמיק על מקום ספציפי באמצעות נתונים כמו ביקורות משתמשים. התשובה לגבי המקום מבוססת על רשימת מקורות כמו ביקורות משתמשים.

מאפיינים

למקור של ביקורת על מקום או על משתמש יש את המאפיינים הבאים:

מאפיינים
title	חובה: Object הכותרת של המקור.
uri	חובה: string ‫URI שמקשר למקור.
place_id	חובה: string מזהה ייחודי של המקום.
review_id	חובה: string מזהה ייחודי של הביקורת.

retrieval

עיגון התשובה באמצעות נתונים פרטיים מחיפוש מבוסס-Vertex AI כמאגר נתונים. הגדרה של כלי לאחזור מידע שהמודל יכול להשתמש בו כדי לגשת לידע חיצוני.

פרמטרים
vertexAiSearch	חובה: VertexAISearch הארקה עם מקורות נתונים של חיפוש מבוסס-Vertex AI.

VertexAISearch

פרמטרים
datastore	חובה: string מזהה משאב מאגר נתונים מלא מחיפוש מבוסס-Vertex AI, בפורמט הבא: projects/{project}/locations/{location}/collections/default_collection/dataStores/{datastore}

דוגמאות

בקטע הזה מופיעות דוגמאות לעיגון תשובה על סמך נתונים ציבוריים באינטרנט באמצעות חיפוש Google, ועיגון תשובה על סמך נתונים פרטיים באמצעות חיפוש מבוסס-Vertex AI.

התבססות על נתונים ציבוריים באינטרנט באמצעות חיפוש Google

התשובה מבוססת על נתונים ציבוריים מחיפוש Google. כוללים את הכלי google_search_retrieval בבקשה. לא נדרשים פרמטרים נוספים.

Python

התקנה

pip install --upgrade google-genai

מידע נוסף מופיע ב מאמרי העזרה בנושא SDK.

מגדירים משתני סביבה כדי להשתמש ב-Gen AI SDK עם 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

כך מתקינים או מעדכנים את Go.

מידע נוסף מופיע ב מאמרי העזרה בנושא SDK.

מגדירים משתני סביבה כדי להשתמש ב-Gen AI SDK עם 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

כך מתקינים או מעדכנים את Java.

מידע נוסף מופיע ב מאמרי העזרה בנושא SDK.

מגדירים משתני סביבה כדי להשתמש ב-Gen AI SDK עם 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

התקנה

npm install @google/genai

מידע נוסף מופיע ב מאמרי העזרה בנושא SDK.

מגדירים משתני סביבה כדי להשתמש ב-Gen AI SDK עם 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;
}

התבססות על נתונים פרטיים באמצעות חיפוש מבוסס-Vertex AI

התשובה מבוססת על נתונים ממאגר נתונים של חיפוש מבוסס-Vertex AI. מידע נוסף זמין במאמר בנושא חיפוש מבוסס-Vertex AI.

לפני שמעגנים תשובה לנתונים פרטיים, צריך ליצור מאגר נתונים ואפליקציית חיפוש.

אזהרה: בשלב הזה, ממשק ה-grounding הזה לא תומך ב'מצב חלוקה לקטעים' של חיפוש מבוסס-Vertex AI.

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

המאמרים הבאים

לעיון בתיעוד מפורט:

• הארקה
• ‫Gemini API