Enlazado Interno Semántico IA — Guía completa

Presentación

DataFirefly Enlazado Interno Semántico IA (dfaisemanticlinks) construye el enlazado interno de tu tienda PrestaShop a partir de embeddings vectoriales. Cada producto, categoría y página CMS se transforma en un vector por un proveedor de IA (Mistral u OpenAI), los vectores se comparan por similitud coseno, y el módulo propone enlaces contextuales con anclas extraídas literalmente del texto fuente. Validas las sugerencias una a una o en lote, y cada enlace insertado puede retirarse quirúrgicamente gracias a un marcador único data-dfasl.

Requisitos

• PrestaShop 8.0 → 9.x (PrestaShop 1.7 no compatible)
• PHP 8.1, 8.2 u 8.3
• MySQL 5.7+ / MariaDB 10.3+
• Una clave API de Mistral (console.mistral.ai) o de OpenAI (platform.openai.com)
• Acceso CLI recomendado para catálogos de más de 1.000 entidades (cron)

Instalación

1. Backoffice → Módulos → Gestor de módulos → Subir un módulo.
2. Sube dfaisemanticlinks.zip y haz clic en Instalar.
3. El módulo crea 5 tablas con prefijo dfasl_ (embedding, queue, suggestion, inserted_link, job) y un menú Enlazado IA con 4 pestañas: Panel, Sugerencias, Enlaces insertados, Configuración.

Configuración

1. Proveedor de embeddings

Pestaña Configuración, primer bloque:

• Proveedor: Mistral (mistral-embed, 1024 dimensiones, por defecto, alojamiento UE) u OpenAI (text-embedding-3-small, 1536 dimensiones).
• Clave API: pega la clave del proveedor seleccionado.
• Probar conexión API: el botón envía una cadena de prueba y muestra las dimensiones recibidas. Valida siempre la clave aquí antes de lanzar una indexación.

2. Indexación

• Tipos indexados: productos, categorías, páginas CMS — cada uno activable de forma independiente.
• Longitud mínima (por defecto 200 caracteres): los contenidos demasiado cortos tras la limpieza HTML se ignoran.
• Tamaño de lote (por defecto 20): número de elementos enviados por petición API. Una sola llamada de embedding por lote.
• Reindexación automática (activada por defecto): cada cambio de producto/categoría/CMS vuelve a poner la entidad en cola vía hooks. Desactívala temporalmente durante una importación CSV masiva.

3. Sugerencias e inserción

• Umbral de similitud (por defecto 0,78): los pares por debajo del umbral se ignoran. Baja a 0,72 para más sugerencias, sube a 0,82 para mayor severidad.
• Enlaces máx. por página (por defecto 5): protección SEO anti-sobreoptimización.
• Estrategia de anclado: n-gramas optimizados (por defecto) o título bruto del destino.

Primera indexación

1. Pestaña Panel → botón Reindexar todo: todas las entidades activas de los tipos habilitados se ponen en cola, en todos los idiomas activos.
2. Haz clic en Procesar lote tantas veces como sea necesario (catálogos pequeños), o lanza el worker CLI (ver más abajo).
3. Cada lote: extracción + limpieza del texto, llamada de embedding en batch, almacenamiento del vector, y cálculo de las sugerencias por similitud coseno.

El panel muestra en continuo: entidades totales, embeddings activos, sugerencias pendientes, enlaces activos, y los estados de la cola (Pendiente, En proceso, Completado, Error).

Validar las sugerencias

Pestaña Sugerencias: tabla paginada con, por fila, la fuente, el destino, la puntuación de similitud, el ancla propuesta, un snippet de contexto, y los botones Insertar / Rechazar.

Elegir el ancla

El generador de anclas extrae los n-gramas (2 a 6 palabras) del título destino presentes literalmente en el cuerpo fuente, ordenados del más largo al más corto. El desplegable lista todos los candidatos; la opción Personalizar abre un campo libre. El ancla por defecto es el n-grama más largo encontrado — en general 3 o 4 palabras que incluyen las palabras clave principales del destino.

Inserción

En la inserción, el módulo enlaza la primera ocurrencia del ancla que no esté ya dentro de una etiqueta a, code o pre (patrones PCRE SKIP/FAIL). Si no existe ninguna ocurrencia libre, se añade un párrafo de respaldo con la clase dfasl-related al pie de la descripción. Cada enlace recibe un atributo data-dfasl con un identificador único de 36 caracteres.

Acciones en lote

Marca varias filas (casilla de cabecera para seleccionar todo) y luego Insertar selección o Rechazar selección. Paginación de 50 filas.

Retirar un enlace (reversión)

Pestaña Enlaces insertados: lista paginada de los enlaces activos con fuente, destino, ancla, fecha, empleado. El botón Retirar elimina únicamente la etiqueta a data-dfasl con ese identificador — el texto del ancla permanece intacto, ningún otro elemento HTML se ve afectado, y el enlace se marca como retirado en la base de datos.

Worker CLI y cron

Para catálogos voluminosos, usa el worker de línea de comandos:

php modules/dfaisemanticlinks/bin/analyze.php [opciones]

• --shop=N: apunta a una tienda concreta (multitienda).
• --enqueue-all: vuelve a encolar todas las entidades activas antes de procesar.
• --loop: itera mientras queden elementos pendientes.
• --max-batches=N: limita el número de lotes por ejecución (seguridad anti-runaway).
• --sleep=N: pausa en segundos entre lotes (rate limits API).

Cron recomendado cada 15 minutos:

*/15 * * * * php /ruta/a/prestashop/modules/dfaisemanticlinks/bin/analyze.php --loop --max-batches=50 --sleep=1

Reindexación automática

Los hooks actionObjectProductUpdateAfter, actionObjectCategoryUpdateAfter y actionObjectCmsUpdateAfter vuelven a encolar la entidad modificada en todos los idiomas activos. Los hooks de eliminación purgan embeddings y sugerencias en cascada. El hash de contenido SHA-256 evita cualquier llamada API si el texto real no ha cambiado (por ejemplo, una simple modificación de stock).

Multitienda y multiidioma

Los embeddings tienen scope por el triplete (entidad, idioma, tienda). Las sugerencias nunca cruzan fronteras lingüísticas ni de tienda. La configuración (clave API, umbral, tipos indexados) puede diferir por tienda mediante el selector de contexto multitienda estándar de PrestaShop.

Solución de problemas

«Clave API no configurada» o error en la prueba de conexión

Comprueba que la clave corresponde al proveedor seleccionado en el desplegable (una clave Mistral no funciona con el proveedor OpenAI y viceversa) y que dispone de créditos. Los errores API detallados se registran en Parámetros avanzados → Logs (PrestaShopLogger).

Hay elementos que permanecen en estado «En proceso»

Probablemente un worker fue interrumpido. Espera 30 minutos (reset automático) o haz clic en Vaciar cola y relanza Reindexar todo.

Pocas o ninguna sugerencia generada

Tres causas frecuentes: umbral de similitud demasiado alto (prueba 0,72), contenidos demasiado cortos (por debajo de la longitud mínima), o catálogo demasiado homogéneo/heterogéneo. Comprueba también que los tipos de entidades deseados estén activados en Configuración.

El ancla propuesta es el título bruto del destino

Es el modo fallback: ningún n-grama del título destino aparece literalmente en el cuerpo fuente. Elige un ancla personalizada o enriquece la descripción fuente.

Arquitectura técnica

• PHP 8.1+ estricto, PSR-4 bajo el namespace DataFirefly/AiSemanticLinks/ mapeado en src/
• Controllers admin legacy ModuleAdminController (compatibilidad estable PS8/PS9)
• Mini-contenedor de servicios casero (independiente del contenedor Symfony)
• Vectores en BLOB float32 empaquetado little-endian + norma L2 precalculada
• 5 tablas: dfasl_embedding, dfasl_queue, dfasl_suggestion, dfasl_inserted_link, dfasl_job
• Código fuente sin cifrar, listo para override