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.

Cómo usar RAGFlow: Una guía práctica para construir aplicaciones RAG confiables

Si has intentado construir un sistema de generación aumentada por recuperación (RAG), probablemente te has topado con los problemas clásicos: alucinaciones, recuperación inconsistente, pipelines lentos y un preprocesamiento de documentos desordenado. RAGFlow entra en juego como una herramienta de flujo de trabajo integral que te ayuda a orquestar la ingesta, el chunking, la vectorización, la recuperación y la generación de documentos con mayor control y observabilidad.

Esta guía adopta un enfoque práctico y orientado a la solución. Repasaremos una configuración limpia, te mostraremos cómo usar RAGFlow para documentos reales y compartiremos patrones que realmente reducen las alucinaciones y mejoran la calidad de las respuestas.

¿Qué es RAGFlow y por qué usarlo?

RAGFlow es un sistema para construir pipelines de Generación Aumentada por Recuperación. En una configuración RAG típica, tú:

Ingieres documentos (PDFs, páginas web, diapositivas, código, etc.)

Divides el contenido en unidades recuperables (chunking)

Incrustas los chunks en vectores para la búsqueda semántica

Recuperas los top‑k chunks relevantes al momento de la pregunta

Generas una respuesta fundamentada utilizando un LLM

RAGFlow añade valores predeterminados con criterio, bloques de flujo de trabajo y medidas de seguridad para que puedas iterar más rápido y lanzar aplicaciones más fiables. Es particularmente útil si quieres:

Chunking y metadatos consistentes: Una mejor recuperación comienza con mejores chunks.

Incrustaciones y LLMs conectables: Intercambia OpenAI, modelos locales o endpoints empresariales.

Evaluaciones y medidas de seguridad: Mide la calidad de la recuperación y reduce las alucinaciones.

Pipelines implementables: Pasa del notebook a la producción con menos reescrituras.

Inicio rápido: De cero a un pipeline RAGFlow funcional

A continuación, se muestra un flujo de trabajo mínimo de extremo a extremo que puedes adaptar. Incluso si tu entorno difiere, la secuencia y las medidas de seguridad son portátiles.

1) Prepara tu entorno

Crea un .env con tus claves:

OPENAI_API_KEY (u otro proveedor de LLM)

EMBEDDINGS_API_KEY (si utilizas un proveedor independiente)

VECTOR_DB_URL (por ejemplo, Pinecone, Weaviate, Qdrant o local)

Establece un directorio de proyecto, por ejemplo, ragflow-project/ con carpetas:

data/raw/ (archivos fuente)

data/processed/ (chunks limpios)

configs/ (YAML/JSON para la configuración del pipeline)

eval/ (conjuntos de datos e informes)

2) Ingiere documentos con metadatos limpios

Buenos metadatos = mejor recuperación. Normaliza títulos, autores, fechas y fuentes.

Convierte PDFs y diapositivas a texto con un parser robusto

Conserva la estructura: encabezados, listas, bloques de código y tablas

Adjunta metadatos a cada chunk: source, section, page, timestamp, version

Consejo: Mantén un doc_id y un chunk_id para admitir citas y la re‑ingesta.

3) Elige una estrategia de chunking que se adapte a tu contenido

El chunking afecta fuertemente la calidad de la recuperación y la latencia.

Para documentos narrativos: chunking semántico (dividir por encabezados/párrafos)

Para documentos técnicos: utiliza chunking híbrido (semántico + ventana fija)

Para código: divide por función/clase con una pequeña ventana deslizante

Configuración recomendada para empezar:

chunk_size: 600–1,000 tokens

chunk_overlap: 50–100 tokens

max_depth: limita las secciones anidadas a 2–3 niveles para evitar la fragmentación

4) Elige incrustaciones y un almacén de vectores

Comienza con un modelo de incrustación fuerte de propósito general (por ejemplo, text‑embedding‑3‑large o un modelo local moderno). Si la privacidad es clave, considera las incrustaciones autoalojadas.

Utiliza una base de datos vectorial que admita:

Búsqueda híbrida (densa + palabra clave)

Filtros (restricciones de metadatos)

Upserts por lotes y métricas de índice

Configuración de índice para probar:

top_k = 5–10 para la recuperación inicial

similarity_metric = cosine (o dot para ciertos modelos)

Habilita máxima relevancia marginal (MMR) para reducir la redundancia

5) Orquestación de la recuperación

Implementa un recuperador de dos etapas:

Recuperación rápida de candidatos

Búsqueda híbrida (BM25 + densa)

top_k grande (por ejemplo, 30–50)

Reranking

Reranker de codificador cruzado o puntuación basada en LLM

Reduce al top_k final (por ejemplo, 5–8)

Añade filtros de metadatos: source:"handbook" AND section:"benefits" AND version:"v2" para restringir las respuestas a documentos de confianza.

6) Generación fundamentada con estructura

Tu prompt debe exigir citas y rechazo cuando la evidencia sea débil.

Ejemplo de prompt del sistema:

Eres un asistente cuidadoso. Responde SÓLO con información respaldada por el contexto proporcionado.
- Cita las fuentes en línea como [doc_id:chunk_id].
- Si el contexto es insuficiente, di "No hay suficiente información en los documentos proporcionados."
- No inventes hechos.

Plantilla de prompt del usuario:

Pregunta: {query}
Contexto:
{top_chunks}
Instrucciones:
- Proporciona primero una respuesta concisa, luego los detalles.
- Incluye citas después de cada afirmación factual.

7) Añade medidas de seguridad para reducir las alucinaciones

Comprobación de la capacidad de respuesta: Antes de la generación, pregunta a un modelo pequeño: “¿Hay evidencia directa en los chunks recuperados?” Si no, devuelve una pregunta aclaratoria.

Política de citar‑o‑silenciar: Bloquea las salidas que carecen de citas.

Filtros de toxicidad/PII para contenido empresarial.

8) Evaluación y mejora continua

Crea un conjunto eval/ con:

50–200 preguntas reales de usuarios

Respuestas correctas (o referencias de confianza)

Fuentes esperadas (ids de documentos) cuando corresponda

Mide:

Tasa de aciertos de recuperación (¿aparece la fuente de oro en el top‑k?)

Fidelidad de la respuesta (declaraciones respaldadas por citas)

Latencia (p95 de extremo a extremo)

Costo (por 100 consultas)

Itera en:

Tamaño y superposición del chunk

Elección del modelo de incrustación

Reranker vs. top‑k más alto

Estructura y restricciones del prompt

Un pipeline RAGFlow completo: Ejemplo de configuración

A continuación, se muestra una configuración conceptual que puedes adaptar a tu cadena de herramientas. Reemplaza los nombres de los proveedores según sea necesario.

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

Cómo usar RAGFlow para diferentes tipos de contenido

Manuales de productos y guías

Prefiere el chunking semántico con límites de sección claros

Adjunta la versión y la fecha de vigencia para evitar respuestas obsoletas

Utiliza filtros estrictos: siempre requiere version = latest

Bases de conocimiento y preguntas frecuentes

Utiliza chunks más pequeños (400–600 tokens) para respuestas precisas

Aumenta el grupo de candidatos y confía en el reranking para encontrar el fragmento exacto

Genera automáticamente pares Q/A canónicos para impulsar la recuperación a través de la búsqueda léxica

Documentos de ingeniería y código

Divide por función/módulo e incluye gráficos de importación en los metadatos

Habilita la recuperación padre‑hijo: devuelve la función + su contexto de cadena de documentación

Utiliza un reranker consciente del código para priorizar los símbolos relevantes

Legal y cumplimiento

Requiere citas a nivel de párrafo

Añade lógica de rechazo para un contexto incompleto

Mantén un conjunto dorado de fuentes aprobadas por el regulador en un índice separado

Patrones de prompt que realmente funcionan

Responde y luego cita: Respuesta corta al principio; citas en línea después de cada afirmación

Cadena de recuperación: Pide al modelo que resuma cada chunk primero, luego sintetiza

Reescritura de la consulta: Amplía las consultas de los usuarios con sinónimos y términos de dominio antes de la recuperación

Prompts contrastivos: “Explica por qué la opción A es mejor que la B según el contexto.” Esto fuerza el uso de la evidencia

Ejemplo de paso de reescritura de consulta:

Original: "¿cuál es nuestra política de traspaso de PTO?"
Reescritura: "política de traspaso de tiempo libre pagado; transferencia de vacaciones; horas máximas; última versión de la política"

Observabilidad y bucles de retroalimentación

Registra qué chunks se utilizaron, sus puntuaciones y cuáles se ignoraron

Captura los pulgares hacia arriba/abajo con una breve justificación; incorpora eso a la optimización del recuperador

Ejecuta pruebas de regresión semanales en tu conjunto de evaluación antes de implementar cualquier cambio de modelo

Hoja de trucos para la optimización del rendimiento

Si las respuestas se sienten genéricas: aumenta candidate_top_k y añade un reranker más fuerte

Si las respuestas omiten detalles: reduce el tamaño del chunk; aumenta ligeramente el peso léxico

Si las citas repiten el mismo chunk: habilita MMR y aumenta la diversidad

Si la latencia es alta: almacena en caché las incrustaciones, precalcula las reescrituras de consultas, utiliza un reranker más pequeño

Si los costos se disparan: baja la temperatura de generación, acorta los prompts, prueba con un LLM más pequeño para la primera pasada

Aspectos esenciales de seguridad y gobernanza

Cifra los vectores almacenados y redacta los campos confidenciales en los metadatos

Utiliza el control de acceso por índice; segmenta por equipo o sensibilidad de los datos

Mantén un registro de la procedencia de los datos: URL de la fuente del documento, checksum y marca de tiempo de la ingesta

Instantánea del caso de estudio: De PDFs desordenados a respuestas confiables

Un equipo de soporte ingirió 1,200 páginas de PDFs. La recuperación inicial fue inconsistente; los agentes no confiaban en el bot. Después de cambiar a chunking semántico‑híbrido (800 tokens, 80 de superposición), habilitar el reranking del codificador cruzado y exigir citar‑o‑silenciar, la tasa de aciertos del top‑k aumentó del 62% al 89% y la adopción por parte de los agentes se duplicó. La clave no fue un LLM más grande, sino chunks más limpios y una recuperación más estricta.

Consejo de herramienta: Iteración rápida con una barra lateral de IA

Vale la pena señalar: si estás experimentando con prompts y fragmentos de recuperación en muchos documentos, un asistente de IA que te permita chatear sobre PDFs, páginas web y código directamente desde el navegador puede acelerar la iteración. Por cierto, Sider.AI (https://sider.ai/) ofrece una barra lateral de IA que te permite extraer contexto de la página en la que te encuentras, resumir y refinar los prompts rápidamente. Es útil para crear prototipos de prompts RAG y probar la calidad de los chunks antes de formalizar el pipeline.

Solución de problemas de RAGFlow: Soluciones rápidas

“El modelo está seguro pero equivocado.”

Habilita la comprobación de la capacidad de respuesta; baja la temperatura; exige citas

“La búsqueda devuelve casi‑duplicados.”

Activa MMR; añade un reranker; reduce la superposición de chunks

“La latencia se dispara en el pico.”

Incrustaciones por lotes; almacena en caché las reescrituras de consultas; utiliza la generación de streaming

“Las políticas antiguas siguen apareciendo.”

Filtra en version = latest; descarta o elimina documentos obsoletos

Próximos pasos: Haz que tu RAGFlow sea fiable en producción

Comienza con un corpus pequeño y de confianza; perfecciona primero el chunking y los filtros

Añade un reranker antes de actualizar el LLM

Crea un conjunto de evaluación de 100 preguntas y realiza un seguimiento semanal de la tasa de aciertos

Conecta la retroalimentación del usuario para optimizar continuamente la recuperación

Conclusiones clave:

La calidad de la recuperación supera el tamaño del modelo para RAG

El chunking, los metadatos y el reranking son tus palancas principales

Las medidas de seguridad como citar‑o‑silenciar aumentan la confianza drásticamente

Invierte temprano en la observabilidad y la evaluación

Con estas prácticas, RAGFlow se convierte en una columna vertebral fiable para las respuestas fundamentadas, ya sea que estés impulsando un bot de ayuda, un copiloto para desarrolladores o un asistente de conocimiento interno.

FAQ

P1: ¿Qué es RAGFlow y cómo lo uso para el control de calidad de documentos? RAGFlow es un marco para construir pipelines de generación aumentada por recuperación. Ingiere, divide, incrusta, recupera y genera respuestas con citas para reducir las alucinaciones y mejorar la precisión.

P2: ¿Cómo debo dividir los documentos en RAGFlow? Utiliza chunking semántico o híbrido con chunks de 600 a 1,000 tokens y una superposición de 50 a 100 tokens. Para el código, divide por función o clase e incluye el contexto circundante.

P3: ¿Qué base de datos vectorial funciona mejor con RAGFlow? Elige una tienda que admita búsqueda híbrida, filtros de metadatos y reranking: Qdrant, Weaviate, Pinecone o una opción local son opciones comunes.

P4: ¿Cómo evito las alucinaciones en una aplicación RAGFlow? Exige una política de citar‑o‑silenciar, añade una comprobación de la capacidad de respuesta antes de la generación y mantén los prompts estrictos sobre el uso exclusivo del contexto recuperado.

P5: ¿Qué métricas debo rastrear para evaluar RAGFlow? Supervisa la tasa de aciertos de recuperación, la fidelidad de la respuesta, la latencia y el costo por 100 consultas, y mantén un conjunto de evaluación pequeño pero representativo.