Ancrage avec la recherche Google

Cette page explique comment ancrer les réponses de Gemini à l'aide des résultats du moteur de recherche Google, qui utilise des données Web accessibles au public. Les suggestions de recherche incluses dans vos réponses sont également expliquées.

Ancrage avec la recherche Google

Si vous souhaitez associer votre modèle à des connaissances du monde entier, à un large éventail de sujets possibles ou à des informations à jour disponibles sur Internet, utilisez l'ancrage avec la recherche Google.

Pour en savoir plus sur l'ancrage des modèles dans Gemini Enterprise Agent Platform, consultez la page Présentation de l'ancrage.

Modèles compatibles

Cette section liste les modèles compatibles avec l'ancrage avec la recherche.

Langues disponibles

Pour obtenir la liste des langues disponibles, consultez Langues.

Utiliser l'ancrage avec la recherche Google

Suivez les instructions ci-dessous pour ancrer un modèle avec des données Web accessibles au public.

Remarques

• Pour utiliser l'ancrage avec la recherche Google, vous devez activer les suggestions de recherche Google. Pour en savoir plus, consultez Utiliser les suggestions de recherche Google.

• Pour obtenir des résultats optimaux, utilisez une température de 1.0. Pour en savoir plus sur la définition de cette configuration, consultez le corps de la requête API Gemini dans la documentation de référence du modèle.

• L'ancrage avec la recherche Google est limité à un million de requêtes par jour. Si vous avez besoin de plus de requêtes, contactez l'assistanceCloud de Confiance by S3NS pour obtenir de l'aide.

• Combinaisons d'outils : l'API Gemini ne permet pas de combiner des outils de recherche (comme googleSearch) avec des outils autres que de recherche (comme l'appel de fonction ou l'outil de moteur RAG retrieval de Gemini Enterprise Agent Platform) dans la même requête generateContent. Plusieurs outils ne sont acceptés que s'il s'agit uniquement d'outils de recherche.

Les résultats de recherche peuvent être personnalisés pour un emplacement géographique spécifique de l'utilisateur final à l'aide des coordonnées de latitude et de longitude. Pour en savoir plus, consultez l'API Grounding.

pip install --upgrade google-genai

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

from google import genai
from google.genai.types import (
    GenerateContentConfig,
    GoogleSearch,
    HttpOptions,
    Tool,
)

client = genai.Client(http_options=HttpOptions(api_version="v1"))

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="When is the next total solar eclipse in the United States?",
    config=GenerateContentConfig(
        tools=[
            # Use Google Search Tool
            Tool(
                google_search=GoogleSearch(
                    # Optional: Domains to exclude from results
                    exclude_domains=["domain.com", "domain2.com"]
                )
            )
        ],
    ),
)

print(response.text)
# Example response:
# 'The next total solar eclipse in the United States will occur on ...'

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithGoogleSearch shows how to generate text using Google Search.
func generateWithGoogleSearch(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	modelName := "gemini-2.5-flash"
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: "When is the next total solar eclipse in the United States?"},
		},
			Role: genai.RoleUser},
	}
	config := &genai.GenerateContentConfig{
		Tools: []*genai.Tool{
			{GoogleSearch: &genai.GoogleSearch{ExcludeDomains: []string{"example.com", "example.org"}}},
		},
	}

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// The next total solar eclipse in the United States will occur on March 30, 2033, but it will only ...

	return nil
}

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.GoogleSearch;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.Tool;

public class ToolsGoogleSearchWithText {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-2.5-flash";
    generateContent(modelId);
  }

  // Generates content with Google Search tool
  public static String generateContent(String modelId) {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      // Create a GenerateContentConfig and set Google Search tool
      GenerateContentConfig contentConfig =
          GenerateContentConfig.builder()
              .tools(Tool.builder().googleSearch(GoogleSearch.builder().build()).build())
              .build();

      GenerateContentResponse response =
          client.models.generateContent(
              modelId, "When is the next total solar eclipse in the United States?", contentConfig);

      System.out.print(response.text());
      // Example response:
      // The next total solar eclipse in the United States will occur on...
      return response.text();
    }
  }
}

npm install @google/genai

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateGoogleSearch(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: 'When is the next total solar eclipse in the United States?',
    config: {
      tools: [
        {
          googleSearch: {},
        },
      ],
    },
  });

  console.log(response.text);

  // Example response:
  //    'The next total solar eclipse in United States will occur on ...'

  return response.text;
}

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent

{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "TEXT"
    }]
  }],
  "tools": [{
    "googleSearch": {
      "exclude_domains": [ "domain.com", "domain2.com" ]
    }
  }],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {
        "latitude": LATITUDE,
        "longitude": LONGITUDE
      }
    }
  },
  "model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "The weather in Chicago this weekend, will be partly cloudy. The temperature will be between 49°F (9°C) and 55°F (13°C) on Saturday and between 51°F (11°C) and 56°F (13°C) on Sunday. There is a slight chance of rain on both days.\n"
          }
        ]
      },
      "finishReason": "STOP",
      "groundingMetadata": {
        "webSearchQueries": [
          "weather in Chicago this weekend"
        ],
        "searchEntryPoint": {
          "renderedContent": "..."
        },
        "groundingChunks": [
          {
            "web": {
              "uri": "https://www.google.com/search?q=weather+in+Chicago,+IL",
              "title": "Weather information for locality: Chicago, administrative_area: IL",
              "domain": "google.com"
            }
          },
          {
            "web": {
              "uri": "...",
              "title": "weatherbug.com",
              "domain": "weatherbug.com"
            }
          }
        ],
        "groundingSupports": [
          {
            "segment": {
              "startIndex": 85,
              "endIndex": 214,
              "text": "The temperature will be between 49°F (9°C) and 55°F (13°C) on Saturday and between 51°F (11°C) and 56°F (13°C) on Sunday."
            },
            "groundingChunkIndices": [
              0
            ],
            "confidenceScores": [
              0.8662828
            ]
          },
          {
            "segment": {
              "startIndex": 215,
              "endIndex": 261,
              "text": "There is a slight chance of rain on both days."
            },
            "groundingChunkIndices": [
              1,
              0
            ],
            "confidenceScores": [
              0.62836814,
              0.6488607
            ]
          }
        ],
        "retrievalMetadata": {}
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 98,
    "totalTokenCount": 108,
    "trafficType": "ON_DEMAND",
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 10
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 98
      }
    ]
  },
  "modelVersion": "gemini-2.0-flash",
  "createTime": "2025-05-19T14:42:55.000643Z",
  "responseId": "b0MraIMFoqnf-Q-D66G4BQ"
}

Ancrage avec Google Images

L'ancrage avec la recherche d'images Google permet aux modèles d'utiliser des images Web récupérées à partir de la recherche d'images Google comme contexte visuel lors de la génération d'images. La recherche d'images Google est un nouveau type de recherche dans l'outil d'ancrage existant avec la recherche Google. Elle existe parallèlement à la recherche sur le Web Google standard. L'ancrage avec la recherche d'images Google est disponible en version Preview pour Gemini Nano Banana 2.1 et Gemini 3.1 Flash Image.

Configuration des requêtes API

Pour activer la recherche d'images Google, configurez l'outil googleSearch dans votre requête API et spécifiez imageSearch dans l'objet searchTypes. Vous pouvez utiliser la recherche d'images Google indépendamment ou avec la recherche sur le Web Google.

Conditions requises pour l'affichage

Lorsque vous utilisez la recherche d'images Google avec l'ancrage avec la Recherche Google, vous devez respecter les conditions suivantes :

• Attribution de la source : vous devez fournir un lien vers la page Web contenant l'image source (la "page contenant l'image", et non le fichier image lui-même) de manière à ce que l'utilisateur puisse l'identifier comme un lien.

• Navigation directe : si vous choisissez également d'afficher les images sources, vous devez fournir un chemin d'accès direct en un seul clic entre les images sources et la page Web source qui les contient. Toute autre implémentation qui retarde ou abstrait l'accès des utilisateurs finaux aux pages Web sources, y compris, mais sans s'y limiter, tout chemin à plusieurs clics ou l'utilisation d'une visionneuse d'images intermédiaire, n'est pas autorisée.

Réponse

Pour les réponses ancrées utilisant la recherche d'images, l'API fournit une attribution et des métadonnées claires pour associer sa sortie à des sources validées. L'objet groundingMetadata inclut les champs suivants :

• imageSearchQueries : requête spécifique utilisée par le modèle pour le contexte visuel (également appelée "recherche d'images").

• groundingChunks : contient les informations sources des résultats récupérés. Pour les sources d'images, elles sont renvoyées sous forme d'URL de redirection à l'aide d'un nouveau type de bloc d'image. Le fragment inclut les éléments suivants :

  • url : URL de la page Web pour l'attribution (également appelée "page de destination").
  • image_url : URL directe de l'image.

• groundingSupports : fournit des mappages spécifiques qui associent le contenu généré à sa source de citation pertinente dans les blocs.

• searchEntryPoint : inclut le chip de recherche Google qui contient du code HTML et CSS conforme pour afficher les suggestions de recherche Google.

Comprendre votre réponse

Si le prompt de votre modèle utilise correctement l'ancrage avec la recherche Google depuis Agent Studio ou depuis l'API, les réponses incluent des métadonnées avec des liens sources (URL Web). Toutefois, il existe plusieurs raisons expliquant pourquoi il est possible que ces métadonnées ne soient pas fournies, et donc la réponse du prompt ne sera pas ancrée. Par exemple : faible pertinence de la source ou informations incomplètes dans la réponse du modèle.

Citations insérées

Les citations intégrées utilisent l'objet grounding_metadata structuré renvoyé par l'API pour associer des segments spécifiques du texte généré à des sources vérifiables.

Cette fonctionnalité est compatible avec toutes les méthodes d'ancrage, y compris la recherche, Google Maps et la recherche par agent. Elle fournit les informations précises sur la source nécessaires pour afficher des citations exactes et interactives dans votre application.

response = client.models.generate_content(
   model="gemini-3.5-flash",
   contents="Where will the next FIFA World Cup be held?",
   config=types.GenerateContentConfig(
       tools=[types.Tool(google_search=types.GoogleSearch())],
   ),
)

display(Markdown(response.text))
print(response.candidates[0].grounding_metadata.grounding_chunks)
display(HTML(response.candidates[0].grounding_metadata.search_entry_point.rendered_content))

Exemple de résultat :

…

Citations:
Wikipedia. "2026 FIFA World Cup." Retrieved February 11, 2026. (https://en.wikipedia.org/wiki/2026_FIFA_World_Cup)
US Soccer Players. "2026 FIFA World Cup FAQ — Dates, Hosts, Tickets, Teams & More." (https://ussoccerplayers.com/2026-fifa-world-cup-faq)
Holafly. "2026 World Cup host cities and countries: Full list of stadiums." (https://travel.holafly.com/esims/2026-world-cup-host-cities/)
…

Support d'ancrage

Il est obligatoire d'afficher un support d'ancrage, car cela vous aide à valider les réponses des éditeurs et vous permet d'apprendre davantage.

Le support d'ancrage des réponses provenant de sources Web doit être affiché à la fois de manière intégrée et globale. Par exemple, consultez l'image suivante pour savoir comment procéder.

Utilisation d'options de moteur de recherche alternatives

Lorsqu'elle utilise l'ancrage avec la Recherche Google, une Application du Client peut :

• proposer d'autres options de moteur de recherche ;
• définir d'autres moteurs de recherche comme option par défaut ;
• Afficher leurs propres suggestions ou résultats de recherche ou ceux de tiers, à condition que les résultats non Google soient affichés séparément des résultats ancrés et des suggestions de recherche de Google, et de manière à ne pas induire les utilisateurs en erreur ni à suggérer qu'ils proviennent de Google.

Avantages

Les requêtes et les workflows complexes suivants, qui nécessitent de la planification, du raisonnement et de la réflexion, sont possibles lorsque vous utilisez l'ancrage avec la recherche Google comme outil :

• Vous pouvez utiliser l'ancrage pour vous assurer que les réponses sont basées sur les informations les plus récentes et les plus précises.
• Vous pouvez récupérer des artefacts sur le Web pour effectuer une analyse.
• Vous pouvez trouver des images, des vidéos ou d'autres contenus multimédias pertinents pour faciliter le raisonnement multimodal ou la génération de tâches.
• Vous pouvez coder, résoudre des problèmes techniques et effectuer d'autres tâches spécialisées.
• Vous pouvez trouver des informations spécifiques à une région ou aider à traduire du contenu avec précision.
• Vous pouvez trouver des sites Web pertinents à consulter.

Utiliser les suggestions de recherche Google

Lorsque vous utilisez l'ancrage avec la recherche Google et que vous recevez des suggestions de recherche dans votre réponse, vous devez afficher les suggestions de recherche en production et dans vos applications.

Plus précisément, vous devez afficher les requêtes de recherche incluses dans les métadonnées de la réponse ancrée. La réponse inclut :

• "content" : réponse générée par le LLM.
• "webSearchQueries" : requêtes à utiliser pour les suggestions de recherche.

Par exemple, dans l'extrait de code suivant, Gemini répond à une requête ancrée avec la recherche Google qui pose une question sur un type de plante tropicale.

"predictions": [
  {
    "content": "Monstera is a type of vine that thrives in bright indirect light…",
    "groundingMetadata": {
      "webSearchQueries": ["What's a monstera?"],
    }
  }
]

Vous pouvez récupérer ce résultat et l'afficher à l'aide des suggestions de recherche.

Conditions requises pour les suggestions de recherche

Les éléments suivants sont requis pour les suggestions de recherche :

Conditions requises pour l'affichage

Voici les exigences concernant l'affichage :

• Affichez la suggestion de recherche exactement telle qu'elle est fournie, et n'apportez aucune modification aux couleurs, aux polices ni à l'apparence. Assurez-vous que les suggestions de recherche s'affichent comme spécifié dans les exemples ci-dessous, y compris pour les modes clair et sombre :

• Chaque fois qu'une réponse avec ancrage est affichée, sa suggestion de recherche correspondante doit rester visible.
• Pour la marque, vous devez strictement respecter les consignes de Google concernant l'utilisation par les tiers des caractéristiques de la marque Google, disponibles dans le Centre de ressources pour la marque.
• Lorsque vous utilisez l'ancrage avec la recherche, des chips de suggestions de recherche s'affichent. Le champ contenant les chips de suggestions de recherche doit avoir la même largeur que la réponse ancrée du LLM.

Comportement au moment du clic

Lorsqu'un utilisateur appuie sur le chip, il est directement redirigé vers une page de résultats de recherche (SRP) pour le terme de recherche affiché dans le chip. Le SRP peut s'ouvrir dans votre navigateur intégré ou dans une application de navigateur distincte. Il est important de ne pas minimiser, supprimer ni masquer l'affichage du SRP. L'exemple animé suivant illustre l'interaction de type "tap-to-SRP" (clic vers SRP).

Comportement au moment du clic

Code permettant d'implémenter une suggestion de recherche

Lorsque vous utilisez l'API pour ancrer une réponse à la recherche, la réponse du modèle fournit un style HTML et CSS conforme dans le champ renderedContent, que vous implémentez pour afficher les suggestions de recherche dans votre application.

Auparavant, les suggestions de recherche étaient appelées points d'entrée de recherche. Bien que vous puissiez trouver des références aux points d'entrée de recherche dans certains champs d'API, les deux termes font référence aux suggestions de recherche actuelles que vous recevez dans la réponse de l'API.

L'exemple suivant montre comment utiliser curl pour ancrer une réponse à la recherche :

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "Why is the sky blue?"
      }
    },
    "tools": [
      {
        "googleSearch": {}
      }
    ]
  }'

Changements dans la facturation avec Gemini 3

Lorsque vous utilisez l'ancrage avec la recherche Google sur les modèles Gemini 3, la facturation s'applique à chaque requête de recherche générée par Gemini et envoyée à la recherche. Une seule requête peut générer une ou plusieurs requêtes de recherche.

Exemple

Cet exemple montre un exemple de requête utilisateur et de requêtes de recherche qui pourraient être facturées.

• Requête utilisateur : Parle-moi de la vie d'Albert Einstein.
• Gemini peut générer les requêtes de recherche suivantes :
  • Albert Einstein naissance et éducation
  • Théorie de la relativité d'Albert Einstein
  • La vie d'Albert Einstein aux États-Unis

Dans cet exemple, ces trois requêtes de recherche sont facturées.

Étapes suivantes

• Pour en savoir plus sur l'ancrage, consultez la section Présentation de l'ancrage.
• Découvrez comment envoyer des requêtes de chat.
• Découvrez les bonnes pratiques d'IA responsable et les filtres de sécurité de Gemini Enterprise Agent Platform.