Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Pipeline RAG Completo

Aula 14 de 18 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Juntar Todas as Peças
  2. O Pipeline Completo
  3. Executar o Pipeline
  4. Cinco Direções para Melhoria Futura
  5. Pontos-chave

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.1 para 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