Grounding z użyciem wyszukiwarki Google

Grounding z użyciem wyszukiwarki Google łączy model Gemini z treściami internetowymi aktualizowanymi w czasie rzeczywistym i działa we wszystkich dostępnych językach. Dzięki temu Gemini może udzielać dokładniejszych odpowiedzi i cytować wiarygodne źródła wykraczające poza datę odcięcia wiedzy.

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

• Zwiększanie dokładności: zmniejsz halucynacje modelu, opierając odpowiedzi na informacjach ze świata rzeczywistego.
• Dostęp do informacji w czasie rzeczywistym: odpowiadaj na pytania dotyczące ostatnich wydarzeń i tematów.

• Podawaj cytaty: buduj zaufanie użytkowników, podają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-flash-preview",
    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-flash-preview",
  contents: "Who won the euro 2024?",
  config,
});

console.log(response.text);

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview: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łem informacji przy użyciu wyszukiwarki Google

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

1. Prompt użytkownika: Twoja aplikacja wysyła prompt użytkownika do interfejsu Gemini API z włączonym narzędziem google_search.
2. Analiza promptu: model analizuje prompt i określa, czy wyszukiwarka Google może poprawić odpowiedź.
3. Wyszukiwarka Google: w razie potrzeby model automatycznie generuje jedno lub kilka zapytań 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ź, która jest oparta na wynikach wyszukiwania. Odpowiedź zawiera tekst wygenerowany przez modelgroundingMetadata wraz z wyszukiwanymi hasłami, wynikami wyszukiwania w internecie i cytatami.

Informacje o odpowiedzi dotyczącej podstaw

Gdy odpowiedź zostanie prawidłowo uzasadniona, będzie zawierać pole groundingMetadata. Te dane strukturalne są niezbędne do weryfikowania roszczeń i tworzenia w aplikacji rozbudowanych 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 z symbolem groundingMetadata:

• webSearchQueries : tablica użytych zapytań. Jest to przydatne do debugowania i zrozumienia procesu wnioskowania modelu.
• searchEntryPoint : zawiera kod HTML i CSS do renderowania wymaganych sugestii wyszukiwania. Pełne wymagania dotyczące korzystania z usługi są opisane w Warunkach korzystania z usługi.
• groundingChunks : tablica obiektów zawierająca źródła internetowe (uri i title).
• groundingSupports : tablica fragmentów do połączenia odpowiedzi modelu text ze źródłami w groundingChunks. Każdy fragment łączy tekst segment (zdefiniowany przez startIndex i endIndex) z co najmniej 1 groundingChunkIndices. To klucz do tworzenia cytatów w tekście.

Uziemianie za pomocą wyszukiwarki Google można też stosować w połączeniu z narzędziem do kontekstu adresu URL, aby uziemiać odpowiedzi zarówno na podstawie publicznych danych internetowych, jak i określonych adresów URL.

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

Interfejs API zwraca uporządkowane dane cytowania, dzięki czemu masz pełną kontrolę nad sposobem wyświetlania źródeł w interfejsie użytkownika. Możesz użyć pól groundingSupports i groundingChunks, aby połączyć wypowiedzi modelu bezpośrednio z ich źródłami. Oto typowy wzorzec przetwarzania metadanych w celu utworzenia odpowiedzi z klikalnymi cytatami w tekście.

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 funkcji Grounding przy użyciu wyszukiwarki Google w Gemini 3, za każde zapytanie wyszukiwania, które model zdecyduje się wykonać, Twój projekt jest obciążany opłatą. Jeśli model zdecyduje się wykonać kilka zapytań, aby odpowiedzieć na jeden prompt (np. wyszukać "UEFA Euro 2024 winner" i "Spain vs England Euro 2024 final score" w ramach jednego 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 internetowej podczas zliczania unikalnych zapytań. Ten model rozliczeń dotyczy tylko modeli Gemini 3. Jeśli używasz groundingu w wyszukiwarce z modelami Gemini 2.5 lub starszymi, projekt jest rozliczany za prompt.

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

Obsługiwane modele

Nie obejmuje to modeli eksperymentalnych i wersji podglądowych. Ich możliwości znajdziesz na stronie informacji o modelu.

Obsługiwane kombinacje narzędzi

Możesz używać Grounding z wyszukiwarką Google z innymi narzędziami, takimi jak wykonywanie kodu i kontekst adresu URL, aby obsługiwać bardziej złożone przypadki użycia.

Co dalej?

• Wypróbuj grounding z użyciem wyszukiwarki Google w zbiorze Cookbook interfejsu Gemini API.
• Dowiedz się więcej o innych dostępnych narzędziach, takich jak wywoływanie funkcji.
• Dowiedz się, jak wzbogacać prompty o konkretne adresy URL za pomocą narzędzia kontekstu adresu URL.