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.

Grounding pomaga tworzyć aplikacje, które mogą:

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

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

from google import genai
from google.genai import types

client = genai.Client()

grounding_tool = types.Tool(
    google_search=types.GoogleSearch()
)

config = types.GenerateContentConfig(
    tools=[grounding_tool]
)

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Who won the euro 2024?",
    config=config,
)

print(response.text)

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

const ai = new GoogleGenAI({});

const groundingTool = {
  googleSearch: {},
};

const config = {
  tools: [groundingTool],
};

const response = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: "Who won the euro 2024?",
  config,
});

console.log(response.text);

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {"text": "Who won the euro 2024?"}
        ]
      }
    ],
    "tools": [
      {
        "google_search": {}
      }
    ]
  }'

Więcej informacji znajdziesz w notatniku narzędzia do wyszukiwania.

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.

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 wynikach wyszukiwania: interfejs API zwraca ostateczną, przyjazną dla użytkownika odpowiedź opartą na wynikach wyszukiwania. Ta odpowiedź zawiera tekstową odpowiedź modelu oraz groundingMetadata z zapytaniami, wynikami wyszukiwania i cytatami.

Informacje o odpowiedzi opartej na wynikach wyszukiwania

Gdy odpowiedź jest oparta na wynikach wyszukiwania, zawiera pole groundingMetadata. Te uporządkowane dane są niezbędne do weryfikowania twierdzeń i tworzenia w aplikacji bogatych cytatów.

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Spain won Euro 2024, defeating England 2-1 in the final. This victory marks Spain's record fourth European Championship title."
          }
        ],
        "role": "model"
      },
      "groundingMetadata": {
        "webSearchQueries": [
          "UEFA Euro 2024 winner",
          "who won euro 2024"
        ],
        "searchEntryPoint": {
          "renderedContent": "<!-- HTML and CSS for the search widget -->"
        },
        "groundingChunks": [
          {"web": {"uri": "https://vertexaisearch.cloud.google.com.....", "title": "aljazeera.com"}},
          {"web": {"uri": "https://vertexaisearch.cloud.google.com.....", "title": "uefa.com"}}
        ],
        "groundingSupports": [
          {
            "segment": {"startIndex": 0, "endIndex": 85, "text": "Spain won Euro 2024, defeatin..."},
            "groundingChunkIndices": [0]
          },
          {
            "segment": {"startIndex": 86, "endIndex": 210, "text": "This victory marks Spain's..."},
            "groundingChunkIndices": [0, 1]
          }
        ]
      }
    }
  ]
}

Interfejs Gemini API zwraca te informacje w polu groundingMetadata:

• webSearchQueries : tablica użytych zapytań. Przydaje się do debugowania i zrozumienia procesu rozumowania modelu.
• searchEntryPoint : zawiera kod HTML i CSS do renderowania wymaganych sugestii wyszukiwania. Pełne wymagania dotyczące użytkowania są opisane w Warunkach korzystania z usługi.
• groundingChunks : tablica obiektów zawierających źródła internetowe (uri i title).
• groundingSupports : tablica fragmentów, które łączą odpowiedź modelu text ze źródłami w groundingChunks. Każdy fragment łączy segment tekstu (zdefiniowany przez startIndex i endIndex) z co najmniej 1 elementem groundingChunkIndices. Jest to klucz do tworzenia cytatów w tekście.

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 zarówno na publicznych danych internetowych, jak i na konkretnych adresach URL, które podasz.

Przypisywanie źródeł za pomocą cytatów w tekście

Interfejs API zwraca uporządkowane dane cytatów, co daje Ci pełną kontrolę nad sposobem wyświetlania źródeł w interfejsie użytkownika. Za pomocą pól groundingSupports i groundingChunks możesz bezpośrednio łączyć stwierdzenia modelu z ich źródłami. Oto typowy wzorzec przetwarzania metadanych w celu utworzenia odpowiedzi z cytatami w tekście, które można kliknąć.

def add_citations(response):
    text = response.text
    supports = response.candidates[0].grounding_metadata.grounding_supports
    chunks = response.candidates[0].grounding_metadata.grounding_chunks

    # Sort supports by end_index in descending order to avoid shifting issues when inserting.
    sorted_supports = sorted(supports, key=lambda s: s.segment.end_index, reverse=True)

    for support in sorted_supports:
        end_index = support.segment.end_index
        if support.grounding_chunk_indices:
            # Create citation string like [1](link1)[2](link2)
            citation_links = []
            for i in support.grounding_chunk_indices:
                if i < len(chunks):
                    uri = chunks[i].web.uri
                    citation_links.append(f"[{i + 1}]({uri})")

            citation_string = ", ".join(citation_links)
            text = text[:end_index] + citation_string + text[end_index:]

    return text

# Assuming response with grounding metadata
text_with_citations = add_citations(response)
print(text_with_citations)

function addCitations(response) {
    let text = response.text;
    const supports = response.candidates[0]?.groundingMetadata?.groundingSupports;
    const chunks = response.candidates[0]?.groundingMetadata?.groundingChunks;

    // Sort supports by end_index in descending order to avoid shifting issues when inserting.
    const sortedSupports = [...supports].sort(
        (a, b) => (b.segment?.endIndex ?? 0) - (a.segment?.endIndex ?? 0),
    );

    for (const support of sortedSupports) {
        const endIndex = support.segment?.endIndex;
        if (endIndex === undefined || !support.groundingChunkIndices?.length) {
        continue;
        }

        const citationLinks = support.groundingChunkIndices
        .map(i => {
            const uri = chunks[i]?.web?.uri;
            if (uri) {
            return `[${i + 1}](${uri})`;
            }
            return null;
        })
        .filter(Boolean);

        if (citationLinks.length > 0) {
        const citationString = citationLinks.join(", ");
        text = text.slice(0, endIndex) + citationString + text.slice(endIndex);
        }
    }

    return text;
}

const textWithCitations = addCitations(response);
console.log(textWithCitations);

Nowa odpowiedź z cytatami w tekście będzie wyglądać tak:

Spain won Euro 2024, defeating England 2-1 in the final.[1](https:/...), [2](https:/...), [4](https:/...), [5](https:/...) This victory marks Spain's record-breaking fourth European Championship title.[5]((https:/...), [2](https:/...), [3](https:/...), [4](https:/...)

Ceny

Gdy używasz powiązania ze źródłami informacji przy użyciu wyszukiwarki Google z Gemini 3, Twój projekt jest obciążany za każde zapytanie, które model zdecyduje się wykonać. Jeśli model zdecyduje się wykonać kilka zapytań, aby odpowiedzieć na 1 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 podczas zliczania unikalnych zapytań. Ten model rozliczeń dotyczy tylko modeli Gemini 3. Gdy używasz grounding przy użyciu wyszukiwarki z modelami Gemini 2.5 lub starszymi, Twój projekt jest obciążany za każdego prompta.

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

Obsługiwane modele

Pełne możliwości znajdziesz na stronie przeglądu modelu.

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 wykonanie kodu i kontekst adresu URL, aby obsługiwać bardziej złożone przypadki użycia.

Modele Gemini 3 obsługują łączenie narzędzi wbudowanych (takich jak grounding przy użyciu wyszukiwarki Google) z narzędziami niestandardowymi (wywoływanie funkcji). Więcej informacji znajdziesz na stronie dotyczącej kombinacji narzędzi.

Co dalej?

• Wypróbuj powiązanie ze źródłami informacji przy użyciu wyszukiwarki Google w przewodniku Gemini API Cookbook.
• Dowiedz się więcej o innych dostępnych narzędziach, takich jak wywoływanie funkcji.
• Dowiedz się, jak rozszerzać prompty o konkretne adresy URL za pomocą narzędzia kontekstu adresu URL.