WebRAG AI
Assistente AI conversazionale chiamato Helpie, che opera interamente nel browser senza inviare dati a server esterni
Cos’è?
Helpie è un assistente AI intelligente integrato nel Virtual Desktop Site che permette di esplorare i contenuti del sito attraverso domande in linguaggio naturale. Utilizza la tecnica RAG (Retrieval-Augmented Generation) per fornire risposte accurate basate sui contenuti reali del sito.
La particolarità di questo progetto è che tutto viene eseguito localmente nel browser dell’utente: nessun dato viene inviato a server esterni, garantendo massima privacy e conformità GDPR.
Come Funziona
1. Knowledge Base Automatica
Al build del sito, Jekyll genera automaticamente un file rag-feed.json contenente tutti i contenuti indicizzabili:
- Blog post e articoli
- Pagine progetto (Etna, PyPbald, EasyLFS, etc.)
- Descrizioni dei parchment e delle icone desktop
2. Ricerca Semantica (Retrieval)
Quando l’utente pone una domanda:
- Il testo viene convertito in un vettore di embedding usando Transformers.js
- Il sistema cerca i contenuti più rilevanti tramite similarità coseno
- I chunk più pertinenti vengono selezionati come contesto
3. Generazione Risposta (Generation) - Opzionale
Se attivato, i contenuti recuperati vengono passati a un LLM locale (TinyLlama o Llama 3.2) che:
- Genera una risposta conversazionale in italiano
- Cita le fonti con link cliccabili
- Risponde solo basandosi sul contesto fornito
Modalità disponibili:
- Solo Ricerca (default): Ricerca semantica veloce senza LLM
- Conversazione: Ricerca + generazione risposte con LLM locale
Stack Tecnologico
| Componente | Tecnologia | Funzione |
|---|---|---|
| Embeddings | Transformers.js | Vettorizzazione testo multilingue (ONNX/WASM) |
| LLM Inference | Transformers.js | Esecuzione modelli LLM via WebGPU/WASM |
| Modello Embeddings | paraphrase-multilingual-MiniLM-L12-v2 |
100MB, supporto 50+ lingue |
| Modelli LLM | TinyLlama-1.1B-Chat, Llama-3.2-1B-Instruct |
1-1.1GB, quantizzati 4-bit |
| Vector Search | Vanilla JS | Similarità coseno in memoria |
| Persistence | IndexedDB | Cache modelli tra sessioni |
Principi di Design
Privacy-First
| Aspetto | Implementazione |
|---|---|
| Zero Backend | Nessun server API esterno |
| Privacy-First | Nessun dato utente lascia il browser |
| Costo Zero | GitHub Pages + CPU/GPU dell’utente |
| GDPR Compliant | Consenso esplicito ogni sessione |
Cosa viene memorizzato
- ✅ Modelli AI (IndexedDB): per evitare ri-download (~1-1.1GB)
- ✅ Embeddings pre-calcolati: per velocizzare la ricerca
- ❌ Consenso utente: richiesto ogni sessione (sessionStorage)
- ❌ Cronologia chat: persa al refresh/chiusura tab
- ❌ Dati personali: mai raccolti
Requisiti di Sistema
Browser Supportati
| Browser | Supporto | Note |
|---|---|---|
| Chrome 113+ | ✅ Full (WebGPU) | Raccomandato |
| Edge 113+ | ✅ Full (WebGPU) | Raccomandato |
| Firefox 127+ | ✅ WASM Fallback | Funzionante |
| Safari 17+ | ✅ WASM Fallback | Funzionante |
| Mobile | ⚠️ Limitato | “Solo Ricerca” consigliato |
Risorse Hardware
| Risorsa | Requisito Minimo | Raccomandato |
|---|---|---|
| RAM | 2GB disponibili (Solo Ricerca) | 4GB+ (Conversazione) |
| GPU | Non richiesta (WASM) | Dedicata (WebGPU) |
| Storage | 500MB (IndexedDB) | 2GB |
| Connessione | Stabile per download iniziale | Fibra 100Mbps |
Flusso di Interazione
- Click su icona Helpie nel desktop VDS
- Dialog di consenso (richiesto ogni sessione):
- Scelta modello embeddings (default: MiniLM)
- Scelta modalità LLM (default: Solo Ricerca)
- Informazioni sui requisiti hardware
- Privacy policy sintetica
- Verifica compatibilità browser (WebGPU/WASM)
- Caricamento modelli (barra di progresso multi-fase)
- Ready! Helpie è pronto per rispondere
Funzionalità
Domande Supportate
Helpie può rispondere a domande su:
- Progetti open source: Etna, PyPbald, EasyLFS, GAP, etc.
- Blog post e articoli: architettura, AI, programmazione
- Pubblicazioni scientifiche: Grid computing, P2P, QoS
- Informazioni biografiche: esperienza, competenze
Esempio di Interazione
Modalità Solo Ricerca
👤 Utente: Parlami del progetto Etna
🔍 Helpie: Ho trovato 3 risultati:
1. Progetto Etna: architettura sperimentale... (92%)
[Link al progetto]
2. Etna Monitor con AI per analisi sismica... (78%)
[Link al post]
Modalità Conversazione
👤 Utente: Parlami del progetto Etna
🤖 Helpie: Il progetto Etna è un sistema di monitoraggio vulcanico
che utilizza AI per l'analisi automatizzata dei segnali sismici
del Monte Etna. Include una pipeline di acquisizione dati,
generazione di embeddings tramite autoencoder, dashboard
Streamlit e notifiche Telegram.
📎 Fonte: [Etna Tremor Monitor](/etna/)
Integrazione VDS
Helpie è integrato nel Virtual Desktop Site come:
- Icona desktop “Helpie” con icona AI distintiva
- Voce nel Start Menu sotto “Accesso Rapido”
- Finestra draggable/resizable con tutti i controlli standard
Performance
| Metrica | Solo Ricerca | Conversazione (LLM) |
|---|---|---|
| Cold Start (download) | < 10s | < 60s |
| Warm Start (cached) | < 2s | < 5s |
| Indexing documenti | < 3s | < 3s |
| Time to First Token | Istantaneo | < 3s (WebGPU) |
| Ricerca query | < 500ms | < 500ms |
Limitazioni
- Dipendenza da WebGPU per LLM: browser non compatibili usano fallback WASM (più lento)
- Risorse hardware per LLM: dispositivi con poca RAM possono usare “Solo Ricerca”
- Contesto limitato: le risposte sono basate solo sui contenuti del sito
- Download iniziale: ~100MB (Solo Ricerca) o ~1.1GB (Conversazione)
Sviluppi Futuri
- ✅ Pre-calcolo embeddings a build time (IMPLEMENTATO)
- ✅ Fallback automatico a Solo Ricerca se LLM fallisce (IMPLEMENTATO)
- ⏳ Service Worker per funzionalità offline
- ⏳ Suggerimenti domande basati su query frequenti
- ⏳ Supporto vocale (Web Speech API)
- ⏳ Multi-turn conversation con context history
Architettura Tecnica
1. Architettura di Sistema (Component Diagram)
Interazione tra componenti: build statico Jekyll ↔ runtime VDS nel browser con AI locale
flowchart TB
subgraph SSB["Server-Side / Build Time"]
MD[Markdown Content]
Layouts[Liquid Layouts]
Jekyll[Jekyll Engine]
Assets[Static Assets]
RAGFeed[rag-feed.json]
RAGEmb[rag-embeddings.json]
MD --> Jekyll
Layouts --> Jekyll
Jekyll --> Assets
Jekyll --> RAGFeed
Jekyll --> RAGEmb
end
subgraph CSR["Client-Side / Runtime (Browser)"]
Boot[Boot Loader]
VDS[Virtual Desktop System]
Helpie[Helpie AI Assistant]
DOM[DOM Interface]
IDB[IndexedDB Cache]
AI_Local[AI Engine\nTransformers.js]
Boot --> VDS
VDS --> Helpie
Helpie --> DOM
Helpie --> IDB
Helpie --> AI_Local
end
Assets -.->|HTTP| Boot
RAGFeed -.->|HTTP| Helpie
RAGEmb -.->|HTTP| Helpie
2. RAG Pipeline - State Diagram
Pipeline AI locale/in-browser senza dipendenze API esterne
stateDiagram-v2
[*] --> Idle
Idle --> UserInput : User asks question
UserInput --> BrowserCheck : Validate
BrowserCheck --> Embedding : Browser OK
note right of Embedding : Local Model (100MB)
Embedding --> Retrieval : Query Embedding Generated
note right of Retrieval
Vector Search in
precomputed embeddings
end note
Retrieval --> Context : Top-K Chunks Selected
state if_llm <>
Context --> if_llm : LLM loaded?
if_llm --> ShowResults : No (Solo Ricerca)
if_llm --> Inference : Yes (Conversazione)
Inference --> Streaming : Stream Tokens to UI
Streaming --> Idle : Complete
ShowResults --> Idle : Complete
</div>
</div>
---
## Link Correlati
- [Virtual Desktop Site](/virtual-desktop-site/) - Framework desktop integrato
- [Privacy Policy](/privacy/) - Informativa sulla privacy
- [GitHub Repository](https://github.com/gnovelli/gnovelli.github.io) - Codice sorgente
3. Helpie Interaction - Sequence Diagram
Flusso dall'apertura di Helpie alla generazione della risposta
sequenceDiagram
actor User
participant UI as Helpie Window
participant Consent as Consent Dialog
participant Embedder as Transformers.js
participant Retriever as Vector Search
participant LLM as LLM (Optional)
participant Cache as IndexedDB
User->>UI: Click "Helpie" Icon
UI->>Consent: Show Consent Dialog
Consent->>User: Choose Model
User->>Consent: Select "Solo Ricerca"
Consent->>Cache: Check Models Cached
alt Models Not Cached
Cache-->>Consent: Missing
Consent->>Embedder: Download Model (~100MB)
Embedder-->>Cache: Store Model
Consent->>User: Progress Bar
else Models Cached
Cache-->>Consent: Available
Consent->>User: Instant Ready
end
Consent->>UI: Load Embeddings
UI->>User: Ready State
User->>UI: Type Question
UI->>Embedder: Generate Query Embedding
Embedder-->>UI: Query Vector
UI->>Retriever: Search precomputed embeddings
Retriever-->>UI: Top-K Relevant Chunks
alt Solo Ricerca Mode
UI->>User: Show Results List
else Conversazione Mode
UI->>LLM: Prompt + Context
loop Streaming Tokens
LLM-->>UI: Token
UI-->>User: Display Token
end
LLM-->>UI: Complete Response
UI->>User: Show Sources Links
end
4. Deployment Infrastructure
Pipeline CI/CD da sviluppo a produzione su GitHub Pages
flowchart LR
subgraph Dev["💻 Developer Environment"]
Code[VS Code / Local Git]
LocalPreview[Local Jekyll Serve]
Code --> LocalPreview
end
subgraph GitHub["☁️ GitHub Ecosystem"]
Repo[Git Repository]
subgraph Actions["⚙️ GitHub Actions"]
RAGScript[Generate Embeddings]
TestUnit[Unit Tests]
Build[Jekyll Build]
end
Pages[GitHub Pages]
end
subgraph Client["📱 User Device"]
Browser[Browser]
Helpie[Helpie Assistant]
end
Code -->|Push| Repo
Repo --> RAGScript
RAGScript --> TestUnit
TestUnit --> Build
Build -->|Deploy| Pages
Pages -->|HTTPS| Browser
Browser --> Helpie