# 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…
- Pagina:
- Lingua: it
- Aggiornato il: 2026-07-01
- Altre lingue: [fr](https://www.datafirefly.com/documentation/dfaisemanticlinks/index.md), [en](https://www.datafirefly.com/en/documentation/dfaisemanticlinks/index.md), [es](https://www.datafirefly.com/es/documentation/dfaisemanticlinks/index.md), [de](https://www.datafirefly.com/de/documentation/dfaisemanticlinks/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfaisemanticlinks/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfaisemanticlinks/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfaisemanticlinks/index.md)
- Indice:
## 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`.
Il modulo non effettua alcuna chiamata IA sul front-office: le similarità sono precalcolate e i link convalidati vengono scritti direttamente nelle descrizioni. Impatto sulle prestazioni: zero.
## 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.
La disinstallazione elimina in modo pulito le 5 tabelle e tutte le variabili di configurazione `DFASL_*`. Esporta i tuoi dati prima se desideri conservarli.
## 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.
Se cambi provider dopo un'indicizzazione, le dimensioni vettoriali cambiano (1024 vs 1536). Il modulo ti inviterà a rilanciare un **Reindicizza tutto** — i vecchi vettori vengono sovrascritti, ma i link già inseriti restano al loro posto.
### 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).
Costo indicativo: 1.000 prodotti in 3 lingue ≈ 1,5 milioni di token ≈ 0,15 EUR (Mistral) o 0,03 USD (OpenAI). Il rilevamento tramite hash SHA-256 fa sì che le reindicizzazioni successive paghino solo i contenuti realmente modificati.
## 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
```
Il worker reimposta automaticamente le voci bloccate nello stato «In elaborazione» da più di 30 minuti (crash di un'esecuzione precedente), contrassegna gli elementi falliti con il messaggio di errore API, e continua a elaborare il resto del batch.
## 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