espiritismo-rag-system/BUILD.md

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:

# Download model (approximately 2GB)
cd backend
wget https://huggingface.co/MaziyarPanahi/Llama-3.2-3B-Instruct-GGUF/resolve/main/llama-3.2-3b-instruct-q4_0.gguf

# 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
• Download do Modelo
• Configuração de Ambiente
• Build do Projeto
• Deploy com Docker Compose
• Indexação dos Livros
• Uso da Aplicação
• Monitoramento
• Troubleshooting
• Segurança
• 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

cd backend
mkdir -p models

# Baixe o modelo Llama 3.2 3B quantizado (4-bit)
wget https://huggingface.co/MaziyarPanahi/Llama-3.2-3B-Instruct-GGUF/resolve/main/llama-3.2-3b-instruct-q4_0.gguf

# 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

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: curl -O https://gpt4all.io/models/Llama-3-2-3B-Instruct-GGUF-Q4_0.gguf

Opção 3: Script Automático

#!/bin/bash
# download_model.sh

cd backend
mkdir -p models

MODEL_URL="https://huggingface.co/MaziyarPanahi/Llama-3.2-3B-Instruct-GGUF/resolve/main/llama-3.2-3b-instruct-q4_0.gguf"

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

# 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

git clone https://git.labexposed.com/lgcosta/espiritismo-rag-system.git
cd espiritismo-rag-system

2. Copie o Template de Variáveis de Ambiente

50ae4db417

cp backend/.env.example .env

<<<<<<< HEAD 2. Edit .env and set your Telegram credentials:

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:

docker-compose build

2. Start all services:

docker-compose up -d

Index the Books

After starting the services, index the 6 existing books:

docker-compose run --rm web python backend/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

docker-compose down

View Logs

# 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:

# Download manually
cd backend/models
wget <model-url>

Qdrant Not Starting

# 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:

docker-compose build --no-cache web
docker-compose up -d web

=======

3. Configure as Variáveis

Edite o arquivo .env com suas configurações:

# === 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

# 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

# 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)

# 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

# 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

# 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

# Start em background
docker-compose up -d

# Start com logs
docker-compose up

2. Verificar Status dos Serviços

# 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

# 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

# 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

# Método 1: Via container
docker-compose run --rm web python backend/scripts/index_books.py

# Método 2: Com limite de logs
docker-compose run --rm web python backend/scripts/index_books.py 2>&1 | tee index.log

3. Monitorar Progresso

# 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

# 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)

# Limpar indexação anterior
rm -rf backend/index/*
rm backend/schedules.json

# Reindexar
docker-compose run --rm web python backend/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

# 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

# CPU Usage
docker stats

# Memory Usage
docker stats --no-stream

# Container Status
docker-compose ps -a

Logs por Serviço

# 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

# 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

# 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

# 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

# Verificar status do Qdrant
docker-compose ps qdrant

# Ver logs
docker-compose logs qdrant

# Reiniciar
docker-compose restart qdrant

4. Redis não conecta

# Verificar status do Redis
docker-compose ps redis

# Ver logs
docker-compose logs redis

# Reiniciar
docker-compose restart redis

5. Erro no Model Loading

# Verificar se modelo existe
ls -lh backend/models/

# Baixar novamente
cd backend
wget https://huggingface.co/MaziyarPanahi/Llama-3.2-3B-Instruct-GGUF/resolve/main/llama-3.2-3b-instruct-q4_0.gguf

# Reiniciar containers
docker-compose down
docker-compose up -d

6. Indexação falha

# Verificar arquivos PDF
ls -lh PDF/

# Verificar permissões
chmod -R 755 PDF/

# Reindexar
docker-compose run --rm web python backend/scripts/index_books.py 2>&1 | tee reindex.log

Comandos de Diagnóstico

# 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

   # Sempre use .env local para credenciais
   cp .env.example .env
   chmod 600 .env  # Apenas dono pode ler
   

2. Não Expor Portas Externas

   # docker-compose.yml
   web:
     ports:
       - "127.0.0.1:8000:8000"  # Apenas local
   

3. Proteger Qdrant (se necessário)

   qdrant:
     environment:
       - QDRANT_API_KEY=your_secret_key
   

4. Atualizar Dependências Regularmente

   # Verificar vulnerabilidades
   docker-compose exec web pip list --outdated
   

Backups

# 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

# docker-compose.yml
web:
  deploy:
    replicas: 3
    resources:
      limits:
        cpus: '2'
        memory: 4G

Load Balancing

# 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

# 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):

   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):

   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):

   celery:
     command: celery -A app.tasks.celery_tasks worker --loglevel=info --concurrency=4
   

Monitoramento de Performance

# 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
• Documentação
• BUILD.md
• Design Specs

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 ✅

50ae4db417