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.

Com utilitzar RAGFlow: Una guia pràctica per a construir aplicacions RAG fiables

Si has intentat construir un sistema de generació augmentada per recuperació (RAG), probablement has topat amb els problemes clàssics: al·lucinacions, recuperació inconsistent, pipelines lents i un preprocessament de documents desordenat. RAGFlow entra en joc com una eina de flux de treball integral que t'ajuda a orquestrar la ingesta de documents, la divisió en fragments, la vectorització, la recuperació i la generació amb més control i observabilitat.

Aquesta guia adopta un enfocament pràctic i orientat a la solució. Repassarem una configuració neta, et mostrarem com utilitzar RAGFlow per a documents reals i compartirem patrons que realment redueixen les al·lucinacions i milloren la qualitat de les respostes.

Què és RAGFlow i per què utilitzar-lo?

RAGFlow és un sistema per construir pipelines de generació augmentada per recuperació. En una configuració RAG típica, tu:

Ingereixes documents (PDFs, pàgines web, diapositives, codi, etc.)

Divideixes el contingut en unitats recuperables

Integres fragments en vectors per a la cerca semàntica

Recuperes els k fragments rellevants principals en el moment de la pregunta

Generes una resposta fonamentada utilitzant un LLM

RAGFlow afegeix valors per defecte amb opinions, blocs de flux de treball i proteccions perquè puguis iterar més ràpid i enviar aplicacions més fiables. És particularment útil si vols:

Fragmentació i metadades consistents: Una millor recuperació comença amb millors fragments.

Integracions i LLMs connectables: Intercanvia OpenAI, models locals o endpoints empresarials.

Avaluacions i proteccions: Mesura la qualitat de la recuperació i redueix les al·lucinacions.

Pipelines desplegables: Mou-te del notebook a la producció amb menys reescriptures.

Inici ràpid: De zero a un pipeline RAGFlow funcional

A continuació, es mostra un flux de treball mínim i integral que pots adaptar. Fins i tot si el teu entorn és diferent, la seqüència i les proteccions són portàtils.

1) Prepara el teu entorn

Crea un fitxer .env amb les teves claus:

OPENAI_API_KEY (o un altre proveïdor de LLM)

EMBEDDINGS_API_KEY (si utilitzes un proveïdor separat)

VECTOR_DB_URL (p. ex., Pinecone, Weaviate, Qdrant, o local)

Estableix un directori de projecte, p. ex., ragflow-project/ amb les carpetes:

data/raw/ (fitxers font)

data/processed/ (fragments nets)

configs/ (YAML/JSON per a la configuració del pipeline)

eval/ (conjunts de dades i informes)

2) Ingesta documents amb metadades netes

Bones metadades = millor recuperació. Normalitza títols, autors, dates i fonts.

Converteix PDFs i diapositives a text amb un parser robust

Conserva l'estructura: encapçalaments, llistes, blocs de codi i taules

Adjunta metadades a cada fragment: source, section, page, timestamp, version

Consell: Mantén un doc_id i un chunk_id per donar suport a les cites i la re-ingesta.

3) Tria una estratègia de fragmentació que s'adapti al teu contingut

La fragmentació afecta fortament la qualitat de la recuperació i la latència.

Per a documents narratius: fragmentació semàntica (dividir per encapçalaments/paràgrafs)

Per a documents tècnics: utilitza fragmentació híbrida (semàntica + finestra fixa)

Per al codi: fragmenta per funció/classe amb una petita finestra lliscant

Configuració recomanada per començar:

chunk_size: 600–1.000 tokens

chunk_overlap: 50–100 tokens

max_depth: limita les seccions imbricades a 2–3 nivells per evitar la fragmentació

4) Tria embeddings i un magatzem de vectors

Comença amb un model d'embedding fort de propòsit general (p. ex., text‑embedding‑3‑large o un model local modern). Si la privadesa és clau, considera els embeddings auto‑hostatjats.

Utilitza una base de dades vectorial que admeti:

Cerca híbrida (densa + paraula clau)

Filtres (restriccions de metadades)

Insercions per lots i mètriques d'índex

Configuració d'índex per provar:

top_k = 5–10 per a la recuperació inicial

similarity_metric = cosine (o punt per a certs models)

Activa la rellevància marginal màxima (MMR) per reduir la redundància

5) Orquestració de la recuperació

Implementa un recuperador de dues etapes:

Recuperació ràpida de candidats

Cerca híbrida (BM25 + densa)

top_k gran (p. ex., 30–50)

Reclassificació

Reclassificador de codificació creuada o puntuació basada en LLM

Redueix al top_k final (p. ex., 5–8)

Afegeix filtres de metadades: source:"handbook" AND section:"benefits" AND version:"v2" per restringir les respostes a documents de confiança.

6) Generació fonamentada amb estructura

El teu prompt ha d'imposar cites i la negativa quan l'evidència és feble.

Exemple de prompt del sistema:

Ets un assistent atent. Respon NOMÉS amb informació recolzada pel context proporcionat.
- Cita les fonts en línia com a [doc_id:chunk_id].
- Si el context és insuficient, digues "No hi ha prou informació als documents proporcionats."
- No inventis fets.

Plantilla de prompt d'usuari:

Pregunta: {query}
Context:
{top_chunks}
Instruccions:
- Proporciona primer una resposta concisa i, després, detalls.
- Inclou cites després de cada afirmació factual.

7) Afegeix proteccions per reduir les al·lucinacions

Comprovació de la capacitat de resposta: Abans de la generació, pregunta a un model petit: "Hi ha evidència directa als fragments recuperats?" Si no, retorna una pregunta aclaridora.

Política de cita‑o‑silenci: Bloqueja les sortides que no tinguin cites.

Filtres de toxicitat/PII per al contingut empresarial.

8) Avaluació i millora contínua

Crea un conjunt eval/ amb:

50–200 preguntes reals d'usuari

Respostes de veritat fonamentada (o referències de confiança)

Fonts esperades (ids de documents) quan sigui aplicable

Mesura:

Taxa d'encerts de recuperació (apareix la font d'or al top‑k?)

Fidelitat de la resposta (declaracions recolzades per cites)

Latència (p95 d'extrem a extrem)

Cost (per 100 consultes)

Itera sobre:

Mida i superposició del fragment

Elecció del model d'embedding

Reclassificador vs. top‑k superior

Estructura i restriccions del prompt

Un pipeline RAGFlow complet: Exemple de configuració

A continuació, es mostra una configuració conceptual que pots adaptar a la teva cadena d'eines. Reemplaça els noms dels proveïdors segons sigui necessari.

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

Com utilitzar RAGFlow per a diferents tipus de contingut

Manuals de producte i manuals

Prefereix la fragmentació semàntica amb límits de secció clars

Adjunta la versió i la data d'efecte per evitar respostes desactualitzades

Utilitza filtres estrictes: sempre requereix version = latest

Bases de coneixement i FAQs

Utilitza fragments més petits (400–600 tokens) per a respostes precises

Augmenta el pool de candidats i confia en la reclassificació per trobar el fragment exacte

Genera automàticament parells Q/A canònics per augmentar la recuperació mitjançant la cerca lèxica

Documents d'enginyeria i codi

Fragmenta per funció/mòdul i inclou gràfics d'importació a les metadades

Activa la recuperació pare‑fill: retorna la funció + el seu context de docstring

Utilitza un reclassificador conscient del codi per prioritzar els símbols rellevants

Legal i compliment

Requereix cites a nivell de paràgraf

Afegeix lògica de negativa per a context incomplet

Mantén un conjunt d'or de fonts aprovades pel regulador en un índex separat

Patrons de prompt que realment funcionen

Respon i després cita: Resposta curta a la part superior; cites en línia després de cada afirmació

Cadena de recuperació: Demana al model que resumeixi cada fragment primer i, després, que sintetitzi

Reescriptura de la consulta: Amplia les consultes d'usuari amb sinònims i termes de domini abans de la recuperació

Prompts contrastius: "Explica per què l'opció A és millor que la B basant-te en el context." Això força l'ús d'evidència

Exemple de pas de reescriptura de la consulta:

Original: "quina és la nostra política de transferència de PTO?"
Reescriptura: "política de transferència de temps lliure pagat; transferència de vacances; hores màximes; versió de la política més recent"

Observabilitat i bucles de feedback

Registra quins fragments es van utilitzar, les seves puntuacions i quins es van ignorar

Captura polzes amunt/avall amb una breu justificació; alimenta això de nou a l'ajustament del recuperador

Executa proves de regressió setmanals al teu conjunt d'avaluació abans de desplegar qualsevol canvi de model

Full de trucs d'ajustament del rendiment

Si les respostes se senten genèriques: augmenta candidate_top_k i afegeix un reclassificador més fort

Si les respostes ometen detalls: redueix la mida del fragment; augmenta lleugerament el pes lèxic

Si les cites repeteixen el mateix fragment: activa MMR i augmenta la diversitat

Si la latència és alta: posa en memòria cau els embeddings, precalcula les reescriptures de consulta, utilitza un reclassificador més petit

Si els costos augmenten: mou la temperatura de generació cap avall, escurça els prompts, prova un LLM més petit per a la primera passada

Essentials de seguretat i governança

Xifra els vectors emmagatzemats i redueix els camps sensibles a les metadades

Utilitza el control d'accés per índex; segmenta per equip o sensibilitat de les dades

Mantén un registre de llinatge de dades: URL de la font del document, checksum i timestamp d'ingesta

Instantània d'estudi de cas: De PDFs desordenats a respostes de confiança

Un equip de suport va ingerir 1.200 pàgines de PDFs. La recuperació inicial era inconsistent; els agents no confiaven en el bot. Després de canviar a la fragmentació semàntica‑híbrida (800 tokens, 80 de superposició), activar la reclassificació de codificació creuada i imposar cita‑o‑silenci, la taxa d'encerts del top‑k va augmentar del 62% al 89%, i l'adopció de l'agent es va duplicar. La clau no era un LLM més gran, sinó fragments més nets i una recuperació més estricta.

Consell d'eines: Iteració ràpida amb una barra lateral d'IA

Val la pena assenyalar: si estàs experimentant amb prompts i fragments de recuperació a través de molts documents, un assistent d'IA que et permeti xatejar sobre PDFs, pàgines web i codi directament des del navegador pot accelerar la iteració. Per cert, Sider.AI (https://sider.ai/) ofereix una barra lateral d'IA que et permet incorporar context de la pàgina en què et trobes, resumir i refinar els prompts ràpidament. És útil per prototipar prompts RAG i provar la qualitat dels fragments abans de formalitzar el pipeline.

Resolució de problemes de RAGFlow: Solucions ràpides

"El model és confiat però incorrecte."

Activa la comprovació de la capacitat de resposta; redueix la temperatura; requereix cites

"La cerca retorna quasi‑duplicats."

Activa MMR; afegeix un reclassificador; redueix la superposició de fragments

"Els pics de latència en el pic."

Embeddings per lots; reescriptures de consulta en memòria cau; utilitza la generació de streaming

"Les polítiques antigues segueixen apareixent."

Filtra per version = latest; deprecia o tomba documents desactualitzats

Propers passos: Fes que el teu RAGFlow sigui fiable en producció

Comença amb un corpus petit i de confiança; perfecciona primer la fragmentació i els filtres

Afegeix un reclassificador abans d'actualitzar el LLM

Construeix un conjunt d'avaluació de 100 preguntes i fes un seguiment setmanal de la taxa d'encerts

Connecta el feedback de l'usuari per ajustar contínuament la recuperació

Principals conclusions:

La qualitat de la recuperació supera la mida del model per a RAG

La fragmentació, les metadades i la reclassificació són les teves palanques principals

Les proteccions com cita‑o‑silenci augmenten la confiança dramàticament

Inverteix aviat en observabilitat i avaluació

Amb aquestes pràctiques, RAGFlow es converteix en una columna vertebral fiable per a respostes fonamentades, ja sigui que estiguis alimentant un bot d'ajuda, un copilot de desenvolupador o un assistent de coneixement intern.

FAQ

Q1: Què és RAGFlow i com l'utilitzo per a QA de documents? RAGFlow és un framework per construir pipelines de generació augmentada per recuperació. Ingereixes, fragmentes, integres, recuperes i generes respostes amb cites per reduir les al·lucinacions i millorar la precisió.

Q2: Com he de fragmentar els documents a RAGFlow? Utilitza la fragmentació semàntica o híbrida amb fragments de 600–1.000 tokens i una superposició de 50–100 tokens. Per al codi, fragmenta per funció o classe i inclou el context circumdant.

Q3: Quina base de dades vectorial funciona millor amb RAGFlow? Tria un magatzem que admeti la cerca híbrida, els filtres de metadades i la reclassificació: Qdrant, Weaviate, Pinecone o una opció local són opcions comunes.

Q4: Com puc evitar les al·lucinacions en una aplicació RAGFlow? Imposa una política de cita‑o‑silenci, afegeix una comprovació de la capacitat de resposta abans de la generació i mantén els prompts estrictes sobre l'ús només del context recuperat.

Q5: Quines mètriques he de fer un seguiment per avaluar RAGFlow? Monitora la taxa d'encerts de recuperació, la fidelitat de la resposta, la latència i el cost per 100 consultes, i mantén un conjunt d'avaluació petit però representatiu.