Pipeline RAG Completo
Nesta página
Juntar Todas as Peças
As lições anteriores abordaram cada elo da cadeia separadamente: carregamento, fragmentação, codificação, indexação, recuperação e geração. Agora é altura de os soldar num único programa completo e de ponta a ponta, que pode executar tal como está e depois adaptar aos seus próprios documentos. Este script cabe num único ficheiro e requer apenas quatro dependências.
pip install mistralai faiss-cpu numpy requests
O Pipeline Completo
Duas escolhas de design estruturam este código. Primeiro, agrupamos toda a configuração no topo do ficheiro: modelos, tamanho dos fragmentos, tamanho do lote e TOP_K são constantes nomeadas. Isto poupa-o de procurar valores codificados (“hard-coded”) enterrados dentro de funções quando precisar de afinar o comportamento. Segundo, dividimos a lógica em seis funções independentes, cada uma correspondendo a um passo e imprimindo o seu progresso como [n/6]. Este registo não é decorativo: quando o pipeline falha ou devolve uma resposta estranha, indica-lhe imediatamente se o problema reside no carregamento, na fragmentação ou na recuperação. Cada função também é substituível isoladamente — pode trocar o carregador de PDF na função load_data sem tocar no resto.
A função main encadeia os passos e, em seguida, consulta o corpus com três perguntas sobre o ensaio de Paul Graham utilizado como nosso conjunto de dados de demonstração. Note que a recuperação e a geração ocorrem dentro do ciclo, enquanto a indexação acontece apenas uma vez antes: recodificar todo o corpus para cada pergunta seria absurdo em termos de custo e latência.
import os
import json
import numpy as np
import faiss
import requests
from mistralai.client import Mistral
# ============================================================
# Configuração
# ============================================================
MISTRAL_API_KEY = os.environ.get("MISTRAL_API_KEY")
EMBED_MODEL = "mistral-embed"
CHAT_MODEL = "mistral-large-latest"
CHUNK_SIZE = 2048
BATCH_SIZE = 25
TOP_K = 3
client = Mistral(api_key=MISTRAL_API_KEY)
# ============================================================
# Passo 1: Carregar Dados
# ============================================================
def load_data(url):
"""Carregar um documento de texto a partir de um URL."""
print("[1/6] A carregar dados...")
response = requests.get(url)
response.raise_for_status()
text = response.text
print(f" -> {len(text)} carateres carregados")
return text
# ============================================================
# Passo 2: Criar Fragmentos
# ============================================================
def create_chunks(text, chunk_size=CHUNK_SIZE):
"""Dividir o texto em fragmentos."""
print("[2/6] A criar fragmentos...")
chunks = []
paragraphs = text.split("\n\n")
current = ""
for para in paragraphs:
para = para.strip()
if not para:
continue
if len(current) + len(para) + 2 <= chunk_size:
current = current + "\n\n" + para if current else para
else:
if current:
chunks.append(current)
current = para
if current:
chunks.append(current)
print(f" -> {len(chunks)} fragmentos criados (tamanho médio: {sum(len(c) for c in chunks) // len(chunks)} carateres)")
return chunks
# ============================================================
# Passo 3: Gerar Embeddings
# ============================================================
def create_embeddings(chunks, batch_size=BATCH_SIZE):
"""Codificar fragmentos em embeddings via mistral-embed."""
print("[3/6] A gerar embeddings...")
all_embeddings = []
for i in range(0, len(chunks), batch_size):
batch = chunks[i:i + batch_size]
response = client.embeddings.create(
model=EMBED_MODEL,
inputs=batch,
)
all_embeddings.extend([d.embedding for d in response.data])
print(f" -> Lote {i // batch_size + 1}/{(len(chunks) - 1) // batch_size + 1} codificado")
embeddings = np.array(all_embeddings, dtype=np.float32)
print(f" -> Matriz: {embeddings.shape}")
return embeddings
# ============================================================
# Passo 4: Criar Índice FAISS
# ============================================================
def create_index(embeddings):
"""Criar e povoar um índice FAISS."""
print("[4/6] A criar índice FAISS...")
dimension = embeddings.shape[1]
index = faiss.IndexFlatL2(dimension)
index.add(embeddings)
print(f" -> Índice: {index.ntotal} vetores, dimensão {dimension}")
return index
# ============================================================
# Passo 5: Recuperar Fragmentos Relevantes
# ============================================================
def retrieve(question, index, chunks, k=TOP_K):
"""Recuperar os fragmentos mais relevantes."""
print(f"[5/6] À procura de: '{question[:50]}...'")
response = client.embeddings.create(
model=EMBED_MODEL,
inputs=[question],
)
query_vector = np.array([response.data[0].embedding], dtype=np.float32)
distances, indices = index.search(query_vector, k)
results = []
for dist, idx in zip(distances[0], indices[0]):
if idx >= 0:
results.append({
"text": chunks[idx],
"distance": float(dist),
})
print(f" -> {len(results)} fragmentos recuperados")
return results
# ============================================================
# Passo 6: Gerar Resposta
# ============================================================
def generate(question, context_chunks):
"""Gerar a resposta utilizando o contexto recuperado."""
print("[6/6] A gerar resposta...")
context = "\n\n---\n\n".join([c["text"] for c in context_chunks])
prompt = f"""Contexto informativo:
{context}
---
Com base APENAS no contexto acima, responda à seguinte pergunta de forma precisa e completa.
Pergunta: {question}"""
response = client.chat.complete(
model=CHAT_MODEL,
messages=[
{"role": "system", "content": "É um assistente que responde com base no contexto fornecido."},
{"role": "user", "content": prompt},
],
temperature=0.1,
)
answer = response.choices[0].message.content
print(f" -> Resposta gerada ({len(answer)} carateres)")
return answer
# ============================================================
# Pipeline Principal
# ============================================================
def main():
"""Executar o pipeline RAG completo."""
# 1. Carregar
url = "https://raw.githubusercontent.com/run-llama/llama_index/main/docs/docs/examples/data/paul_graham/paul_graham_essay.txt"
text = load_data(url)
# 2. Fragmentar
chunks = create_chunks(text)
# 3. Codificar
embeddings = create_embeddings(chunks)
# 4. Indexar
index = create_index(embeddings)
# 5+6. Pergunta -> Resposta
questions = [
"What were the two main things the author worked on before college?",
"What did the author do during their time at Y Combinator?",
"What programming language did the author learn first?",
]
for question in questions:
print(f"\n{'='*60}")
context = retrieve(question, index, chunks)
answer = generate(question, context)
print(f"\nP: {question}")
print(f"R: {answer}")
if __name__ == "__main__":
main()
Executar o Pipeline
Guarde este código como rag_pipeline.py, exporte a sua chave de API no ambiente — nunca a codifique diretamente no ficheiro, pois acabará mais tarde ou mais cedo num repositório — e execute o script. O resultado percorre os seis passos e, em seguida, processa as três perguntas com as respetivas respostas. Se alguma resposta parecer fora de contexto, compare-a com os fragmentos apresentados no passo 5 antes de culpar o modelo de geração.
export MISTRAL_API_KEY="your-api-key"
python rag_pipeline.py
Cinco Direções para Melhoria Futura
Este pipeline é uma base, não um produto acabado, e cada uma das suas limitações aponta para um próximo passo. A mais imediata é a persistência: na sua forma atual, o script recodifica todo o corpus em cada execução, enquanto guardar o índice FAISS e os fragmentos tornaria as execuções subsequentes quase instantâneas. O “re-ranking” (reordenação) é o nível seguinte, passando os resultados do FAISS por um modelo “cross-encoder” que avalia a relevância de forma muito mais fina do que apenas a distância vetorial. A filtragem por metadados responde a outra necessidade: restringir a pesquisa por data, categoria ou autor, para além da similaridade. Duas melhorias finais focam-se na experiência do utilizador: o “streaming”, que exibe a resposta à medida que é gerada em vez de após vários segundos de silêncio, e o histórico de conversação, que permite aos utilizadores fazer perguntas de seguimento como «e quanto à versão 2?» sem terem de repetir toda a pergunta.
# 1. Guardar o índice para evitar recálculos
faiss.write_index(index, "my_rag.index")
np.save("my_chunks.npy", np.array(chunks, dtype=object))
# 2. Adicionar re-ranking
# Após a recuperação FAISS, usar um modelo cross-encoder
# para reordenar os resultados por relevância detalhada
# 3. Filtragem por metadados
# Adicionar filtros (data, categoria, autor) para além
# da similaridade vetorial
# 4. Streaming da resposta
# Usar client.chat.stream() para exibir a resposta
# à medida que é gerada
# 5. Histórico de conversação
# Adicionar trocas anteriores ao prompt
# para um chatbot RAG contextual
Pontos-chave
- O pipeline RAG completo divide-se em 6 passos: carregar, fragmentar, codificar, indexar, recuperar, gerar
- Cada passo é uma função independente, fácil de testar e substituir
- Utilize
temperature=0.1para respostas factuais - Guarde o índice FAISS e os embeddings para evitar recálculos em cada execução
- Este pipeline é um ponto de partida sólido para enriquecer conforme as suas necessidades