Búsqueda Semántica IA para PrestaShop
Instalar, configurar y explotar la búsqueda semántica por embeddings IA: autocompletado, página de resultados, productos similares y analytics.
Este módulo añade una búsqueda semántica con inteligencia artificial a su tienda PrestaShop: autocompletado, página de resultados, bloque «También te puede gustar» en la ficha de producto y panel de analytics comparten la misma clasificación por significado, calculada con embeddings vectoriales.
Requisitos
- PrestaShop 8.0 a 9.x
- PHP 7.4 a 8.3 con la extensión cURL activada
- Una clave API de un proveedor de embeddings: OpenAI, Mistral AI o cualquier pasarela compatible con OpenAI
Instalación
- En el back office, abra Módulos > Gestor de módulos.
- Haga clic en Subir un módulo y cargue el archivo ZIP.
- Una vez instalado, haga clic en Configurar.
El módulo crea cuatro tablas (dfvectorsearch_index, dfvectorsearch_qcache, dfvectorsearch_log, dfvectorsearch_similar) y una pestaña oculta para sus llamadas AJAX. No hay nada visible en el front hasta que se construye el índice.
Configuración del proveedor de embeddings
En la pestaña Ajustes, elija su proveedor e introduzca su clave API.
OpenAI
Seleccione el proveedor OpenAI e introduzca su clave. El modelo recomendado es text-embedding-3-small (buena relación calidad/precio). Para una precisión máxima en un catálogo exigente, puede usar text-embedding-3-large.
Mistral AI (alojamiento europeo)
Seleccione Mistral AI para un tratamiento de datos en Europa, conforme al RGPD. El modelo a utilizar es mistral-embed.
Pasarela compatible con OpenAI
Seleccione Custom para usar su propia pasarela (proxy interno, Azure OpenAI, etc.). Introduzca entonces la URL base de la API, por ejemplo https://mi-pasarela.ejemplo.com/v1.
La clave API se enmascara tras guardar. Deje el valor enmascarado tal cual para conservar la clave existente; introduzca una nueva clave solo si desea reemplazarla.
Dimensiones
El campo Dimensiones permite reducir el tamaño de los vectores para acelerar la búsqueda en catálogos muy grandes. Deje 0 para usar el tamaño por defecto del modelo. Los modelos OpenAI text-embedding-3 admiten dimensiones reducidas (por ejemplo 512).
Cambiar de proveedor, de modelo o de número de dimensiones deja obsoleto todo el índice: al guardar, el índice se marca automáticamente para reconstrucción completa y se vacía la caché de consultas. Vuelva a lanzar una indexación después.
Construir el índice
Tras guardar la clave API, vaya al recuadro Índice de embeddings en la parte superior de la página de configuración.
- Haga clic en Indexar ahora. El módulo procesa los productos por lotes con una barra de progreso, idioma por idioma y tienda por tienda.
- Deje la página abierta hasta que el estado muestre Índice actualizado.
Tamaño de los lotes
El ajuste Tamaño del lote de indexación controla cuántos productos se procesan por llamada (5 a 100). Redúzcalo si su servidor sufre tiempos de espera agotados.
Indexación planificada (cron)
Para mantener el índice sincronizado automáticamente con el catálogo, copie la URL de indexación cron mostrada en la configuración y llámela con regularidad (por ejemplo cada 15 minutos) desde el planificador de su alojamiento.
La URL contiene un token de seguridad. Cada llamada trabaja unos veinte segundos y se detiene limpiamente, para mantenerse compatible con los límites de tiempo de ejecución de PHP.
Cómo funciona la reindexación
Cada vez que un producto se añade, modifica o elimina, la entrada correspondiente se marca para reindexación. El módulo calcula una huella (checksum) del texto del producto: si solo cambió el precio o el stock, el texto permanece idéntico y no se dispara ninguna nueva llamada API. Los productos y los idiomas desactivados se limpian automáticamente del índice.
Búsqueda en el front
Autocompletado
Active Autocompletado del front office para adjuntar un menú de sugerencias semánticas a la barra de búsqueda de su tema. El campo Selector CSS del campo de búsqueda indica al módulo a qué campo engancharse. El valor por defecto #search_widget input[type="text"] funciona con los temas basados en classic.
Desactivar el autocompletado del tema
El ajuste Desactivar el autocompletado del tema (activado por defecto) elimina las sugerencias de búsqueda nativas (ps_searchbar y equivalentes) para evitar un menú desplegable duplicado. El módulo anula el registro del script nativo y oculta cualquier menú inyectado por un tema personalizado.
Modo híbrido
Con el modo híbrido activado (recomendado), la clasificación semántica va primero y los resultados nativos por palabra clave ausentes se añaden después. Nunca obtiene menos resultados que la búsqueda original.
Umbral y número de resultados
La puntuación de similitud mínima (entre 0 y 0,99; recomendado: 0,30) descarta los resultados demasiado alejados. El número máximo de resultados limita las sugerencias mostradas en el autocompletado.
La página de resultados de búsqueda
El ajuste Tomar el control de la página de resultados (activado por defecto) hace que el módulo proporcione la clasificación de la página mediante el hook productSearchProvider, el mecanismo oficial de PrestaShop utilizado por la navegación por facetas. En concreto:
- el autocompletado y la página muestran los mismos productos, en el mismo orden;
- la paginación y la ordenación del tema siguen funcionando (la ordenación «relevancia» conserva el orden semántico; precio, nombre y fecha se recalculan dentro de la clasificación);
- si la API de embeddings no está disponible, el módulo recurre silenciosamente a los resultados nativos y registra el incidente: la página de búsqueda nunca se rompe.
El módulo solo se activa en una búsqueda de texto. Las categorías, páginas de etiquetas y otros listados conservan sus mecanismos nativos.
Productos similares (También te puede gustar)
El Bloque de productos similares (activado por defecto) muestra en cada ficha de producto un «También te puede gustar» calculado por proximidad semántica entre los vectores ya almacenados en su base de datos. No se realiza ninguna llamada API: el bloque funciona incluso sin clave API mientras exista el índice.
- Número de productos similares: de 2 a 12 (por defecto 6).
- Puntuación mínima de productos similares: umbral dedicado, independiente del de búsqueda (recomendado: 0,45). Por debajo, el producto no aparece, aunque se muestren menos tarjetas. Cambiarlo purga automáticamente la caché de similares.
- Un bonus de afinidad favorece los productos de la misma categoría por defecto y de la misma marca.
- Los resultados se almacenan en caché 24 horas por producto y se invalidan automáticamente al reindexar.
- El renderizado usa las miniaturas nativas de su tema: etiquetas, wishlist, vista rápida y estilos de hover incluidos.
En un catálogo de demostración pequeño donde todas las fichas comparten el mismo texto de marketing, las similitudes son naturalmente más laxas. Suba el umbral a 0,55-0,60 para conservar solo las coincidencias cercanas.
Estadísticas y analytics
La página de configuración muestra un panel calculado sobre los últimos 30 días: número de búsquedas, tasa sin resultados, resultados medios por búsqueda, histograma del volumen diario, top 20 de consultas (recuento, resultados medios, mejor puntuación) y top 20 de consultas sin resultados.
Las consultas sin resultados son una mina de oro: indican exactamente qué buscan sus clientes sin encontrarlo, y por tanto qué añadir a su catálogo o a sus sinónimos.
- El botón Exportar CSV descarga el registro completo (separador punto y coma) con la fuente de cada búsqueda: autocompletado o página de resultados.
- El registro se purga automáticamente tras 365 días.
Caché de consultas
Los embeddings de las consultas de los clientes se almacenan en caché 30 días. Las búsquedas repetidas son instantáneas y no se vuelven a facturar. El botón Vaciar la caché de consultas permite reiniciarla en cualquier momento.
Actualización del módulo
Si actualiza el módulo reemplazando sus archivos (fuera del Gestor de módulos), abra una vez la página de configuración: el módulo registra entonces automáticamente los hooks que falten, crea las tablas y columnas que falten y establece los nuevos valores por defecto. Los archivos CSS y JS del front integran un cache-buster, no es necesario vaciar la caché del navegador.
Resolución de problemas
- No aparece ningún resultado: compruebe que el índice está construido (contador «Vectores indexados» > 0) y que la clave API es válida.
- Aparecen dos menús desplegables: compruebe que Desactivar el autocompletado del tema está activado y vacíe una vez la caché de PrestaShop.
- El autocompletado y la página de resultados difieren: abra una vez la página de configuración del módulo (el hook de la página de resultados se registra automáticamente) y compruebe que Tomar el control de la página de resultados está activado.
- El bloque También te puede gustar está vacío: el índice debe estar construido para el idioma y la tienda actuales; si no, baje la puntuación mínima de productos similares.
- Tiempos de espera agotados durante la indexación: reduzca el tamaño de los lotes y priorice la indexación por cron.
- Resultados incoherentes tras un cambio de modelo: vuelva a lanzar una reconstrucción completa del índice.