Ancrage avec la recherche Google

L'ancrage avec la recherche Google permet d'associer le modèle Gemini au 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 limite de connaissances.

L'ancrage vous aide à créer des applications qui peuvent:

  • Améliorer la justesse factuelle:réduisez les hallucinations du modèle en basant les réponses sur des informations réelles.
  • Accès aux informations en temps réel:répondez aux questions sur des événements et des sujets récents.
  • Citez vos sources: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?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, consultez 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. Invite utilisateur:votre application envoie l'invite de l'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 basée sur les résultats de recherche:l'API renvoie une réponse finale, conviviale, basée sur 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 de mise à la terre

Lorsqu'une réponse est correctement établie, elle inclut un champ groundingMetadata. Ces données structurées sont essentielles pour valider les revendications 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 segments permettant de connecter la réponse du modèle text aux sources de groundingChunks. Chaque bloc lie un segment de texte (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 manière dont vous affichez les sources dans votre interface utilisateur. Vous pouvez utiliser les champs groundingSupports et groundingChunks pour associer directement les instructions du modèle à leurs sources. Voici un modèle courant pour traiter les métadonnées afin de créer une réponse avec des citations intégrées cliquables.

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ésente 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 dans la recherche Google, votre projet est facturé par requête 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 invite (par exemple, rechercher "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 la tarification, consultez la page des tarifs de l'API Gemini.

Modèles compatibles

Les modèles expérimentaux et les modèles en version Preview ne sont pas inclus. Vous trouverez leurs fonctionnalités sur la page Présentation du modèle.

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

Mise à la terre avec les modèles Gemini 1.5 (ancien)

Bien que l'outil google_search soit recommandé pour Gemini 2.0 et versions ultérieures, Gemini 1.5 est compatible avec un ancien outil nommé google_search_retrieval. Cet outil fournit un mode dynamic qui permet au modèle de décider d'effectuer une recherche en fonction de son degré de confiance quant à la nécessité d'informations récentes pour l'invite. Si le niveau de confiance du modèle est supérieur à un dynamic_threshold que vous avez défini (valeur comprise entre 0,0 et 1,0), une recherche est effectuée.

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(api_key=os.getenv("GEMINI_API_KEY"))

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({ apiKey: process.env.GEMINI_API_KEY });

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?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