Gemini Search Grounding

Utilisez Google Search Grounding pour associer les passages de réponse aux sources Web.

Gemini Search Grounding permet aux modèles compatibles d’obtenir des informations récentes avec Google Search et d’associer les passages de réponse aux sources via groundingMetadata.

Grounding ne consiste pas seulement à activer la recherche. L’application doit aussi lire les correspondances entre requêtes, sources et passages pour afficher des citations vérifiables.

La prise en charge du protocole ne garantit pas celle du modèle

Generate Content peut représenter l’outil Google Search, mais sa disponibilité dépend du modèle et du compte. Vérifiez le modèle dans le Catalogue de modèles, puis consultez Gemini Generate Content Reference.

Envoyer une requête Grounding

Le chemin Gemini natif ajoute /v1beta à l’Origin du site, et non à une Base URL qui contient déjà /v1 :

curl --request POST \
  'https://api.agtcloud.cn/v1beta/models/MODEL_ID:generateContent' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Quelles actualités sur l’IA méritent l’attention aujourd’hui ? Indiquez vos sources."
          }
        ]
      }
    ],
    "tools": [
      {
        "google_search": {}
      }
    ]
  }'

Le modèle détermine si une recherche est nécessaire et peut produire une ou plusieurs requêtes. L’activation de l’outil ne garantit pas la présence de Grounding Metadata.

Traitement de Grounding

1. Envoyer la question et l’outil de recherche

Placez la question dans contents[].parts et activez Google Search dans tools.

2. Lire la réponse

Lisez le texte dans content.parts des candidats, sans supposer qu’il n’existe qu’un candidat ou qu’une Part.

3. Lire les Grounding Metadata

Conservez les requêtes, les sources Web et la correspondance entre passages et index de sources.

4. Afficher des citations cliquables

Insérez les citations à la fin des passages ou affichez des cartes de sources à côté de la réponse pour permettre la vérification.

Comprendre `groundingMetadata`

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {"text": "D’après les informations récentes, les évolutions comprennent…"}
        ]
      },
      "groundingMetadata": {
        "webSearchQueries": [
          "intelligence artificielle actualités aujourd’hui"
        ],
        "groundingChunks": [
          {
            "web": {
              "uri": "https://example.com/article",
              "title": "Titre de la source"
            }
          }
        ],
        "groundingSupports": [
          {
            "segment": {
              "startIndex": 0,
              "endIndex": 12,
              "text": "D’après les informations récentes"
            },
            "groundingChunkIndices": [0]
          }
        ]
      }
    }
  ]
}

Champ	Utilisation côté client
`webSearchQueries`	Conserver les requêtes réellement utilisées pour le diagnostic et expliquer le périmètre
`groundingChunks`	Conserver les URI, titres et autres informations des sources
`groundingSupports`	Associer les passages à un ou plusieurs index de sources

Certains champs peuvent être absents ; utilisez un accès optionnel et des tableaux vides par défaut.

Insérer des citations dans le texte

Insérez les citations par ordre décroissant de segment.endIndex pour éviter de décaler les positions suivantes :

function addCitations(text, supports = [], chunks = []) {
  const sorted = [...supports].sort(
    (a, b) => (b.segment?.endIndex ?? 0) - (a.segment?.endIndex ?? 0),
  );

  for (const support of sorted) {
    const endIndex = support.segment?.endIndex;
    if (endIndex == null) continue;

    const links = (support.groundingChunkIndices ?? [])
      .map((index) => {
        const source = chunks[index]?.web;
        return source?.uri ? `[${index + 1}](${source.uri})` : null;
      })
      .filter(Boolean);

    if (links.length > 0) {
      text = `${text.slice(0, endIndex)}${links.join('')}${text.slice(endIndex)}`;
    }
  }

  return text;
}

Dans le navigateur, traitez le Markdown ou le HTML de manière sécurisée et ajoutez les attributs de sécurité des nouveaux onglets aux liens externes.

Échecs et solutions de repli

Situation	Traitement
`groundingMetadata` absent	Afficher la réponse et signaler l’absence de sources Grounding affichables
Index de source hors limites	Ignorer l’association invalide et conserver la réponse expurgée, sans insérer de lien erroné
Positions textuelles incohérentes	Afficher les sources en fin de réponse plutôt qu’insérer les citations au mauvais endroit
Recherche échouée	Selon l’erreur, limiter les tentatives ou répondre sans recherche
Sources contradictoires	Afficher les sources et dates pour permettre une appréciation, sans masquer les divergences

Vérifications avant la mise en production

Le modèle prend en charge Google Search Grounding.
L’endpoint Gemini utilise l’Origin du site sans produire /v1/v1beta.
Les textes, requêtes, sources et correspondances de passages sont conservés séparément.
Un index de citation invalide ne provoque pas de panne de la page.
Les pages externes ne sont pas directement interprétées comme des instructions métier fiables.
Aucune fausse citation n’est générée en l’absence de sources.

Si l’application utilise Chat plutôt que Gemini natif, utilisez les champs de recherche Chat explicitement pris en charge, sans copier directement l’analyseur groundingMetadata.

Sur cette page