Grounding z użyciem wyszukiwarki Google

Powiązanie ze źródłami informacji przy użyciu wyszukiwarki Google łączy model Gemini z treściami z internetu w czasie rzeczywistym i działa we wszystkich dostępnych językach. Pozwala to Gemini udzielać dokładniejszych odpowiedzi i cytować zweryfikowane źródła poza jego granicą wiedzy.

Powiązanie ze źródłami informacji pomaga tworzyć aplikacje, które mogą:

  • zwiększać dokładność faktów: zmniejszają halucynacje modelu, ponieważ odpowiedzi są oparte na informacjach ze świata rzeczywistego;
  • uzyskiwać dostęp do informacji w czasie rzeczywistym: odpowiadać na pytania dotyczące najnowszych wydarzeń i tematów;

  • podawać cytaty: budować zaufanie użytkowników, pokazując źródła twierdzeń modelu.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Who won the euro 2024?",
    tools=[{"type": "google_search"}]
)

print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "Who won the euro 2024?",
    tools: [{ type: "google_search" }]
});

console.log(interaction.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("What is the current score of the Lakers game?"))
        .tools(Arrays.asList(new GoogleSearch()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Who won the euro 2024?",
    "tools": [{"type": "google_search"}]
  }'

Jak działa powiązanie ze źródłami informacji przy użyciu wyszukiwarki Google

Gdy włączysz narzędzie google_search, model automatycznie obsługuje cały proces wyszukiwania, przetwarzania i cytowania informacji.

grounding-overview

  1. Prompt użytkownika: Twoja aplikacja wysyła prompta użytkownika do interfejsu Gemini API z włączonym narzędziem google_search.
  2. Analiza prompta: model analizuje prompta i określa, czy wyszukiwanie w Google może poprawić odpowiedź.
  3. Wyszukiwanie w Google: w razie potrzeby model automatycznie generuje co najmniej 1 zapytanie i je wykonuje.
  4. Przetwarzanie wyników wyszukiwania: model przetwarza wyniki wyszukiwania, syntetyzuje informacje i formułuje odpowiedź.
  5. Odpowiedź oparta na źródłach informacji: interfejs API zwraca ostateczną, przyjazną dla użytkownika odpowiedź opartą na wynikach wyszukiwania. Ta odpowiedź zawiera tekstową odpowiedź modelu z wbudowanymi annotations zawierającymi cytaty, a także kroki google_search_call i google_search_result z zapytaniami i sugestiami wyszukiwania.

Informacje o odpowiedzi opartej na źródłach informacji

Gdy odpowiedź jest oparta na źródłach informacji, tekst wygenerowany przez model zawiera wbudowane annotations bezpośrednio w bloku treści tekstowej. Te adnotacje zawierają informacje o cytatach, które łączą części odpowiedzi z ich źródłami.

{
  "steps": [
    {
      "type": "thought",
      "summary": [
        {
          "type": "text",
          "text": "The user is asking for the winner of Euro 2024. I need to search for the result of the Euro 2024 final."
        }
      ],
      "signature": "CoMDAXLI2nynRYojJIy6B1Jh9os2crpWLfB0..."
    },
    {
      "type": "google_search_call",
      "arguments": {
        "queries": ["UEFA Euro 2024 winner"]
      }
    },
    {
      "type": "google_search_result",
      "call_id": "search_001",
      "result": [
        {
          "search_suggestions": "<!-- HTML and CSS for the search widget -->"
        }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Spain won Euro 2024, defeating England 2-1 in the final. This victory marks Spain's record fourth European Championship title.",
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://www.aljazeera.com/sports/euro-2024-final",
              "title": "aljazeera.com",
              "start_index": 0,
              "end_index": 56
            },
            {
              "type": "url_citation",
              "url": "https://www.uefa.com/euro2024/news/spain-wins-euro-2024",
              "title": "uefa.com",
              "start_index": 57,
              "end_index": 124
            }
          ]
        }
      ]
    }
  ]
}

Kluczowe pola w odpowiedzi:

  • google_search_call : zawiera queries wyszukiwania wykonane przez model.
  • google_search_result : zawiera search_suggestions, czyli fragment kodu HTML do renderowania sugestii wyszukiwania w interfejsie. Pełne wymagania dotyczące użytkowania są opisane w Warunkach korzystania z usługi.
  • text z annotations : syntetyzowana odpowiedź modelu z wbudowanymi cytatami. Każda adnotacja url_citation łączy segment tekstu (zdefiniowany przez start_index i end_index) z adresem URL źródła. Jest to klucz do tworzenia wbudowanych cytatów.

Powiązanie ze źródłami informacji przy użyciu wyszukiwarki Google można też stosować w połączeniu z narzędziem kontekstu adresu URL, aby opierać odpowiedzi na danych publicznych z internetu i na konkretnych adresach URL, które podasz.

Podawanie źródeł za pomocą wbudowanych cytatów

Interfejs API zwraca wbudowane adnotacje url_citation w bloku treści tekstowej, co daje Ci pełną kontrolę nad sposobem wyświetlania źródeł w interfejsie użytkownika. Każda adnotacja zawiera start_index i end_index, aby określić, którą część tekstu cytuje. Oto jak je wyodrębnić i wyświetlić.

Python

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nCitations:")
                    for annotation in content_block.annotations:
                        if annotation.type == "url_citation":
                            cited_text = content_block.text[annotation.start_index:annotation.end_index]
                            print(f"  [{annotation.title}]({annotation.url})")
                            print(f"    Cited text: \"{cited_text}\"")

JavaScript

for (const step of interaction.steps) {
  if (step.type === 'model_output') {
    for (const contentBlock of step.content) {
      if (contentBlock.type === 'text') {
        console.log(contentBlock.text);
        if (contentBlock.annotations) {
          console.log("\nCitations:");
          for (const annotation of contentBlock.annotations) {
            if (annotation.type === 'url_citation') {
              const citedText = contentBlock.text.slice(annotation.startIndex, annotation.endIndex);
              console.log(`  [${annotation.title}](${annotation.url})`);
              console.log(`    Cited text: "${citedText}"`);
            }
          }
        }
      }
    }
  }
}

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.URLCitation;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("What happened in tech news today?"))
        .tools(Arrays.asList(new GoogleSearch()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content content : outputStep.content().get()) {
          if (content instanceof TextContent) {
            TextContent textContent = (TextContent) content;
            System.out.println("Response: " + textContent.text().orElse(""));
            if (textContent.annotations().isPresent()) {
              for (Annotation annotation : textContent.annotations().get()) {
                if (annotation instanceof URLCitation) {
                  URLCitation citation = (URLCitation) annotation;
                  System.out.printf("  [%s](%s)\n", citation.title().orElse(""), citation.url().orElse(""));
                }
              }
            }
          }
        }
      }
    }
  }
}

Dane wyjściowe będą zawierać tekst, a następnie jego cytaty:

Spain won Euro 2024, defeating England 2-1 in the final. This victory marks Spain's record fourth European Championship title.

Citations:
  [aljazeera.com](https://www.aljazeera.com/sports/euro-2024-final)
    Cited text: "Spain won Euro 2024, defeating England 2-1 in the final."
  [uefa.com](https://www.uefa.com/euro2024/news/spain-wins-euro-2024)
    Cited text: "This victory marks Spain's record fourth European Championship title."

Ceny

Gdy używasz powiązania ze źródłami informacji przy użyciu wyszukiwarki Google z Gemini 3, za każde zapytanie, które model zdecyduje się wykonać, zostanie naliczona opłata. Jeśli model zdecyduje się wykonać kilka zapytań, aby odpowiedzieć na jednego prompta (np. wyszukać hasła "UEFA Euro 2024 winner" i "Spain vs England Euro 2024 final score" w ramach tego samego wywołania interfejsu API), będzie to liczone jako 2 płatne użycia narzędzia w przypadku tego żądania. Na potrzeby rozliczeń ignorujemy puste zapytania w wyszukiwarce podczas zliczania unikalnych zapytań. Ten model rozliczeń dotyczy tylko modeli Gemini 3. Gdy używasz powiązania ze źródłami informacji przy użyciu wyszukiwarki z Gemini 2.5 lub starszymi modelami, opłata jest naliczana za prompta.

Szczegółowe informacje o cenach znajdziesz na stronie z cennikiem interfejsu Gemini API.

Obsługiwane modele

Pełne możliwości znajdziesz na stronie z omówieniem modelu.

Model Powiązanie ze źródłem informacji przy użyciu wyszukiwarki Google
Gemini 3.8 Flash ✔️
Gemini 3.7 Flash ✔️
Gemini 3.6 Flash ✔️
Gemini 3.5 Flash-Lite ✔️
Gemini 3.5 Flash ✔️
Gemini 3.1 Flash Image Preview ✔️
Gemini 3.1 Pro (wersja testowa) ✔️
Gemini 3 Pro Image Preview ✔️
Gemini 3 Flash (wersja testowa) ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️
Gemini 2.0 Flash ✔️

Obsługiwane kombinacje narzędzi

Powiązanie ze źródłami informacji przy użyciu wyszukiwarki Google możesz stosować z innymi narzędziami, takimi jak wykonywanie kodu, kontekst adresu URL i powiązanie ze źródłami informacji przy użyciu Map Google (obsługiwane w Gemini 3.5 Flash i nowszych modelach), aby obsługiwać bardziej złożone przypadki użycia. Modele Gemini 3 obsługują też łączenie tych wbudowanych narzędzi z narzędziami niestandardowymi (wywoływanie funkcji). Więcej informacji znajdziesz na stronie dotyczącej kombinacji narzędzi.

Co dalej?