La función de fundamentación con la Búsqueda de Google en la API de Gemini y AI Studio se puede usar para mejorar la precisión y la actualización de las respuestas del modelo. Además de las respuestas más fácticas, cuando se habilita la función Fundamentos con la Búsqueda de Google, la API de Gemini muestra fuentes de fundamentación (vínculos de respaldo intercalados) y Sugerencias de la Búsqueda de Google junto con el contenido de la respuesta. Las sugerencias de búsqueda dirigen a los usuarios a los resultados de la búsqueda que corresponden a la respuesta fundamentada.
Esta guía te ayudará a comenzar a usar la Fundamentación con la Búsqueda de Google con uno de los SDKs de la API de Gemini o la API de REST.
Configura la fundamentación de la Búsqueda
A partir de Gemini 2.0, la Búsqueda de Google está disponible como herramienta. Esto significa que el modelo puede decidir cuándo usar la Búsqueda de Google. En el siguiente ejemplo, se muestra cómo configurar la Búsqueda como una herramienta.
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 funcionalidad de Búsqueda como herramienta también habilita búsquedas de varios turnos y consultas de varias herramientas (por ejemplo, combinar Grounding con la Búsqueda de Google y la ejecución de código).
La búsqueda como herramienta permite indicaciones y flujos de trabajo complejos que requieren planificación, razonamiento y pensamiento:
- Fundamentación para mejorar la veracidad y la actualidad, y proporcionar respuestas más precisas
- Cómo recuperar artefactos de la Web para realizar un análisis más detallado
- Encontrar imágenes, videos y otros elementos multimedia relevantes para ayudar en tareas de razonamiento o generación multimodal
- Programación, solución de problemas técnicos y otras tareas especializadas
- Encontrar información específica de la región o ayudar a traducir el contenido con precisión
- Cómo encontrar sitios web relevantes para seguir navegando
La función de fundamentación con la Búsqueda de Google funciona con todos los idiomas disponibles cuando se hacen instrucciones de texto. En el nivel pagado de la API de Gemini Developer, puedes obtener 1,500 consultas de Grounding with Google Search por día de forma gratuita, con las consultas adicionales facturadas a USD 35 por cada 1,000 consultas.
Para obtener más información, prueba el notebook de la herramienta de búsqueda.
Sugerencias de la Búsqueda de Google
Para usar la fundamentación con la Búsqueda de Google, debes mostrar las sugerencias de la Búsqueda de Google, que son búsquedas sugeridas incluidas en los metadatos de la respuesta fundamentada. Para obtener más información sobre los requisitos de visualización, consulta Cómo usar las sugerencias de la Búsqueda de Google.
Recuperación de la Búsqueda de Google
Recuperación dinámica
Es probable que algunas búsquedas se beneficien más de la Fundamentación con la Búsqueda de Google que otras. La función de recuperación dinámica te brinda control adicional sobre cuándo usar la Fundamentación con la Búsqueda de Google.
Si no se especifica el modo de recuperación dinámico, siempre se activa la vinculación con la Búsqueda de Google. Si el modo está configurado como dinámico, el modelo decide cuándo usar la conexión a tierra según un umbral que puedes configurar. El umbral es un valor de punto flotante en el rango [0,1] y su valor predeterminado es 0.3. Si el valor del umbral es 0, la respuesta siempre se basa en la Búsqueda de Google. Si es 1, nunca es así.
Cómo funciona la recuperación dinámica
Puedes usar la recuperación dinámica en tu solicitud para elegir cuándo activar la Fundamentación con la Búsqueda de Google. Esto es útil cuando la instrucción no requiere una respuesta basada en la Búsqueda de Google y el modelo puede proporcionar una respuesta basada en su propio conocimiento sin fundamentación. Esto te ayuda a administrar la latencia, la calidad y el costo de manera más eficaz.
Antes de invocar la configuración de recuperación dinámica en tu solicitud, ten en cuenta la siguiente terminología:
Puntuación de predicción: Cuando solicitas una respuesta basada en la realidad, Gemini asigna una puntuación de predicción a la instrucción. La puntuación de la predicción es un valor de punto flotante en el rango [0,1]. Su valor depende de si la instrucción puede beneficiarse de fundamentar la respuesta con la información más actualizada de la Búsqueda de Google. Por lo tanto, si una instrucción requiere una respuesta basada en los hechos más recientes de la Web, tiene una puntuación de predicción más alta. Una instrucción para la que una respuesta generada por un modelo es suficiente tiene una puntuación de predicción más baja.
Estos son ejemplos de algunas instrucciones y sus puntuaciones de predicción.
Instrucción Puntuación de predicción Comentario "Escribe un poema sobre las peonías" 0.13 El modelo puede basarse en su conocimiento, y la respuesta no necesita fundamentación. "Sugiere un juguete para un niño de 2 años" 0.36 El modelo puede basarse en su conocimiento, y la respuesta no necesita fundamentación. "¿Puedes darme la receta de un guacamole inspirado en la cocina asiática?" 0.55 La Búsqueda de Google puede dar una respuesta fundamentada, pero la fundamentación no es estrictamente necesaria; el conocimiento del modelo podría ser suficiente. "¿Qué es Agent Builder? "¿Cómo se factura la conexión a tierra en Agent Builder?" 0.72 Requiere que la Búsqueda de Google genere una respuesta fundamentada. "¿Quién ganó el último Gran Premio de Fórmula 1?" 0.97 Requiere que la Búsqueda de Google genere una respuesta fundamentada. Umbral: En tu solicitud a la API, puedes especificar una configuración de recuperación dinámica con un umbral. El umbral es un valor de punto flotante en el rango [0,1] y su valor predeterminado es 0.3. Si el valor del umbral es cero, la respuesta siempre se fundamenta con la Búsqueda de Google. Para todos los demás valores del umbral, se aplica lo siguiente:
- Si la puntuación de predicción es mayor o igual que el umbral, la respuesta se basa en la Búsqueda de Google. Un umbral más bajo implica que más instrucciones tienen respuestas que se generan con la Fundamentación con la Búsqueda de Google.
- Si la puntuación de la predicción es inferior al umbral, es posible que el modelo genere la respuesta, pero no se basa en la Búsqueda de Google.
Para obtener información sobre cómo establecer el umbral de recuperación dinámico con un SDK o la API de REST, consulta el ejemplo de código correspondiente.
Para encontrar un buen umbral que se adapte a las necesidades de tu empresa, puedes crear un conjunto representativo de las búsquedas que esperas encontrar. Luego, puedes ordenar las consultas según la puntuación de predicción en la respuesta y seleccionar un buen umbral para tu caso de uso.
Una respuesta fundamentada
Si la instrucción se fundamenta correctamente en la Búsqueda de Google, la respuesta incluirá groundingMetadata. Una respuesta fundamentada podría verse de la siguiente manera (se omitieron partes de la respuesta por brevedad):
{
"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 respuesta no incluye groundingMetadata, significa que la respuesta
no se aplicó correctamente. Esto puede ocurrir por varios motivos, como la baja relevancia de la fuente o la información incompleta en la respuesta del modelo.
Cuando se genera un resultado basado en la ubicación, los metadatos contienen URIs que redireccionan a los editores del contenido que se usó para generar el resultado basado en la ubicación.
Estos URI contienen el subdominio vertexaisearch, como en este ejemplo truncado: https://vertexaisearch.cloud.google.com/grounding-api-redirect/.... Los metadatos también contienen los dominios de los publicadores. Se puede acceder a los URIs proporcionados durante 30 días después de que se genera el resultado de la conexión a tierra.
El campo renderedContent dentro de searchEntryPoint es el código proporcionado para implementar las sugerencias de la Búsqueda de Google. Consulta Cómo usar las sugerencias de la Búsqueda de Google para obtener más información.