La fonctionnalité d'ancrage avec la recherche Google de l'API Gemini et d'AI Studio peut être utilisée pour améliorer la précision et la fraîcheur des réponses du modèle. En plus de fournir des réponses plus factuelles, lorsque l'ancrage avec la recherche Google est activé, l'API Gemini renvoie des sources d'ancrage (liens d'accompagnement intégrés) et des suggestions de recherche Google avec le contenu de la réponse. Les suggestions de recherche redirigent les utilisateurs vers les résultats de recherche correspondant à la réponse avec ancrage.
Ce guide vous aidera à commencer à utiliser l'ancrage dans la recherche Google à l'aide de l'un des SDK de l'API Gemini ou de l'API REST.
Configurer l'ancrage de la recherche
À partir de Gemini 2.0, la recherche Google est disponible en tant qu'outil. Cela signifie que le modèle peut décider quand utiliser la recherche Google. L'exemple suivant montre comment configurer la recherche en tant qu'outil.
from google import genai
from google.genai.types import Tool, GenerateContentConfig, GoogleSearch
client = genai.Client()
model_id = "gemini-2.0-flash"
google_search_tool = Tool(
google_search = GoogleSearch()
)
response = client.models.generate_content(
model=model_id,
contents="When is the next total solar eclipse in the United States?",
config=GenerateContentConfig(
tools=[google_search_tool],
response_modalities=["TEXT"],
)
)
for each in response.candidates[0].content.parts:
print(each.text)
# Example response:
# The next total solar eclipse visible in the contiguous United States will be on ...
# To get grounding metadata as web content.
print(response.candidates[0].grounding_metadata.search_entry_point.rendered_content)
La fonctionnalité de recherche en tant qu'outil permet également d'effectuer des recherches multi-tours et des requêtes multi-outils (par exemple, en combinant la mise à la terre avec la recherche Google et l'exécution de code).
La recherche en tant qu'outil permet d'utiliser des requêtes et des workflows complexes qui nécessitent de la planification, du raisonnement et de la réflexion:
- Ancrage pour améliorer la facticité et la récence, et fournir des réponses plus précises
- Récupération d'artefacts sur le Web pour effectuer une analyse plus approfondie
- Trouver des images, des vidéos ou d'autres contenus multimédias pertinents pour faciliter les tâches de raisonnement ou de génération multimodales
- Codage, dépannage technique et autres tâches spécialisées
- Rechercher des informations spécifiques à une région ou aider à traduire des contenus de manière précise
- Trouver des sites Web pertinents pour poursuivre la navigation
L'ancrage dans la recherche Google fonctionne avec toutes les langues disponibles lors de l'utilisation d'invites textuelles. Avec le niveau payant de l'API Gemini Developer, vous pouvez effectuer sans frais 1 500 requêtes d'ancrage dans la recherche Google par jour, et les requêtes supplémentaires sont facturées au tarif standard de 35 USD pour 1 000 requêtes.
Pour en savoir plus, essayez le notebook de l'outil de recherche.
Suggestions de recherche Google
Pour utiliser l'ancrage avec la recherche Google, vous devez afficher les suggestions de recherche Google, qui sont des requêtes suggérées incluses dans les métadonnées de la réponse ancrée. Pour en savoir plus sur les exigences d'affichage, consultez Utiliser les suggestions de recherche Google.
Récupérer des informations à partir de la recherche Google
Récupération dynamique
Certaines requêtes sont plus susceptibles de bénéficier de l'ancrage avec la recherche Google que d'autres. La fonctionnalité de récupération dynamique vous permet de mieux contrôler quand utiliser l'ancrage dans la recherche Google.
Si le mode de récupération dynamique n'est pas spécifié, l'ancrage dans la recherche Google est toujours déclenché. Si le mode est défini sur "dynamique", le modèle décide quand utiliser la mise à la terre en fonction d'un seuil que vous pouvez configurer. Le seuil est une valeur à virgule flottante comprise entre 0 et 1, et sa valeur par défaut est 0,3. Si la valeur du seuil est égale à 0, la réponse est toujours ancrée dans la recherche Google. Si elle est égale à 1, elle ne l'est jamais.
Fonctionnement de la récupération dynamique
Vous pouvez utiliser la récupération dynamique dans votre requête pour choisir quand activer l'ancrage dans la recherche Google. Cela est utile lorsque la requête ne nécessite pas de réponse basée sur la recherche Google et que le modèle peut fournir une réponse basée sur ses propres connaissances sans ancrage. Cela vous permet de gérer plus efficacement la latence, la qualité et les coûts.
Avant d'appeler la configuration de récupération dynamique dans votre requête, comprenez la terminologie suivante :
Score de prédiction: lorsque vous demandez une réponse fondée, Gemini attribue un score de prédiction à la requête. Le score de prédiction est une valeur à virgule flottante comprise entre 0 et 1. Sa valeur dépend de la possibilité de l'ancrer avec les informations les plus récentes de la recherche Google. Par conséquent, si une requête nécessite une réponse basée sur les faits les plus récents sur le Web, elle a un score de prédiction plus élevé. Une requête pour laquelle une réponse générée par le modèle est suffisante a un score de prédiction plus faible.
Voici des exemples de suggestions et leurs scores de prédiction.
Requête Score de prédiction Commentaire "Écris un poème sur les pivoines" 0,13 Le modèle peut s'appuyer sur ses connaissances et la réponse n'a pas besoin d'être ancrée. "Propose un jouet pour un enfant de 2 ans" 0,36 Le modèle peut s'appuyer sur ses connaissances et la réponse n'a pas besoin d'être ancrée. "Peux-tu me donner la recette d'un guacamole d'inspiration asiatique ?" 0,55 La recherche Google peut fournir une réponse fondée, mais la justification n'est pas strictement nécessaire. Les connaissances du modèle peuvent suffire. "Qu'est-ce qu'Agent Builder ? Comment est facturé l'ancrage dans Agent Builder ?" 0.72 Nécessite la recherche Google pour générer une réponse pertinente. "Qui a remporté le dernier Grand Prix de F1 ?" 0,97 Nécessite la recherche Google pour générer une réponse pertinente. Seuil: dans votre requête API, vous pouvez spécifier une configuration de récupération dynamique avec un seuil. Le seuil est une valeur à virgule flottante comprise entre 0 et 1, et sa valeur par défaut est 0,3. Si la valeur du seuil est nulle, la réponse est toujours ancrée dans la recherche Google. Pour toutes les autres valeurs de seuil, les règles suivantes s'appliquent :
- Si le score de prédiction est supérieur ou égal au seuil, la réponse est basée sur la recherche Google. Un seuil plus faible implique que davantage de requêtes ont des réponses générées à l'aide de l'ancrage avec la recherche Google.
- Si le score de prédiction est inférieur au seuil, le modèle peut générer la réponse, mais elle n'est pas ancrée dans la recherche Google.
Pour savoir comment définir le seuil de récupération dynamique à l'aide d'un SDK ou de l'API REST, consultez l'exemple de code approprié.
Pour trouver un seuil adapté à vos besoins commerciaux, vous pouvez créer un ensemble représentatif de requêtes que vous êtes susceptible de rencontrer. Vous pouvez ensuite trier les requêtes en fonction du score de prédiction dans la réponse et sélectionner un seuil adapté à votre cas d'utilisation.
Une réponse fondée
Si votre requête est correctement ancrée dans la recherche Google, la réponse inclura groundingMetadata. Une réponse justifiée peut se présenter comme suit (certaines parties de la réponse ont été omises par souci de concision):
{
"candidates": [
{
"content": {
"parts": [
{
"text": "Carlos Alcaraz won the Gentlemen's Singles title at the 2024 Wimbledon Championships. He defeated Novak Djokovic in the final, winning his second consecutive Wimbledon title and fourth Grand Slam title overall. \n"
}
],
"role": "model"
},
...
"groundingMetadata": {
"searchEntryPoint": {
"renderedContent": "\u003cstyle\u003e\n.container {\n align-items: center;\n border-radius: 8px;\n display: flex;\n font-family: Google Sans, Roboto, sans-serif;\n font-size: 14px;\n line-height: 20px;\n padding: 8px 12px;\n}\n.chip {\n display: inline-block;\n border: solid 1px;\n border-radius: 16px;\n min-width: 14px;\n padding: 5px 16px;\n text-align: center;\n user-select: none;\n margin: 0 8px;\n -webkit-tap-highlight-color: transparent;\n}\n.carousel {\n overflow: auto;\n scrollbar-width: none;\n white-space: nowrap;\n margin-right: -12px;\n}\n.headline {\n display: flex;\n margin-right: 4px;\n}\n.gradient-container {\n position: relative;\n}\n.gradient {\n position: absolute;\n transform: translate(3px, -9px);\n height: 36px;\n width: 9px;\n}\n@media (prefers-color-scheme: light) {\n .container {\n background-color: #fafafa;\n box-shadow: 0 0 0 1px #0000000f;\n }\n .headline-label {\n color: #1f1f1f;\n }\n .chip {\n background-color: #ffffff;\n border-color: #d2d2d2;\n color: #5e5e5e;\n text-decoration: none;\n }\n .chip:hover {\n background-color: #f2f2f2;\n }\n .chip:focus {\n background-color: #f2f2f2;\n }\n .chip:active {\n background-color: #d8d8d8;\n border-color: #b6b6b6;\n }\n .logo-dark {\n display: none;\n }\n .gradient {\n background: linear-gradient(90deg, #fafafa 15%, #fafafa00 100%);\n }\n}\n@media (prefers-color-scheme: dark) {\n .container {\n background-color: #1f1f1f;\n box-shadow: 0 0 0 1px #ffffff26;\n }\n .headline-label {\n color: #fff;\n }\n .chip {\n background-color: #2c2c2c;\n border-color: #3c4043;\n color: #fff;\n text-decoration: none;\n }\n .chip:hover {\n background-color: #353536;\n }\n .chip:focus {\n background-color: #353536;\n }\n .chip:active {\n background-color: #464849;\n border-color: #53575b;\n }\n .logo-light {\n display: none;\n }\n .gradient {\n background: linear-gradient(90deg, #1f1f1f 15%, #1f1f1f00 100%);\n }\n}\n\u003c/style\u003e\n\u003cdiv class=\"container\"\u003e\n \u003cdiv class=\"headline\"\u003e\n \u003csvg class=\"logo-light\" width=\"18\" height=\"18\" viewBox=\"9 9 35 35\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\"\u003e\n \u003cpath fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M42.8622 27.0064C42.8622 25.7839 42.7525 24.6084 42.5487 23.4799H26.3109V30.1568H35.5897C35.1821 32.3041 33.9596 34.1222 32.1258 35.3448V39.6864H37.7213C40.9814 36.677 42.8622 32.2571 42.8622 27.0064V27.0064Z\" fill=\"#4285F4\"/\u003e\n \u003cpath fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M26.3109 43.8555C30.9659 43.8555 34.8687 42.3195 37.7213 39.6863L32.1258 35.3447C30.5898 36.3792 28.6306 37.0061 26.3109 37.0061C21.8282 37.0061 18.0195 33.9811 16.6559 29.906H10.9194V34.3573C13.7563 39.9841 19.5712 43.8555 26.3109 43.8555V43.8555Z\" fill=\"#34A853\"/\u003e\n \u003cpath fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M16.6559 29.8904C16.3111 28.8559 16.1074 27.7588 16.1074 26.6146C16.1074 25.4704 16.3111 24.3733 16.6559 23.3388V18.8875H10.9194C9.74388 21.2072 9.06992 23.8247 9.06992 26.6146C9.06992 29.4045 9.74388 32.022 10.9194 34.3417L15.3864 30.8621L16.6559 29.8904V29.8904Z\" fill=\"#FBBC05\"/\u003e\n \u003cpath fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M26.3109 16.2386C28.85 16.2386 31.107 17.1164 32.9095 18.8091L37.8466 13.8719C34.853 11.082 30.9659 9.3736 26.3109 9.3736C19.5712 9.3736 13.7563 13.245 10.9194 18.8875L16.6559 23.3388C18.0195 19.2636 21.8282 16.2386 26.3109 16.2386V16.2386Z\" fill=\"#EA4335\"/\u003e\n \u003c/svg\u003e\n \u003csvg class=\"logo-dark\" width=\"18\" height=\"18\" viewBox=\"0 0 48 48\" xmlns=\"http://www.w3.org/2000/svg\"\u003e\n \u003ccircle cx=\"24\" cy=\"23\" fill=\"#FFF\" r=\"22\"/\u003e\n \u003cpath d=\"M33.76 34.26c2.75-2.56 4.49-6.37 4.49-11.26 0-.89-.08-1.84-.29-3H24.01v5.99h8.03c-.4 2.02-1.5 3.56-3.07 4.56v.75l3.91 2.97h.88z\" fill=\"#4285F4\"/\u003e\n \u003cpath d=\"M15.58 25.77A8.845 8.845 0 0 0 24 31.86c1.92 0 3.62-.46 4.97-1.31l4.79 3.71C31.14 36.7 27.65 38 24 38c-5.93 0-11.01-3.4-13.45-8.36l.17-1.01 4.06-2.85h.8z\" fill=\"#34A853\"/\u003e\n \u003cpath d=\"M15.59 20.21a8.864 8.864 0 0 0 0 5.58l-5.03 3.86c-.98-2-1.53-4.25-1.53-6.64 0-2.39.55-4.64 1.53-6.64l1-.22 3.81 2.98.22 1.08z\" fill=\"#FBBC05\"/\u003e\n \u003cpath d=\"M24 14.14c2.11 0 4.02.75 5.52 1.98l4.36-4.36C31.22 9.43 27.81 8 24 8c-5.93 0-11.01 3.4-13.45 8.36l5.03 3.85A8.86 8.86 0 0 1 24 14.14z\" fill=\"#EA4335\"/\u003e\n \u003c/svg\u003e\n \u003cdiv class=\"gradient-container\"\u003e\u003cdiv class=\"gradient\"\u003e\u003c/div\u003e\u003c/div\u003e\n \u003c/div\u003e\n \u003cdiv class=\"carousel\"\u003e\n \u003ca class=\"chip\" href=\"https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4x8Epe-gzpwRBvp7o3RZh2m1ygq1EHktn0OWCtvTXjad4bb1zSuqfJd6OEuZZ9_SXZ_P2SvCpJM7NaFfQfiZs6064MeqXego0vSbV9LlAZoxTdbxWK1hFeqTG6kA13YJf7Fbu1SqBYM0cFM4zo0G_sD9NKYWcOCQMvDLDEJFhjrC9DM_QobBIAMq-gWN95G5tvt6_z6EuPN8QY=\"\u003ewho won wimbledon 2024\u003c/a\u003e\n \u003c/div\u003e\n\u003c/div\u003e\n"
},
"groundingChunks": [
{
"web": {
"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4whET1ta3sDETZvcicd8FeNe4z0VuduVsxrT677KQRp2rYghXI0VpfYbIMVI3THcTuMwggRCbFXS_wVvW0UmGzMe9h2fyrkvsnQPJyikJasNIbjJLPX0StM4Bd694-ZVle56MmRA4YiUvwSqad1w6O2opmWnw==",
"title": "wikipedia.org"
}
},
{
"web": {
"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4wR1M-9-yMPUr_KdHlnoAmQ8ZX90DtQ_vDYTjtP2oR5RH4tRP04uqKPLmesvo64BBkPeYLC2EpVDxv9ngO3S1fs2xh-e78fY4m0GAtgNlahUkm_tBm_sih5kFPc7ill9u2uwesNGUkwrQlmP2mfWNU5lMMr23HGktr6t0sV0QYlzQq7odVoBxYWlQ_sqWFH",
"title": "wikipedia.org"
}
},
{
"web": {
"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4wsDmROzbP-tmt8GdwCW_pqISTZ4IRbBuoaMyaHfcQg8WW-yKRQQvMDTPAuLxJh-8_U8_iw_6JKFbQ8M9oVYtaFdWFK4gOtL4RrC9Jyqc5BNpuxp6uLEKgL5-9TggtNvO97PyCfziDFXPsxylwI1HcfQdrz3Jy7ZdOL4XM-S5rC0lF2S3VWW0IEAEtS7WX861meBYVjIuuF_mIr3spYPqWLhbAY2Spj-4_ba8DjRvmevIFUhRuESTKvBfmpxNSM",
"title": "cbssports.com"
}
},
{
"web": {
"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4yzjLkorHiUKjhOPkWaZ9b4cO-cLG-02vlEl6xTBjMUjyhK04qSIclAa7heR41JQ6AAVXmNdS3WDrLOV4Wli-iezyzW8QPQ4vgnmO_egdsuxhcGk3-Fp8-yfqNLvgXFwY5mPo6QRhvplOFv0_x9mAcka18QuAXtj0SPvJfZhUEgYLCtCrucDS5XFc5HmRBcG1tqFdKSE1ihnp8KLdaWMhrUQI21hHS9",
"title": "jagranjosh.com"
}
},
{
"web": {
"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4y9L4oeNGWCatFz63b9PpP3ys-Wi_zwnkUT5ji9lY7gPUJQcsmmE87q88GSdZqzcx5nZG9usot5FYk2yK-FAGvCRE6JsUQJB_W11_kJU2HVV1BTPiZ4SAgm8XDFIxpCZXnXmEx5HUfRqQm_zav7CvS2qjA2x3__qLME6Jy7R5oza1C5_aqjQu422le9CaigThS5bvJoMo-ZGcXdBUCj2CqoXNVjMA==",
"title": "apnews.com"
}
}
],
"groundingSupports": [
{
"segment": {
"endIndex": 85,
"text": "Carlos Alcaraz won the Gentlemen's Singles title at the 2024 Wimbledon Championships."
},
"groundingChunkIndices": [
0,
1,
2,
3
],
"confidenceScores": [
0.97380733,
0.97380733,
0.97380733,
0.97380733
]
},
{
"segment": {
"startIndex": 86,
"endIndex": 210,
"text": "He defeated Novak Djokovic in the final, winning his second consecutive Wimbledon title and fourth Grand Slam title overall."
},
"groundingChunkIndices": [
1,
0,
4
],
"confidenceScores": [
0.96145374,
0.96145374,
0.96145374
]
}
],
"webSearchQueries": [
"who won wimbledon 2024"
]
}
}
],
...
}
Si la réponse n'inclut pas groundingMetadata, cela signifie que la réponse n'a pas été correctement mise à la terre. Plusieurs raisons peuvent expliquer cette situation, comme une faible pertinence de la source ou des informations incomplètes dans la réponse du modèle.
Lorsqu'un résultat ancré est généré, les métadonnées contiennent des URI qui redirigent vers les éditeurs du contenu utilisé pour générer le résultat ancré.
Ces URI contiennent le sous-domaine vertexaisearch, comme dans cet exemple tronqué : https://vertexaisearch.cloud.google.com/grounding-api-redirect/.... Les métadonnées contiennent également les domaines des éditeurs. Les URI fournis restent accessibles pendant 30 jours après la génération du résultat.
Le champ renderedContent dans searchEntryPoint est le code fourni pour implémenter les suggestions de recherche Google. Pour en savoir plus, consultez Utiliser les suggestions de recherche Google.