API de búsqueda semántica: qué es y cómo elegir una

¿Qué hace exactamente una API de búsqueda semántica?

Tres cosas, siempre las mismas, sea cual sea el proveedor:

1. Indexa tu catálogo. Convierte cada elemento en un vector numérico, llamado embedding, que representa su significado. Dos textos que quieren decir lo mismo quedan cerca, aunque usen palabras distintas.
2. Convierte cada consulta en un vector con el mismo modelo.
3. Devuelve los elementos más cercanos a la consulta, ordenados por una puntuación de similitud.

Por eso «cascos sin cable para correr» puede devolver «auriculares deportivos Bluetooth»: no comparten palabras, pero sus vectores están cerca.

¿En qué se diferencia de un buscador por palabras clave?

Un buscador por palabras clave compara letras: encuentra lo que contiene los términos de la consulta. Funciona muy bien con códigos, referencias y nombres exactos, y falla con sinónimos y con consultas que describen una necesidad. Uno semántico hace lo contrario. Los mejores resultados salen de combinar los dos, y eso se llama búsqueda híbrida. Lo desarrollamos en búsqueda semántica frente a palabras clave.

¿Qué necesito para usar una?

• Tus datos como textos cortos: un producto, un artículo o una pregunta por elemento.
• Una clave API, que es secreta y vive en tu servidor.
• Una llamada HTTP desde tu servidor cada vez que alguien busca.

Con XEYE, la llamada es esta. El nombre de la lista y el texto buscado son los únicos campos obligatorios:

curl -X POST https://search.xeye.es/api/v1/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $XEYE_API_KEY" \
  -d '{
    "list_name": "products",
    "search_term": "cascos sin cable para correr",
    "limit": 5
  }'

Y la respuesta trae cada resultado con su puntuación y con los parámetros que guardaste junto al elemento, para que puedas pintarlo sin una segunda consulta:

{
  "success": true,
  "results": [
    {
      "item": "Auriculares inalámbricos Bluetooth con cancelación de ruido",
      "score": 0.93,
      "params": {
        "id": 1842,
        "sku": "AUR-BT-900",
        "url": "/productos/auriculares-bluetooth-900",
        "price": 89.9
      }
    }
  ],
  "total_results": 1,
  "duration_ms": 42
}

La referencia completa de parámetros, errores y límites está en la guía de integración por API.

¿Qué debo mirar al elegir una?

¿Cuándo no me hace falta una?

• Si tus usuarios buscan sobre todo por código o referencia exacta, un buscador por palabras clave es suficiente y más barato.
• Si necesitas facetas, filtros y resultados mientras se escribe con interfaz incluida, te conviene un buscador completo. Lo comparamos en XEYE frente a Algolia.
• Si tus datos ya están en PostgreSQL y tienes quien lo programe, puedes hacerlo en tu propia base de datos. Lo comparamos en XEYE frente a pgvector.
• Si manejas millones de documentos o necesitas agregaciones, mira XEYE frente a Elasticsearch.

¿Cómo empiezo con XEYE?

1. Crea una cuenta. Empiezas con crédito de bienvenida y no hace falta tarjeta.
2. Crea una lista, márcala como pública y añade elementos a mano o importando un JSON.
3. Lanza el entrenamiento desde la pestaña Entrenamientos y espera a que termine.
4. Prueba búsquedas en el playground de la consola, que es gratis.
5. Crea una clave API y llama al endpoint desde tu servidor.

El recorrido completo, paso a paso, está en primeros pasos. Si usas Nuxt, Shopify o WooCommerce, hay un tutorial para cada uno en recursos.