Assistente de estudo com Retrieval-Augmented Generation (RAG), offline e com aprendizado aditivo.
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.
- 💬 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.
- Python 3.10+ (testado com 3.12)
- ~1 GB de espaço em disco (modelo de embeddings)
# 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.txtO modelo de embeddings é baixado na primeira execução (~470 MB).
python -m streamlit run chat_app.pyO app abre em http://localhost:8501.
No Windows com Python da Microsoft Store: o comando
streamlitcostuma não estar no PATH. Usepython -m streamlit ...ou dê dois cliques eminiciar.bat, que já resolve isso.
- Abra o app e digite sua pergunta no campo de chat.
- O sistema busca os trechos mais relevantes nos PDFs e responde citando a fonte de cada trecho.
- Expanda "Fontes consultadas" para ver os chunks utilizados e o nível de relevância.
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/).
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
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
| 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 |
.
├── 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/eknowledge/são gerados em tempo de execução e ficam fora do versionamento (ver.gitignore).
| 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.
| 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 |
- 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)
Contribuições são bem-vindas!
- Faça um fork do projeto.
- Crie um branch:
git checkout -b feature/minha-melhoria. - Faça suas alterações e commits.
- Abra um Pull Request.
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)