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.

Como Usar o RAGFlow: Um Guia Prático para Construir Aplicações RAG Confiáveis

Se você já tentou construir um sistema de geração aumentada por recuperação (RAG), provavelmente já se deparou com os clássicos pontos problemáticos: alucinações, recuperação instável, pipelines lentos e pré-processamento de documentos confuso. O RAGFlow surge como uma ferramenta de fluxo de trabalho completa que ajuda você a orquestrar a ingestão de documentos, divisão em partes (chunking), vetorização, recuperação e geração com mais controle e observabilidade.

Este guia adota uma abordagem prática e orientada para soluções. Vamos percorrer uma configuração limpa, mostrar como usar o RAGFlow para documentos reais e compartilhar padrões que realmente reduzem as alucinações e melhoram a qualidade da resposta.

O que é RAGFlow e por que usá-lo?

RAGFlow é um sistema para construir pipelines de Geração Aumentada por Recuperação. Em uma configuração RAG típica, você:

Ingere documentos (PDFs, páginas da web, slides, código, etc.)

Divide o conteúdo em unidades recuperáveis

Incorpora os chunks em vetores para pesquisa semântica

Recupera os top‑k chunks relevantes no momento da pergunta

Gera uma resposta fundamentada usando um LLM

O RAGFlow adiciona padrões opinativos, blocos de fluxo de trabalho e proteções para que você possa iterar mais rapidamente e lançar aplicativos mais confiáveis. É particularmente útil se você quiser:

Chunking e metadados consistentes: Uma melhor recuperação começa com melhores chunks.

Embeddings e LLMs plugáveis: Troque OpenAI, modelos locais ou endpoints corporativos.

Avaliações e proteções: Meça a qualidade da recuperação e reduza as alucinações.

Pipelines implementáveis: Mova do notebook para a produção com menos reescritas.

Início rápido: De zero a um pipeline RAGFlow funcional

Abaixo está um fluxo de trabalho mínimo e completo que você pode adaptar. Mesmo que seu ambiente seja diferente, a sequência e as proteções são portáteis.

1) Prepare seu ambiente

Crie um .env com suas chaves:

OPENAI_API_KEY (ou outro provedor de LLM)

EMBEDDINGS_API_KEY (se estiver usando um provedor separado)

VECTOR_DB_URL (por exemplo, Pinecone, Weaviate, Qdrant ou local)

Defina um diretório de projeto, por exemplo, ragflow-project/ com pastas:

data/raw/ (arquivos de origem)

data/processed/ (chunks limpos)

configs/ (YAML/JSON para configurações de pipeline)

eval/ (conjuntos de dados e relatórios)

2) Ingira documentos com metadados limpos

Bons metadados = melhor recuperação. Normalize títulos, autores, datas e fontes.

Converta PDFs e slides em texto com um parser robusto

Preserve a estrutura: títulos, listas, blocos de código e tabelas

Anexe metadados a cada chunk: source, section, page, timestamp, version

Dica: Mantenha um doc_id e chunk_id para suportar citações e re‑ingestão.

3) Escolha uma estratégia de chunking que se adapte ao seu conteúdo

O chunking afeta fortemente a qualidade da recuperação e a latência.

Para documentos narrativos: chunking semântico (dividir por títulos/parágrafos)

Para documentos técnicos: use chunking híbrido (semântico + janela fixa)

Para código: chunk por função/classe com uma pequena janela deslizante

Configurações recomendadas para começar:

chunk_size: 600–1.000 tokens

chunk_overlap: 50–100 tokens

max_depth: limite seções aninhadas a 2–3 níveis para evitar fragmentação

4) Escolha embeddings e um vector store

Comece com um modelo de embedding forte de propósito geral (por exemplo, text‑embedding‑3‑large ou um modelo local moderno). Se a privacidade for fundamental, considere embeddings auto-hospedados.

Use um vector DB que suporte:

Pesquisa híbrida (densa + palavra-chave)

Filtros (restrições de metadados)

Upserts em lote e métricas de índice

Configurações de índice para testar:

top_k = 5–10 para recuperação inicial

similarity_metric = cosine (ou dot para certos modelos)

Ative máxima relevância marginal (MMR) para reduzir a redundância

5) Orquestração de recuperação

Implemente um retriever de dois estágios:

Recall rápido de candidatos

Pesquisa híbrida (BM25 + densa)

top_k grande (por exemplo, 30–50)

Reclassificação

Reclassificador de codificador cruzado ou pontuação baseada em LLM

Reduza para top_k final (por exemplo, 5–8)

Adicione filtros de metadados: source:"handbook" AND section:"benefits" AND version:"v2" para restringir as respostas a documentos confiáveis.

6) Geração fundamentada com estrutura

Seu prompt deve impor citações e recusa quando a evidência for fraca.

Exemplo de prompt do sistema:

Você é um assistente cuidadoso. Responda APENAS com informações suportadas pelo contexto fornecido.
- Cite as fontes inline como [doc_id:chunk_id].
- Se o contexto for insuficiente, diga "Não há informações suficientes nos documentos fornecidos."
- Não invente fatos.

Modelo de prompt do usuário:

Pergunta: {query}
Contexto:
{top_chunks}
Instruções:
- Forneça uma resposta concisa primeiro, depois os detalhes.
- Inclua citações após cada afirmação factual.

7) Adicione proteções para reduzir as alucinações

Verificação de capacidade de resposta: Antes da geração, pergunte a um modelo pequeno: “Existe evidência direta nos chunks recuperados?” Se não, retorne uma pergunta de esclarecimento.

Política Citar‑ou‑silenciar: Bloqueie saídas que carecem de citações.

Filtros de Toxicidade/PII para conteúdo corporativo.

8) Avaliação e melhoria contínua

Crie um conjunto eval/ com:

50–200 perguntas reais de usuários

Respostas de verdade absoluta (ou referências confiáveis)

Fontes esperadas (ids de documentos) onde aplicável

Meça:

Taxa de acerto de recuperação (a fonte de ouro aparece no top‑k?)

Fidelidade da resposta (declarações suportadas por citação)

Latência (p95 de ponta a ponta)

Custo (por 100 consultas)

Itere em:

Tamanho do chunk e sobreposição

Escolha do modelo de embedding

Reclassificador vs. top‑k mais alto

Estrutura e restrições do prompt

Um pipeline RAGFlow completo: Exemplo de configuração

Abaixo está uma configuração conceitual que você pode adaptar à sua toolchain. Substitua os nomes dos provedores conforme necessário.

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

Como usar o RAGFlow para diferentes tipos de conteúdo

Manuais e guias de produtos

Prefira o chunking semântico com limites de seção claros

Anexe a versão e a data de vigência para evitar respostas desatualizadas

Use filtros estritos: sempre exija version = latest

Bases de conhecimento e FAQs

Use chunks menores (400–600 tokens) para respostas precisas

Aumente o pool de candidatos e confie na reclassificação para encontrar o snippet exato

Gere automaticamente pares Q/A canônicos para aumentar o recall por meio da pesquisa lexical

Documentos de engenharia e código

Chunk por função/módulo e inclua gráficos de importação em metadados

Ative a recuperação pai‑filho: retorne a função + seu contexto de docstring

Use um reclassificador com reconhecimento de código para priorizar símbolos relevantes

Jurídico e conformidade

Exija citações no nível do parágrafo

Adicione lógica de recusa para contexto incompleto

Mantenha um conjunto dourado de fontes aprovadas pelo regulador em um índice separado

Padrões de prompt que realmente funcionam

Responda e cite: Resposta curta no topo; citações inline após cada afirmação

Cadeia de recuperação: Peça ao modelo para resumir cada chunk primeiro e, em seguida, sintetizar

Reescrita de consulta: Expanda as consultas do usuário com sinônimos e termos de domínio antes da recuperação

Prompts contrastivos: “Explique por que a opção A é melhor que a B com base no contexto.” Isso força o uso de evidências

Exemplo de etapa de reescrita de consulta:

Original: "qual é a nossa política de carryover de PTO?"
Reescrita: "política de carryover de tempo livre remunerado; rollover de férias; horas máximas; versão mais recente da política"

Observabilidade e loops de feedback

Registre quais chunks foram usados, suas pontuações e quais foram ignorados

Capture polegares para cima/para baixo com uma pequena justificativa; alimente isso de volta no ajuste do retriever

Execute testes de regressão semanais em seu conjunto de avaliação antes de implementar qualquer alteração de modelo

Cheatsheet de ajuste de desempenho

Se as respostas parecerem genéricas: aumente candidate_top_k e adicione um reclassificador mais forte

Se as respostas perderem detalhes: reduza o tamanho do chunk; aumente ligeiramente o peso lexical

Se as citações repetirem o mesmo chunk: ative o MMR e aumente a diversidade

Se a latência for alta: armazene em cache os embeddings, pré-calcule as reescritas de consulta, use um reclassificador menor

Se os custos aumentarem: diminua a temperatura de geração, encurte os prompts, tente um LLM menor para a primeira passagem

Essenciais de segurança e governança

Criptografe vetores armazenados e oculte campos confidenciais em metadados

Use controle de acesso por índice; segmente por equipe ou sensibilidade de dados

Mantenha um registro de linhagem de dados: URL da fonte do documento, checksum e timestamp de ingestão

Snapshot de estudo de caso: De PDFs confusos a respostas confiáveis

Uma equipe de suporte ingeriu 1.200 páginas de PDFs. A recuperação inicial era inconsistente; os agentes não confiavam no bot. Após mudar para chunking semântico‑híbrido (800 tokens, 80 de sobreposição), ativar a reclassificação de codificador cruzado e impor citar‑ou‑silenciar, a taxa de acerto top‑k subiu de 62% para 89%, e a adoção do agente dobrou. A chave não era um LLM maior—era chunks mais limpos e recuperação mais rigorosa.

Dica de ferramenta: Iteração rápida com uma barra lateral de IA

Vale a pena notar: se você estiver experimentando prompts e snippets de recuperação em muitos documentos, um assistente de IA que permite conversar sobre PDFs, páginas da web e código diretamente do navegador pode acelerar a iteração. A propósito, Sider.AI (https://sider.ai/) oferece uma barra lateral de IA que permite inserir contexto da página em que você está, resumir e refinar prompts rapidamente. É útil para prototipar prompts RAG e testar a qualidade do chunk antes de formalizar o pipeline.

Solução de problemas do RAGFlow: Correções rápidas

“O modelo está confiante, mas errado.”

Ative a verificação de capacidade de resposta; diminua a temperatura; exija citações

“A pesquisa retorna quase duplicatas.”

Ative o MMR; adicione um reclassificador; reduza a sobreposição de chunks

“Picos de latência no pico.”

Embeddings em lote; armazene em cache reescritas de consulta; use geração de streaming

“Políticas antigas continuam aparecendo.”

Filtre em version = latest; descontinue ou coloque em desuso documentos desatualizados

Próximos passos: Torne seu RAGFlow confiável em produção

Comece com um corpus pequeno e confiável; aperfeiçoe o chunking e os filtros primeiro

Adicione um reclassificador antes de atualizar o LLM

Crie um conjunto de avaliação de 100 perguntas e acompanhe a taxa de acerto semanalmente

Conecte o feedback do usuário para ajustar continuamente a recuperação

Principais conclusões:

A qualidade da recuperação supera o tamanho do modelo para RAG

Chunking, metadados e reclassificação são suas alavancas principais

Proteções como citar‑ou‑silenciar aumentam a confiança drasticamente

Invista cedo em observabilidade e avaliação

Com essas práticas, o RAGFlow se torna uma espinha dorsal confiável para respostas fundamentadas—se você estiver alimentando um bot de ajuda, um copiloto de desenvolvedor ou um assistente de conhecimento interno.

FAQ

Q1: O que é RAGFlow e como posso usá-lo para QA de documentos? RAGFlow é uma estrutura para construir pipelines de geração aumentada por recuperação. Você ingere, chunk, incorpora, recupera e gera respostas com citações para reduzir as alucinações e melhorar a precisão.

Q2: Como devo dividir os documentos em partes no RAGFlow? Use chunking semântico ou híbrido com chunks de 600–1.000 tokens e sobreposição de 50–100 tokens. Para código, chunk por função ou classe e inclua o contexto circundante.

Q3: Qual banco de dados vetorial funciona melhor com RAGFlow? Escolha um armazenamento que suporte pesquisa híbrida, filtros de metadados e reclassificação—Qdrant, Weaviate, Pinecone ou uma opção local são todas as escolhas comuns.

Q4: Como evito alucinações em um aplicativo RAGFlow? Aplique uma política de citar‑ou‑silenciar, adicione uma verificação de capacidade de resposta antes da geração e mantenha os prompts estritos sobre o uso apenas do contexto recuperado.

Q5: Quais métricas devo acompanhar para avaliar o RAGFlow? Monitore a taxa de acerto da recuperação, a fidelidade da resposta, a latência e o custo por 100 consultas e mantenha um conjunto de avaliação pequeno, mas representativo.