Desde el 29 de abril del 2025, los modelos Gemini 1.5 Pro y Gemini 1.5 Flash no están disponibles en proyectos donde no se hayan utilizado previamente, incluidos los proyectos nuevos. Para obtener más información, consulta Versiones y ciclo de vida de los modelos.

Esta página se ha traducido con Cloud Translation API.

Fundamentación con tu API de búsqueda

Puedes conectar Gemini a tus fuentes de datos externas mediante la API de búsqueda. De esta forma, puedes usar cualquier servicio de búsqueda como fuente de información para Gemini, lo que ayuda a garantizar que las respuestas se basen en la información más reciente y relevante de tus sistemas. Esto es especialmente útil para los datos específicos de una empresa que no están disponibles públicamente.

En esta página se explica cómo configurar y usar la fundamentación con cualquier API de búsqueda con Gemini.

Cómo funciona la fundamentación con tu API de búsqueda

Cuando fundamentas con tu API de búsqueda, Gemini puede consultar un endpoint de API externo que proporciones. De esta forma, Gemini puede usar tu función de búsqueda personalizada como herramienta para mejorar sus respuestas. Permite interacciones más dinámicas y contextuales, ya que el modelo puede buscar información en las fuentes de datos que hayas especificado cuando sea necesario.

Durante una solicitud de generación, Gemini puede hacer una llamada al endpoint de la API externa con una consulta de búsqueda. A continuación, tu API debería devolver fragmentos de datos relevantes. Gemini usa estos fragmentos como fuente de información para generar una respuesta más precisa y fundamentada.

Puedes combinar la fundamentación con tu API de búsqueda con otras fuentes de fundamentación, como la Búsqueda de Google. Una solicitud de generación admite hasta 10 fuentes de fundamentación y consultas de varias herramientas en las que Gemini puede aprovechar diferentes fuentes de información para generar la mejor respuesta posible.

Modelos admitidos

Los siguientes modelos admiten la fundamentación con tu API:

Para obtener más información, consulta Modelos de Gemini.

Antes de empezar

Para usar la fundamentación con tu API de búsqueda, haz lo siguiente:

Asegúrate de que la API Vertex AI esté habilitada en tu Google Cloud proyecto.
Si tienes previsto seguir la guía de configuración detallada para crear un nuevo endpoint de la API Search, asegúrate de que tienes instalada e inicializada la CLI de Google Cloud.

Requisitos de la API de búsqueda

Para usar tu infraestructura de búsqueda con Gemini, tu endpoint de API debe cumplir los siguientes requisitos:

Esquema de la API

Método HTTP: POST

Cuerpo de la solicitud (de Gemini a tu API):

{
  "query": "the user's search query string"
}

Cuerpo de la respuesta (de tu API a Gemini): una matriz JSON de objetos. Cada objeto representa un resultado de búsqueda y debe contener los campos snippet y uri.

[
  {
    "snippet": "A text snippet containing the answer or relevant information.",
    "uri": "A URI/URL linking to the source of the information, or a relevant identifier."
  },
  {
    "snippet": "Another piece of information.",
    "uri": "https://example.com/another-source"
  }
]

Si no se encuentran resultados, tu endpoint de API debe devolver una matriz vacía.

Autenticación

La fundamentación con tu API de búsqueda admite el uso de la clave de API, que protege tu endpoint de API. Gemini envía esta clave de API como un parámetro de consulta llamado key.

Usar la fundamentación con tu API de búsqueda con un endpoint compatible

Si ya tienes un endpoint de API que cumple los requisitos de esquema y autenticación, puedes configurarlo directamente en tus llamadas a la API de Gemini.

Configurar la herramienta `externalApi`

Cuando hagas una solicitud a la API de Gemini, incluye el parámetro "tools" con una herramienta de recuperación configurada para externalApi. Entre los campos clave se incluyen los siguientes:

api_spec: "SIMPLE_SEARCH": indica a Gemini que use el esquema de entrada y salida predefinido.
endpoint: la URL completa del endpoint de API Gateway, como https://YOUR_GATEWAY_HOSTNAME/v0/search.
apiAuth.apiKeyConfig.apiKeyString: la clave de API que usa Gemini para autenticarse con tu API. Gemini añade esta clave como ?key=<YOUR_API_KEY> a la URL del endpoint.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

LOCATION: la región en la que se procesará la solicitud, como us-central1.
PROJECT_ID: el ID de tu proyecto de Google Cloud .
MODEL_ID: el ID de modelo de un modelo de Gemini compatible, como gemini-2.0-flash-001.
USER_PROMPT las instrucciones de texto que se deben incluir en la petición.
EXTERNAL_API_ENDPOINT la URL completa del endpoint de API Gateway seguro al que llama Gemini, como https://YOUR_GATEWAY_HOSTNAME/v0/search. Este endpoint debe cumplir el esquema de API especificado.
EXTERNAL_API_KEY: la clave de API que has generado y configurado para tu API Gateway. Gemini usa esta clave para autenticarse con tu endpoint.

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

  {
  "contents": [{
      "role": "user",
      "parts": [{
          "text": "USER_PROMPT"
      }]
  }],
  "tools": [{
      "retrieval": {
        "externalApi": {
          "api_spec": "SIMPLE_SEARCH",
          "endpoint": "EXTERNAL_API_ENDPOINT",
          "apiAuth": {
            "apiKeyConfig": {
              "apiKeyString": "EXTERNAL_API_KEY"
            }
          }
        }
      }
  }]
}

Para enviar tu solicitud, utiliza una de estas opciones:

curl

En el siguiente comando se da por hecho que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud CLI init o gcloud CLI auth login , o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud. Puedes comprobar la cuenta activa ejecutando gcloud CLI auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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

Powershell

El siguiente comando presupone que has iniciado sesión en gcloud CLI con tu cuenta de usuario ejecutando gcloud CLI init o gcloud CLI auth login. Puedes consultar la cuenta activa ejecutando el comando gcloud CLI auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$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/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la siguiente:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "You can make an appointment on the website https://dmv.gov/"
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        "..."
      ],
      "groundingMetadata": {
        "retrievalQueries": [
          "How to make appointment to renew driving license?"
        ],
        "groundingChunks": [
          {
            "retrievedContext": {
              "uri": "https://...",
              "snippet": "Snippet text about driving license renewal"
            }
          }
        ],
        "groundingSupport": [
          {
            "segment": {
              "startIndex": 25,
              "endIndex": 147
            },
            "segment_text": "ipsum lorem ...",
            "supportChunkIndices": [1, 2],
            "confidenceScore": [0.9541752, 0.97726375]
          },
          {
            "segment": {
              "startIndex": 294,
              "endIndex": 439
            },
            "segment_text": "ipsum lorem ...",
            "supportChunkIndices": [1],
            "confidenceScore": [0.9541752, 0.9325467]
          }
        ]
      }
    }
  ],
  "usageMetadata": {
    "..."
  }
}

Configurar un endpoint de API de búsqueda

Si no tienes ningún endpoint de API que cumpla los requisitos, en esta sección se explica cómo configurar uno con Cloud Functions y API Gateway.

Crear un envoltorio de API externa con Cloud Functions

Una función de Cloud puede actuar como intermediario que recibe consultas de Gemini, envía las consultas adecuadas a tu infraestructura de búsqueda, como una base de datos, un motor de búsqueda interno o una búsqueda de vectores, y, a continuación, da formato a los resultados en el esquema que entiende Gemini.

Para obtener más información, consulta la documentación de las funciones de Cloud Run.

Ejemplo de configuración de Cloud Functions (Python)

En este ejemplo se usa una lista de productos codificada para hacer una demostración. Deberás sustituir la lógica de recuperación de datos por llamadas a tu sistema de búsqueda.

main.py

import functions_framework
import json
from flask import jsonify

@functions_framework.http
def custom_search_wrapper(request):
    """
    HTTP Cloud Function to provide a minimal, fixed response for Gemini grounding.
    """
    if request.method != 'POST':
        return 'Only POST requests are accepted', 405

    request_json = request.get_json(silent=True)

    if not request_json or 'query' not in request_json:
        return jsonify({"error": "Invalid request. JSON body with 'query' field is required."}), 400

    user_query = request_json['query']
    print(f"Received query: '{user_query}'. Responding with fixed data.")

    # --- FIXED RESPONSE ---
    # This is a hardcoded response. In a real scenario, you would
    # use the 'user_query' to fetch relevant data.
    fixed_results = [
        {
            "snippet": "This is a fixed snippet from your custom Search API. The original query was: " + user_query,
            "uri": "https://example.com/docs/fixed-test-data"
        },
        {
            "snippet": "Another piece of fixed information to demonstrate the list format.",
            "uri": "https://example.com/another-fixed-source"
        }
    ]
    # --- END OF FIXED RESPONSE ---

    return jsonify(fixed_results)

requirements.py

functions-framework>=3.0.0
Flask>=2.0.0

Despliegue: ve al directorio que contiene main.py y requirements.txt y ejecuta lo siguiente:
```
gcloud functions deploy custom_search_wrapper \
  --runtime python311 \
  --trigger-http \
  --entry-point custom_search_wrapper \
  --region YOUR_REGION \
  --allow-unauthenticated \
  --gen2
```
- Sustituye YOUR_REGION por la región que hayas elegido, como Google Cloud .us-central1
- Se especifica --allow-unauthenticated porque API Gateway gestiona la autenticación.
Importante: La URL de activación después de la implementación tiene el formato https://....run.app. Usa este formato para la configuración de API Gateway en el siguiente paso.

Proteger Cloud Functions con API Gateway y una clave de API

API Gateway proporciona un punto de entrada seguro y gestionado a tus Cloud Functions y te permite aplicar la autenticación con clave de API.

Para obtener más información, consulta la documentación de API Gateway.

Crea una especificación de OpenAPI (openapi-spec.yaml): este archivo define cómo expone API Gateway tus Cloud Functions. Especifica que la pasarela espera una solicitud POST a la ruta /v0/search y requiere una clave de API enviada como parámetro de consulta llamado key.

swagger: '2.0'
info:
  title: Custom Search API for Gemini Grounding
  description: Wraps an internal search function, secured by API Key for Gemini.
  version: 1.0.0
schemes:
  - https
produces:
  - application/json
consumes:
  - application/json
paths:
  /v0/search: # TODO: This will be part of API endpoint URL change if necessary
    post:
      summary: Custom search endpoint for Gemini
      operationId: customSearchForGemini # TODO: Change if needed
      x-google-backend:
        address: YOUR_CLOUD_FUNCTION_TRIGGER_URL # TODO: Replace with your Cloud Function trigger URL
      parameters:
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              query:
                type: string
      security:
        - api_key_query: []
      responses:
        '200':
          description: Search results
          schema:
            type: array
            items:
              type: object
              properties:
                snippet:
                  type: string
                uri:
                  type: string
        '400':
          description: Invalid request
        '401':
          description: Unauthorized (Missing or invalid API key)
        '500':
          description: Internal server error
securityDefinitions:
  api_key_query:
    type: apiKey
    name: key # Gemini will send its API key using this query parameter name
    in: query

Despliega API Gateway: después de sustituir las siguientes variables, ejecuta los comandos de la CLI de gcloud:

YOUR_PROJECT_ID: tu ID de proyecto de Google Cloud .
YOUR_REGION: la Google Cloud región que has usado para tus Cloud Functions, como us-central1.

# 1. Create an API
gcloud api-gateway apis create custom-search-gemini-api --project=YOUR_PROJECT_ID

# 2. Create an API Config from your OpenAPI spec
gcloud api-gateway api-configs create v1 \
  --api=custom-search-gemini-api \
  --openapi-spec=openapi-spec.yaml \
  --project=YOUR_PROJECT_ID \
  --display-name="Version 1"

# 3. Create a Gateway
gcloud api-gateway gateways create custom-search-gateway \
  --api=custom-search-gemini-api \
  --api-config=v1 \
  --location=YOUR_REGION \
  --project=YOUR_PROJECT_ID

Después de la implementación, el nombre de host (URL de la pasarela) tiene el siguiente formato:

https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev

Puede usar el nombre de host para crear la URL completa del endpoint de Gemini. Por ejemplo:

https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev/v0/search

Crea y restringe una clave de API: debes crear una clave de API que Gemini use para acceder a tu endpoint de API Gateway. Para obtener más información, consulta Gestionar claves de API.

Para crear y restringir una clave de API, sigue estos pasos:
1. En la Google Cloud consola, ve a la página API Gateway > Habilitar APIs.
  Ve a API Gateway API/Enable APIs (API de API Gateway/Habilitar APIs).
2. Si la API de API Gateway no está habilitada, haz clic en Iniciar y, a continuación, en Habilitar.
3. Selecciona Credenciales.
4. Haz clic en Crear credenciales y selecciona Clave de API.
5. Haz clic en Mostrar clave y copia la clave de API generada. Guarda la clave en un lugar seguro. Esta clave la usa Gemini.
6. Haz clic en Editar clave de API o en el nombre de la clave.
7. En la sección Restricciones de API, haz lo siguiente:
  1. Selecciona la opción Restringir clave.
  2. Selecciona el servicio gestionado de API Gateway. Debe tener el nombre de tu API, como Custom Search API for Gemini Grounding API.
  3. Si no se incluye la clave o tienes intención de gestionar la pasarela con la API mediante esta clave, asegúrate de que esté seleccionada la API API Gateway (apigateway.googleapis.com). Para la fundamentación, la clave necesita acceder a tu servicio de API específico alojado en API Gateway.
  Nota: Normalmente, se usa una clave o una cuenta de servicio independientes para la gestión.
8. Haz clic en Guardar. El endpoint de API Gateway está protegido y, cuando lo usas, debes enviar la clave de API como parámetro de consulta. Por ejemplo:
  
  https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev/v0/search?key=YOUR_GENERATED_API_KEY

Consideraciones sobre la API Search

Consulta las siguientes consideraciones para elegir la API de búsqueda que más te convenga:

Calidad del fragmento: el texto del fragmento devuelto por tu API es fundamental. Debe ser concisa, pero lo suficientemente informativa para que Gemini la use como base objetiva para su respuesta.
Latencia: tu API de búsqueda debe responder rápidamente. Una latencia alta en tu API aumenta el tiempo de respuesta general de Gemini.
Gestión de errores: implementa una gestión de errores sólida en tus Cloud Functions o en la API de búsqueda. Si tu API genera errores o se agota el tiempo de espera con frecuencia, afectará negativamente a la capacidad de Gemini para generar respuestas fundamentadas.

Siguientes pasos

Fundamentación con la Búsqueda.