lgcosta
7af7ba530d
The image context was backend/, so COPY frontend/ failed. Build from the repo root, place Python modules on the import path, and pin packages that exist on PyPI. The web process no longer loads the LLM at startup.
360 lines
10 KiB
Markdown
360 lines
10 KiB
Markdown
# Sistema RAG Espiritismo
|
|
|
|
|
|
|
|
|
|
|
|
Sistema de consulta assistida por IA para livros de espiritismo em PDF, com interface web rica e bot do Telegram.
|
|
|
|
## 🚀 Visão Geral
|
|
|
|
Este projeto implementa um **Sistema RAG (Retrieval-Augmented Generation)** completo para consultar e analisar livros de espiritismo usando inteligência artificial. O sistema permite:
|
|
|
|
- 🔍 **Chat Inteligente**: Pergunte sobre espiritismo e receba respostas baseadas nos livros
|
|
- 📄 **Upload de PDFs**: Adicione novos livros facilmente
|
|
- 📱 **Bot Telegram**: Receba conteúdo agendado no Telegram
|
|
- 🌐 **Interface Web**: Interface amigável e responsiva
|
|
- 🤖 **IA Local**: Modelos em CPU-only (Llama 3.2 3B)
|
|
|
|
## 📋 Stack Tecnológica
|
|
|
|
### IA & Machine Learning
|
|
- **GPT4All**: Framework para modelos LLM local
|
|
- **Llama 3.2 3B**: Modelo quantizado em 4-bit (aprox. 2GB)
|
|
- **LangChain**: Framework para aplicações RAG
|
|
- **Sentence Transformers**: Geração de embeddings
|
|
- **Qdrant**: Banco de dados vetorial
|
|
|
|
### Backend & API
|
|
- **FastAPI**: Framework web moderno e rápido
|
|
- **Pydantic**: Validação de dados
|
|
- **Celery**: Processamento assíncrono
|
|
- **Redis**: Broker para Celery
|
|
|
|
### Frontend
|
|
- **HTML5/CSS3**: Estrutura e estilização
|
|
- **Vanilla JavaScript**: Interatividade
|
|
|
|
### Deployment
|
|
- **Docker**: Containerização
|
|
- **Docker Compose**: Orquestração de serviços
|
|
- **Gitea**: Hospedagem do código
|
|
|
|
## 📋 Funcionalidades
|
|
|
|
### 1. Chat com IA
|
|
- Interface de chat intuitiva
|
|
- Respostas baseadas nos livros indexados
|
|
- Citações de fontes com referências
|
|
|
|
### 2. Upload de PDFs
|
|
- Upload de novos livros PDF
|
|
- Processamento automático de texto
|
|
- Indexação em Qdrant
|
|
|
|
### 3. Bot Telegram
|
|
- **/start**: Apresentação do sistema
|
|
- **/help**: Lista de comandos disponíveis
|
|
- **/status**: Verificar status do sistema
|
|
- **/books**: Listar livros disponíveis
|
|
- **Comando de pergunta**: Enviar perguntas diretamente ao bot
|
|
|
|
### 4. Agendamento de Mensagens
|
|
- Criar agendamentos via interface web
|
|
- Escolher data/hora específica
|
|
- Especificar livro ou "todos os livros"
|
|
|
|
### 5. Conteúdo Diário
|
|
- Geração automática de conteúdo diário
|
|
- Enviado às 8:00 todos os dias
|
|
|
|
## 📁 Estrutura do Projeto
|
|
|
|
```
|
|
espiritismo-rag-system/
|
|
├── backend/
|
|
│ ├── app/
|
|
│ │ ├── main.py # FastAPI com todas as rotas
|
|
│ │ ├── models.py # Pydantic models
|
|
│ │ ├── services/
|
|
│ │ │ ├── rag_service.py # RAGService (Qdrant + LLM)
|
|
│ │ │ ├── pdf_processor.py # PDFProcessor
|
|
│ │ │ └── bot_service.py # Telegram Bot
|
|
│ │ ├── utils/
|
|
│ │ │ ├── embeddings.py # EmbeddingService
|
|
│ │ │ └── schedule_manager.py # CRUD de agendamentos
|
|
│ │ ├── templates/
|
|
│ │ │ └── index.html # Interface web
|
|
│ │ └── tasks/
|
|
│ │ └── celery_tasks.py # Celery tasks
|
|
│ ├── scripts/
|
|
│ │ └── index_books.py # Script de indexação
|
|
│ ├── Dockerfile # Container backend
|
|
│ └── requirements.txt # Dependências Python
|
|
├── frontend/
|
|
│ └── static/
|
|
│ ├── css/style.css # Estilos
|
|
│ └── js/script.js # JavaScript funcional
|
|
├── docs/
|
|
│ └── superpowers/
|
|
│ ├── plans/
|
|
│ │ └── 2025-11-01-espiritismo-rag-system.md
|
|
│ └── specs/
|
|
│ └── 2025-11-01-espiritismo-rag-system-design.md
|
|
├── PDF/ # Livros PDF (6 livros)
|
|
├── docker-compose.yml # Orquestração de serviços
|
|
├── .env # Variáveis de ambiente
|
|
├── .env.example # Template de .env
|
|
├── BUILD.md # Instruções de build
|
|
├── README.md # Este arquivo
|
|
├── IMPLEMENTATION_COMPLETE.md # Resumo da implementação
|
|
└── LICENSE # MIT License
|
|
```
|
|
|
|
## 🔧 Pré-requisitos
|
|
|
|
- Docker e Docker Compose instalados
|
|
- ~5GB de espaço em disco
|
|
- 8GB de RAM (recomendado)
|
|
- CPU para inferência de modelo
|
|
|
|
## 📦 Instalação e Deploy
|
|
|
|
### 1. Clone o Repositório
|
|
|
|
```bash
|
|
git clone https://git.labexposed.com/lgcosta/espiritismo-rag-system.git
|
|
cd espiritismo-rag-system
|
|
```
|
|
|
|
### 2. Download do Modelo (Aprox. 2GB)
|
|
|
|
```bash
|
|
cd backend
|
|
mkdir -p models
|
|
|
|
# Baixe o modelo Llama 3.2 3B quantizado
|
|
wget -O llama-3.2-3b-instruct-q4_0.gguf "https://us.aws.cdn.hf.co/xet-bridge-us/6718a700b21019fade8d68ac/b472da725da9aaf0e050c885680a67f61fceb097eb4277b0cc1e0b94e3559345?user_id=public&xip=4ii5zzvItH8&X-Xet-Cas-Uid=public&response-content-disposition=attachment%3B+filename*%3DUTF-8%27%27llama-3.2-3b-instruct-q4_0.gguf%3B+filename%3D%22llama-3.2-3b-instruct-q4_0.gguf%22%3B&Expires=1793546619&Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cHM6Ly91cy5hd3MuY2RuLmhmLmNvL3hldC1icmlkZ2UtdXMvNjcxOGE3MDBiMjEwMTlmYWRlOGQ2OGFjL2I0NzJkYTcyNWRhOWFhZjBlMDUwYzg4NTY4MGE2N2Y2MWZjZWIwOTdlYjQyNzdiMGNjMWUwYjk0ZTM1NTkzNDVcXD91c2VyX2lkPXB1YmxpYyZ4aXA9NGlpNXp6dkl0SDgmWC1YZXQtQ2FzLVVpZD1wdWJsaWMmcmVzcG9uc2UtY29udGVudC1kaXNwb3NpdGlvbj1hdHRhY2htZW50JTNCK2ZpbGVuYW1lJTJBJTNEVVRGLTglMjclMjdsbGFtYS0zLjItM2ItaW5zdHJ1Y3QtcTRfMC5nZ3VmJTNCK2ZpbGVuYW1lJTNEJTIybGxhbWEtMy4yLTNiLWluc3RydWN0LXE0XzAuZ2d1ZiUyMiUzQiIsIkNvbmRpdGlvbiI6eyJEYXRlTGVzc1RoYW4iOnsiRXBvY2hUaW1lIjoxNzkzNTQ2NjE5fX19XX0_&Signature=MEUCIBdL2cMsOqav%7EbG9Q2mearSLUBdBtfCA3sOBE5GdbXUnAiEA7xWOea%7ETy0Jf%7EPgRYyx1S9bxvnSFoTBI%7ERadl-Nmd8E_&Key-Pair-Id=01KXEF4KZ1B6FV465MAWR4M21F&Hash-Algorithm=SHA256"
|
|
mv llama-3.2-3b-instruct-q4_0.gguf models/
|
|
|
|
# Ou use o GPT4All para baixar automaticamente
|
|
```
|
|
|
|
### 3. Configurar Variáveis de Ambiente
|
|
|
|
```bash
|
|
cp backend/.env.example .env
|
|
```
|
|
|
|
Edite o arquivo `.env`:
|
|
|
|
```env
|
|
GPT4ALL_MODEL=models/llama-3.2-3b-instruct-q4_0.gguf
|
|
QDRANT_URL=http://localhost:6333
|
|
TELEGRAM_BOT_TOKEN=seu_token_aqui
|
|
TELEGRAM_CHAT_ID=seu_chat_id_aqui
|
|
CELERY_BROKER_URL=redis://localhost:6379/0
|
|
CELERY_RESULT_BACKEND=redis://localhost:6379/0
|
|
UPLOAD_DIR=/app/uploads
|
|
INDEX_DIR=/app/index
|
|
```
|
|
|
|
**Para obter seu Telegram Bot Token:**
|
|
1. Chat com @BotFather no Telegram
|
|
2. Envie `/newbot` e siga as instruções
|
|
3. Copie o token
|
|
|
|
**Para obter seu Chat ID:**
|
|
1. Crie um bot com @BotFather
|
|
2. Envie `/start` para o bot
|
|
3. Use uma ferramenta como `curl "https://api.telegram.org/bot<token>/getUpdates"`
|
|
|
|
### 4. Build e Start dos Serviços
|
|
|
|
```bash
|
|
# Build das imagens Docker
|
|
docker-compose build
|
|
|
|
# Start de todos os serviços
|
|
docker-compose up -d
|
|
|
|
# Verificar status
|
|
docker-compose ps
|
|
```
|
|
|
|
### 5. Indexar os Livros
|
|
|
|
```bash
|
|
docker compose run --rm web python scripts/index_books.py
|
|
```
|
|
|
|
Isso irá:
|
|
- Carregar os 6 livros PDF da pasta `PDF/`
|
|
- Extrair texto e gerar chunks
|
|
- Criar embeddings com Sentence Transformers
|
|
- Salvar em Qdrant
|
|
|
|
### 6. Acessar os Serviços
|
|
|
|
- **Web Interface**: http://localhost:8000
|
|
- **API Docs**: http://localhost:8000/docs
|
|
- **Qdrant Dashboard**: http://localhost:6333/dashboard
|
|
|
|
## 📖 Uso
|
|
|
|
### Web Interface
|
|
|
|
1. Abra http://localhost:8000 no navegador
|
|
2. Digite uma pergunta sobre espiritismo
|
|
3. Receba resposta com fontes
|
|
4. Faça upload de novos PDFs
|
|
5. Crie agendamentos de mensagens
|
|
|
|
### Telegram Bot
|
|
|
|
1. Inicie o bot com `/start`
|
|
2. Use `/help` para ver comandos
|
|
3. Use `/status` para ver status
|
|
4. Use `/books` para listar livros
|
|
5. Pergunte qualquer coisa para receber respostas
|
|
|
|
### Agendamento de Mensagens
|
|
|
|
1. Acesse a interface web
|
|
2. Vá até "Agendar Mensagens"
|
|
3. Selecione data/hora
|
|
4. Escolha livro ou "Todos os livros"
|
|
5. Clique em "Adicionar Agendamento"
|
|
|
|
## 🔄 Agendamentos Automáticos
|
|
|
|
O sistema executa automaticamente:
|
|
|
|
- **A cada hora**: Envia mensagens agendadas
|
|
- **Todo dia às 8:00**: Gera conteúdo diário
|
|
|
|
## 🧪 Testando
|
|
|
|
### Testar Chat
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8000/api/chat \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"message": "Qual é o princípio fundamental do espiritismo?", "top_k": 3}'
|
|
```
|
|
|
|
### Testar Lista de Livros
|
|
|
|
```bash
|
|
curl http://localhost:8000/api/books
|
|
```
|
|
|
|
### Testar Upload de PDF
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8000/api/upload \
|
|
-F "file=@caminho/para/seu/livro.pdf"
|
|
```
|
|
|
|
## 📊 Monitoramento
|
|
|
|
### Ver Logs dos Serviços
|
|
|
|
```bash
|
|
# Todos os serviços
|
|
docker-compose logs -f
|
|
|
|
# Web service
|
|
docker-compose logs -f web
|
|
|
|
# Celery worker
|
|
docker-compose logs -f celery
|
|
|
|
# Celery beat
|
|
docker-compose logs -f celery-beat
|
|
|
|
# Qdrant
|
|
docker-compose logs -f qdrant
|
|
```
|
|
|
|
## 🛠️ Troubleshooting
|
|
|
|
### Problemas de Build
|
|
|
|
```bash
|
|
# Limpar cache e rebuild
|
|
docker-compose build --no-cache
|
|
docker-compose down
|
|
docker-compose up -d
|
|
```
|
|
|
|
### Qdrant Não Inicia
|
|
|
|
```bash
|
|
# Remover volume existente
|
|
docker volume rm espiritismo_qdrant_data
|
|
|
|
# Reiniciar
|
|
docker-compose up -d qdrant
|
|
```
|
|
|
|
### Out of Memory
|
|
|
|
```bash
|
|
# Reduzir workers do Celery
|
|
# Edite docker-compose.yml
|
|
celery:
|
|
command: celery -A app.tasks.celery_tasks worker --loglevel=info --concurrency=2
|
|
|
|
# Reiniciar
|
|
docker-compose restart celery
|
|
```
|
|
|
|
## 📈 Métricas
|
|
|
|
### Performance Estimada
|
|
|
|
- **Indexação de 6 livros**: ~5-10 minutos (CPU)
|
|
- **Tempo de resposta**: ~2-5 segundos por pergunta
|
|
- **Consumo de RAM**: ~4GB (com modelo carregado)
|
|
- **Espaço em disco**: ~5GB total
|
|
|
|
### Resources
|
|
|
|
- **Llama 3.2 3B q4_0**: ~2GB
|
|
- **Embeddings (384 dims)**: ~1GB
|
|
- **Qdrant index**: ~1GB
|
|
- **Livros PDF**: ~1GB
|
|
|
|
## 🤝 Contribuindo
|
|
|
|
Contribuições são bem-vindas! Sinta-se livre para:
|
|
- Reportar bugs
|
|
- Sugerir melhorias
|
|
- Enviar pull requests
|
|
- Adicionar novos livros
|
|
|
|
## 📄 Documentação
|
|
|
|
- **[BUILD.md](BUILD.md)** - Instruções detalhadas de build e deploy
|
|
- **[IMPLEMENTATION_COMPLETE.md](IMPLEMENTATION_COMPLETE.md)** - Relatório completo da implementação
|
|
- **[Design Document](docs/superpowers/specs/2025-11-01-espiritismo-rag-system-design.md)** - Design técnico detalhado
|
|
- **[Implementation Plan](docs/superpowers/plans/2025-11-01-espiritismo-rag-system.md)** - Plano de implementação
|
|
|
|
## 🔗 Links Úteis
|
|
|
|
- [FastAPI Documentation](https://fastapi.tiangolo.com/)
|
|
- [GPT4All Documentation](https://gpt4all.io/)
|
|
- [LangChain Documentation](https://python.langchain.com/)
|
|
- [Qdrant Documentation](https://qdrant.tech/documentation/)
|
|
|
|
## 📄 Licença
|
|
|
|
MIT License - Veja o arquivo [LICENSE](LICENSE) para detalhes.
|
|
|
|
---
|
|
|
|
**Versão**: 1.0.0
|
|
**Status**: ✅ Production Ready
|
|
**Data**: 2026-11-01
|