Búsqueda Visual por Imagen y Shop the Look IA — Guía completa

Este módulo añade la búsqueda de productos por imagen a su tienda: el cliente arrastra una foto y obtiene los artículos de su catálogo visualmente más parecidos, ordenados por puntuación de similitud. El modo Shop the Look detecta cada artículo de una escena completa y propone los productos correspondientes. El motor es agnóstico: usted elige el proveedor de IA (Voyage, Cohere, OpenAI o Mistral) y usa su propia clave. Esta guía cubre la instalación, la configuración, la indexación del catálogo y el funcionamiento de la búsqueda.

Instalación

1. Descargue el archivo dfvisualsearch.zip desde su cuenta DataFirefly.
2. Back office de PrestaShop → Módulos → Subir un módulo → envíe el ZIP.
3. El módulo crea su tabla de índice, registra sus hooks y añade una pestaña de administración dedicada.

Configuración general

Vaya a Módulos → Búsqueda Visual & Shop the Look IA → Configurar.

Elegir el proveedor

Seleccione el motor en la lista e introduzca la clave API correspondiente. Paga la IA según su uso con el proveedor, sin suscripción añadida por el módulo.

• Voyage y Cohere: embeddings multimodales directos de la imagen.
• OpenAI y Mistral: análisis de visión y luego embedding, y además habilitan el Shop the Look.
• Clave API: almacenada en el servidor, nunca expuesta al front office. Cada proveedor tiene su propio modelo y dimensión de vector configurables.

Comportamiento

• Número de resultados: cuántos productos mostrar en una búsqueda por imagen.
• Similitud mínima (0–1): 0 muestra todo ordenado por relevancia; auméntela (por ejemplo 0,2 a 0,4) para descartar coincidencias débiles. Ajústela según el proveedor.
• Activar el Shop the Look y productos por artículo detectado.
• Productos similares en la ficha de producto y su número.
• Inyectar el botón de cámara en la cabecera, o colocarlo manualmente en su tema mediante el hook displayDfVisualSearchButton.
• Tamaño máximo de subida y reindexación automática al guardar un producto.

Indexar el catálogo

En el panel Índice del catálogo de la configuración:

1. Haga clic en Indexar / reindexar el catálogo: el módulo procesa los productos por lotes, con una barra de progreso, sin riesgo de timeout del servidor.
2. El contador muestra los productos indexados para el proveedor activo.
3. Vaciar el índice elimina los vectores de la tienda actual.

La indexación convierte la imagen de portada de cada producto en un vector almacenado en la base de datos. Una vez indexado, un producto solo se vuelve a codificar si su imagen cambia.

Cómo funciona la búsqueda

Cada imagen se convierte en un vector (embedding) normalizado. La foto enviada por el cliente la codifica el mismo proveedor y luego se compara con el índice mediante similitud de coseno — que, sobre vectores normalizados, se reduce a un simple producto escalar. Los productos se ordenan por puntuación descendente y se filtran por el umbral mínimo configurado.

• Voyage y Cohere codifican la imagen directamente.
• OpenAI y Mistral describen la imagen con un modelo de visión y luego codifican esa descripción: la indexación y la consulta viven así en el mismo espacio vectorial.

Shop the Look

A partir de una foto de escena, el Shop the Look identifica cada artículo visible y lanza una búsqueda por artículo, presentando los resultados en grupos distintos.

Productos visualmente similares

En la ficha de producto aparece automáticamente un bloque de «productos visualmente similares». Reutiliza el vector ya calculado al indexar el producto: no se envía ninguna petición adicional a la IA, por lo que la recomendación no añade coste recurrente.

Visualización para el cliente

El botón de cámara abre una ventana donde el cliente arrastra y suelta una foto o la selecciona. Aparece una vista previa y luego los resultados se muestran como tarjetas de producto con su puntuación de similitud en porcentaje. Si el Shop the Look está activado, el cliente puede marcar la opción para obtener los resultados agrupados por artículo detectado.

Elegir un proveedor

Todos los proveedores realizan la búsqueda por imagen. La elección depende de sus necesidades:

• Voyage / Cohere: embeddings multimodales directos, simples y rápidos, sin Shop the Look.
• OpenAI / Mistral: análisis de visión que habilita la detección de varios artículos del Shop the Look.

Compatibilidad y notas técnicas

• PrestaShop 1.7.6 a 9.x, multitienda y multiidioma; cada tienda mantiene su propio índice.
• Controlador de administración legacy (sin controlador Symfony) para la compatibilidad PS8/PS9.
• Hooks utilizados: displayHeader, displayTop, displayDfVisualSearchButton, displayFooterProduct, actionProductSave, actionProductDelete.
• Vectores almacenados normalizados en la base de datos, codificados para un almacenamiento robusto; búsqueda por producto escalar.
• Un limitador antiabuso por sesión protege su cuota de IA.
• Endpoint de búsqueda AJAX mediante el enlace del módulo; respuesta en formato JSON.

FAQ y resolución de problemas

El botón de búsqueda no aparece. Compruebe que hay un proveedor configurado y que su clave es válida (botón Probar el proveedor), y luego que la inyección en la cabecera está activada o que el hook está colocado en su tema.

La búsqueda no devuelve resultados. Asegúrese de que el catálogo se ha indexado para el proveedor activo y baje la similitud mínima si es demasiado alta para el espacio vectorial del proveedor.

El Shop the Look devuelve un solo grupo. El proveedor activo no admite la detección (Voyage o Cohere). Cambie a OpenAI o Mistral para la detección de varios artículos y reindexe.

Cambié de proveedor y los resultados son incoherentes. Lance una reindexación completa: los vectores deben recalcularse en el espacio del nuevo proveedor.