# 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…

- Página: <https://www.datafirefly.com/es/documentation/topic-cluster-detector/>
- Idioma: es
- Actualizado el: 2026-06-28
- Otros idiomas: [fr](https://www.datafirefly.com/documentation/topic-cluster-detector/index.md), [en](https://www.datafirefly.com/en/documentation/topic-cluster-detector/index.md), [de](https://www.datafirefly.com/de/documentation/topic-cluster-detector/index.md), [it](https://www.datafirefly.com/it/documentation/topic-cluster-detector/index.md), [pl](https://www.datafirefly.com/pl/documentation/topic-cluster-detector/index.md), [nl](https://www.datafirefly.com/nl/documentation/topic-cluster-detector/index.md), [pt](https://www.datafirefly.com/pt/documentation/topic-cluster-detector/index.md)
- Índice: <https://www.datafirefly.com/es/documentation/llms.txt>

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)

**A recordar.** El módulo no crea páginas directamente en PrestaShop. Le proporciona un borrador para copiar-pegar en una nueva página CMS o landing de categoría, manteniendo la decisión editorial en sus manos.

## 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

| Clave | Por defecto | Descripción |
| --- | --- | --- |
| `DFTC_MODE` | `tfidf` | Modo de clustering: `tfidf` (local), `openai` o `mistral` |
| `DFTC_K_AUTO` | activado | Si está activado, calcula automáticamente k = ceil(√(N/2)) limitado a [5, 30] |
| `DFTC_K_MANUAL` | 12 | Valor de k utilizado si `DFTC_K_AUTO` está desactivado |
| `DFTC_MAX_ITER` | 60 | Número máximo de iteraciones del k-means |
| `DFTC_MIN_CLUSTER_SIZE` | 3 | Tamaño mínimo de un cluster; por debajo, se descarta |

### 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

| Clave | Por defecto | Descripción |
| --- | --- | --- |
| `DFTC_MIN_DOC_FREQ` | 2 | Término ignorado si aparece en menos de N productos |
| `DFTC_MAX_DOC_FREQ_RATIO` | 0.50 | Término ignorado si aparece en más del X% del catálogo |
| `DFTC_NGRAM_MAX` | 2 | 1 = unigramas, 2 = unigramas + bigramas |
| `DFTC_TOP_TERMS_COUNT` | 8 | Número de términos mostrados por cluster |

### APIs de embeddings

| Clave | Descripción |
| --- | --- |
| `DFTC_OPENAI_API_KEY` | Bearer token OpenAI (sk-...) |
| `DFTC_OPENAI_MODEL` | Modelo (por defecto `text-embedding-3-small`) |
| `DFTC_MISTRAL_API_KEY` | Clave API Mistral |
| `DFTC_MISTRAL_MODEL` | Modelo (por defecto `mistral-embed`) |
| `DFTC_BATCH_SIZE` | Número de productos por llamada API (por defecto 32) |

### 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.

**Consejo.** La caché de embeddings es automática: si vuelve a ejecutar sobre el mismo catálogo sin modificar los textos, los vectores se recuperan de la tabla `df_topicclusters_embedding_cache` sin nueva llamada API.

### 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

**Importante.** El módulo establece `set_time_limit(0)` y `memory_limit=1024M` durante la ejecución. En hostings muy limitados, estas directivas pueden ser ignoradas. Prefiera una ejecución nocturna o use el límite de productos para dividir.

## 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).

**Buenas prácticas SEO.** Una pillar page de calidad tiene al menos 1.500 palabras, integra enlaces internos a los productos del cluster, y usa los top-términos de forma natural en el contenido. El borrador generado es un punto de partida, no un entregable final.

## 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

**Soporte.** Para cualquier pregunta o bug, contacte [support@datafirefly.com](mailto:support@datafirefly.com). Los comentarios son valiosos para orientar la roadmap.