Skip to content

README.md

Latest commit

 

History

History
234 lines (173 loc) · 9.07 KB

README.md

File metadata and controls

234 lines (173 loc) · 9.07 KB
Raw

📚 Chat de Estudos RAG

Assistente de estudo com Retrieval-Augmented Generation (RAG), offline e com aprendizado aditivo.

Python Streamlit FAISS Embeddings Sem API key Windows macOS Linux

📖 Sobre o projeto

Um sistema de estudo universitário com RAG: faça perguntas sobre os PDFs da pasta pdf/ e receba respostas com as fontes citadas — tudo processado localmente, sem depender de LLM externo, chave de API ou internet após a instalação.

A base de conhecimento não é estática: além dos PDFs iniciais, você pode ensinar novos conteúdos (anotações e uploads de PDF) pela interface, que são incorporados ao índice de forma aditiva — sem reconstruir tudo do zero.

✨ Funcionalidades

  • 💬 Chat interativo com respostas extrativas e offline, sempre citando a fonte dos trechos recuperados.
  • 🔍 Busca semântica com embeddings multilingue (paraphrase-multilingual-MiniLM-L12-v2) + índice FAISS persistente.
  • 🎯 Rerank híbrido (semântico + léxico): perguntas conceituais encontram o conteúdo certo mesmo quando as palavras não batem exatamente.
  • 🧹 Limpeza automática de PDFs: remove cabeçalhos/rodapés de página, marcas de exportação (ex.: 0jhtp.indb 454 07/07/2016 15:19:55) e trechos de código espúrios antes da indexação.
  • ➕ Aprendizado aditivo: adicione anotações ou faça upload de PDFs pela barra lateral — o novo conhecimento entra no índice na hora e é persistido.
  • 🧠 Expansão de consulta: termos conceituais são expandidos (ex.: "pilares" → encapsulamento, herança, polimorfismo, abstração).
  • 🔁 Índice auto-gerenciado: se as fontes mudarem, o índice é reconstruído automaticamente.
  • 🔒 Privado por padrão: nenhum dado sai da sua máquina.

🚀 Início rápido

Pré-requisitos

  • Python 3.10+ (testado com 3.12)
  • ~1 GB de espaço em disco (modelo de embeddings)

Instalação

# 1. Clone o repositório
git clone https://github.com/SEU_USUARIO/SEU_REPO.git
cd SEU_REPO

# 2. (Recomendado) Crie um ambiente virtual
python -m venv .venv
.venv\Scripts\activate          # Windows
source .venv/bin/activate       # macOS/Linux

# 3. Instale as dependências
pip install -r requirements.txt

O modelo de embeddings é baixado na primeira execução (~470 MB).

Executando o chat

python -m streamlit run chat_app.py

O app abre em http://localhost:8501.

No Windows com Python da Microsoft Store: o comando streamlit costuma não estar no PATH. Use python -m streamlit ... ou dê dois cliques em iniciar.bat, que já resolve isso.

🖥️ Como usar

Perguntando sobre os materiais

  1. Abra o app e digite sua pergunta no campo de chat.
  2. O sistema busca os trechos mais relevantes nos PDFs e responde citando a fonte de cada trecho.
  3. Expanda "Fontes consultadas" para ver os chunks utilizados e o nível de relevância.

Ensinando novo conhecimento

Na barra lateral do app:

Ação O que acontece
✍️ Digitar uma anotação e clicar em "Salvar na base" O texto é fragmentado, incorporado e adicionado ao índice na hora
📄 Fazer upload de um PDF O texto é extraído, limpo e incorporado ao índice na hora

O conhecimento ensinado fica salvo em knowledge/ (anotações em user_knowledge.json e uploads em uploads/).

🏗️ Arquitetura

flowchart LR
    A[PDFs em pdf/] --> B[Extração de texto<br/>pypdf]
    B --> C[Limpeza<br/>remover ruído de layout]
    C --> D[Chunking<br/>800 chars / overlap 150]
    D --> E[Embeddings<br/>Sentence-Transformer MiniLM]
    E --> F[(Índice FAISS<br/>faiss_index/)]
    G[Pergunta do usuário] --> H[Expansão de consulta]
    H --> I[Embedding da pergunta]
    I --> F
    F --> J[Recuperação<br/>300 candidatos]
    J --> K[Rerank híbrido<br/>semântico + léxico]
    K --> L[Resposta extrativa<br/>com fonte citada]
    M[Anotações / uploads] --> E
Loading

Fluxo da busca (pipeline RAG)

pergunta do usuário
      │
      ▼
 1. Expansão de consulta (sinônimos conceituais)
      │
      ▼
 2. Embedding da pergunta (SentenceTransformer)
      │
      ▼
 3. FAISS top-300 candidatos (similaridade de cosseno)
      │
      ▼
 4. Rerank híbrido (65% semântico + 35% overlap léxico)
      │
      ▼
 5. Seleção das frases mais relevantes + citação da fonte

🧰 Tecnologias

Camada Tecnologia
Interface Streamlit
Embeddings sentence-transformers (paraphrase-multilingual-MiniLM-L12-v2, 384 dim)
Indexação vetorial FAISS (IndexFlatIP, vetores normalizados)
Extração de PDF pypdf
Numérica NumPy

📁 Estrutura do projeto

.
├── pdf/                        # Conhecimento inicial (PDFs)
├── rag/                        # Pacote do motor RAG: limpeza, embeddings, FAISS, aprendizado aditivo
│   ├── __init__.py             # Entrypoint do pacote (importações padrão)
│   ├── __main__.py             # Chamada CLI: python -m rag
│   ├── config.py               # Constantes de configuração e caminhos de arquivo
│   ├── utils.py                # Utilitários de arquivo, cálculo de hashes e limpeza de PDFs
│   ├── store.py                # RAGStore (gerenciamento do índice e FAISS)
│   └── generation.py           # Expansão de consulta e geração da resposta extrativa
├── chat_app.py                 # Interface de chat (Streamlit)
├── iniciar.bat                 # Atalho de inicialização no Windows
├── requirements.txt            # Dependências do projeto
├── README.md
│
├── faiss_index/                # Índice persistente (GERADO — não versionado)
│   ├── index.thz               #   vetores FAISS
│   ├── chunks.thz              #   texto dos chunks + fonte
│   └── sources.thz             #   impressão digital das fontes
│
└── knowledge/                  # Conhecimento aprendido (GERADO — não versionado)
    ├── user_knowledge.thz      #   anotações do usuário
    └── uploads/                #   PDFs enviados pela interface

faiss_index/ e knowledge/ são gerados em tempo de execução e ficam fora do versionamento (ver .gitignore).

⚙️ Configurações principais

Constante Valor Descrição
CHUNK_SIZE 800 Tamanho do chunk (caracteres)
CHUNK_OVERLAP 150 Sobreposição entre chunks
TOP_K 6 Resultados finais exibidos
MIN_CANDIDATES 300 Candidatos recuperados antes do rerank
SCORE_THRESHOLD 0.20 Limiar mínimo de similaridade
LEX_WEIGHT 0.35 Peso do rerank léxico

Todas ficam em rag/config.py.

🛠️ Solução de problemas

Problema Solução
streamlit não é reconhecido no Windows Use python -m streamlit run chat_app.py ou o iniciar.bat
Download do modelo demora na 1ª execução Normal: ~470 MB baixados do Hugging Face
Índice foi "apagado" Ele é reconstruído automaticamente ao iniciar
Resposta diz que não encontrou conteúdo Reformule a pergunta ou ensine o conteúdo na barra lateral
Erro de instalação de faiss-cpu Garanta Python 3.10+ e pip install --upgrade pip antes

🗺️ Roadmap (ideias)

  • Opção de respostas com LLM local (ex.: Qwen/Llama via transformers)
  • Múltiplos "cadernos" de conhecimento
  • Feedback do usuário nas respostas (bom/ruim) para calibrar o rerank
  • Exportação/importação da base de conhecimento
  • Suporte a outros formatos (Markdown, DOCX, URLs)

🤝 Contribuindo

Contribuições são bem-vindas!

  1. Faça um fork do projeto.
  2. Crie um branch: git checkout -b feature/minha-melhoria.
  3. Faça suas alterações e commits.
  4. Abra um Pull Request.

⚖️ Licença

AGPL-3.0 Todas as alterações feitas neste projeto devem ser disponibilizadas sob a mesma licença. E devem voltar para a comunidade (Este projeto é open source)