What is RAGFlow and how do I use it for document QA?

RAGFlow is a framework for building retrieval-augmented generation pipelines. You ingest, chunk, embed, retrieve, and generate answers with citations to reduce hallucinations and improve accuracy.

How should I chunk documents in RAGFlow?

Use semantic or hybrid chunking with 600–1,000 token chunks and 50–100 token overlap. For code, chunk by function or class and include surrounding context.

Which vector database works best with RAGFlow?

Choose a store that supports hybrid search, metadata filters, and reranking—Qdrant, Weaviate, Pinecone, or a local option are all common choices.

How do I prevent hallucinations in a RAGFlow app?

Enforce a cite‑or‑silence policy, add an answerability check before generation, and keep prompts strict about using only retrieved context.

What metrics should I track to evaluate RAGFlow?

Monitor retrieval hit rate, answer faithfulness, latency, and cost per 100 queries, and maintain a small but representative evaluation set.

Come usare RAGFlow: Una guida pratica alla creazione di app RAG affidabili

Se hai provato a costruire un sistema di generazione aumentata dal recupero (RAG), probabilmente ti sei imbattuto nei classici punti critici: allucinazioni, recupero incostante, pipeline lente e preelaborazione dei documenti disordinata. RAGFlow interviene come uno strumento di flusso di lavoro end-to-end che ti aiuta a orchestrare l'inserimento, la suddivisione in chunk, la vettorializzazione, il recupero e la generazione di documenti con maggiore controllo e osservabilità.

Questa guida adotta un approccio pratico e orientato alla soluzione. Ti guideremo attraverso una configurazione pulita, ti mostreremo come utilizzare RAGFlow per documenti reali e condivideremo modelli che riducono effettivamente le allucinazioni e migliorano la qualità delle risposte.

Cos'è RAGFlow e perché usarlo?

RAGFlow è un sistema per la creazione di pipeline di generazione aumentata dal recupero. In una tipica configurazione RAG, si:

Inseriscono documenti (PDF, pagine web, slide, codice, ecc.)

Suddividono il contenuto in unità recuperabili

Incorporano i chunk in vettori per la ricerca semantica

Recuperano i top‑k chunk rilevanti al momento della domanda

Generano una risposta fondata utilizzando un LLM

RAGFlow aggiunge impostazioni predefinite basate su opinioni, blocchi di flusso di lavoro e misure di sicurezza in modo da poter iterare più velocemente e spedire app più affidabili. È particolarmente utile se desideri:

Chunking e metadati coerenti: un recupero migliore inizia con chunk migliori.

Embedding e LLM collegabili: scambia OpenAI, modelli locali o endpoint aziendali.

Valutazioni e misure di sicurezza: misura la qualità del recupero e riduci le allucinazioni.

Pipeline implementabili: passa dal notebook alla produzione con meno riscritture.

Avvio rapido: da zero a una pipeline RAGFlow funzionante

Di seguito è riportato un flusso di lavoro minimo ed end‑to‑end che puoi adattare. Anche se il tuo ambiente è diverso, la sequenza e le misure di sicurezza sono portatili.

1) Prepara il tuo ambiente

Crea un file .env con le tue chiavi:

OPENAI_API_KEY (o un altro provider LLM)

EMBEDDINGS_API_KEY (se si utilizza un provider separato)

VECTOR_DB_URL (es. Pinecone, Weaviate, Qdrant o locale)

Imposta una directory di progetto, es. ragflow-project/ con le cartelle:

data/raw/ (file di origine)

data/processed/ (chunk puliti)

configs/ (YAML/JSON per le impostazioni della pipeline)

eval/ (dataset e report)

2) Inserisci documenti con metadati puliti

Metadati validi = recupero migliore. Normalizza titoli, autori, date e fonti.

Converti PDF e slide in testo con un parser robusto

Preserva la struttura: intestazioni, elenchi, blocchi di codice e tabelle

Allega metadati a ciascun chunk: source, section, page, timestamp, version

Suggerimento: conserva un doc_id e un chunk_id per supportare citazioni e re‑inserimento.

3) Scegli una strategia di chunking adatta al tuo contenuto

Il chunking influisce notevolmente sulla qualità del recupero e sulla latenza.

Per documenti narrativi: chunking semantico (suddividi per intestazioni/paragrafi)

Per documenti tecnici: utilizza chunking ibrido (semantico + finestra fissa)

Per il codice: dividi in chunk per funzione/classe con una piccola finestra scorrevole

Impostazioni consigliate per iniziare:

chunk_size: 600–1.000 token

chunk_overlap: 50–100 token

max_depth: limita le sezioni nidificate a 2–3 livelli per evitare la frammentazione

4) Scegli embedding e un vector store

Inizia con un modello di embedding generico potente (es. text‑embedding‑3‑large o un modello locale moderno). Se la privacy è fondamentale, considera gli embedding self‑hosted.

Utilizza un vector DB che supporti:

Ricerca ibrida (densa + parola chiave)

Filtri (vincoli sui metadati)

Upsert in batch e metriche di indice

Impostazioni dell'indice da testare:

top_k = 5–10 per il recupero iniziale

similarity_metric = cosine (o dot per alcuni modelli)

Abilita la massima rilevanza marginale (MMR) per ridurre la ridondanza

5) Orchestrazione del recupero

Implementa un retriever a due stadi:

Richiamo rapido dei candidati

Ricerca ibrida (BM25 + densa)

top_k elevato (es. 30–50)

Reranking

Reranker cross‑encoder o scoring basato su LLM

Riduci al top_k finale (es. 5–8)

Aggiungi filtri di metadati: source:"handbook" AND section:"benefits" AND version:"v2" per limitare le risposte a documenti affidabili.

6) Generazione fondata con struttura

Il tuo prompt dovrebbe imporre citazioni e rifiuto quando le prove sono deboli.

Esempio di prompt di sistema:

Sei un assistente scrupoloso. Rispondi SOLO con informazioni supportate dal contesto fornito.
- Cita le fonti in linea come [doc_id:chunk_id].
- Se il contesto è insufficiente, dì "Non ci sono informazioni sufficienti nei documenti forniti."
- Non inventare fatti.

Modello di prompt utente:

Domanda: {query}
Contesto:
{top_chunks}
Istruzioni:
- Fornisci prima una risposta concisa, quindi i dettagli.
- Includi citazioni dopo ogni affermazione fattuale.

7) Aggiungi misure di sicurezza per ridurre le allucinazioni

Controllo di risposta: prima della generazione, chiedi a un piccolo modello: “Ci sono prove dirette nei chunk recuperati?” In caso contrario, restituisci una domanda di chiarimento.

Politica Cita‑o‑silenzio: blocca gli output privi di citazioni.

Filtri di tossicità/PII per contenuti aziendali.

8) Valutazione e miglioramento continuo

Crea un set eval/ con:

50–200 domande reali degli utenti

Risposte corrette (o riferimenti affidabili)

Fonti previste (ID documento) ove applicabile

Misura:

Tasso di successo del recupero (la fonte gold appare nel top‑k?)

Fedeltà della risposta (affermazioni supportate da citazioni)

Latenza (p95 end‑to‑end)

Costo (per 100 query)

Itera su:

Dimensione e sovrapposizione dei chunk

Scelta del modello di embedding

Reranker vs. top‑k superiore

Struttura e vincoli del prompt

Una pipeline RAGFlow completa: esempio di configurazione

Di seguito è riportata una configurazione concettuale che puoi adattare alla tua toolchain. Sostituisci i nomi dei provider secondo necessità.

project: product-handbook-rag
io:
input_path: data/raw/
output_index: product-handbook-index
parsing:
pdf:
strategy: auto
keep_layout: true
extract_tables: true
markdown:
preserve_headings: true
chunking:
method: semantic_hybrid
target_tokens: 800
overlap_tokens: 80
windowing: 2
metadata:
fields: [doc_id, title, section, page, version, source]
embeddings:
provider: openai
model: text-embedding-3-large
vectorstore:
type: qdrant
url: ${VECTOR_DB_URL}
similarity: cosine
retrieval:
hybrid: true
lexical_weight: 0.35
semantic_weight: 0.65
candidate_top_k: 40
rerank:
enabled: true
model: bge-reranker-large
final_top_k: 7
generation:
llm: gpt-4o
temperature: 0.2
cite_or_silence: true
guardrails:
answerability_check: true
pii_filter: true
toxicity_filter: moderate
monitoring:
log_traces: true
latency_budget_ms: 3500
cost_budget_per_100: 1.25

Come utilizzare RAGFlow per diversi tipi di contenuto

Manuali di prodotto e manuali

Preferisci il chunking semantico con chiari confini di sezione

Allega la versione e la data di validità per evitare risposte obsolete

Utilizza filtri rigorosi: richiedi sempre version = latest

Knowledge base e FAQ

Utilizza chunk più piccoli (400–600 token) per risposte precise

Aumenta il pool di candidati e affidati al reranking per trovare lo snippet esatto

Genera automaticamente coppie Q/A canoniche per aumentare il richiamo tramite la ricerca lessicale

Documenti di ingegneria e codice

Dividi in chunk per funzione/modulo e includi grafici di importazione nei metadati

Abilita il recupero padre‑figlio: restituisci la funzione + il suo contesto di docstring

Utilizza un reranker consapevole del codice per dare la priorità ai simboli rilevanti

Aspetti legali e conformità

Richiedi citazioni a livello di paragrafo

Aggiungi una logica di rifiuto per un contesto incompleto

Conserva un set golden di fonti approvate dal regolatore in un indice separato

Modelli di prompt che funzionano davvero

Rispondi quindi cita: risposta breve in alto; citazioni in linea dopo ogni affermazione

Catena di recupero: chiedi al modello di riassumere prima ogni chunk, quindi sintetizzare

Riscrivi la query: espandi le query degli utenti con sinonimi e termini di dominio prima del recupero

Prompt contrastivi: “Spiega perché l'opzione A è migliore di B in base al contesto.” Questo forza l'uso delle prove

Esempio di passaggio di riscrittura della query:

Originale: "qual è la nostra politica di riporto del PTO?"
Riscrivi: "politica di riporto dei permessi retribuiti; rollover delle ferie; ore massime; ultima versione della politica"

Osservabilità e cicli di feedback

Registra quali chunk sono stati utilizzati, i loro punteggi e quali sono stati ignorati

Acquisisci pollici in su/giù con una breve motivazione; reinseriscili nella messa a punto del retriever

Esegui test di regressione settimanali sul tuo set di valutazione prima di distribuire qualsiasi modifica al modello

Foglio di trucchi per la messa a punto delle prestazioni

Se le risposte sembrano generiche: aumenta candidate_top_k e aggiungi un reranker più potente

Se le risposte perdono dettagli: riduci le dimensioni dei chunk; aumenta leggermente il peso lessicale

Se le citazioni ripetono lo stesso chunk: abilita MMR e aumenta la diversità

Se la latenza è elevata: memorizza nella cache gli embedding, precalcola le riscritture delle query, utilizza un reranker più piccolo

Se i costi aumentano: riduci la temperatura di generazione, accorcia i prompt, prova un LLM più piccolo per il primo passaggio

Elementi essenziali per la sicurezza e la governance

Crittografa i vettori memorizzati e oscura i campi sensibili nei metadati

Utilizza il controllo dell'accesso per indice; segmenta per team o sensibilità dei dati

Mantieni un record di provenienza dei dati: URL della fonte del documento, checksum e timestamp di inserimento

Snapshot di un caso di studio: dai PDF disordinati a risposte affidabili

Un team di supporto ha inserito 1.200 pagine di PDF. Il recupero iniziale era incoerente; gli agenti non si fidavano del bot. Dopo essere passati al chunking semantico‑ibrido (800 token, 80 di sovrapposizione), aver abilitato il reranking cross‑encoder e aver imposto cita‑o‑silenzio, il tasso di successo del top‑k è aumentato dal 62% all'89% e l'adozione da parte degli agenti è raddoppiata. La chiave non era un LLM più grande, ma chunk più puliti e un recupero più rigoroso.

Suggerimento per gli strumenti: iterazione rapida con una barra laterale AI

Vale la pena notare: se stai sperimentando con prompt e snippet di recupero su molti documenti, un assistente AI che ti consente di chattare su PDF, pagine web e codice direttamente dal browser può accelerare l'iterazione. A proposito, Sider.AI (https://sider.ai/) offre una barra laterale AI che ti consente di inserire il contesto dalla pagina in cui ti trovi, riassumere e perfezionare rapidamente i prompt. È utile per prototipare prompt RAG e testare la qualità dei chunk prima di formalizzare la pipeline.

Risoluzione dei problemi di RAGFlow: correzioni rapide

“Il modello è sicuro ma sbagliato.”

Abilita il controllo di risposta; abbassa la temperatura; richiedi citazioni

“La ricerca restituisce quasi duplicati.”

Attiva MMR; aggiungi un reranker; riduci la sovrapposizione dei chunk

“La latenza aumenta al picco.”

Embedding in batch; memorizza nella cache le riscritture delle query; utilizza la generazione in streaming

“Continuano a comparire vecchie politiche.”

Filtra su version = latest; depreca o cancella i documenti obsoleti

Passaggi successivi: rendi il tuo RAGFlow affidabile in produzione

Inizia con un corpus piccolo e affidabile; perfeziona prima il chunking e i filtri

Aggiungi un reranker prima di aggiornare l'LLM

Crea un set di valutazione di 100 domande e monitora il tasso di successo settimanalmente

Integra il feedback degli utenti per ottimizzare continuamente il recupero

Punti chiave:

La qualità del recupero batte le dimensioni del modello per RAG

Chunking, metadati e reranking sono le tue leve principali

Le misure di sicurezza come cita‑o‑silenzio aumentano notevolmente la fiducia

Investi presto in osservabilità e valutazione

Con queste pratiche, RAGFlow diventa una spina dorsale affidabile per risposte fondate, sia che tu stia alimentando un help bot, un copilota per sviluppatori o un assistente di conoscenza interno.

FAQ

D1: Cos'è RAGFlow e come posso usarlo per la QA dei documenti? RAGFlow è un framework per la creazione di pipeline di generazione aumentata dal recupero. Inserisci, dividi in chunk, incorpora, recupera e genera risposte con citazioni per ridurre le allucinazioni e migliorare l'accuratezza.

D2: Come devo dividere i documenti in chunk in RAGFlow? Utilizza chunking semantico o ibrido con chunk di 600–1.000 token e una sovrapposizione di 50–100 token. Per il codice, dividi in chunk per funzione o classe e includi il contesto circostante.

D3: Quale database vettoriale funziona meglio con RAGFlow? Scegli un archivio che supporti la ricerca ibrida, i filtri di metadati e il reranking: Qdrant, Weaviate, Pinecone o un'opzione locale sono tutte scelte comuni.

D4: Come posso prevenire le allucinazioni in un'app RAGFlow? Applica una politica di cita‑o‑silenzio, aggiungi un controllo di risposta prima della generazione e mantieni i prompt rigorosi sull'utilizzo solo del contesto recuperato.

D5: Quali metriche devo monitorare per valutare RAGFlow? Monitora il tasso di successo del recupero, la fedeltà della risposta, la latenza e il costo per 100 query e mantieni un set di valutazione piccolo ma rappresentativo.