Se usó la API de Cloud Translation para traducir esta página.

Fundamentos con tu API de búsqueda

Puedes conectar Gemini a tus fuentes de datos externas fundamentando 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 fundamentas con tu API de búsqueda, Gemini puede consultar un extremo de API externo que proporciones. Esto permite que Gemini use tu función 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 en las fuentes de datos especificadas cuando sea necesario.

Durante una solicitud de generación, Gemini puede llamar al extremo de API externa con una búsqueda. Luego, tu API debe 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 y 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 con varias herramientas en las que Gemini puede aprovechar diferentes fuentes de información para generar la mejor respuesta posible.

Modelos compatibles

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

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

Antes de comenzar

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

Asegúrate de que la API de Vertex AI esté habilitada en tu proyecto de Google Cloud.
Si planeas seguir la guía de configuración detallada para crear un extremo de API de Search nuevo, asegúrate de tener Google Cloud CLI instalada y, además, inicializada.

Requisitos de la API de Search

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 de objetos JSON. Cada objeto representa un resultado de la búsqueda y debe contener los campos de URI y fragmento.

[
  {
    "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 devolver un array vacío.

Autenticación

La fundamentación con tu API de búsqueda admite el uso de la clave de API, lo que protege tu extremo de API. Gemini envía esta clave de API como un parámetro de búsqueda 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 de `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 los siguientes:

api_spec: "SIMPLE_SEARCH": 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 Gemini usa para autenticarse con tu API. Gemini agrega esta clave como ?key=<YOUR_API_KEY> a la URL del extremo.

REST

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

LOCATION: Es la región para procesar la solicitud, como us-central1.
PROJECT_ID: Es el Google Cloud ID del proyecto.
MODEL_ID: Es el ID de un modelo de Gemini compatible, como gemini-2.0-flash-001.
USER_PROMPT: Las instrucciones de texto que se incluirán en la instrucción.
EXTERNAL_API_ENDPOINT: Es la URL completa de tu 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/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, 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

En 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. 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, esta sección te guía para configurar uno con Cloud Functions y API Gateway.

Crea tu wrapper de API externa con Cloud Functions

Una Cloud Function puede actuar como intermediaria que recibe consultas de Gemini, emite las 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, formatea 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 Function (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.

main.py

import functions_framework
import json
from flask import jsonify

@functions_framework.http
def custom_search_wrapper_minimal(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

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 Google Cloud que elegiste, comous-central1.
- Se especifica --allow-unauthenticated porque API Gateway controla 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.

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 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 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

Implementa API Gateway: Después de reemplazar las siguientes variables, ejecuta los comandos de gcloud CLI:
- YOUR_PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
- YOUR_REGION: La región Google Cloud 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 crear la URL completa del extremo 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 extremo de API Gateway. Para obtener más información, consulta Cómo administrar claves de API.

Para crear y restringir una clave de API, haz lo siguiente:
1. En la consola de Google Cloud , ve a la página API Gateway / Enable APIs.
  Ve a API Gateway API / Enable APIs
2. Si la API de API Gateway no está habilitada, haz clic en Launch y, luego, en Enable.
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 llave en un lugar seguro. 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 planeas administrar la puerta de enlace con la API usando esta clave, asegúrate de que la API de API Gateway (apigateway.googleapis.com) esté seleccionada. Para la fundamentación, la clave necesita acceso a tu servicio de API específico alojado por API Gateway.
  Nota: Por lo general, se usa una clave o una cuenta de servicio independientes para la administración.
8. Haz clic en Guardar. Tu extremo de API Gateway está protegido y, cuando lo usas, debes pasar la clave de API como un parámetro de búsqueda. 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 devuelve tu API es fundamental. Debe ser concisa, pero lo suficientemente informativa para que Gemini la use como base fáctica 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 la API de búsqueda. Si tu API suele mostrar errores o agotarse el tiempo de espera, esto afecta negativamente la capacidad de Gemini para generar respuestas fundamentadas.

¿Qué sigue?

Fundamentación con la Búsqueda.