Preparar os Dados
Nesta página
A Qualidade do RAG Depende dos Seus Dados
Um pipeline RAG só é tão bom quanto os dados que indexa. Pode criar o prompt perfeito e selecionar o melhor modelo de geração, mas se o fragmento recuperado cortar uma definição ao meio ou incluir um rodapé repetitivo em vez de texto útil, a sua resposta será prejudicada. A preparação ocorre em três fases: obter os dados onde eles residem, remover tudo o que não tem significado e dividi-los em fragmentos otimizados para indexação.
Obtenção dos Dados
Os corpora do mundo real raramente são homogéneos. Tipicamente, terá documentação Markdown num repositório, algumas páginas de um site público e alguns PDFs regulamentares. Cada fonte requer o seu próprio carregador, mas todos devem produzir a mesma estrutura — conteúdo, origem e tipo — para que o restante do pipeline permaneça agnóstico à origem do texto.
Para ficheiros de texto, uma varredura recursiva de diretórios é suficiente, e a filtragem por extensão impede o carregamento acidental de ficheiros binários.
import os
def load_text_files(directory, extensions=(".txt", ".md", ".rst")):
"""Load all text files from a directory."""
documents = []
for root, dirs, files in os.walk(directory):
for f in files:
if any(f.endswith(ext) for ext in extensions):
filepath = os.path.join(root, f)
with open(filepath, "r", encoding="utf-8") as fh:
content = fh.read()
documents.append({
"content": content,
"source": filepath,
"type": "text",
})
return documents
docs = load_text_files("./data/")
print(f"{len(docs)} documents loaded")
As páginas web chegam via HTTP, mas o que obtém é HTML. A extração abaixo remove as tags usando expressões regulares e colapsa múltiplos espaços. Isto é suficiente para um protótipo, mas o comentário lembra-o de que, em produção, o BeautifulSoup fará um trabalho muito melhor com tabelas e listas aninhadas.
import requests
def fetch_web_page(url):
"""Fetch the text content of a web page."""
response = requests.get(url)
response.raise_for_status()
# Basic text extraction (use BeautifulSoup for production)
text = response.text
# Remove HTML tags
import re
text = re.sub(r'<[^>]+>', ' ', text)
text = re.sub(r'\s+', ' ', text).strip()
return {
"content": text,
"source": url,
"type": "web",
}
# Example
page = fetch_web_page("https://raw.githubusercontent.com/run-llama/llama_index/main/docs/docs/examples/data/paul_graham/paul_graham_essay.txt")
print(f"Content: {len(page['content'])} characters")
Os PDFs merecem um tratamento especial. Em vez de concatenar o documento inteiro, mantenha uma entrada por página e codifique o número da página na origem como file.pdf#page=12. Quando o seu assistente citar esta passagem, o utilizador saberá exatamente onde a verificar.
# pip install PyPDF2
from PyPDF2 import PdfReader
def load_pdf(filepath):
"""Extract text from a PDF."""
reader = PdfReader(filepath)
pages = []
for i, page in enumerate(reader.pages):
text = page.extract_text()
if text.strip():
pages.append({
"content": text,
"source": f"{filepath}#page={i+1}",
"type": "pdf",
"page": i + 1,
})
return pages
Limpeza dos Dados
A limpeza é crítica para a qualidade da recuperação, pois cada caractere stray consome espaço no fragmento e turva o vetor resultante. A função seguinte encadeia quatro tratamentos: remove caracteres de controlo deixados por conversões de formato, normaliza sequências de novas linhas e espaços, apaga marcadores de paginação típicos de PDFs e substitui URLs intermináveis por um marcador simples para que não consumam um fragmento inteiro.
import re
def clean_text(text):
"""Clean text for RAG indexing."""
# Remove control characters
text = re.sub(r'[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]', '', text)
# Normalize spaces and newlines
text = re.sub(r'\n{3,}', '\n\n', text)
text = re.sub(r' {2,}', ' ', text)
# Remove repetitive headers/footers (PDF)
text = re.sub(r'Page \d+ of \d+', '', text)
# Remove very long URLs
text = re.sub(r'https?://\S{100,}', '[URL]', text)
return text.strip()
# Apply cleaning
for doc in docs:
doc["content"] = clean_text(doc["content"])
Estratégias de Fragmentação
A fragmentação é o passo mais importante na preparação: o tamanho e o método do fragmento impactam diretamente a qualidade da recuperação. Existem três abordagens, que vão da mecânica à consciente da estrutura.
A fragmentação de tamanho fixo percorre o texto em fatias regulares. Ignora completamente o significado, tornando-a aplicável a qualquer fonte, mas frequentemente corta frases ao meio. A sobreposição corrige parcialmente esta falha: com overlap=200, o fim de cada fragmento repete-se no início do seguinte, garantindo que uma ideia dividida permaneça inteira em pelo menos uma das duas peças.
def chunk_fixed_size(text, chunk_size=2048, overlap=200):
"""Fixed-size chunking with overlap."""
chunks = []
start = 0
while start < len(text):
end = min(start + chunk_size, len(text))
chunk = text[start:end]
if chunk.strip():
chunks.append(chunk.strip())
start += chunk_size - overlap
return chunks
A fragmentação baseada em parágrafos, recomendada para documentação, confia nas fronteiras naturais do texto. Acumula parágrafos enquanto estes permanecerem abaixo do max_size, abrindo depois um novo fragmento. O limiar min_size impede a indexação de um cabeçalho órfão ou linha isolada, o que produziria um vetor sem conteúdo utilizável.
def chunk_by_paragraphs(text, max_size=1500, min_size=100):
"""Intelligent paragraph-based chunking."""
paragraphs = text.split("\n\n")
chunks = []
current = ""
for para in paragraphs:
para = para.strip()
if not para:
continue
if len(current) + len(para) + 2 <= max_size:
current = current + "\n\n" + para if current else para
else:
if len(current) >= min_size:
chunks.append(current)
current = para
if current and len(current) >= min_size:
chunks.append(current)
return chunks
A fragmentação por secções Markdown aproveita a informação que o autor já forneceu: os seus títulos. Cada secção torna-se um fragmento autónomo, garantindo que uma pergunta sobre “autenticação” recupera a secção inteira em vez de um fragmento. As secções demasiado longas recorrem à fragmentação por parágrafos, assegurando que nenhum fragmento excede o limite.
def chunk_by_markdown_sections(text, max_size=2000):
"""Chunking by Markdown headings (## and ###)."""
sections = re.split(r'\n(?=##\s)', text)
chunks = []
for section in sections:
section = section.strip()
if not section:
continue
if len(section) <= max_size:
chunks.append(section)
else:
# Sub-chunk overly long sections
sub_chunks = chunk_by_paragraphs(section, max_size=max_size)
chunks.extend(sub_chunks)
return chunks
Pipeline de Preparação Completo
Finalmente, encadeie as três operações e escolha a estratégia de fragmentação com base no tipo de ficheiro: ficheiros .md passam pelas secções, todo o resto pelos parágrafos. Cada fragmento carrega então os seus metadados — origem, posição no documento e número total de fragmentos desse documento. Sem isto, não conseguirá atribuir a origem de uma resposta. As últimas duas linhas mostram a taxa de expansão e o tamanho médio: se esta média cair bem abaixo do seu chunk_size, o documento está mais fragmentado do que o esperado e precisa de rever a sua estratégia de fragmentação.
def prepare_documents(raw_docs, chunk_size=1500, overlap=200):
"""Complete pipeline: clean, chunk, enrich with metadata."""
all_chunks = []
for doc in raw_docs:
# 1. Clean
clean = clean_text(doc["content"])
# 2. Chunk based on type
if doc.get("source", "").endswith(".md"):
chunks = chunk_by_markdown_sections(clean, max_size=chunk_size)
else:
chunks = chunk_by_paragraphs(clean, max_size=chunk_size)
# 3. Enrich with metadata
for i, chunk in enumerate(chunks):
all_chunks.append({
"text": chunk,
"source": doc["source"],
"chunk_index": i,
"total_chunks": len(chunks),
})
return all_chunks
# Execution
chunks = prepare_documents(docs)
print(f"{len(docs)} documents -> {len(chunks)} chunks")
print(f"Average size: {sum(len(c['text']) for c in chunks) / len(chunks):.0f} characters")
Pontos-chave
- A qualidade do RAG depende diretamente da qualidade dos dados e da estratégia de fragmentação
- Limpe os dados antes da indexação (remova caracteres stray, URLs longos, duplicados)
- A fragmentação por parágrafos ou secções Markdown preserva a coerência semântica
- Uma sobreposição de 10–15% entre fragmentos impede a divisão de ideias
- Mantenha os metadados (origem, página, posição) para a rastreabilidade das respostas