Grounding API

Bei der generativen KI ist Fundierung die Fähigkeit, die Modellausgabe mit überprüfbaren Informationsquellen zu verbinden. Wenn Sie den Modellen Zugang zu bestimmten Datenquellen gewähren, dann bindet die Fundierung ihre Ausgabe an diese Daten und verringert die Wahrscheinlichkeit, dass Inhalte erfunden werden.

Mit Vertex AI können Sie Modellausgaben so fundieren:

• Mit der Google Suche fundieren – Ein Modell mit öffentlich verfügbaren Webdaten fundieren.
• Mit Google Maps fundieren – Ein Modell mit geografischen Daten aus Google Maps fundieren.
• Mit Ihren Daten fundieren – Ein Modell mit Ihren Daten aus Vertex AI Search als Datenspeicher fundieren.

Weitere Informationen zur Fundierung finden Sie unter Fundierungsübersicht.

Unterstützte Modelle

Parameterliste

Einzelheiten zur Implementierung finden Sie in den Beispielen.

googleSearch

Die Antwort mit öffentlich verfügbaren Webdaten aus der Google Suche fundieren.

googleMaps

Die Antwort mit öffentlich verfügbaren geografischen Daten aus Google Maps fundieren.

Die API-Eingabe enthält den folgenden Parameter:

Eingabeparameter
enable_widget	Pflichtfeld: boolean Flag, das auf true oder false gesetzt werden kann. Bei einem Wert von true wird ein Token mit der API-Antwort zurückgegeben, das Sie mit der Benutzeroberfläche des Google Maps-Kontextwidgets verwenden können.

Die API-Antwortstruktur enthält den folgenden Parameter:

Antwortparameter
grounding_metadata	Pflichtfeld: Object Das primäre Feld, das Fundierungsinformationen enthält.	grounding_support: Ein Unterfeld, das den Grad der Fundierungsunterstützung angibt. grounding_chunks.maps: Ein Unterfeld mit den Ortsquellen, die zum Generieren der fundierten Antwort verwendet wurden. place_answer_sources.review_snippets: Ein Unterfeld in grounding_chunks.maps, das angezeigt wird, wenn eine Ortsantwort zum Beantworten einer Anfrage verwendet wird. Ortsantworten liefern mithilfe von Daten wie Nutzerrezensionen detailliertere Kontextinformationen zu einem bestimmten Ort. Die Ortsantwort wird durch eine Liste von Quellen wie Nutzer Rezensionen unterstützt.

Attribute

Eine Orts- oder Nutzerrezensionsquelle hat die folgenden Attribute:

Attribute
title	Pflichtfeld: Object Der Titel der Quelle.
uri	Pflichtfeld: string Ein URI, der auf die Quelle verweist.
place_id	Pflichtfeld: string Eine eindeutige ID für den Ort.
review_id	Pflichtfeld: string Eine eindeutige ID für die Rezension.

retrieval

Die Antwort mit privaten Daten aus Vertex AI Search als Datenspeicher fundieren. Definiert ein Abruftool, das das Modell aufrufen kann, um auf externes Wissen zuzugreifen.

Parameter
vertexAiSearch	Erforderlich: VertexAISearch Mit Vertex AI Search-Datenquellen fundieren.

VertexAISearch

Parameter
datastore	Erforderlich: string Vollständige Datenspeicher-Ressourcen-ID aus Vertex AI Search im folgenden Format: projects/{project}/locations/{location}/collections/default_collection/dataStores/{datastore}

Beispiele

In diesem Abschnitt finden Sie Beispiele für die Fundierung einer Antwort mit öffentlichen Webdaten über die Google Suche und die Fundierung einer Antwort mit privaten Daten über Vertex AI Search.

Fundierungsantwort zu öffentlichen Webdaten mit der Google Suche

Die Antwort mit öffentlichen Daten aus der Google Suche fundieren. Fügen Sie das Tool google_search_retrieval in die Anfrage ein. Es sind keine zusätzlichen Parameter erforderlich.

Python

Installieren

pip install --upgrade google-genai

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Legen Sie Umgebungsvariablen fest, um das Gen AI SDK mit Vertex AI zu verwenden:

# 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

Informationen zum Installieren oder Aktualisieren von Go

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Legen Sie Umgebungsvariablen fest, um das Gen AI SDK mit Vertex AI zu verwenden:

# 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

Informationen zum Installieren oder Aktualisieren von Java

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Legen Sie Umgebungsvariablen fest, um das Gen AI SDK mit Vertex AI zu verwenden:

# 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

Installieren

npm install @google/genai

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Legen Sie Umgebungsvariablen fest, um das Gen AI SDK mit Vertex AI zu verwenden:

# 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;
}

Fundierungsantwort für private Daten mit Vertex AI Search

Die Antwort mit Daten aus einem Vertex AI Search-Datenspeicher fundieren. Weitere Informationen finden Sie unter Vertex AI Search.

Bevor Sie eine Antwort mit privaten Daten fundieren, erstellen Sie einen Datenspeicher und eine Suchanwendung.

WARNUNG: Derzeit unterstützt diese Fundierungsschnittstelle den Chunk-Modus von Vertex AI Search nicht.

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

Nächste Schritte

Eine ausführliche Dokumentation finden Sie hier:

• Fundierung
• Gemini API