Architettura
I3K RAG Enterprise Community è un unico binario Rust che gira interamente dentro il tuo perimetro. Non è uno stack da assemblare: avvia da sé il database vettoriale e il motore di inferenza, e calcola gli embedding nel proprio processo.
Per l'installazione vedi l'avvio rapido. Per la gestione, la guida al deployment.
Componenti
| Componente | Ruolo |
|---|---|
| API e server | Rust, axum — superficie REST, gestione utenti JWT, orchestrazione delle query |
| Frontend | React + Vite, compilato e servito dalla directory del binario |
| Embedding | BAAI/bge-m3 tramite Candle, nel processo, su GPU o CPU |
| Database vettoriale | Qdrant, 1024 dimensioni, distanza coseno — avviato dal motore |
| Modello linguistico | eullm come processo separato, avviato e tenuto aggiornato dal motore |
| Database applicativo | SQLite tramite sqlx — utenti, documenti, conversazioni |
| OCR | pdfium per la rasterizzazione, Tesseract per il riconoscimento — entrambi caricati a runtime da un percorso incluso, non linkati in compilazione |
Tutto ascolta su una sola porta (8000 di default). In questo quadro non compaiono Docker, Compose né Java.
Perché il modello di embedding viene caricato per primo
Il modello di embedding viene caricato prima di quello linguistico di proposito. eullm dimensiona il proprio offload su GPU in base alla VRAM libera che osserva all'avvio, quindi deve poter vedere la memoria già occupata dal modello di embedding. Invertendo l'ordine, eullm si impegna più memoria di quella realmente disponibile.
La pipeline
- Ingest. I documenti arrivano dalla web UI o dall'API REST: PDF, DOCX, XLSX, HTML, TXT, Markdown e CSV. Le pagine scansionate vengono riconosciute in automatico — quando una pagina restituisce troppo poco testo viene rasterizzata con pdfium e passata a Tesseract in italiano e inglese.
- Embed e store. Il testo viene diviso in blocchi sovrapposti ed embeddato con
BAAI/bge-m3— 1024 dimensioni, multilingua su oltre 100 lingue — poi salvato in Qdrant con i metadati usati per il filtro per ruolo. - Retrieve. La domanda viene embeddata allo stesso modo e la risposta si costruisce dai passaggi più vicini. Soglia di rilevanza e top-K sono configurabili, e il filtro per ruolo si applica qui: una query non arriva mai al modello portandosi dietro passaggi che chi chiede non può vedere.
- Generate. I passaggi vanno al modello linguistico locale tramite eullm, che genera la risposta parola per parola mostrando ogni fonte. Le conversazioni vengono conservate e la cronologia viene considerata nelle domande successive.
Utenti e ruoli
Autenticazione JWT con tre ruoli:
- Utente — fa domande e legge le risposte.
- Super utente — tutto quello che può fare un utente, più il caricamento e la cancellazione dei documenti.
- Amministratore — gestione completa del sistema, inclusi account e configurazione.
L'applicazione dei permessi avviene a livello di retrieval, tradotta in filtri sui metadati del database vettoriale, e non applicata alla risposta dopo che è stata generata.
Sovranità dei dati
La regola di progetto è che niente esce dal perimetro.
- Il modello linguistico gira sul tuo hardware tramite eullm, un processo sulla stessa macchina.
- Gli embedding vengono calcolati dentro il processo del motore, non richiesti a un servizio.
- Qdrant salva i vettori su disco locale; SQLite tiene utenti, documenti e conversazioni su disco locale.
- Dopo il primo avvio non serve alcun accesso di rete.
- Non c'è telemetria. Non viene raccolto né inviato nulla, mai.
Sicurezza
- Trasporto — il TLS si termina su un reverse proxy davanti al motore.
- Autenticazione — token JWT firmati con
AUTH__JWT_SECRET, l'unica impostazione senza default. - Integrità dei componenti — ogni componente scaricato viene verificato contro uno sha256 dichiarato nel manifest; se non corrisponde, l'avvio si interrompe.
- Traffico in uscita — nessuno dopo il primo avvio. L'installazione può essere gestita completamente air-gapped.
Backup
Un archivio giornaliero schedulato contiene il database SQLite e uno snapshot di Qdrant presi insieme, così la coppia è coerente, più un endpoint amministrativo per ripristinarne uno sull'installazione in esecuzione. I backup sono file locali sotto BACKUP__DIR; non viene caricato niente da nessuna parte.
Misurarlo
Il binario sa cronometrarsi da solo, sul tuo hardware e sui tuoi documenti:
./i3k-rag-engine --bench /percorso/documento.pdfProduce un report Markdown con i tempi di ogni fase — estrazione, suddivisione, embedding, scrittura, prefill, decode — con grafici che mostrano dove se ne va il tempo. --bench-live registra invece ogni caricamento e ogni query reali di una sessione e produce il report alla chiusura.
Serve per il dimensionamento: trasforma «quanto hardware ci serve» da una stima in una misura sul corpus vero.
Licenza
Il motore Community è pubblicato sotto AGPL-3.0-only. Le release fino alla v0.1.39 inclusa sono state pubblicate sotto Apache-2.0 e restano disponibili a quei termini.
Usarlo internamente — dentro la propria azienda, sui propri documenti — non comporta alcun obbligo di divulgazione del sorgente. L'articolo 13 dell'AGPL si applica quando offri una versione modificata agli utenti attraverso una rete. Per le organizzazioni che non possono accettare quei termini è disponibile una licenza commerciale separata.
Sorgente: github.com/I3K-IT/RAG-Enterprise.