Link Interni Semantici IA — Guida completa

Panoramica

DataFirefly Link Interni Semantici IA (dfaisemanticlinks) costruisce il linking interno del tuo negozio PrestaShop a partire da embedding vettoriali. Ogni prodotto, categoria e pagina CMS viene trasformato in un vettore da un provider IA (Mistral o OpenAI), i vettori vengono confrontati tramite similarità coseno, e il modulo propone link contestuali con ancore estratte letteralmente dal testo sorgente. Convalidi i suggerimenti uno a uno o in blocco, e ogni link inserito può essere rimosso chirurgicamente grazie a un marcatore unico data-dfasl.

Requisiti

• PrestaShop 8.0 → 9.x (PrestaShop 1.7 non supportato)
• PHP 8.1, 8.2 o 8.3
• MySQL 5.7+ / MariaDB 10.3+
• Una chiave API Mistral (console.mistral.ai) o OpenAI (platform.openai.com)
• Accesso CLI consigliato per cataloghi con più di 1.000 entità (cron)

Installazione

1. Back office → Moduli → Gestione moduli → Carica un modulo.
2. Carica dfaisemanticlinks.zip e clicca su Installa.
3. Il modulo crea 5 tabelle con prefisso dfasl_ (embedding, queue, suggestion, inserted_link, job) e un menu Linking IA con 4 schede: Dashboard, Suggerimenti, Link inseriti, Impostazioni.

Configurazione

1. Provider di embedding

Scheda Impostazioni, primo blocco:

• Provider: Mistral (mistral-embed, 1024 dimensioni, predefinito, hosting UE) o OpenAI (text-embedding-3-small, 1536 dimensioni).
• Chiave API: incolla la chiave del provider selezionato.
• Testa connessione API: il pulsante invia una stringa di prova e mostra le dimensioni ricevute. Convalida sempre la chiave qui prima di avviare un’indicizzazione.

2. Indicizzazione

• Tipi indicizzati: prodotti, categorie, pagine CMS — ognuno attivabile in modo indipendente.
• Lunghezza minima (predefinito 200 caratteri): i contenuti troppo corti dopo la pulizia HTML vengono ignorati.
• Dimensione batch (predefinito 20): numero di elementi inviati per richiesta API. Una sola chiamata di embedding per batch.
• Reindicizzazione automatica (attiva per default): ogni modifica prodotto/categoria/CMS rimette l’entità in coda tramite hook. Disattivala temporaneamente durante un’importazione CSV massiva.

3. Suggerimenti e inserimento

• Soglia di similarità (predefinito 0,78): le coppie sotto la soglia vengono ignorate. Scendi a 0,72 per più suggerimenti, sali a 0,82 per maggiore severità.
• Link max per pagina (predefinito 5): protezione SEO anti-sovraottimizzazione.
• Strategia di ancoraggio: n-grammi ottimizzati (predefinito) o titolo grezzo della destinazione.

Prima indicizzazione

1. Scheda Dashboard → pulsante Reindicizza tutto: tutte le entità attive dei tipi abilitati vengono messe in coda, in tutte le lingue attive.
2. Clicca su Elabora batch tutte le volte necessarie (cataloghi piccoli), oppure avvia il worker CLI (vedi sotto).
3. Ogni batch: estrazione + pulizia del testo, chiamata di embedding in batch, memorizzazione del vettore, poi calcolo dei suggerimenti tramite similarità coseno.

La dashboard mostra in continuo: entità totali, embedding attivi, suggerimenti in attesa, link attivi, e gli stati della coda (In attesa, In elaborazione, Completato, Errore).

Convalidare i suggerimenti

Scheda Suggerimenti: tabella paginata con, per riga, la sorgente, la destinazione, il punteggio di similarità, l’ancora proposta, uno snippet di contesto, e i pulsanti Inserisci / Rifiuta.

Scegliere l’ancora

Il generatore di ancore estrae gli n-grammi (da 2 a 6 parole) del titolo di destinazione presenti letteralmente nel corpo sorgente, ordinati dal più lungo al più corto. Il menu a discesa elenca tutti i candidati; l’opzione Personalizza apre un campo libero. L’ancora predefinita è l’n-gramma più lungo trovato — di solito 3 o 4 parole che includono le parole chiave principali della destinazione.

Inserimento

All’inserimento, il modulo collega la prima occorrenza dell’ancora che non sia già dentro un tag a, code o pre (pattern PCRE SKIP/FAIL). Se non esiste alcuna occorrenza libera, viene aggiunto un paragrafo di fallback con la classe dfasl-related in fondo alla descrizione. Ogni link riceve un attributo data-dfasl con un identificatore unico di 36 caratteri.

Azioni in blocco

Seleziona più righe (casella di intestazione per selezionare tutto) poi Inserisci selezione o Rifiuta selezione. Paginazione di 50 righe.

Rimuovere un link (rollback)

Scheda Link inseriti: elenco paginato dei link attivi con sorgente, destinazione, ancora, data, dipendente. Il pulsante Rimuovi elimina solo il tag a data-dfasl con quell’identificatore — il testo dell’ancora resta intatto, nessun altro elemento HTML viene toccato, e il link viene contrassegnato come rimosso nel database.

Worker CLI e cron

Per cataloghi voluminosi, usa il worker da riga di comando:

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

• --shop=N: punta a un negozio specifico (multishop).
• --enqueue-all: rimette in coda tutte le entità attive prima di elaborare.
• --loop: cicla finché restano elementi in attesa.
• --max-batches=N: limita il numero di batch per esecuzione (sicurezza anti-runaway).
• --sleep=N: pausa in secondi tra i batch (rate limit API).

Cron consigliato ogni 15 minuti:

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

Reindicizzazione automatica

Gli hook actionObjectProductUpdateAfter, actionObjectCategoryUpdateAfter e actionObjectCmsUpdateAfter rimettono in coda l’entità modificata in tutte le lingue attive. Gli hook di eliminazione eliminano embedding e suggerimenti a cascata. L’hash del contenuto SHA-256 evita qualsiasi chiamata API se il testo reale non è cambiato (ad esempio una semplice modifica di stock).

Multi-negozio e multilingua

Gli embedding hanno scope per tripletta (entità, lingua, negozio). I suggerimenti non attraversano mai i confini linguistici né quelli dei negozi. La configurazione (chiave API, soglia, tipi indicizzati) può differire per negozio tramite il selettore di contesto multishop standard di PrestaShop.

Risoluzione dei problemi

«Chiave API non configurata» o errore al test di connessione

Verifica che la chiave corrisponda al provider selezionato nel menu a discesa (una chiave Mistral non funziona con il provider OpenAI e viceversa) e che disponga di crediti. Gli errori API dettagliati sono registrati in Parametri avanzati → Log (PrestaShopLogger).

Alcuni elementi restano nello stato «In elaborazione»

Probabilmente un worker è stato interrotto. Attendi 30 minuti (reset automatico) oppure clicca Svuota coda e rilancia Reindicizza tutto.

Pochi o nessun suggerimento generato

Tre cause frequenti: soglia di similarità troppo alta (prova 0,72), contenuti troppo corti (sotto la lunghezza minima), o catalogo troppo omogeneo/eterogeneo. Verifica anche che i tipi di entità desiderati siano attivati nelle Impostazioni.

L’ancora proposta è il titolo grezzo della destinazione

È la modalità fallback: nessun n-gramma del titolo di destinazione appare letteralmente nel corpo sorgente. Scegli un’ancora personalizzata o arricchisci la descrizione sorgente.

Architettura tecnica

• PHP 8.1+ strict, PSR-4 sotto il namespace DataFirefly/AiSemanticLinks/ mappato su src/
• Controller admin legacy ModuleAdminController (compatibilità stabile PS8/PS9)
• Mini-container di servizi interno (indipendente dal container Symfony)
• Vettori in BLOB float32 compresso little-endian + norma L2 precalcolata
• 5 tabelle: dfasl_embedding, dfasl_queue, dfasl_suggestion, dfasl_inserted_link, dfasl_job
• Codice sorgente non criptato, pronto per l’override