Detector de Topic Clusters — Documentación

Esta documentación describe la instalación, configuración y uso del módulo Detector de Topic Clusters en PrestaShop 8 y 9. El módulo detecta automáticamente las agrupaciones temáticas de su catálogo mediante clustering semántico y sugiere las pillar pages faltantes con un borrador SEO completo para cada oportunidad.

Presentación

El Detector de Topic Clusters analiza su catálogo de productos para hacer emerger los topic clusters realmente presentes en su oferta, y luego detecta las pillar pages faltantes: esos temas transversales fuertemente cubiertos por sus productos pero sin una página madre estructurante (CMS o categoría).

Para cada gap detectado, el módulo genera un borrador completo:

• Título H1 optimizado para SEO
• Slug URL-safe
• Meta descripción
• Plan H2 markdown completo
• Lista de palabras clave objetivo
• Puntuación de prioridad (tamaño × cohesión)

Instalación

Requisitos previos

• PrestaShop 8.0+ o 9.x
• PHP 8.0 mínimo (PHP 8.1 u 8.2 recomendado)
• memory_limit de al menos 512 MB (1024 MB recomendado para catálogos grandes)
• Opcional: clave API OpenAI o Mistral para el modo embeddings

Procedimiento de instalación

1. Descargue el archivo dftopicclusters.zip desde su área de cliente DataFirefly.
2. En el back-office PrestaShop, vaya a Módulos → Module Manager y haga clic en Subir un módulo.
3. Seleccione el ZIP y confirme. El módulo se instala automáticamente.
4. Una vez instalado, haga clic en Configurar.

En la instalación, el módulo crea automáticamente:

• Las 5 tablas SQL prefijadas df_topicclusters_
• La pestaña padre DataFirefly bajo el menú Mejorar (si no existe)
• La pestaña hija Topic Clusters bajo ese padre
• Las 19 claves de configuración por defecto

Primer acceso

Una vez instalado, el módulo es accesible vía Mejorar → DataFirefly → Topic Clusters. El panel de control le presenta el formulario de lanzamiento de un nuevo análisis y el historial de ejecuciones anteriores (vacío en el primer acceso).

Configuración

Haga clic en el botón Ajustes en la parte superior derecha del panel para acceder a la página de configuración. Los ajustes se agrupan en cinco secciones.

General

Extracción de texto

Permite elegir qué campos del producto se inyectan en el análisis. La ponderación por campo es fija (nombre × 3, meta × 2, descripción corta × 2, categorías × 2, etiquetas × 2, descripción larga × 1, características × 1).

• DFTC_INCLUDE_DESCRIPTION — Incluir la descripción larga (recomendado: activado)
• DFTC_INCLUDE_CATEGORIES — Incluir los nombres de categorías (recomendado: activado)
• DFTC_INCLUDE_TAGS — Incluir las etiquetas PrestaShop (recomendado: activado)
• DFTC_INCLUDE_FEATURES — Incluir las características del producto (recomendado: desactivado salvo características muy descriptivas)

Ajustes TF-IDF

APIs de embeddings

Detección de pillar pages

• DFTC_PILLAR_MATCH_THRESHOLD — Umbral de match (por defecto 0.45). Por debajo, el cluster se marca como pillar gap. Aumente el umbral para ser más estricto, redúzcalo para ser más tolerante.

Los tres modos en detalle

Modo TF-IDF (recomendado para empezar)

El TF-IDF (Term Frequency × Inverse Document Frequency) es un método estadístico clásico en NLP. El módulo construye un vocabulario a partir de todos los textos de productos, filtra los términos demasiado raros o demasiado frecuentes, y luego representa cada producto como un vector disperso en este espacio.

Ventajas: 100% local, instantáneo, sin coste, sin dependencias externas. Excelente para catálogos léxicamente homogéneos (un dominio, un vocabulario consistente).

Limitaciones: no comprende sinónimos (dos productos que usan términos diferentes para el mismo concepto serán mal agrupados).

Modo embeddings OpenAI

Utiliza la API OpenAI text-embedding-3-small por defecto. Cada producto está representado por un vector denso de 1536 dimensiones que captura su semántica.

Ventajas: comprende sinónimos, variantes léxicas y contexto. Excelente para catálogos diversificados o con descripciones narrativas.

Coste indicativo: aproximadamente 0,02 USD por millón de tokens, es decir menos de 0,10 USD para un catálogo de 1.000 productos.

Modo embeddings Mistral

Utiliza la API Mistral mistral-embed por defecto. Modelo multilingüe de alto rendimiento, particularmente bueno en francés.

Ventajas: alojado en Europa (cumplimiento RGPD facilitado), excelente en contenidos francófonos, precio competitivo.

Lanzar un análisis

Desde el panel de control, el formulario Lanzar un nuevo análisis propone seis parámetros:

• Idioma — el idioma en el que se extraerán y analizarán los textos de los productos. Lance una ejecución distinta para cada idioma activo de su tienda.
• Modo — TF-IDF, OpenAI o Mistral (sobrescribe el ajuste por defecto solo para esta ejecución).
• Número de clusters (k) — Deje 0 para el auto-k. De lo contrario, fuerce un valor entre 2 y 100.
• Tamaño mínimo — Clusters más pequeños descartados (por defecto 3).
• Umbral pillar — Umbral de match por debajo del cual un cluster se marca como gap (por defecto 0.45).
• Límite de productos — Limita el número de productos analizados (útil para debug o prueba rápida). Deje 0 para analizar todo el catálogo.

Haga clic en Lanzar análisis. La ejecución comienza inmediatamente. Para un catálogo de 1.000 productos:

• Modo TF-IDF: 5 a 15 segundos
• Modo embeddings (primera ejecución): 30 segundos a 2 minutos según el batch size
• Modo embeddings (ejecuciones siguientes con caché caliente): equivalente al TF-IDF

Leer los resultados

Una vez completada la ejecución, accede a la página de detalle. Cada cluster se muestra como una tarjeta con cuatro secciones.

Encabezado de cluster

El encabezado combina una insignia de estado, un número de cluster y una etiqueta generada. La insignia es:

• PILLAR GAP (naranja) — Ninguna pillar page existente cubre este tema. Oportunidad fuerte.
• OK (verde) — Una página CMS o categoría ya cubre este tema (el módulo lo ha hecho match).

La etiqueta se compone de los 3 top-términos del cluster unidos por ·. Ejemplo: «sneakers · cuero premium · zapatos».

Estadísticas

• Productos — Número de productos en el cluster
• Cohesión — Similitud media de los miembros con el centroide (0 a 100%). Cuanto más alta, más homogéneo es el cluster.
• Match — Puntuación de match con la mejor pillar page existente. Si está por debajo del umbral → gap.

Top términos

Los términos más representativos del cluster. En modo TF-IDF, son los términos con la componente más fuerte en el centroide. En modo embeddings, el módulo calcula un TF interno al cluster ponderado por el IDF global para hacer destacar los términos distintivos.

Sugerencia de pillar page

Presente solo si el cluster está marcado como gap. Contiene:

• Título — Título H1 optimizado SEO en lenguaje natural
• Slug — URL-safe, en kebab-case
• Meta descripción — 150-160 caracteres
• Prioridad — Puntuación combinada tamaño (0.6) × cohesión (0.4)
• Plan sugerido — Plan H2 en markdown con secciones clásicas (intro, qué es, cómo elegir, comparativa, mejores productos, casos de uso, errores a evitar, FAQ, CTA)

Productos del cluster

Lista de los productos agrupados con su puntuación de similitud al centroide, ordenados por similitud decreciente. Haga clic en el ID del producto para abrir la ficha directamente en una nueva ventana.

Workflow recomendado

Aquí tiene un uso típico del módulo en 4 pasos.

1. Primera auditoría — Lance una ejecución TF-IDF en su idioma principal con los parámetros por defecto. Examine los clusters marcados como gap: ¿son editorialmente relevantes?
2. Triaje — Para cada gap, use el botón Descartar si el cluster no merece una pillar page (por ejemplo, una agrupación accidental de productos heterogéneos). Los gaps restantes son sus prioridades.
3. Redacción — Para cada gap retenido, cree una nueva página CMS en PrestaShop con el título, slug y meta del borrador. Use el plan H2 como esqueleto de redacción. Haga clic en Marcar Hecho una vez publicado.
4. Reanudar — Después de publicar las nuevas páginas, vuelva a lanzar una ejecución. Los gaps anteriores ahora deberían estar OK (el módulo detectará las nuevas pillar pages).

Exportación

Desde la página de detalle de una ejecución, dos botones en la parte superior derecha permiten exportar:

• CSV — Tabla con una fila por cluster, columnas: id_cluster, label, n_members, cohesión, pillar_gap, match_score, suggested_title, suggested_slug, suggested_meta, priority_score, target_keywords. Codificación UTF-8 con BOM (compatible con Excel).
• JSON — Exportación completa que incluye la lista de productos por cluster y el plan markdown integral. Ideal para automatización o integración externa.

Arquitectura técnica

Base de datos

El módulo crea 5 tablas con prefijo df_topicclusters_:

• run — Metadatos de cada ejecución (modo, idioma, estado, duración, contadores)
• cluster — Clusters individuales (label, top términos JSON, cohesión, flag pillar_gap, match_score)
• cluster_product — Pertenencia producto → cluster con puntuación de similitud
• pillar — Sugerencias de pillar pages (título, slug, meta, outline, prioridad, estado)
• embedding_cache — Caché de vectores de embeddings indexado por hash de texto

PSR-4 y autoload

El namespace raíz es DataFirefly/TopicClusters/. Un autoload manual se registra vía spl_autoload_register en el archivo principal del módulo, por lo que no se requiere ninguna dependencia Composer.

Controllers y compatibilidad PS 8 / PS 9

El módulo utiliza un ModuleAdminController legacy (y no un controller Symfony) para garantizar la compatibilidad con ambas versiones principales. Las consultas SQL están escritas para respetar los esquemas de ambas versiones, particularmente la eliminación de la columna meta_keywords en PS 9.

Rendimiento y límites

• Catálogos hasta 1.000 productos — Ejecuciones en pocos segundos. Sin preocupación particular.
• 1.000 a 10.000 productos — El modo TF-IDF sigue siendo rápido (10-60 s). Modo embeddings: prever 1 a 5 minutos para la primera ejecución, instantáneo después gracias a la caché.
• Más de 10.000 productos — Privilegie el parámetro Límite de productos para dividir, o aumente memory_limit a 2 GB.

La complejidad del k-means es O(n × k × iter × d) donde n es el número de productos, k el número de clusters, iter el número de iteraciones (típicamente 10-30) y d la dimensión de los vectores (variable en TF-IDF, 1536 en OpenAI).

Solución de problemas

Ningún cluster detectado

Verifique que sus productos tengan contenido textual en el idioma analizado (al menos un nombre e idealmente una descripción). Si DFTC_MIN_DOC_FREQ es demasiado alto para su catálogo, redúzcalo a 1.

Todos los clusters están marcados como pillar gap

El umbral DFTC_PILLAR_MATCH_THRESHOLD probablemente sea demasiado alto. Pruebe 0.30 en lugar de 0.45 si su tienda tiene pocas páginas CMS. Verifique también que sus páginas CMS y categorías estén activas.

Error «Unknown column meta_keywords»

Este error ocurre en PrestaShop 9 con una versión anterior del módulo. Actualice a la versión 1.0.0 o superior, que elimina todas las referencias a meta_keywords (columna eliminada en PS 9).

Error «Compile Error: Access level to processExport() must be public»

Este error ocurría en una versión pre-1.0.0. El nombre del método ahora es doExport() para evitar la colisión con AdminControllerCore. Actualice el módulo.

La ejecución falla con error API

Verifique que la clave API introducida en la configuración sea válida y tenga créditos. Pruebe con curl en CLI para confirmar que el servidor puede alcanzar api.openai.com o api.mistral.ai.

Próximas evoluciones

• Creación directa de páginas CMS desde el borrador (en un clic)
• Comparación de ejecuciones (antes/después de la publicación de pillar pages)
• Visualización gráfica de la red semántica inter-clusters
• Soporte de embeddings Cohere y Voyage AI
• Cron automático para reejecuciones periódicas