Come funziona
Lo stack in azienda
Tutto su una macchina nella rete del cliente. Solo i servizi indicati hanno una porta esposta.
| Servizio | Cosa fa | Esposto |
|---|---|---|
| app | Chat, login, pannello di amministrazione, API per il browser | Porta 443 sulla rete del cliente |
| worker | Indicizzazione, scansioni delle fonti, ricerche approfondite, migrazioni | API interna solo su 127.0.0.1 |
| postgres | Postgres 17 con pgvector: utenti, documenti indicizzati, vettori, conversazioni | Solo rete interna Docker |
| llm | vLLM, unico motore di inferenza | Solo rete interna Docker |
| embed | Qwen3 Embedding servito da vLLM, 1024 dimensioni | Solo rete interna Docker |
| rerank | Qwen3 Reranker servito da vLLM | Solo rete interna Docker |
| docling | docling-serve: testo, tabelle e OCR da PDF, Office e scansioni | Solo rete interna Docker |
| updater | Aggiornamenti firmati, copie del database, certificato, licenza | Servizio di sistema, solo connessioni in uscita |
Una domanda, passo per passo
La ricerca parte sempre prima della prima chiamata al modello: nessun turno sprecato per decidere se cercare.
- La domanda passa subito dalla ricerca ibrida: vettori (indice HNSW, distanza coseno) e testo (indici italian e simple) in parallelo, ciascuno con il filtro sui permessi dentro la query.
- Le due liste si fondono per rango reciproco, le prime 40 parti vanno al reranker e le 8 migliori entrano nel contesto del modello, ognuna con documento, percorso dei titoli e pagine.
- Poi l'agente lavora con gli strumenti: cerca_documenti, leggi_documento, elenca_cartella, i server MCP attivati e le fonti personali dell'utente, entro 8 passaggi e un tetto di token letti.
- Per le domande larghe delega a sottoagenti: stesso utente e stessi permessi, solo strumenti di lettura, un livello, 90 secondi, un semaforo sull'istanza. Il modello principale riceve solo i riassunti.
- La risposta arriva in streaming con citazioni sul passaggio esatto. Il passaggio si apre solo se il permesso sul file e ancora valido in quel momento.
I permessi
Il modello vede solo quello che l'utente potrebbe gia aprire da solo. Il divieto vince sempre e nel dubbio il file e invisibile: qualunque errore di lettura dei permessi lo esclude dall'indice.
| Fonte | Permessi |
|---|---|
| Cartelle di rete Windows o NAS | Due livelli che si intersecano: permessi della condivisione (per fonte) e ACL NTFS del file (per documento). Servono entrambi. |
| SharePoint, OneDrive, Teams | Permessi dell'elemento da Graph; i link "chiunque nell'organizzazione" diventano il principale "tutta l'azienda". |
| Raccolte caricate | Gruppi scelti dall'amministratore. |
| Allegato in chat | Solo l'utente, solo quella conversazione. |
Modello locale o esterno
Il ciclo agentico e gli strumenti sono gli stessi: cambia dove girano i calcoli.
Locale (predefinito)
vLLM sulla macchina del cliente. Nessun passaggio di documento esce dalla rete.
Endpoint esterno
OpenRouter o qualsiasi endpoint compatibile OpenAI o Anthropic. I passaggi dei documenti escono dalla rete: l'amministratore lo vede scritto, il conto e intestato al cliente.
Solo l'app, senza GPU
App, worker, Postgres e docling in sede su una VM o un mini PC. Le istanze non le ospitiamo noi.
Trasparenza (AI Act, art. 50)
Chi fa cosa, secondo il regolamento europeo sull'intelligenza artificiale.
borc e provider del sistema di IA: lo mette sul mercato a proprio nome, e l'art. 50(1) chiede che le persone sappiano di parlare con un'IA. Per questo l'avviso e fisso in chat, sempre visibile.
Il cliente e deployer: usa il sistema sotto la propria autorita, secondo le istruzioni d'uso. Uso previsto dichiarato: assistente sui documenti aziendali. Usarlo per decisioni su assunzioni, valutazioni del personale o credito lo renderebbe ad alto rischio ed e escluso dal contratto. La formazione prevista dall'art. 4 fa parte del servizio.