Lección 37 · 5 min · Gratis

Fundamentación de información con modelos Gemini

Copyright 2026 Google LLC.

# @title Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

En este notebook, aprenderás a usar la fundamentación de información con los modelos Gemini.

La fundamentación de información es el proceso de conectar estos modelos a fuentes de información específicas y verificables para mejorar la precisión, relevancia y corrección factual de sus respuestas. Si bien los LLM se entrenan con grandes cantidades de datos, este conocimiento puede ser general, desactualizado o carecer de contexto específico para tareas o dominios particulares. La fundamentación ayuda a cerrar esta brecha al proporcionar al LLM acceso a información curada y actualizada.

Aquí experimentarás con:

Fundamentación de información usando la fundamentación de Google Search
Fundamentación de información del mundo real usando la fundamentación de Google Maps
Cómo agregar videos de YouTube usando URI directos
Cómo usar el contexto de URL para incluir URL de sitios web, PDF o imágenes como contexto en tu prompt

Nota: Este notebook usa la API de Interacciones, la forma más reciente de interactuar con los modelos Gemini. ¿Buscas la versión generateContent? Consulta la rama de archivo.

Configura el SDK y el cliente

Instala el SDK

Esta guía usa el SDK de Python google-genai para conectarse a los modelos Gemini.

%pip install -U -q "google-genai>=2.9.0"  # 2.0 for Interactions API

Configura tu clave de API

Para ejecutar la siguiente celda, tu clave de API debe estar almacenada en un Secreto de Colab llamado GEMINI_API_KEY. Si aún no tienes una clave de API o no sabes cómo crear un Secreto de Colab, consulta Autenticación para ver un tutorial.

from google.colab import userdata

GEMINI_API_KEY = userdata.get("GEMINI_API_KEY")

Selecciona el modelo que quieres usar en esta guía:

from google import genai
from google.genai import types

client = genai.Client(api_key=GEMINI_API_KEY)

MODEL_ID = "gemini-3.7-flash" # @param ["gemini-3.1-pro-preview", "gemini-3.7-flash", "gemini-3.5-flash-lite", "gemini-2.5-pro"] {"allow-input":true, isTemplate: true}

Usa la fundamentación de Google Search

La fundamentación de Google Search es particularmente útil para consultas que requieren información actual o conocimiento externo. Usando Google Search, Gemini puede acceder a información casi en tiempo real y dar mejores respuestas.

Para habilitar Google Search, simplemente agrega la herramienta google_search en el interactions.create de esta manera:

    config={
      "tools": [
        {
          "google_search": {}
        }
      ]
    },

La respuesta de interactions.create contiene una lista de steps. Para respuestas de texto, accede a la salida a través de interaction.steps[-1].content[0].text.

from IPython.display import display, HTML, Markdown

interaction = client.interactions.create(
    model=MODEL_ID,
    input="What was the latest Indian Premier League match and who won?",
    tools=[{"type": "google_search"}],
)

# Print the text response
text_output = next((o for o in interaction.steps if o.type == "text"), None)
if text_output:
    display(Markdown(f"**Response**:\n {text_output.text}"))

Puedes ver que ejecutar el mismo prompt sin fundamentación de búsqueda te da información desactualizada:

from IPython.display import display, Markdown

interaction = client.interactions.create(
    model=MODEL_ID,
    input="What was the latest Indian Premier League match and who won?",
)

text_output = next((o for o in interaction.steps if o.type == "text"), None)
if text_output:
    display(Markdown(text_output.text))

Para más ejemplos, consulta el notebook dedicado .

Usa la fundamentación de Google Maps

La fundamentación de Google Maps te permite incorporar fácilmente la funcionalidad de ubicación en tus aplicaciones. Cuando un prompt tiene contexto relacionado con datos de Maps, el modelo Gemini usa Google Maps para proporcionar respuestas precisas y actualizadas que son relevantes para la ubicación especificada o el área general.

Para habilitar la fundamentación con Google Maps, agrega la herramienta google_maps en el argumento tools de interactions.create, y opcionalmente proporciona una ubicación estructurada en el tool_config.

client.models.interactions.create(
    ...,
    config=types.GenerateContentConfig(
      # Enable the tool.
      tools=[types.Tool(google_maps=types.GoogleMaps())],
      # Provide structured location.
      tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
            lat_lng=types.LatLng(
                latitude=34.050481, longitude=-118.248526))),
    )
)

from IPython.display import display, Markdown

interaction = client.interactions.create(
    model=MODEL_ID,
    input="Do any cafes around here do a good flat white? I will walk up to 20 minutes away",
    tools=[{"type": "google_maps"}],
)

text_output = next((o for o in interaction.steps if o.type == "text"), None)
if text_output:
    display(Markdown(f"### Response\n {text_output.text}"))

Todas las salidas fundamentadas requieren que las fuentes se muestren después del texto de la respuesta. Este fragmento de código mostrará las fuentes.

# Note: Grounding metadata (sources/citations) is not yet available 
# in the Interactions API. The function below works with the generate_content API.

# def generate_sources(response):
#     grounding = response.candidates[0].grounding_metadata
#     ...
print("Grounding source display not yet available in Interactions API")

Grounding source display not yet available in Interactions API

La respuesta también incluye datos que puedes usar para armar enlaces en línea. Consulta la documentación de Fundamentación con Google Search para ver un ejemplo de esto.

Renderiza el widget contextual de Google Maps

Si estás creando una aplicación web, puedes agregar un widget interactivo que incluya una vista de mapa, la ubicación contextual, los lugares que Gemini consideró en la consulta y fragmentos de reseñas.

Para cargar el widget, realiza todos los siguientes pasos.

Adquiere una clave de API de Google Maps, habilitada para la API de Places y la API de JavaScript de Maps.
Solicita el token del widget en tu solicitud (con GoogleMaps(enable_widget=True)).
Carga la API de JavaScript de Maps y habilita la biblioteca de Places.
Renderiza el elemento <gmp-place-contextual/>, configurando context-token al valor de google_maps_widget_context_token devuelto en la respuesta de la API de Gemini.

Ten en cuenta que generar un widget puede agregar latencia adicional a la respuesta, por lo que se recomienda que no habilites el widget si no lo vas a mostrar.

Suponiendo que tienes una clave de API de Google Maps con ambas API habilitadas, el siguiente código muestra una forma de renderizar el widget.

from IPython.display import display, HTML

# Load or set your Maps API key here.
MAPS_API_KEY = userdata.get("MAPS_API_KEY")

# Google Maps widget rendering requires the Content-based API
# as the Interactions API does not yet return Maps widget data.
# This is for display purposes only.
interaction = client.interactions.create(
    model=MODEL_ID,
    input="Do any cafes around here do a good flat white? I will walk up to 20 minutes away",
    tools=[{"type": "google_maps"}],
)

text_output = next((o for o in interaction.steps if o.type == "text"), None)
if text_output:
    display(Markdown(text_output.text))

Ejecutar y renderizar el código anterior requerirá una clave de API de Maps. Una vez que lo tengas funcionando, el widget se verá así.

Rendered contextual Places widget

Fundamentación con enlaces de YouTube

Puedes incluir directamente una URL pública de YouTube en tu prompt. Los modelos Gemini procesarán el contenido del video para realizar tareas como resumir y responder preguntas sobre el contenido.

Esta capacidad aprovecha la comprensión multimodal de Gemini, lo que le permite analizar e interpretar datos de video junto con cualquier prompt de texto proporcionado.

Pasa la URL de YouTube como un tipo de entrada video:

yt_link = "https://www.youtube.com/watch?v=XV1kOFo1C8M"

interaction = client.interactions.create(
    model=MODEL_ID,
    input=[
        {
            "type": "video",
            "uri": yt_link,
        },
        {"type": "text", "text": "Summarize this video"},
    ],
)

Markdown(interaction.steps[-1].content[0].text)

Velocidad de fotogramas personalizada

Por defecto, el modelo muestrea un fotograma por segundo (FPS) del video. Puedes anular esta tasa de muestreo proporcionando un valor fps (fotogramas por segundo) personalizado en el parámetro video_metadata.

Establecer un FPS más alto puede ser beneficioso para videos con movimiento rápido o cuando se requiere un análisis temporal muy detallado. Por el contrario, un FPS más bajo se puede usar para videos largos y relativamente estáticos (como conferencias o grabaciones de seguridad) para reducir el consumo de tokens.

yt_link = "https://www.youtube.com/watch?v=XV1kOFo1C8M"

interaction = client.interactions.create(
    model=MODEL_ID,
    input=[
        {
            "type": "video",
            "uri": yt_link,
        },
        {"type": "text", "text": "Describe the action in this video with high detail."},
    ],
    video_metadata=types.VideoMetadata(fps=2) # Set custom FPS to 2
)

Markdown(interaction.steps[-1].content[0].text)

Pero también puedes usar el enlace como fuente de verdad para tu solicitud. En este ejemplo, primero preguntarás cómo los modelos Gemma pueden ayudar en los juegos de ajedrez:

yt_link = "https://www.youtube.com/watch?v=XV1kOFo1C8M"

interaction = client.interactions.create(
    model=MODEL_ID,
    input=[
        {
            "type": "video",
            "uri": yt_link,
        },
        {"type": "text", "text": "In 2 paragraphs, how can Gemma models help with chess games?"},
    ],
)

Markdown(interaction.steps[-1].content[0].text)

Ahora tu respuesta es más perspicaz para el tema que quieres, usando el conocimiento compartido en el video y no necesariamente disponible en el conocimiento del modelo.

Fundamentación de información usando el contexto de URL

La herramienta de Contexto de URL permite a los modelos Gemini acceder y procesar directamente el contenido de URL de páginas web específicas que proporcionas en tus solicitudes de API. Esto es increíblemente interesante porque permite que tus aplicaciones interactúen dinámicamente con información web en vivo sin que necesites preprocesar y alimentar manualmente ese contenido al modelo.

El Contexto de URL es efectivo porque permite a los modelos basar sus respuestas y análisis directamente en el contenido de las páginas web designadas. En lugar de depender únicamente de sus datos de entrenamiento generales o de búsquedas web amplias (que también son herramientas de fundamentación valiosas), el Contexto de URL ancla la comprensión del modelo a la información específica presente en esas URL.

Procesa URL de sitios web

Si quieres que Gemini fundamente específicamente sus respuestas gracias al contenido de un sitio web específico, simplemente agrega las URL en tu prompt y habilita la herramienta agregándola a tu configuración:

config = {
  "tools": [
    {
      "url_context": {}
    }
  ],
}

Puedes agregar hasta 20 enlaces en tu prompt.

prompt = """
  Based on https://ai.google.dev/gemini-api/docs/models, what are the key
  differences between Gemini 1.5, Gemini 2.0 and Gemini 2.5 models?
  Create a markdown table comparing the differences.
"""

interaction = client.interactions.create(
    model=MODEL_ID,
    input=prompt,
    tools=[{"type": "url_context"}],
)

text_output = next((o for o in interaction.steps if o.type == "text"), None)
if text_output:
    display(Markdown(text_output.text))

Puedes ver el estado de la recuperación usando url_context_metadata:

# URL context metadata is available on the interaction object
# Note: The exact fields may differ from the generate_content API
print("URL context metadata is not yet available in the Interactions API.")

URL context metadata is not yet available in the Interactions API.
See Not_yet_in_Interactions_API.ipynb for current limitations.

Agrega PDF por URL

Gemini puede procesar PDF desde una URL. Puedes pasar el URI directamente como una entrada document, o usar la herramienta url_context:

# Method 1: Pass the PDF URI directly as a document input
pdf_url = "https://abc.xyz/assets/cc/27/3ada14014efbadd7a58472f1f3f4/2025q2-alphabet-earnings-release.pdf"

interaction = client.interactions.create(
    model=MODEL_ID,
    input=[
        {
            "type": "document",
            "uri": pdf_url,
            "mime_type": "application/pdf",
        },
        {"type": "text", "text": "Can you give me an overview of the content of this pdf?"},
    ],
)

text_output = next((o for o in interaction.steps if o.type == "text"), None)
if text_output:
    display(Markdown(text_output.text.replace("$", r"\$")))

Grounding.ipynb:cell_41:15: SyntaxWarning: invalid escape sequence '\$'

# Method 2: Use url_context (the model will fetch and process the URL)
interaction = client.interactions.create(
    model=MODEL_ID,
    input="""
        Can you give me an overview of the content of this pdf?
        https://abc.xyz/assets/cc/27/3ada14014efbadd7a58472f1f3f4/2025q2-alphabet-earnings-release.pdf
    """,
    tools=[{"type": "url_context"}],
)

text_output = next((o for o in interaction.steps if o.type == "text"), None)
if text_output:
    display(Markdown(text_output.text.replace("$", r"\$")))

Agrega imágenes por URL

Gemini también puede procesar imágenes desde una URL. Puedes pasar el URI directamente como una entrada image, o usar url_context:

# Method 1: Pass the image URI directly
image_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/4/40/Trombone.svg/960px-Trombone.svg.png"

interaction = client.interactions.create(
    model=MODEL_ID,
    input=[
        {
            "type": "image",
            "uri": image_url,
        },
        {"type": "text", "text": "Can you help me name the numbered parts of that instrument, in French?"},
    ],
)

text_output = next((o for o in interaction.steps if o.type == "text"), None)
if text_output:
    display(Markdown(text_output.text))

# Method 2: Use url_context
interaction = client.interactions.create(
    model=MODEL_ID,
    input="""
        Can you help me name the numbered parts of that instrument, in French?
        https://upload.wikimedia.org/wikipedia/commons/thumb/4/40/Trombone.svg/960px-Trombone.svg.png
    """,
    tools=[{"type": "url_context"}],
)

text_output = next((o for o in interaction.steps if o.type == "text"), None)
if text_output:
    display(Markdown(text_output.text))

Mezcla la fundamentación de búsqueda y el contexto de URL

Las diferentes herramientas también se pueden usar en conjunto agregándolas ambas a la configuración. Es una buena manera de guiar a Gemini en la dirección correcta y luego dejar que haga su magia usando la fundamentación de búsqueda.

prompt = """
  Can you give me an overview of the content of this pdf?
  https://abc.xyz/assets/cc/27/3ada14014efbadd7a58472f1f3f4/2025q2-alphabet-earnings-release.pdf
  Search on the web for the reaction of the main financial analysts, what's the trend?
"""

interaction = client.interactions.create(
    model=MODEL_ID,
    input=prompt,
    tools=[{"type": "url_context"}, {"type": "google_search"}],
)

text_output = next((o for o in interaction.steps if o.type == "text"), None)
if text_output:
    display(Markdown(text_output.text.replace("$", r"\$")))

Próximos pasos

Para obtener más detalles sobre el uso de la fundamentación de Google Search, consulta el libro de cocina de Fundamentación de búsqueda.
Si buscas otros escenarios usando videos, echa un vistazo al libro de cocina de Comprensión de videos.

También consulta las otras capacidades de Gemini que puedes encontrar en los inicios rápidos de Gemini.

Lección del curso «Gemini API Cookbook (quickstarts)» de Google, publicado con licencia Apache 2.0. Traducción y adaptación al español de IA con Clase. IA con Clase no está afiliado a Google. Ver el original · Licencia

Esta lección es gratuita. El resto del curso se abre con la Membresía de IA con Clase, que incluye todos los cursos del catálogo. Ver precios

← Anterior Siguiente: Niveles de inferencia de la API de Gemini →