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.
959 lines
24 KiB
Markdown
959 lines
24 KiB
Markdown
# Build e Deployment Instructions
|
|
|
|
<<<<<<< HEAD
|
|
## Prerequisites
|
|
|
|
- Docker and Docker Compose installed
|
|
- ~5GB free disk space
|
|
- 8GB RAM minimum
|
|
- CPU for model inference
|
|
|
|
## Download the Model
|
|
|
|
Before building, download the Llama 3.2 3B quantized model:
|
|
|
|
```bash
|
|
# Download model (approximately 2GB)
|
|
cd backend
|
|
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"
|
|
|
|
# Place in models directory
|
|
mkdir -p models
|
|
mv llama-3.2-3b-instruct-q4_0.gguf models/
|
|
```
|
|
|
|
Alternatively, use GPT4All's built-in downloader when starting the service.
|
|
|
|
## Environment Setup
|
|
|
|
1. Copy the environment template:
|
|
=======
|
|
|
|
|
|
|
|
|
|
Instruções completas para build, deploy e uso do Sistema RAG Espiritismo.
|
|
|
|
## 📋 Conteúdo
|
|
|
|
- [Pré-requisitos](#pré-requisitos)
|
|
- [Download do Modelo](#download-do-modelo)
|
|
- [Configuração de Ambiente](#configuração-de-ambiente)
|
|
- [Build do Projeto](#build-do-projeto)
|
|
- [Deploy com Docker Compose](#deploy-com-docker-compose)
|
|
- [Indexação dos Livros](#indexação-dos-livros)
|
|
- [Uso da Aplicação](#uso-da-aplicação)
|
|
- [Monitoramento](#monitoramento)
|
|
- [Troubleshooting](#troubleshooting)
|
|
- [Segurança](#segurança)
|
|
- [Escalabilidade](#escalabilidade)
|
|
|
|
## 🔧 Pré-requisitos
|
|
|
|
### Hardware
|
|
|
|
- **CPU**: 4+ cores (recomendado)
|
|
- **RAM**: 8GB mínima (12GB recomendado)
|
|
- **Disco**: 5GB disponíveis
|
|
- **Rede**: Conexão estável para downloads
|
|
|
|
### Software
|
|
|
|
- **Docker**: Versão 20.10+ (https://docs.docker.com/get-docker/)
|
|
- **Docker Compose**: Versão 2.0+ (https://docs.docker.com/compose/install/)
|
|
- **Git**: Versão 2.0+ (https://git-scm.com/downloads)
|
|
- **Terminal**: bash/zsh compatível
|
|
|
|
### Acesso à Internet
|
|
|
|
- Para download do modelo (~2GB)
|
|
- Para clones do repositório
|
|
- Para pull de imagens Docker
|
|
|
|
## 📥 Download do Modelo
|
|
|
|
### Opção 1: Manual Download
|
|
|
|
```bash
|
|
cd backend
|
|
mkdir -p models
|
|
|
|
# Baixe o modelo Llama 3.2 3B quantizado (4-bit)
|
|
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"
|
|
|
|
# Valide o tamanho (deve ser ~2GB)
|
|
ls -lh models/llama-3.2-3b-instruct-q4_0.gguf
|
|
|
|
# Mova para o diretório correto
|
|
mv llama-3.2-3b-instruct-q4_0.gguf models/
|
|
```
|
|
|
|
### Opção 2: GPT4All Auto-Download
|
|
|
|
```bash
|
|
cd backend
|
|
|
|
# Inicie o serviço web primeiro
|
|
docker-compose run --rm web
|
|
|
|
# Na interface web, o GPT4All vai baixar o modelo automaticamente
|
|
# ou use a mesma URL assinada do CDN (Opção 1)
|
|
```
|
|
|
|
### Opção 3: Script Automático
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# download_model.sh
|
|
|
|
cd backend
|
|
mkdir -p models
|
|
|
|
MODEL_URL="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"
|
|
|
|
if [ ! -f "models/llama-3.2-3b-instruct-q4_0.gguf" ]; then
|
|
echo "Baixando modelo Llama 3.2 3B..."
|
|
wget -O models/llama-3.2-3b-instruct-q4_0.gguf "$MODEL_URL"
|
|
echo "Download concluído!"
|
|
else
|
|
echo "Modelo já existe!"
|
|
fi
|
|
```
|
|
|
|
### Validação do Download
|
|
|
|
```bash
|
|
# Verifique o tamanho
|
|
ls -lh backend/models/llama-3.2-3b-instruct-q4_0.gguf
|
|
|
|
# Esperado: ~2.0 GB
|
|
|
|
# Verifique o hash (opcional)
|
|
sha256sum backend/models/llama-3.2-3b-instruct-q4_0.gguf
|
|
```
|
|
|
|
## ⚙️ Configuração de Ambiente
|
|
|
|
### 1. Clone o Repositório
|
|
|
|
```bash
|
|
git clone https://git.labexposed.com/lgcosta/espiritismo-rag-system.git
|
|
cd espiritismo-rag-system
|
|
```
|
|
|
|
### 2. Copie o Template de Variáveis de Ambiente
|
|
|
|
>>>>>>> 50ae4db41723d2c6ea63799065316f1ae27bfb03
|
|
```bash
|
|
cp backend/.env.example .env
|
|
```
|
|
|
|
<<<<<<< HEAD
|
|
2. Edit `.env` and set your Telegram credentials:
|
|
```env
|
|
TELEGRAM_BOT_TOKEN=your_bot_token_here
|
|
TELEGRAM_CHAT_ID=your_chat_id_here
|
|
```
|
|
|
|
To get your chat ID, create a bot with @BotFather on Telegram and send `/start`.
|
|
|
|
## Build and Start
|
|
|
|
1. Build the containers:
|
|
```bash
|
|
docker-compose build
|
|
```
|
|
|
|
2. Start all services:
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
## Index the Books
|
|
|
|
After starting the services, index the 6 existing books:
|
|
|
|
```bash
|
|
docker compose run --rm web python scripts/index_books.py
|
|
```
|
|
|
|
This will:
|
|
- Load PDFs from the `PDF/` directory
|
|
- Extract text chunks
|
|
- Generate embeddings
|
|
- Store in Qdrant
|
|
|
|
## Access the Services
|
|
|
|
- **Web Interface**: http://localhost:8000
|
|
- **Qdrant API**: http://localhost:6333/dashboard
|
|
- **Redis**: localhost:6379
|
|
|
|
## Create a Telegram Bot
|
|
|
|
1. Chat with @BotFather on Telegram
|
|
2. Send `/newbot` and follow instructions
|
|
3. Copy the bot token to `.env`
|
|
|
|
## Schedule Messages
|
|
|
|
1. Open the web interface: http://localhost:8000
|
|
2. Click on "Agendar Mensagens"
|
|
3. Select date/time and optionally a specific book
|
|
4. Click "Adicionar Agendamento"
|
|
|
|
## Stop the Services
|
|
|
|
```bash
|
|
docker-compose down
|
|
```
|
|
|
|
## View Logs
|
|
|
|
```bash
|
|
# All services
|
|
docker-compose logs -f
|
|
|
|
# Specific service
|
|
docker-compose logs -f web
|
|
docker-compose logs -f celery
|
|
docker-compose logs -f celery-beat
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Model Download Issues
|
|
|
|
If the model download fails:
|
|
```bash
|
|
# Download manually (mesma URL assinada da seção Download do Modelo)
|
|
cd backend
|
|
mkdir -p models
|
|
wget -O models/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"
|
|
```
|
|
|
|
### Qdrant Not Starting
|
|
|
|
```bash
|
|
# Remove existing volume
|
|
docker volume rm espiritismo_qdrant_data
|
|
# Restart
|
|
docker-compose up -d qdrant
|
|
```
|
|
|
|
### Out of Memory
|
|
|
|
Reduce the number of workers or use a smaller model.
|
|
|
|
### Import Errors
|
|
|
|
Rebuild with:
|
|
```bash
|
|
docker-compose build --no-cache web
|
|
docker-compose up -d web
|
|
```
|
|
=======
|
|
### 3. Configure as Variáveis
|
|
|
|
Edite o arquivo `.env` com suas configurações:
|
|
|
|
```env
|
|
# === Configurações do Modelo ===
|
|
GPT4ALL_MODEL=models/llama-3.2-3b-instruct-q4_0.gguf
|
|
MODEL_PATH=/app/models/llama-3.2-3b-instruct-q4_0.gguf
|
|
|
|
# === Configurações do Qdrant ===
|
|
QDRANT_URL=http://qdrant:6333
|
|
QDRANT_API_KEY= # Opcional, deixe vazio se não usar autenticação
|
|
|
|
# === Configurações do Telegram Bot ===
|
|
TELEGRAM_BOT_TOKEN=sua_token_aqui
|
|
TELEGRAM_CHAT_ID=sua_chat_id_aqui
|
|
|
|
# === Configurações do Celery ===
|
|
CELERY_BROKER_URL=redis://redis:6379/0
|
|
CELERY_RESULT_BACKEND=redis://6379/0
|
|
|
|
# === Caminhos ===
|
|
UPLOAD_DIR=/app/uploads
|
|
INDEX_DIR=/app/index
|
|
SCHEDULES_PATH=/app/schedules.json
|
|
|
|
# === Configurações de Debug ===
|
|
DEBUG=false
|
|
LOG_LEVEL=INFO
|
|
```
|
|
|
|
### 4. Como Obter Telegram Bot Token
|
|
|
|
#### Criar o Bot
|
|
|
|
1. Abra o Telegram e procure por @BotFather
|
|
2. Envie `/newbot`
|
|
3. Siga as instruções:
|
|
- Dê um nome para o bot (ex: "EspiritismoBot")
|
|
- Dê um username único (ex: "espiritismo_bot")
|
|
4. Copie o token fornecido
|
|
|
|
#### Obter seu Chat ID
|
|
|
|
```bash
|
|
# Método 1: Usando curl
|
|
curl "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/getUpdates"
|
|
|
|
# Procure pela chave "id" no resultado
|
|
# Exemplo: "id": 123456789
|
|
|
|
# Método 2: Usando uma URL no navegador
|
|
https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/getUpdates
|
|
```
|
|
|
|
### 5. Validar Configuração
|
|
|
|
```bash
|
|
# Verifique se .env existe e não está vazio
|
|
if [ -s .env ]; then
|
|
echo "✅ Configuração de ambiente válida"
|
|
else
|
|
echo "❌ .env está vazio ou não existe"
|
|
fi
|
|
```
|
|
|
|
## 🏗️ Build do Projeto
|
|
|
|
### 1. Limpar Cache Anterior (Opcional)
|
|
|
|
```bash
|
|
# Remove imagens existentes
|
|
docker-compose down
|
|
docker system prune -a -f
|
|
|
|
# Remove volumes (apenas se necessário)
|
|
docker volume rm espiritismo_qdrant_data 2>/dev/null || true
|
|
docker volume rm espiritismo_redis_data 2>/dev/null || true
|
|
```
|
|
|
|
### 2. Build das Imagens Docker
|
|
|
|
```bash
|
|
# Build básico
|
|
docker-compose build
|
|
|
|
# Build completo com cache
|
|
docker-compose build --no-cache
|
|
|
|
# Build com progresso detalhado
|
|
docker-compose build --progress=plain
|
|
```
|
|
|
|
### 3. Verificar Imagens Buildadas
|
|
|
|
```bash
|
|
# Listar imagens
|
|
docker images | grep espiritismo
|
|
|
|
# Verificar tamanho
|
|
docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}" | grep espiritismo
|
|
```
|
|
|
|
**Esperado:**
|
|
- `lgcosta/espiritismo-web:latest` (~1.2GB)
|
|
- `lgcosta/espiritismo-celery:latest` (~1.2GB)
|
|
|
|
## 🚀 Deploy com Docker Compose
|
|
|
|
### 1. Iniciar Todos os Serviços
|
|
|
|
```bash
|
|
# Start em background
|
|
docker-compose up -d
|
|
|
|
# Start com logs
|
|
docker-compose up
|
|
```
|
|
|
|
### 2. Verificar Status dos Serviços
|
|
|
|
```bash
|
|
# Lista todos os containers
|
|
docker-compose ps
|
|
|
|
# Status específico
|
|
docker-compose ps qdrant
|
|
docker-compose ps redis
|
|
docker-compose ps web
|
|
```
|
|
|
|
**Esperado:**
|
|
```
|
|
NAME STATUS
|
|
espiritismo-qdrant Up 10 seconds
|
|
espiritismo-redis Up 10 seconds
|
|
espiritismo-web Up 10 seconds
|
|
espiritismo-celery Up 10 seconds
|
|
espiritismo-celery-beat Up 10 seconds
|
|
```
|
|
|
|
### 3. Ver Logs
|
|
|
|
```bash
|
|
# Logs de todos os serviços
|
|
docker-compose logs -f
|
|
|
|
# Logs do web service
|
|
docker-compose logs -f web
|
|
|
|
# Logs do celery
|
|
docker-compose logs -f celery
|
|
|
|
# Logs do celery beat
|
|
docker-compose logs -f celery-beat
|
|
|
|
# Logs do qdrant
|
|
docker-compose logs -f qdrant
|
|
|
|
# Últimas 100 linhas
|
|
docker-compose logs --tail=100
|
|
```
|
|
|
|
### 4. Acessar os Serviços
|
|
|
|
- **Web Interface**: http://localhost:8000
|
|
- **Qdrant Dashboard**: http://localhost:6333/dashboard
|
|
- **API Documentation**: http://localhost:8000/docs
|
|
|
|
## 📚 Indexação dos Livros
|
|
|
|
### 1. Listar Livros Disponíveis
|
|
|
|
```bash
|
|
# Lista arquivos na pasta PDF
|
|
ls -lh PDF/
|
|
|
|
# Deve mostrar:
|
|
# A_Genese-Guillon.pdf
|
|
# Livro_dos_Espiritos-Guillon.pdf
|
|
# Livro_dos_Mediuns-Guillon.pdf
|
|
# O_Ceu_e_o_Inferno-Manuel_Quintao.pdf
|
|
# O_Evangelho_Segundo_o_Espiritismo-Guillon.pdf
|
|
# O_que_e_o_Espiritismo.pdf
|
|
```
|
|
|
|
### 2. Executar Script de Indexação
|
|
|
|
```bash
|
|
# Método 1: Via container
|
|
docker compose run --rm web python scripts/index_books.py
|
|
|
|
# Método 2: Com limite de logs
|
|
docker compose run --rm web python scripts/index_books.py 2>&1 | tee index.log
|
|
```
|
|
|
|
### 3. Monitorar Progresso
|
|
|
|
```bash
|
|
# Processando logs
|
|
docker-compose logs -f web
|
|
|
|
# Esperado:
|
|
# Found 6 books
|
|
# Processing: A_Genese-Guillon.pdf
|
|
# Saved 120 chunks to /app/index/A_Genese-Guillon.json
|
|
# Processing: Livro_dos_Espiritos-Guillon.pdf
|
|
# ...
|
|
# Indexing complete!
|
|
```
|
|
|
|
### 4. Verificar Indexação
|
|
|
|
```bash
|
|
# Lista de chunks indexados
|
|
ls -lh backend/index/
|
|
|
|
# Conteúdo de um chunk JSON (exemplo)
|
|
cat backend/index/A_Genese-Guillon.json | head -20
|
|
|
|
# Verificar em Qdrant
|
|
curl http://localhost:6333/collections/espiritismo_books
|
|
```
|
|
|
|
### 5. Reindexar (Se Necessário)
|
|
|
|
```bash
|
|
# Limpar indexação anterior
|
|
rm -rf backend/index/*
|
|
rm backend/schedules.json
|
|
|
|
# Reindexar
|
|
docker compose run --rm web python scripts/index_books.py
|
|
```
|
|
|
|
## 🎮 Uso da Aplicação
|
|
|
|
### Web Interface
|
|
|
|
1. **Acesse a interface:**
|
|
```
|
|
http://localhost:8000
|
|
```
|
|
|
|
2. **Teste o Chat:**
|
|
- Digite: "Qual é o princípio fundamental do espiritismo?"
|
|
- Clique em "Enviar"
|
|
- Receba resposta com fontes
|
|
|
|
3. **Upload de PDF:**
|
|
- Clique em "Upload PDF"
|
|
- Selecione arquivo PDF
|
|
- Clique em "Upload PDF"
|
|
- Confirme mensagem de sucesso
|
|
|
|
4. **Agendamento:**
|
|
- Vá até "Agendar Mensagens"
|
|
- Selecione data/hora
|
|
- Escolha livro ou "Todos os livros"
|
|
- Clique em "Adicionar Agendamento"
|
|
- Confirme que apareceu na lista
|
|
|
|
### Bot Telegram
|
|
|
|
#### Configuração
|
|
|
|
```bash
|
|
# Verifique se bot está ativo
|
|
docker-compose logs celery | grep -i "polling\|started"
|
|
|
|
# Deve ver:
|
|
# Starting Telegram bot polling...
|
|
```
|
|
|
|
#### Comandos Disponíveis
|
|
|
|
1. **/start** - Apresentação
|
|
```
|
|
/start
|
|
|
|
📚 Sistema RAG Espiritismo
|
|
|
|
Comandos disponíveis:
|
|
/start - Iniciar
|
|
/help - Ajuda
|
|
/status - Ver status
|
|
/books - Listar livros
|
|
```
|
|
|
|
2. **/help** - Lista de comandos
|
|
```
|
|
/help
|
|
|
|
📚 Sistema RAG Espiritismo
|
|
|
|
Comandos disponíveis:
|
|
/start - Iniciar
|
|
/help - Ajuda
|
|
/status - Ver status
|
|
/books - Listar livros
|
|
```
|
|
|
|
3. **/status** - Status do sistema
|
|
```
|
|
/status
|
|
|
|
📚 Status do Sistema RAG Espiritismo
|
|
|
|
Bot: Ativo
|
|
Chat ID: 123456789
|
|
|
|
Direcione uma pergunta sobre espiritismo para eu responder!
|
|
```
|
|
|
|
4. **/books** - Lista de livros
|
|
```
|
|
/books
|
|
|
|
📚 Livros disponíveis:
|
|
|
|
• A Gênese (Allan Kardec)
|
|
• Livro dos Espíritos (Allan Kardec)
|
|
• Livro dos Médiums (Allan Kardec)
|
|
• O Céu e o Inferno (Manuel Quintão)
|
|
• O Evangelho Segundo o Espiritismo (Allan Kardec)
|
|
• O Que é o Espiritismo (Allan Kardec)
|
|
```
|
|
|
|
5. **Pergunta** - Responder perguntas
|
|
```
|
|
Qual é a doutrina da reencarnação?
|
|
|
|
🔍 Processando sua pergunta...
|
|
|
|
✅ Resposta:
|
|
|
|
A reencarnação é um dos princípios fundamentais do espiritismo...
|
|
|
|
📚 Fontes:
|
|
• A Gênese (chunk 45)
|
|
• Livro dos Espíritos (chunk 78)
|
|
• ...
|
|
```
|
|
|
|
### Agendamento de Mensagens
|
|
|
|
1. **Criar Agendamento**
|
|
```
|
|
Data/Hora: 2026-11-02T10:00
|
|
Livro: Livro dos Espíritos
|
|
```
|
|
- Mensagem enviada automaticamente às 10:00
|
|
- Contém resumo do livro escolhido
|
|
|
|
2. **Agendar para Todos os Livros**
|
|
```
|
|
Data/Hora: 2026-11-02T14:00
|
|
Livro: Todos os livros
|
|
```
|
|
- Mensagem enviada às 14:00 com conteúdo de todos os livros
|
|
|
|
3. **Gerenciar Agendamentos**
|
|
- Ver lista de agendamentos na web
|
|
- Editar data/hora
|
|
- Excluir agendamentos
|
|
- Status de execução
|
|
|
|
## 📊 Monitoramento
|
|
|
|
### Métricas do Sistema
|
|
|
|
```bash
|
|
# CPU Usage
|
|
docker stats
|
|
|
|
# Memory Usage
|
|
docker stats --no-stream
|
|
|
|
# Container Status
|
|
docker-compose ps -a
|
|
```
|
|
|
|
### Logs por Serviço
|
|
|
|
```bash
|
|
# Logs web (últimos 50 linhas)
|
|
docker-compose logs --tail=50 web
|
|
|
|
# Logs celery (últimos 50 linhas)
|
|
docker-compose logs --tail=50 celery
|
|
|
|
# Logs celery beat (últimos 50 linhas)
|
|
docker-compose logs --tail=50 celery-beat
|
|
|
|
# Buscar logs específicos
|
|
docker-compose logs | grep "ERROR"
|
|
docker-compose logs | grep "WARNING"
|
|
docker-compose logs | grep "INFO" | grep "index"
|
|
```
|
|
|
|
### Health Checks
|
|
|
|
```bash
|
|
# Web API health
|
|
curl http://localhost:8000/docs
|
|
|
|
# Qdrant health
|
|
curl http://localhost:6333/collections/espiritismo_books
|
|
|
|
# Redis ping
|
|
docker-compose exec redis redis-cli ping
|
|
# Resposta: PONG
|
|
```
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Problemas Comuns
|
|
|
|
#### 1. Container não inicia
|
|
|
|
```bash
|
|
# Ver logs
|
|
docker-compose logs web
|
|
|
|
# Possível solução:
|
|
# Limpar e rebuild
|
|
docker-compose down
|
|
docker-compose build --no-cache
|
|
docker-compose up -d
|
|
```
|
|
|
|
#### 2. Out of Memory
|
|
|
|
```bash
|
|
# Ver uso de memória
|
|
docker stats
|
|
|
|
# Reduzir workers
|
|
# Edite docker-compose.yml
|
|
celery:
|
|
command: celery -A app.tasks.celery_tasks worker --loglevel=info --concurrency=2
|
|
|
|
# Restart
|
|
docker-compose restart celery
|
|
```
|
|
|
|
#### 3. Qdrant não conecta
|
|
|
|
```bash
|
|
# Verificar status do Qdrant
|
|
docker-compose ps qdrant
|
|
|
|
# Ver logs
|
|
docker-compose logs qdrant
|
|
|
|
# Reiniciar
|
|
docker-compose restart qdrant
|
|
```
|
|
|
|
#### 4. Redis não conecta
|
|
|
|
```bash
|
|
# Verificar status do Redis
|
|
docker-compose ps redis
|
|
|
|
# Ver logs
|
|
docker-compose logs redis
|
|
|
|
# Reiniciar
|
|
docker-compose restart redis
|
|
```
|
|
|
|
#### 5. Erro no Model Loading
|
|
|
|
```bash
|
|
# Verificar se modelo existe
|
|
ls -lh backend/models/
|
|
|
|
# Baixar novamente
|
|
cd backend
|
|
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"
|
|
|
|
# Reiniciar containers
|
|
docker-compose down
|
|
docker-compose up -d
|
|
```
|
|
|
|
#### 6. Indexação falha
|
|
|
|
```bash
|
|
# Verificar arquivos PDF
|
|
ls -lh PDF/
|
|
|
|
# Verificar permissões
|
|
chmod -R 755 PDF/
|
|
|
|
# Reindexar
|
|
docker compose run --rm web python scripts/index_books.py 2>&1 | tee reindex.log
|
|
```
|
|
|
|
### Comandos de Diagnóstico
|
|
|
|
```bash
|
|
# Lista todos os containers
|
|
docker ps -a
|
|
|
|
# Ver detalhes de um container
|
|
docker inspect espiritismo-web
|
|
|
|
# Ver redes
|
|
docker network ls
|
|
docker network inspect espiritismo_default
|
|
|
|
# Ver volumes
|
|
docker volume ls
|
|
docker volume inspect espiritismo_qdrant_data
|
|
docker volume inspect espiritismo_redis_data
|
|
```
|
|
|
|
## 🔒 Segurança
|
|
|
|
### Hardening do Sistema
|
|
|
|
1. **Usar Variáveis de Ambiente Seguras**
|
|
```bash
|
|
# Sempre use .env local para credenciais
|
|
cp .env.example .env
|
|
chmod 600 .env # Apenas dono pode ler
|
|
```
|
|
|
|
2. **Não Expor Portas Externas**
|
|
```yaml
|
|
# docker-compose.yml
|
|
web:
|
|
ports:
|
|
- "127.0.0.1:8000:8000" # Apenas local
|
|
```
|
|
|
|
3. **Proteger Qdrant (se necessário)**
|
|
```yaml
|
|
qdrant:
|
|
environment:
|
|
- QDRANT_API_KEY=your_secret_key
|
|
```
|
|
|
|
4. **Atualizar Dependências Regularmente**
|
|
```bash
|
|
# Verificar vulnerabilidades
|
|
docker-compose exec web pip list --outdated
|
|
```
|
|
|
|
### Backups
|
|
|
|
```bash
|
|
# Backup de schedules
|
|
cp backend/schedules.json backend/schedules.json.backup
|
|
|
|
# Backup de index
|
|
tar -czf index_backup.tar.gz backend/index/
|
|
|
|
# Backup de uploads
|
|
tar -czf uploads_backup.tar.gz PDF/
|
|
```
|
|
|
|
## 📈 Escalabilidade
|
|
|
|
### Escalar para Múltiplas Instâncias
|
|
|
|
```yaml
|
|
# docker-compose.yml
|
|
web:
|
|
deploy:
|
|
replicas: 3
|
|
resources:
|
|
limits:
|
|
cpus: '2'
|
|
memory: 4G
|
|
```
|
|
|
|
### Load Balancing
|
|
|
|
```bash
|
|
# Usar Nginx como proxy
|
|
server {
|
|
listen 80;
|
|
server_name seu-dominio.com;
|
|
|
|
location / {
|
|
proxy_pass http://web:8000;
|
|
proxy_set_header Host $host;
|
|
}
|
|
}
|
|
```
|
|
|
|
### Cluster do Qdrant
|
|
|
|
```yaml
|
|
# Qdrant cluster
|
|
qdrant:
|
|
command: >
|
|
qdrant
|
|
--host 0.0.0.0
|
|
--port 6333
|
|
--storage_path /qdrant/storage
|
|
--disk_enabled
|
|
```
|
|
|
|
## 📝 Checklist de Deploy
|
|
|
|
### Pré-deploy Checklist
|
|
|
|
- [ ] Docker e Docker Compose instalados
|
|
- [ ] Modelo Llama 3.2 3B baixado
|
|
- [ ] Token do Telegram configurado
|
|
- [ ] Chat ID do Telegram configurado
|
|
- [ ] .env criado e configurado
|
|
- [ ] Repositório clonado
|
|
- [ ] Código versionado
|
|
|
|
### Deploy Checklist
|
|
|
|
- [ ] Docker images buildadas
|
|
- [ ] Todos os containers iniciados
|
|
- [ ] Container status "Up"
|
|
- [ ] Logs sem erros críticos
|
|
- [ ] Web API acessível em http://localhost:8000
|
|
- [ ] Qdrant acessível em http://localhost:6333/dashboard
|
|
- [ ] Indexação dos livros concluída
|
|
- [ ] Teste de chat realizado
|
|
- [ ] Teste do bot no Telegram realizado
|
|
- [ ] Agendamentos criados e testados
|
|
|
|
### Pós-deploy Checklist
|
|
|
|
- [ ] Monitoramento configurado
|
|
- [ ] Backups automáticos configurados
|
|
- [ ] Logs em produção configurados
|
|
- [ ] Alertas configurados
|
|
- [ ] Documentação atualizada
|
|
- [ ] Equipe treinada
|
|
|
|
## 🎯 Performance Tuning
|
|
|
|
### Otimizações Recomendadas
|
|
|
|
1. **Aumentar chunk_size** (em backend/services/pdf_processor.py):
|
|
```python
|
|
self.text_splitter = RecursiveCharacterTextSplitter(
|
|
chunk_size=1000, # De 500 para 1000
|
|
chunk_overlap=100, # De 50 para 100
|
|
length_function=len,
|
|
)
|
|
```
|
|
|
|
2. **Aumentar top_k** (em frontend/static/js/script.js):
|
|
```javascript
|
|
const result = await fetch(`${API_BASE}/chat`, {
|
|
method: 'POST',
|
|
headers: { 'Content-Type': 'application/json' },
|
|
body: JSON.stringify({ message, top_k: 5 }), // De 3 para 5
|
|
});
|
|
```
|
|
|
|
3. **Aumentar workers do Celery** (em docker-compose.yml):
|
|
```yaml
|
|
celery:
|
|
command: celery -A app.tasks.celery_tasks worker --loglevel=info --concurrency=4
|
|
```
|
|
|
|
### Monitoramento de Performance
|
|
|
|
```bash
|
|
# Métricas em tempo real
|
|
docker stats --no-stream
|
|
|
|
# CPU e memória por container
|
|
docker stats espiritismo-web
|
|
|
|
# Verificar se há gargalos
|
|
docker-compose logs | grep "slow\|timeout"
|
|
```
|
|
|
|
## 📞 Suporte
|
|
|
|
### Recursos
|
|
|
|
- [GitHub Issues](https://git.labexposed.com/lgcosta/espiritismo-rag-system/issues)
|
|
- [Documentação](README.md)
|
|
- [BUILD.md](BUILD.md)
|
|
- [Design Specs](docs/superpowers/specs/2025-11-01-espiritismo-rag-system-design.md)
|
|
|
|
### Canais de Comunicação
|
|
|
|
- Telegram: @seu_bot
|
|
- Email: suporte@exemplo.com
|
|
- Issues: https://git.labexposed.com/lgcosta/espiritismo-rag-system/issues
|
|
|
|
---
|
|
|
|
**Versão**: 1.0.0
|
|
**Última Atualização**: 2026-11-01
|
|
**Status**: Production Ready ✅
|
|
>>>>>>> 50ae4db41723d2c6ea63799065316f1ae27bfb03
|