Auditoría Semántica — Documentación

Instalación

Requisitos previos

• PrestaShop 8.0 a 9.x
• PHP 7.4 mínimo (8.x recomendado)
• MySQL 5.7+ o MariaDB 10.3+
• Una clave API OpenAI o Mistral (opcional — se incluye un modo local sin API)

Instalar el módulo

1. Descomprima el archivo dfsemanticaudit.zip descargado desde su cuenta de cliente.
2. Suba la carpeta dfsemanticaudit/ a /modules/ de su PrestaShop vía FTP, o use la instalación por ZIP desde Módulos → Module manager → Subir un módulo.
3. Haga clic en Instalar.

Activar el módulo

El módulo crea automáticamente cuatro tablas SQL (ps_dfsa_content, ps_dfsa_audit, ps_dfsa_cluster, ps_dfsa_assignment) así como una pestaña de administración accesible desde el menú izquierdo.

Configuración

Antes de la primera auditoría, vaya a Módulos → DataFirefly → Auditoría Semántica → Configuración.

Elección del proveedor de embeddings

Hay tres proveedores disponibles. La elección determina la calidad de los clusters obtenidos.

OpenAI (recomendado)

El proveedor predeterminado. Usa el modelo text-embedding-3-small (1.536 dimensiones). Calidad máxima, coste marginal: aproximadamente 0,02 € por 1.000 productos en la primera indexación.

• Clave API: créela desde platform.openai.com/api-keys
• Modelo: deje text-embedding-3-small por defecto. text-embedding-3-large (3.072 dim) da una calidad ligeramente superior pero cuesta 6× más.

Mistral

Alternativa europea alojada en Francia. Usa mistral-embed (1.024 dimensiones). Tarificación comparable a OpenAI.

• Clave API: créela desde console.mistral.ai
• Modelo: mistral-embed

TF-IDF local

Funciona enteramente en su servidor, sin llamadas API, sin coste recurrente. Usa los principios clásicos del tratamiento estadístico del lenguaje (TF-IDF normalizado) con una dimensión de 384.

• Calidad suficiente para catálogos de menos de 500 productos.
• Soporta FR, EN, ES, DE, IT (stopwords integradas).
• Sin clave API requerida.

Parámetros de auditoría

• k (número de clusters): 8 por defecto. Rango 2–50.
• Umbral fuera de tema: distancia coseno a partir de la cual se marca un contenido. 0,55 por defecto. Rango 0,1 a 1,5.

Auto-reindexación

Activada por defecto. El módulo registra hooks en la creación, modificación y eliminación de productos, categorías y páginas CMS. En cada cambio, el contenido se marca para re-embedding en la próxima ejecución, sin esfuerzo manual.

Lanzar su primera auditoría

Tres pasos a ejecutar en orden desde el panel de control.

Paso 1 — Reindexar el contenido

Haga clic en Reindexar el contenido. El módulo recorre sus productos, categorías activas, páginas CMS y fabricantes, calcula un hash SHA1 del título + extracto, y solo marca para procesamiento el contenido nuevo o modificado.

Para 1.000 elementos, este paso dura unos segundos.

Paso 2 — Generar los embeddings

Haga clic en Generar embeddings. El módulo envía el contenido marcado como «dirty» al proveedor seleccionado en lotes de 50 (OpenAI/Mistral) o en una sola pasada local (TF-IDF). Una barra de progreso sigue el avance.

Para 1.000 elementos:

• OpenAI: ~30 segundos
• Mistral: ~40 segundos
• TF-IDF local: <1 segundo

Paso 3 — Lanzar la auditoría

Haga clic en Lanzar la auditoría. El clustering k-means coseno agrupa el contenido en k clusters (inicialización k-means++, 50 iteraciones máximas), etiqueta cada cluster con sus top términos (TF×IDF), calcula la distancia de cada contenido a su centroide e identifica los outliers.

Este paso tarda menos de un segundo, incluso para 5.000 elementos.

Comprender el informe

Panel de control

Cuatro KPIs clave en la parte superior:

• Contenidos indexados — total de productos, categorías, CMS y fabricantes embebidos.
• Páginas fuera de tema — número absoluto, tasa en porcentaje y reparto por tipo.
• Clusters temáticos — número de grupos temáticos identificados.
• Distancia mediana — distancia coseno mediana al centroide. Por debajo de 0,40 = catálogo muy coherente. Por encima de 0,60 = catálogo disperso.

Clusters

Vista Clusters: lista detallada ordenada por tamaño, con etiqueta automática (top 5 términos TF×IDF), puntuación de cohesión (0 = disperso, 1 = idéntico) y tamaño (número de elementos).

Un cluster con cohesión < 0,40 es demasiado heterogéneo — a menudo es señal de que habría que dividir el tema en dos sub-temas, o que k es demasiado bajo.

Mapa semántico 2D

Proyección de todos los contenidos en un plano vía la técnica Johnson-Lindenstrauss (una proyección aleatoria que preserva aproximadamente las distancias).

Cada punto es un contenido, cada color un cluster. Las cruces marcan los centroides. Los puntos con contorno rojo son los fuera de tema. La leyenda a la derecha permite ocultar/mostrar cada cluster individualmente al hacer clic.

Páginas fuera de tema

Vista Páginas fuera de tema: tabla ordenable de los contenidos cuya distancia coseno al centroide supera el umbral configurado. Para cada fila:

• Tipo, título, URL pública y enlace directo a la ficha de edición
• Cluster actual (con su color)
• Distancia al centroide (cuanto más alta, más alejado el contenido)
• Cluster sugerido (si es pertinente)
• Δ Ganancia: reducción de distancia si se moviera el contenido

Páginas irrecuperables

Al final de la vista Fuera de tema, una sección especial lista los contenidos alejados de todos los clusters. El módulo no ha encontrado un destino viable para ellos.

Tres acciones a considerar:

1. Eliminar si la página no tiene tráfico SEO ni conversión.
2. Noindex para preservar el presupuesto de crawl sin perder el historial.
3. Reescribir para alinear el contenido con un cluster existente.

Sugerencias de reestructuración

Vista Sugerencias: equivalente a Páginas fuera de tema pero centrada en la acción. Todos los desplazamientos propuestos se listan con la ganancia de coherencia esperada. Ordene por ganancia decreciente para tratar primero los casos más impactantes.

El módulo nunca modifica su árbol de categorías automáticamente. Los cambios siguen bajo su control vía el back-office estándar de PrestaShop.

Exportación CSV

Desde cada vista del informe, un botón Exportar CSV permite descargar los datos brutos. Útil para:

• Compartir el informe con un consultor SEO externo
• Tratar los datos en Excel/Sheets
• Archivar el estado de una auditoría antes de modificar el árbol

Automatización vía cron

El módulo expone una URL firmada mostrada en la página de configuración. Dispara en modo headless la cadena completa indexación → embeddings → auditoría.

Ejemplo de tarea cron semanal (cada lunes a las 3h):

0 3 * * 1 wget -q -O /dev/null "https://su-tienda.com/modules/dfsemanticaudit/cron.php?token=SU_TOKEN"

El token se deriva de la _COOKIE_KEY_ de su PrestaShop y solo cambia con la reinstalación. Guárdelo con cuidado.

Costes API

Estimación para un catálogo medio (1.000 productos):

• OpenAI text-embedding-3-small: ~0,02 € la primera vez, después casi cero (solo el contenido modificado se reprocesa)
• OpenAI text-embedding-3-large: ~0,13 € la primera vez
• Mistral mistral-embed: ~0,10 € la primera vez
• TF-IDF local: 0 €

Multi-idioma y multi-tienda

El módulo es nativamente multi-idioma y multi-tienda. Cada auditoría se ejecuta en un par idioma × tienda dado, usando el idioma de contexto del back-office.

Para auditar su tienda en francés y luego en inglés, cambie de idioma en la barra superior de PrestaShop, después lance una nueva auditoría.

Solución de problemas

El paso «Generar embeddings» falla con un error 401

Su clave API es inválida o ha expirado. Verifíquela en la página de configuración y reconfigúrela si es necesario.

El paso «Generar embeddings» falla con un error 429

Ha alcanzado el límite de tasa de su proveedor. Espere unos minutos y vuelva a intentarlo — el módulo reanudará donde se detuvo gracias a su procesamiento por lotes.

Ningún cluster parece pertinente

Tres pistas:

1. Aumente el número de clusters (k). Si su catálogo tiene 10 temáticas distintas pero k=4, el clustering no podrá separarlas.
2. Pase del modo TF-IDF local a OpenAI o Mistral. En catálogos heterogéneos, la calidad semántica marca toda la diferencia.
3. Verifique que los títulos y descripciones de sus contenidos sean suficientemente ricos. Un producto con un título de 2 palabras y sin descripción no dará un buen embedding.

Demasiadas páginas marcadas como fuera de tema

Aumente el umbral fuera de tema (por ejemplo de 0,55 a 0,70). Es esperable si su catálogo cubre legítimamente varias temáticas amplias.

Ninguna página marcada como fuera de tema pero el catálogo parece incoherente

Baje el umbral (por ejemplo de 0,55 a 0,40) para ajustar la detección.

FAQ

¿Es obligatoria una clave API?

No. El modo TF-IDF local funciona sin conexión externa. Es ligeramente menos preciso que OpenAI/Mistral pero suficiente para empezar o para un catálogo homogéneo.

¿El módulo modifica automáticamente mi árbol de categorías?

No. El módulo solo recomienda. Todos los desplazamientos de contenido siguen bajo su responsabilidad vía el back-office estándar de PrestaShop.

¿Cómo elegir el número de clusters (k)?

Regla empírica: k ≈ número de categorías principales de primer nivel. Por defecto k=8 funciona bien entre 100 y 5.000 productos. Lance 2 o 3 auditorías con diferentes valores de k para comparar si duda — las auditorías anteriores se conservan en el historial.

¿Se envían mis vectores a un servidor de terceros?

Con OpenAI o Mistral: sí, los títulos y extractos de sus contenidos se envían a su API de embeddings. Con el modo TF-IDF local: no, ningún dato sale de su servidor.

¿Cuánto tiempo se conservan las auditorías?

Indefinidamente, hasta eliminación manual desde el panel de control. Puede consultar el historial completo para medir la evolución de su coherencia semántica a lo largo del tiempo.

¿El módulo funciona en multi-tienda?

Sí. Cada tienda del multistore puede tener sus propias auditorías independientes.