Cosa abbiamo imparato costruendo il nostro widget di supporto (chat con i tuoi contenuti)

• il retrieval si rompe in modi prevedibili
• la latenza distrugge la fiducia prima che arrivi la prima risposta
• il controllo accessi e facile da sbagliare
• la prompt injection diventa “avvelenamento dei contenuti”
• le risposte devono essere verificabili, altrimenti aumenti il rischio di supporto

Cosa stavamo costruendo (requisiti e vincoli)

• Primo token veloce: gli utenti devono vedere una risposta rapidamente, anche se l’assistente deve “cercare” in background.
• Risposte grounded: le risposte devono essere supportate dai contenuti che pubblichiamo davvero.
• Read-only di default: l’assistente non deve modificare i contenuti.
• Pronto per piu lingue: il sito e localizzato; l’assistente non deve mischiare lingue con leggerezza.
• Escalation sicura: quando non puo rispondere, deve instradare l’utente verso contatto/supporto senza allucinare.

L’assistente deve comportarsi come un ingegnere prudente che legge il nostro sito, non come uno scrittore creativo che improvvisa.

Un modello mentale utile: “support bot = ricerca + navigazione + sintesi”

1. Cerca: identifica pagine/sezioni candidate.
2. Naviga: apre pagine, scansiona heading, segue link, raffina la ricerca.
3. Sintetizza: produce una risposta breve e corretta con indicazioni su da dove arriva.

Lezione 1: un RAG “solo chunk” fallisce quando la risposta e distribuita su piu pagine

• la risposta e divisa tra due pagine
• la “sintassi esatta” e in un blocco di codice che non e entrato in ranking
• la risposta giusta e su una pagina con scarsa sovrapposizione lessicale
• la domanda dell’utente e troppo vaga, quindi il match embedding e “abbastanza vicino”

• tono corretto
• dettagli sbagliati
• nessun modo per verificare

Lezione 2: dare all’assistente primitive deterministiche (docs-come-file)

• find la pagina
• la open
• scorriamo gli heading
• cerchiamo token esatti
• seguiamo i link interni
• ripetiamo finche possiamo provare la risposta

• ogni pagina e un “file”
• le directory rappresentano sezioni (o segmenti dell’URL)
• l’assistente puo fare ls, find, cat e grep

• auditabili (puoi loggare le tool call)
• deterministiche (la stessa query produce le stesse letture)
• scalabili (puo esplorare senza che tu debba hardcodare i flussi)

Architettura (la versione piu semplice che funziona)

Browser widget
  -> /api/support-chat (stream)
      -> Retrieval layer (lexical + vector)
      -> Tool layer ("filesystem" over content)
      -> Answer synthesis (grounded prompt + citations)
      -> Observability (logs + traces + eval hooks)

Modello dati: pagine, chunk e un albero di path

• page: URL/slug canonico + titolo + locale + visibilita + lastmod + heading
• chunk: { page, chunk_index, text, embedding, tokens, hash }
• path_tree: { "services/seo": { isPublic: true, groups: [] }, ... }

• l’assistente ha bisogno di una mappa di “cosa esiste”
• il controllo accessi diventa strutturale (pruni i path prima che inizi la sessione)
• ls/find diventano veloci e cacheabili

Pipeline di ingestion: trasformare un sito in una superficie di conoscenza affidabile

• copy marketing + componenti
• MDX e heading che non mappano pulitamente su HTML
• pagine di navigazione che ripetono blocchi di contenuto
• varianti di lingua che divergono solo in parte

1. Scoperta pagine: sitemap + lista di route note.
2. Fetch HTML renderizzato: cio che utenti e crawler vedono davvero.
3. Estrazione contenuto principale: rimuovi nav, footer, cookie banner, UI ripetuta.
4. Normalizzazione: collassa spazi, rimuovi query di tracking dai link.
5. Segmentazione:
   • record a livello pagina per navigazione e citazioni
   • record a livello chunk per retrieval
6. Annotazione:
   • locale
   • visibilita (pubblico, client-only, interno)
   • outline degli heading
   • link interni in uscita

Retrieval: combinare lessicale e vettoriale prima di “chiedere al modello”

• ricerca lessicale per token esatti (ottima per identificatori, acronimi, codici errore)
• ricerca vettoriale per match semantico (ottima per domande vaghe)

• scarta pagine che non corrispondono al locale dell’utente (a meno che lo chieda esplicitamente)
• preferisci pagine canoniche rispetto a tag page / listing duplicati
• preferisci pagine con forte overlap tra heading e termini della query

Design degli strumenti: cosa puo fare l’assistente (e cosa no)

• elencare directory: ls /services
• cercare path: find -name "billing"
• leggere una pagina completa: cat /services/seo
• cercare nel contenuto: grep -ri "canonical" /

• scrivere o modificare contenuti
• fetch di URL arbitrari
• chiamate di rete arbitrarie

La lezione sulla latenza: filesystem reali sono troppo lenti per una chat interattiva

• il cold start diventa visibile
• la chat sembra rotta
• sei tentato di aggiungere complessita (pool caldi, ecc.)

• ls e find risolvono dal path tree cacheato
• cat ricompone la pagina dai chunk salvati (ordinati per chunk_index)
• i risultati vengono cacheati per sessione (e in parte globalmente, quando e sicuro)

Cache di cio che si ripete: albero, pagine e “target di grep”

• listare le stesse sezioni
• aprire le stesse 5-10 pagine importanti
• fare grep sugli stessi token

• il path tree
• pagine ricostruite complete
• candidati recenti per grep

RBAC: il controllo accessi deve essere strutturale, non basato sul prompt

• costruisci un path tree per utente
• pruni tutto cio a cui l’utente non puo accedere
• applica lo stesso filtro a ogni query e lettura pagina

Guardrail: come abbiamo fermato risposte sbagliate ma “sicure”

Regola 1: niente evidenza, niente risposta

• dire che non ha potuto verificare
• mostrare cosa ha controllato (pagine o sezioni)
• proporre un next step (contatto/supporto)

Regola 2: preferire citazioni a parafrasi per dettagli critici

• cita la/le frase/i rilevanti della pagina letta
• mantieni la sintesi minimale

Regola 3: essere rigorosi su locale e pagine canoniche

• preferire il contenuto di quel locale
• evitare di mischiare lingue nella stessa risposta
• fare fallback sul locale di default solo se la pagina in quel locale non esiste

Il “problema grep”: la feature killer richiede un piano in due fasi

1. filtro grossolano usando l’indice (quali pagine potrebbero contenere il token)
2. filtro fine in memoria sul testo pagina cacheato per estrarre match esatti + contesto

UX del widget: la UI fa o disfa la fiducia

• streaming di token con layout stabile (evita reflow “saltellante”)
• stati chiari:
  • “Cercando…”
  • “Leggendo la pagina…”
  • “Rispondendo…”
• citazioni brevi inline:
  • “Da: /services/seo”
  • “Da: /legal/privacy”
• fallback che non sembrano un fallimento:
  • “Ho controllato X e Y ma non ho potuto confermare; ecco come contattarci.”

Osservabilita: loggare le letture, non solo i token

• tool call (path listati/letti/cercati)
• quali pagine sono state usate come evidenza
• lunghezza della risposta e bucket di latenza
• tasso “non ho potuto verificare”
• tasso di escalation (click su contatto)

• quali pagine mancano di informazioni importanti?
• quali domande non trovano mai evidenza?
• quali pagine generano confusione e richiedono ristrutturazione?

Una checklist pratica di build (cosa rifaremmo)

• indicizzare il sito renderizzato e salvare record a livello pagina
• combinare retrieval lessicale + vettoriale
• aggiungere un layer di esplorazione (file + grep)
• prunare i contenuti per RBAC prima che inizi la sessione
• mantenere gli strumenti read-only di default
• aggiungere la regola “niente evidenza, niente risposta”
• rendere visibile in UI “cercando/leggendo/rispondendo”
• loggare le tool call per poter debuggare i failure

• Web Development
• Web Apps
• AI
• Contact