Fundamentación con tu API de búsqueda

Puedes conectar Gemini a tus fuentes de datos externas mediante la fundamentación con tu API de búsqueda. Esto te permite usar cualquier servicio de búsqueda como fuente de fundamentación para Gemini, lo que ayuda a garantizar que las respuestas se basen en la información más reciente y pertinente de tus sistemas. Esto es particularmente útil para los datos específicos de la 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 realizas la fundamentación con tu API de búsqueda, Gemini puede consultar un extremo de API externo que proporcionas. Esto permite que Gemini use tu funcionalidad de búsqueda personalizada como una herramienta para mejorar sus respuestas. Permite interacciones más dinámicas y contextuales, ya que el modelo puede buscar información de las fuentes de datos especificadas cuando sea necesario.

Durante una solicitud de generación, Gemini puede realizar una llamada al extremo de API externa con una consulta de búsqueda. Luego, tu API debería mostrar fragmentos de datos pertinentes. 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 compatibles

En esta sección, se enumeran los modelos que admiten la fundamentación con tu API de búsqueda.

Haz clic para expandir los modelos compatibles

Antes de comenzar

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

  1. Asegúrate de que la API de Agent Platform esté habilitada en tu Cloud de Confiance by S3NS proyecto.
  2. Si planeas seguir la guía de configuración detallada para crear un extremo de API de búsqueda nuevo, asegúrate de tener Google Cloud CLI instalado e inicializado.

Requisitos de la API de búsqueda

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

esquema de 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): Es un array JSON de objetos. Cada objeto representa un resultado de la 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, el extremo de API debe mostrar un array vacío.

Autenticación

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

Usa la fundamentación con tu API de búsqueda con un extremo compatible

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

Configura la herramienta externalApi

Cuando realices una solicitud a la API de Gemini, incluye el parámetro tools con una herramienta de recuperación configurada para externalApi. Los campos clave incluyen lo siguiente:

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

Python

Instalar

pip install --upgrade google-genai

Para obtener más información, consulta la documentación de referencia del SDK.

Establece variables de entorno para usar el SDK de Google Gen AI con Vertex AI: 

# 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,
      ExternalApi,
      Retrieval,
      Tool,
      HttpOptions,
  )

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

  # Replace with your API details
  EXTERNAL_API_ENDPOINT = "YOUR_EXTERNAL_API_ENDPOINT"  # e.g., https://YOUR_GATEWAY_HOSTNAME/v0/search
  EXTERNAL_API_KEY = "YOUR_EXTERNAL_API_KEY"

  tool = Tool(
      retrieval=Retrieval(
          external_api=ExternalApi(
              api_spec="SIMPLE_SEARCH",
              endpoint=EXTERNAL_API_ENDPOINT,
              api_auth={
                  "apiKeyConfig": {
                      "apiKeyString": EXTERNAL_API_KEY
                  }
              }
          )
      )
  )

  response = client.models.generate_content(
      model="gemini-2.5-flash",  # Or another supported model
      contents="What can you tell me about product Y based on my API?", # Your query
      config=GenerateContentConfig(
          tools=[tool],
      ),
  )

  print(response.text)

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • LOCATION: La región para procesar la solicitud. Para usar el extremo global, excluye la ubicación del nombre del extremo y configura la ubicación del recurso como global.
  • PROJECT_ID: Es el ID del Cloud de Confiance by S3NS proyecto de.
  • MODEL_ID: Es el ID del modelo de un modelo de Gemini compatible, como gemini-2.5-flash.
  • PROMPT: Son las instrucciones de texto que se incluirán en el mensaje.
  • EXTERNAL_API_ENDPOINT: Es la URL completa del extremo de API Gateway protegido al que llama Gemini, como https://YOUR_GATEWAY_HOSTNAME/v0/search. Este extremo debe cumplir con el esquema de API especificado.

  • EXTERNAL_API_KEY: Es la clave de API que generaste y configuraste para tu API Gateway. Gemini usa esta clave para autenticarse con tu extremo.

    Método HTTP y URL:

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

    Cuerpo JSON de la solicitud:

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

    Para enviar tu solicitud, usa una de estas opciones:

    curl

    Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud CLI init o gcloud CLI auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa, ejecuta 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 supone que accediste a la CLI de gcloud con tu cuenta de usuario mediante la ejecución de gcloud CLI init o gcloud CLI auth login. Para comprobar la cuenta activa, ejecuta 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 que se muestra a continuación:

    {
  "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": {
    "..."
  }
}

Configura un extremo de API de búsqueda

Si no tienes un extremo de API existente que cumpla con los requisitos, en esta sección, se te guiará para configurar uno con Cloud Functions y API Gateway.

Crea tu wrapper de API externa con Cloud Functions

Una Cloud Function puede actuar como un intermediario que recibe consultas de Gemini, emite consultas adecuadas a tu infraestructura de búsqueda existente, como una base de datos, un motor de búsqueda interno o una búsqueda de vectores, y, luego, da formato a los resultados en el esquema que Gemini comprende.

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

Ejemplo de configuración de Cloud Functions (Python)

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

  1. 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)

  2. requirements.py

    functions-framework>=3.0.0
Flask>=2.0.0

  3. Deployment: Navega 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
    • Reemplaza YOUR_REGION por la región que elegiste Cloud de Confiance by S3NS , como us-central1.
    • Se especifica --allow-unauthenticated porque API Gateway controla la autenticación.

Protege Cloud Functions con API Gateway y una clave de API

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

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

  1. Crea una especificación de OpenAPI (openapi-spec.yaml): Este archivo define cómo API Gateway expone tus Cloud Functions. Especifica que la puerta de enlace espera una solicitud POST a la ruta de acceso /v0/search y requiere una clave de API enviada como un 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

  2. Implementa API Gateway: Después de reemplazar las siguientes variables, ejecuta los comandos de gcloud CLI:

    • YOUR_PROJECT_ID: Es el ID del Cloud de Confiance proyecto.
    • YOUR_REGION: Es la Cloud de Confiance región que usaste 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 puerta de enlace) tiene el siguiente formato:

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

    Puedes usar el nombre de host para construir la URL completa del extremo para Gemini. Por ejemplo:

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

  3. Crea y restringe una clave de API: Debes crear una clave de API que Gemini use para acceder al extremo de API Gateway. Para obtener más información, consulta Administra claves de API.

    Para crear y restringir una clave de API, haz lo siguiente:

    1. En la Cloud de Confiance consola de, ve a la página API Gateway / Habilitar APIs.

      Ir a API Gateway API / Habilitar APIs

    2. Si la API de API Gateway no está habilitada, haz clic en Iniciar y, luego, 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. Almacena la clave en una ubicación segura. Gemini usa esta clave.

    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 tu servicio administrado de API Gateway. Debe tener el nombre de tu API, como Custom Search API for Gemini Grounding API.

      3. Si la clave no está incluida o si deseas administrar la puerta de enlace con la API usando esta clave, asegúrate de que esté seleccionada la API de API Gateway (apigateway.googleapis.com). Para la fundamentación, la clave necesita acceso a tu servicio de API específico alojado por API Gateway.

    8. Haz clic en Guardar. El extremo de API Gateway está protegido y, cuando lo usas, debes pasar la clave de API como un parámetro de consulta. Por ejemplo:

      https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev/v0/search?key=YOUR_GENERATED_API_KEY

Consideraciones para tu API de búsqueda

Revisa las siguientes consideraciones para ayudarte a elegir tu API de búsqueda:

  • Calidad del fragmento: El texto del fragmento que muestra tu API es fundamental. Debe ser conciso, pero lo suficientemente informativo para que Gemini lo use como base objetiva para su respuesta.
  • Latencia: Tu API de búsqueda debe responder rápidamente. La alta latencia en tu API aumenta el tiempo de respuesta general de Gemini.
  • Control de errores: Implementa manejo de errores sólido en tus Cloud Functions o en tu API de búsqueda. Si tu API muestra errores o se agota el tiempo de espera con frecuencia, afecta negativamente la capacidad de Gemini para generar respuestas fundamentadas.

¿Qué sigue?