Búsqueda Semántica IA para PrestaShop

Este módulo añade una búsqueda semántica con inteligencia artificial a su tienda PrestaShop. En lugar de comparar literalmente las palabras clave, comprende el significado de la consulta del cliente mediante embeddings vectoriales y muestra los productos pertinentes, incluso sin una coincidencia exacta.

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

1. En el back office, abra Módulos > Gestor de módulos.
2. Haga clic en Subir un módulo y cargue el archivo ZIP.
3. Una vez instalado, haga clic en Configurar.

El módulo crea tres tablas (dfvectorsearch_index, dfvectorsearch_qcache, dfvectorsearch_log) 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.

1. 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.
2. Deje la página abierta hasta que el estado muestre Índice actualizado.

Los contadores muestran el número de entradas indexables (productos × idiomas), los vectores ya indexados, las entradas pendientes y el número de embeddings de consultas en caché.

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 las actualizaciones del 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 tareas de su alojamiento.

La URL contiene un token de seguridad. Cada llamada trabaja durante unos veinte segundos y luego 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 desactivados o desvinculados de la tienda, así como los idiomas desactivados, se limpian automáticamente del índice.

Búsqueda en el front

Active Autocompletado del front office para adjuntar un menú de sugerencias semánticas a la barra de búsqueda de su tema.

Selector CSS

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. Para un tema personalizado, adapte este selector al campo de búsqueda de su tema.

Modo híbrido

Con el modo híbrido activado (recomendado), el módulo combina la puntuación semántica con una coincidencia por palabra clave en el nombre del producto. Así se favorecen las coincidencias exactas de nombre, sin sacrificar la pertinencia semántica.

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 campo número máximo de resultados limita el número de sugerencias mostradas.

Analizar las búsquedas

Cada búsqueda se registra (consulta, idioma, tienda, número de resultados, mejor puntuación). Estos datos le ayudan a comprender qué buscan realmente sus clientes y a detectar las consultas sin resultados para enriquecer su catálogo.

Caché de consultas

Los embeddings de las consultas de los clientes se almacenan en caché durante 30 días. Las búsquedas repetidas son así instantáneas y no vuelven a facturarse por el proveedor. El botón Vaciar la caché de consultas permite reiniciarla en cualquier momento.

Resolución de problemas

• No aparece ningún resultado: compruebe que el índice está construido (el contador «Vectores indexados» es > 0) y que la clave API es válida.
• El autocompletado no aparece: compruebe el selector CSS y que el autocompletado está activado. Los mensajes de error detallados se registran en los registros de PrestaShop.
• 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.