Chat RAG con i Loader
Una chat RAG (Retrieval-Augmented Generation) risponde alle domande usando i tuoi documenti. Non si addestra nessun modello: ALIDA divide i documenti in chunk, li trasforma in embedding e, per ogni domanda, passa all'LLM i chunk più pertinenti come contesto.
Una chat RAG si prepara in due passi:
- crei uno o più Loader, le sorgenti da cui vengono letti i documenti;
- crei un Rag, ci incorpori i Loader e configuri i modelli che usa.
Entrambi si trovano nella sezione LLM del menu laterale, sotto Rags e Loaders.

Loader
Un Loader indica da dove arrivano i documenti e come leggerli. Una volta creato, lo stesso Loader può essere incorporato in più Rag.

Fai clic sul nome del Loader per scorrerne i chunk (vedi Testare un Loader). Ogni scheda ha inoltre tre pulsanti:
| Pulsante | Azione |
|---|---|
| ⚙ | Testa il Loader: ALIDA legge la sorgente e segnala se funziona. |
| ✎ | Modifica il Loader. |
| 🗑 | Elimina il Loader. |
Creare un Loader
Vai su LLM → Loaders e fai clic su Create Loader.
Compila i campi comuni:
Campo Cosa inserire Name Il nome mostrato nell'elenco e quando incorpori il Loader in un Rag. Description Facoltativo. Di cosa parlano i documenti. Privacy Level Chi può vedere e usare il Loader, ad esempio Team.Tags Facoltativo. Servono a trovare il Loader nell'elenco. Loader Class Come vengono letti i documenti. Vedi la tabella sotto. Scegli la Loader Class:

Le classi e i loro campi sono descritti in Classi di Loader.
Compila i campi richiesti dalla classe scelta. Per
CustomS3DirectoryLoader, ad esempio:- Datasource: il datasource di ALIDA che contiene i documenti;
- Path: la cartella del bucket da leggere, scelta dal file browser. Vengono caricati tutti i documenti sotto quel prefisso.

Salva il Loader.
Classi di Loader
Le classi si dividono in tre gruppi, a seconda di dove arrivano i documenti. L'amministratore sceglie quali classi offrire, quindi la tua installazione potrebbe mostrarne solo alcune.
Object storage
| Loader Class | Cosa carica | Campi |
|---|---|---|
CustomS3DirectoryLoader | I file sotto una cartella di un datasource object-storage di ALIDA. Bucket, endpoint e credenziali vengono presi dal datasource. | Datasource, Path. Facoltativi: API Version, Verify SSL, AWS Session Token. |
DoclingS3DirectoryLoader | Come CustomS3DirectoryLoader, ma ogni file viene prima convertito in Markdown da docling-serve. Usalo per PDF, DOCX e altri file non testuali: tabelle e impaginazione vengono mantenute. I file in formati che docling non accetta vengono saltati. | Gli stessi di CustomS3DirectoryLoader. |
S3DirectoryLoader | I file sotto un prefisso di un qualsiasi bucket compatibile S3 non registrato come datasource di ALIDA. I dati di connessione si inseriscono a mano. | Bucket, Prefix, Region Name, Endpoint URL, AWS Access Key ID, AWS Secret Access Key, AWS Session Token, Use SSL, Verify SSL, API Version. |
Web
| Loader Class | Cosa carica | Campi |
|---|---|---|
WebBaseLoader | Il testo di un elenco di pagine web. | Web Paths. Facoltativi: Requests Per Second (default 2), Default Parser (html.parser), Raise For Status, Verify SSL. |
SitemapLoader | Tutte le pagine elencate in una sitemap.xml. | Sitemap URL. Facoltativi: Filter URLs (pattern di URL o regex da tenere), Requests Per Second (default 2). |
DoclingLoader | Documenti pubblicati sul web (PDF, DOCX, HTML, ...), convertiti in Markdown da docling-serve. | Web Paths, ad esempio https://arxiv.org/pdf/2206.01062. |
Catalogo ALIDA
Queste classi non hanno campi: leggono il catalogo di ALIDA e creano un documento per ogni elemento, con nome e descrizione. Usale per costruire una chat che risponda a domande come "quale service posso usare per leggere da Kafka?".
| Loader Class | Cosa carica |
|---|---|
AlidaServiceLoader | I service del catalogo. |
AlidaDatasetLoader | I dataset del catalogo. |
AlidaBdaLoader | Le applicazioni BDA del catalogo. |
Per AlidaServiceLoader e AlidaDatasetLoader, il Privacy Level del Loader limita gli elementi caricati, così un Loader condiviso non espone mai elementi privati:
| Privacy Level del Loader | Elementi caricati |
|---|---|
Private | Elementi privati, di team e pubblici. |
Team | Elementi di team e pubblici. |
Public | Solo elementi pubblici. |
Docling richiede tempo
Le classi Docling convertono ogni file prima di dividerlo, e per PDF lunghi può volerci qualche minuto. Durante l'incorporamento la barra di avanzamento può restare ferma all'inizio per un po': è normale.
Testare un Loader
Fai clic su ⚙ nella scheda del Loader. ALIDA legge il primo documento della sorgente e, se ci riesce, mostra Loader Tested! Loader is working correctly. Altrimenti il messaggio riporta l'errore.

Per verificare che i documenti siano divisi come ti aspetti, fai clic sul nome del Loader: i chunk prodotti si aprono in una finestra, uno alla volta. Sono divisi esattamente come verranno incorporati: circa 1000 caratteri ciascuno, con 200 caratteri di sovrapposizione tra chunk consecutivi.

Rag
Un Rag è una chat con i propri Loader e la propria configurazione dei modelli.
Creare un Rag
Vai su LLM → Rags e crea un nuovo Rag.
Compila Name, Description, Privacy Level e Tags, poi fai clic su Save.

Apri il Rag. La chat si apre con il messaggio No Loaders found for this chat: finché non incorpori un Loader, la chat non può rispondere a domande sui tuoi documenti.
Incorporare i Loader
Nella scheda Manage Loaders a destra della chat:
- Embed existing Loader apre l'elenco dei Loader disponibili: fai clic su + accanto a quello che ti serve;
- Create new Loader crea un Loader e lo incorpora in un solo passo.

Mentre i documenti vengono incorporati, il Loader mostra una barra di avanzamento. Aspetta che finisca prima di fare domande su quei documenti.

Configurare il contesto
La scheda Context Configuration imposta i modelli e i parametri di retrieval del Rag. Un nuovo Rag parte con i default dell'installazione, quindi basta cambiare ciò che vuoi diverso. Modifica i valori e fai clic su Save Configuration.

| Parametro | Significato |
|---|---|
llm_model_name | L'LLM che scrive le risposte, ad esempio qwen3:8b. |
embeddings_model_name | Il modello che trasforma chunk e domande in embedding, ad esempio snowflake-arctic-embed2:latest. |
openai_api_base | URL base dell'API compatibile OpenAI che serve l'LLM. |
embeddings_api_base | URL base dell'API compatibile OpenAI che serve il modello di embedding. |
openai_api_key | API key per questi endpoint. È sempre mostrata mascherata (****); lasciala così, o vuota, per usare la chiave dell'installazione. |
prompt | Prompt di sistema: dice all'LLM come usare i chunk recuperati per rispondere. |
k | Quanti chunk vengono passati all'LLM per ogni domanda (default 5). Valori più alti danno più contesto ma prompt più lunghi e lenti. |
temperature | Casualità delle risposte (default 0.7). Valori più bassi danno risposte più deterministiche. |
Cambiare il modello di embedding
Chunk e domande devono essere trasformati con lo stesso modello. Se cambi embeddings_model_name dopo aver incorporato i Loader, incorporali di nuovo.
Risoluzione dei problemi
| Sintomo | Causa e soluzione |
|---|---|
| No Loaders found for this chat | Nel Rag non è incorporato nessun Loader. Incorporane uno da Manage Loaders. |
| Le risposte ignorano i tuoi documenti | L'incorporamento è ancora in corso, oppure k è troppo basso. Aspetta che la barra di avanzamento finisca, o aumenta k. |
| Il test del Loader fallisce | Datasource, path o URL non raggiungibili, oppure il tuo utente non ha accesso. Controlla i campi del Loader. |
| Il testo estratto da PDF o DOCX è vuoto o illeggibile | Usa DoclingS3DirectoryLoader al posto di CustomS3DirectoryLoader. |
| Alcuni file della cartella mancano tra i chunk | Con le classi Docling, i file in formati che docling non accetta vengono saltati. |
| Un Loader del catalogo carica meno elementi del previsto | Il Privacy Level del Loader filtra gli elementi: un Loader Team salta gli elementi privati. Vedi Classi di Loader. |