lgcosta
8934476331
- Documentação visão geral e stack tecnológica - Instruções de instalação e deploy - Funcionalidades detalhadas - Estrutura do projeto - Guia de uso (Web, Telegram, Agendamento) - Comandos de teste e monitoramento - Troubleshooting e escalabilidade - Links úteis e referências Versão 1.0.0 - Production Ready
419 lines
10 KiB
Markdown
419 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
|
|
```
|
|
|
|
## 🔧 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 https://huggingface.co/MaziyarPanahi/Llama-3.2-3B-Instruct-GGUF/resolve/main/llama-3.2-3b-instruct-q4_0.gguf
|
|
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 backend/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
|
|
- **Qdrant Dashboard**: http://localhost:6333/dashboard
|
|
- **Redis**: localhost:6379
|
|
|
|
## 📖 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
|
|
```
|
|
|
|
### Ver Status dos Containers
|
|
|
|
```bash
|
|
docker-compose ps
|
|
```
|
|
|
|
## 🛠️ Deploy em Produção
|
|
|
|
### Requisitos para Produção
|
|
|
|
- Servidor dedicado (recomendado 8GB+ RAM)
|
|
- Docker instalado
|
|
- Modelo Llama 3.2 3B baixado
|
|
- Credenciais de Telegram configuradas
|
|
|
|
### Deploy Padrão
|
|
|
|
```bash
|
|
# Build
|
|
docker-compose build
|
|
|
|
# Start
|
|
docker-compose up -d
|
|
|
|
# Indexar livros
|
|
docker-compose run --rm web python backend/scripts/index_books.py
|
|
```
|
|
|
|
### Configuração de Ambiente de Produção
|
|
|
|
Configure `.env` para produção:
|
|
|
|
```env
|
|
TELEGRAM_BOT_TOKEN=sua_token_producao
|
|
TELEGRAM_CHAT_ID=sua_chat_id
|
|
CELERY_BROKER_URL=redis://redis:6379/0
|
|
CELERY_RESULT_BACKEND=redis://redis:6379/0
|
|
```
|
|
|
|
### Escalabilidade
|
|
|
|
Para escalar, use:
|
|
- Proxy reverso (Nginx)
|
|
- Load balancer
|
|
- Mais instâncias do backend
|
|
- Cluster do Qdrant
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Problemas de Build
|
|
|
|
```bash
|
|
# Limpar cache e rebuild
|
|
docker-compose build --no-cache
|
|
|
|
# Ver logs do build
|
|
docker-compose logs web
|
|
```
|
|
|
|
### Qdrant Não Inicia
|
|
|
|
```bash
|
|
# Remover volume existente
|
|
docker volume rm espiritismo_qdrant_data
|
|
|
|
# Reiniciar
|
|
docker-compose up -d qdrant
|
|
```
|
|
|
|
### Out of Memory
|
|
|
|
Reduza os workers:
|
|
```bash
|
|
# Edit docker-compose.yml
|
|
celery:
|
|
command: celery -A app.tasks.celery_tasks worker --loglevel=info --concurrency=2
|
|
```
|
|
|
|
### Erros de Import
|
|
|
|
```bash
|
|
# Rebuild e clean
|
|
docker-compose down
|
|
docker-compose build --no-cache
|
|
docker-compose up -d
|
|
```
|
|
|
|
## 📈 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
|
|
|
|
## 📝 Licença
|
|
|
|
MIT License - Veja arquivo LICENSE para detalhes.
|
|
|
|
## 👥 Autores
|
|
|
|
Desenvolvido com ❤️ para a comunidade de espiritismo.
|
|
|
|
## 🤝 Contribuindo
|
|
|
|
Contribuições são bem-vindas! Sinta-se livre para:
|
|
- Reportar bugs
|
|
- Sugerir melhorias
|
|
- Enviar pull requests
|
|
- Adicionar novos livros
|
|
|
|
## 📄 Documentação Completa
|
|
|
|
Para documentação detalhada da implementação, veja:
|
|
|
|
- **Design Document**: `docs/superpowers/specs/2025-11-01-espiritismo-rag-system-design.md`
|
|
- **Implementation Plan**: `docs/superpowers/plans/2025-11-01-espiritismo-rag-system.md`
|
|
- **Task Reports**: `docs/superpowers/sdd/2025-11-01-espiritismo-rag-system/task-*.md`
|
|
|
|
## 🔗 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/)
|
|
- [Llama 3.2 Model](https://huggingface.co/meta-llama/Llama-3.2)
|
|
|
|
---
|
|
|
|
**Versão**: 1.0.0
|
|
**Status**: Production Ready ✅
|
|
**Última Atualização**: 2026-11-01
|