Ancrage avec la recherche Google

L'ancrage avec la recherche Google permet d'associer le modèle Gemini à du contenu Web en temps réel et fonctionne dans toutes les langues disponibles. Cela permet à Gemini de fournir des réponses plus précises et de citer des sources vérifiables au-delà de sa date limite de connaissances.

L'ancrage vous aide à créer des applications capables de :

  • Améliorer la justesse factuelle : réduisez les hallucinations du modèle en basant les réponses sur des informations réelles.
  • Accéder à des informations en temps réel : obtenez des réponses à des questions sur des événements et des thèmes récents.
  • Fournissez des citations : gagnez la confiance des utilisateurs en indiquant les sources des affirmations du modèle.

Python

from google import genai
from google.genai import types

# Configure the client
client = genai.Client()

# Define the grounding tool
grounding_tool = types.Tool(
    google_search=types.GoogleSearch()
)

# Configure generation settings
config = types.GenerateContentConfig(
    tools=[grounding_tool]
)

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

# Print the grounded response
print(response.text)

JavaScript

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

// Configure the client
const ai = new GoogleGenAI({});

// Define the grounding tool
const groundingTool = {
  googleSearch: {},
};

// Configure generation settings
const config = {
  tools: [groundingTool],
};

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

// Print the grounded response
console.log(response.text);

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.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": {}
      }
    ]
  }'

Pour en savoir plus, essayez le notebook de l'outil de recherche.

Fonctionnement de l'ancrage avec la recherche Google

Lorsque vous activez l'outil google_search, le modèle gère automatiquement l'ensemble du workflow de recherche, de traitement et de citation des informations.

grounding-overview

  1. Requête utilisateur : votre application envoie la requête d'un utilisateur à l'API Gemini avec l'outil google_search activé.
  2. Analyse de la requête : le modèle analyse la requête et détermine si une recherche Google peut améliorer la réponse.
  3. Recherche Google : si nécessaire, le modèle génère automatiquement une ou plusieurs requêtes de recherche et les exécute.
  4. Traitement des résultats de recherche : le modèle traite les résultats de recherche, synthétise les informations et formule une réponse.
  5. Réponse ancrée : l'API renvoie une réponse finale et conviviale ancrée dans les résultats de recherche. Cette réponse inclut la réponse textuelle du modèle et groundingMetadata avec les requêtes de recherche, les résultats Web et les citations.

Comprendre la réponse d'ancrage

Lorsqu'une réponse est correctement ancrée, elle inclut un champ groundingMetadata. Ces données structurées sont essentielles pour valider les affirmations et créer une expérience de citation enrichie dans votre application.

{
  "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]
          }
        ]
      }
    }
  ]
}

L'API Gemini renvoie les informations suivantes avec groundingMetadata :

  • webSearchQueries : tableau des requêtes de recherche utilisées. Cela est utile pour déboguer et comprendre le processus de raisonnement du modèle.
  • searchEntryPoint : contient le code HTML et CSS permettant d'afficher les suggestions de recherche requises. Les conditions d'utilisation complètes sont détaillées dans les Conditions d'utilisation.
  • groundingChunks : tableau d'objets contenant les sources Web (uri et title).
  • groundingSupports : tableau de blocs permettant de relier la réponse du modèle text aux sources dans groundingChunks. Chaque bloc associe un segment (défini par startIndex et endIndex) à un ou plusieurs groundingChunkIndices. C'est la clé pour créer des citations intégrées.

Vous pouvez également utiliser l'ancrage avec la recherche Google en combinaison avec l'outil de contexte d'URL pour ancrer les réponses à la fois dans les données Web publiques et dans les URL spécifiques que vous fournissez.

Attribuer des sources avec des citations intégrées

L'API renvoie des données de citation structurées, ce qui vous permet de contrôler entièrement la façon dont vous affichez les sources dans votre interface utilisateur. Vous pouvez utiliser les champs groundingSupports et groundingChunks pour associer directement les déclarations du modèle à leurs sources. Voici un schéma courant pour traiter les métadonnées afin de créer une réponse avec des citations cliquables intégrées.

Python

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)

JavaScript

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);

La nouvelle réponse avec des citations intégrées se présentera comme suit :

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:/...)

Tarifs

Lorsque vous utilisez l'ancrage avec la recherche Google, votre projet est facturé par requête d'API incluant l'outil google_search. Si le modèle décide d'exécuter plusieurs requêtes de recherche pour répondre à une seule requête (par exemple, en recherchant "UEFA Euro 2024 winner" et "Spain vs England Euro 2024 final score" dans le même appel d'API), cela compte comme une seule utilisation facturable de l'outil pour cette requête.

Pour en savoir plus sur les tarifs, consultez la page des tarifs de l'API Gemini.

Modèles compatibles

Les modèles expérimentaux et en aperçu ne sont pas inclus. Vous trouverez leurs capacités sur la page Présentation des modèles.

Modèle Ancrage avec la recherche Google
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️
Gemini 2.0 Flash ✔️
Gemini 1.5 Pro ✔️
Gemini 1.5 Flash ✔️

Ancrage avec les modèles Gemini 1.5 (ancienne version)

L'outil google_search est recommandé pour Gemini 2.0 et les versions ultérieures, mais Gemini 1.5 est compatible avec un ancien outil nommé google_search_retrieval. Cet outil propose un mode dynamic qui permet au modèle de décider s'il doit effectuer une recherche en fonction de sa certitude que la requête nécessite des informations récentes. Si le niveau de confiance du modèle est supérieur à dynamic_threshold (valeur comprise entre 0,0 et 1,0) que vous avez défini, il effectuera une recherche.

Python

# Note: This is a legacy approach for Gemini 1.5 models.
# The 'google_search' tool is recommended for all new development.
import os
from google import genai
from google.genai import types

client = genai.Client()

retrieval_tool = types.Tool(
    google_search_retrieval=types.GoogleSearchRetrieval(
        dynamic_retrieval_config=types.DynamicRetrievalConfig(
            mode=types.DynamicRetrievalConfigMode.MODE_DYNAMIC,
            dynamic_threshold=0.7 # Only search if confidence > 70%
        )
    )
)

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

response = client.models.generate_content(
    model='gemini-1.5-flash',
    contents="Who won the euro 2024?",
    config=config,
)
print(response.text)
if not response.candidates[0].grounding_metadata:
  print("\nModel answered from its own knowledge.")

JavaScript

// Note: This is a legacy approach for Gemini 1.5 models.
// The 'googleSearch' tool is recommended for all new development.
import { GoogleGenAI, DynamicRetrievalConfigMode } from "@google/genai";

const ai = new GoogleGenAI({});

const retrievalTool = {
  googleSearchRetrieval: {
    dynamicRetrievalConfig: {
      mode: DynamicRetrievalConfigMode.MODE_DYNAMIC,
      dynamicThreshold: 0.7, // Only search if confidence > 70%
    },
  },
};

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

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

console.log(response.text);
if (!response.candidates?.[0]?.groundingMetadata) {
  console.log("\nModel answered from its own knowledge.");
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.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_retrieval": {
        "dynamic_retrieval_config": {
          "mode": "MODE_DYNAMIC",
          "dynamic_threshold": 0.7
        }
      }
    }]
  }'

Étape suivante