Tutto quello che vorresti sapere prima di installare.
Uno sguardo dettagliato su come funziona DataFirefly Linking Interno Semantico IA — Embedding vettoriali, similarità coseno e inserimento semi-automatico con ancore intelligenti per PrestaShop 8 & 9 (Mistral, OpenAI), perché l'abbiamo progettato così, e il ragionamento dietro le funzionalità qui sopra.
Perché il linking interno semantico è superiore al linking per parole chiave
I moduli di linking interno classici funzionano per regole parola-chiave verso URL. Inserisci tappeto berbero e associ l'URL della categoria tappeto-berbero. Il motore esegue poi un find-replace nell'HTML dei tuoi articoli, prodotti o pagine. Questo approccio ha due limiti principali. È rigido: attiva un link solo quando appare la parola chiave esatta, il che esclude tutte le pagine in cui l'argomento è trattato sotto un'altra formulazione (tappeto marocchino, kilim, tappeto tradizionale). Ed è cieco al contesto semantico: il motore non sa se la pagina target è davvero pertinente per il contenuto sorgente, fa solo un match di stringa. Il linking semantico funziona diversamente: ogni contenuto è rappresentato da un vettore di diverse centinaia di dimensioni che codifica il suo senso — prodotto, categoria, pagina CMS, blog. Due contenuti sono collegati se sono vicini in questo spazio vettoriale, indipendentemente dalle parole utilizzate. Il modulo individua così opportunità di linking che un motore per parole chiave non vedrebbe mai, ed evita i falsi positivi in cui una parola chiave appare in un contesto non pertinente.
Embedding IA: come funziona nella pratica
Durante la prima indicizzazione, il modulo scorre tutte le entità attive del tuo negozio per i tipi attivati (prodotti, categorie, pagine CMS). Per ogni entità, il contenuto testuale viene estratto e pulito: titolo, meta_title, meta_description, descrizione breve e descrizione lunga (l'HTML viene strippato correttamente). Il testo pulito viene poi inviato in batch al fornitore IA configurato (Mistral o OpenAI), che restituisce un vettore di embedding per item — una lista di numeri in virgola mobile che rappresenta la semantica del testo. Questo vettore è archiviato in database sotto forma di BLOB float32 impacchettato in little-endian, con la sua norma L2 pre-calcolata per accelerare i calcoli successivi di similarità. La similarità tra due contenuti è poi calcolata in PHP tramite prodotto scalare normalizzato (similarità coseno), un'operazione estremamente rapida una volta pre-calcolate le norme. Su un catalogo di 5.000 entità, il calcolo completo di tutte le coppie in una lingua impiega solo pochi secondi.
Perché due fornitori e non uno solo
Ogni fornitore ha il suo sweet spot. Mistral mistral-embed è l'opzione di default raccomandata: 1024 dimensioni, latenza molto bassa, hosting Europa (sovranità UE per i negozi sensibili), costo di circa 10 centesimi per milione di token — ossia meno di un euro per indicizzare un catalogo di diverse migliaia di entità multilingua. OpenAI text-embedding-3-small è l'alternativa: 1536 dimensioni (spazio vettoriale più ricco), eccellente sulle lingue non europee, costo di circa 2 centesimi per milione di token (cinque volte meno caro di Mistral in USD). Il modulo unifica i due fornitori dietro un'interfaccia comune: stesso formato di ritorno, stesso meccanismo di batch, stessa gestione degli errori con PrestaShopLogger. Puoi passare da un fornitore all'altro dal dropdown di configurazione — il modulo rileverà che le dimensioni sono cambiate e inviterà a reindicizzare (un semplice clic su Reindicizza tutto).
Il generatore di ancore, vera punta di diamante del modulo
È il punto che fa la differenza rispetto a un modulo di suggerimento grezzo. Per ogni coppia (sorgente, target) al di sopra della soglia di similarità, il generatore di ancore applica il seguente algoritmo: estrae il titolo del target, lo divide in n-grammi da 2 a 6 parole, rimuove le stopword (francesi e inglesi), poi cerca ciascuno di questi n-grammi verbatim nel corpo della sorgente. Gli n-grammi trovati sono classificati per lunghezza decrescente (i più lunghi sono più discriminanti e più ottimizzati SEO) e presentati nel dropdown del back-office. L'ancora di default selezionata è la più lunga trovata — il che dà tipicamente un'ancora di 3 o 4 parole che include le parole chiave principali del titolo target. Se nessun n-gramma del titolo target appare nella sorgente, il modulo propone il titolo target grezzo (modalità fallback). Mantieni ovviamente il controllo: dropdown modificabile, opzione Personalizza per inserire qualsiasi testo di ancora. Al momento dell'inserimento, il modulo sceglie la prima occorrenza del testo di ancora nel corpo della sorgente che non sia già in un tag a, code o pre — nessun rischio di rompere un link esistente né di ri-linkare un testo già linkato.
Rollback chirurgico tramite marcatore univoco
È la funzionalità che rassicura tutti i merchant prudenti con le loro descrizioni. Ogni link inserito riceve un attributo HTML data-dfasl con un identificativo univoco di 36 caratteri generato casualmente all'inserimento (formato di tipo UUID). L'identificativo è archiviato anche in database nella tabella dfasl_inserted_link, con l'entità sorgente, il target, l'ancora, la data di inserimento e l'identificativo del dipendente che ha convalidato. Per rimuovere un link, vai nel tab Link inseriti, clicchi su Rimuovi accanto alla riga interessata: il modulo esegue una regex che matcha esattamente il pattern di ancora a data-dfasl con questo identificativo univoco, rimuove il tag a mantenendo intatto il testo dell'ancora, e marca il link come rimosso nel database. Nessun altro tag della descrizione viene toccato, nessun link manuale è in pericolo. Su 500 link inseriti dal modulo in 200 schede prodotto, puoi rimuoverne uno solo con un clic senza toccare gli altri 499.
Worker CLI e strategia di elaborazione per cataloghi grandi
Su un catalogo di alcune decine di prodotti, tutto può essere fatto dal back-office: Reindicizza tutto poi Elabora un lotto è sufficiente. Oltre le diverse migliaia di entità, l'interfaccia diventa lenta e l'utente non ha voglia di tenere il browser aperto per ore. Il modulo espone un worker CLI (bin/analyze.php) che si lancia a riga di comando PHP con quattro opzioni. --shop per puntare a un negozio preciso in un ambiente multishop. --enqueue-all per ri-accodare tutte le entità attive prima di elaborare — utile per una re-indicizzazione completa dopo un cambio di fornitore o di modello. --loop per continuare a ciclare finché restano item da elaborare. --max-batches per limitare il numero di lotti elaborati in un singolo run (sicurezza anti-runaway). --sleep per intercalare una pausa tra lotti (utile per restare sotto i rate limit API). Il comando tipo per un cron ogni 15 minuti è: php modules/dfaisemanticlinks/bin/analyze.php --loop --max-batches=50 --sleep=1. Il worker resetta automaticamente le voci bloccate in stato In corso da più di 30 minuti (caso in cui un worker precedente si fosse piantato), gestisce gli errori API marcando gli item interessati in stato In errore con il messaggio, e continua a elaborare gli item sani del lotto.
Auto-reindicizzazione e freschezza dell'indice
Un indice che si desincronizza dal catalogo non ha più alcun valore. Il modulo gestisce la freschezza tramite hook PrestaShop nativi. A ogni modifica di un prodotto, di una categoria o di una pagina CMS (hook actionObjectProductUpdateAfter, actionObjectCategoryUpdateAfter, actionObjectCmsUpdateAfter), l'entità interessata viene rimessa nella coda con uno stato In attesa, in tutte le lingue attive — il worker successivo la elaborerà automaticamente. Alla cancellazione (hook actionObjectProductDeleteAfter, actionObjectCategoryDeleteAfter, actionObjectCmsDeleteAfter), gli embedding e i suggerimenti associati vengono purgati in cascata. Il modulo include anche un hash di contenuto (SHA-256 del testo pulito): se un'entità viene rimessa in coda senza che il suo contenuto reale sia cambiato (per esempio perché un dipendente ha appena toccato lo stock), il batch di indicizzazione rileva l'hash invariato e salta la chiamata API — risparmio di token. L'auto-reindicizzazione è attivabile dalle Impostazioni (opzione DFASL_AUTO_INDEX), utile per sospenderla durante un import CSV massiccio e riprenderla una volta finito l'import con un Reindicizza tutto.
Multinegozio e multilingua nativi
Il modulo è nativamente multinegozio e multilingua. Gli embedding sono scopati per tripletta (entità, lingua, negozio) — uno stesso prodotto in due negozi avrà due embedding indipendenti se le descrizioni differiscono, e uno stesso prodotto in francese e in inglese avrà due embedding diversi anche se la scheda è la stessa. I suggerimenti non attraversano mai le frontiere linguistiche: un prodotto francese non vedrà mai suggerito un link verso un prodotto inglese (il che non avrebbe alcun senso in SEO). Le frontiere dei negozi sono rispettate allo stesso modo. La configurazione può essere diversa per negozio (chiave API, soglia di similarità, tipi indicizzati, hook di visualizzazione) — utile quando hai un negozio B2B con contenuto tecnico e un negozio B2C con contenuto generalista nella stessa infrastruttura.
Casi d'uso tipici
Negozio di moda multilingua con catalogo di 2.000 prodotti — il linking semantico individua le coppie di prodotti visivamente o stilisticamente vicini (per esempio due varianti di un taglio di abito) che regole per parole chiave perderebbero sistematicamente. Negozio B2B tecnico con descrizioni dense — il linking semantico collega i prodotti che condividono uno stesso caso d'uso industriale senza che il vocabolario sia identico. Blog e-commerce — ogni articolo può citare automaticamente i prodotti, categorie e altri articoli più pertinenti per senso, con ancore estratte verbatim dal testo dell'articolo (il contrario di un find-replace meccanico). Refactoring di catalogo — dopo un import massiccio o una riorganizzazione, un Reindicizza tutto ricostruisce il linking in pochi minuti dove una strategia manuale avrebbe richiesto settimane di lavoro editoriale. Catalogo a forte vocabolario specifico (cosmetica bio, attrezzatura medica, prodotti tecnici) — il modulo rileva le prossimità semantiche che i non esperti non vedrebbero, e permette al team SEO di scoprire opportunità di linking non evidenti.
Architettura interna e compatibilità PrestaShop 8 e 9
Il modulo è costruito in PHP 8.1+ con tipi stretti, classi readonly e funzionalità moderne (match, enum). L'autoload è PSR-4 nel namespace DataFirefly/AiSemanticLinks/ mappato su src/. I controller admin sono in legacy ModuleAdminController (non Symfony Grid) — scelta volontaria per garantire una compatibilità stabile tra PrestaShop 8.0 e 9.x senza dover mantenere due varianti del codice. Un mini-container di servizi personalizzato (ServiceContainer) collega i repository e i servizi di business — il che isola il modulo dalle differenze di container Symfony tra le versioni di PrestaShop, ed evita una dipendenza che si romperebbe a ogni aggiornamento maggiore. Cinque tabelle SQL con prefisso dfasl_: embedding (vettori e hash), queue (coda di lavoro), suggestion (coppie proposte), inserted_link (link attivi), job (operazioni di bulk). La disinstallazione rimuove correttamente le 5 tabelle e purga tutte le variabili di configurazione DFASL_*. Il codice sorgente è consegnato non offuscato, conforme PSR — puoi sovrascriverlo, auditarlo o estenderlo come ritieni opportuno.
Ancora non ci sono recensioni.