0 Fork 0

Files

T

lgcosta 7cb4ea0627 docs: Adicionar BUILD.md com instruções completas de build e deploy

- Pré-requisitos detalhados (hardware, software, acesso)
- Download do modelo com múltiplas opções
- Configuração de ambiente passo a passo
- Build do projeto com cache options
- Deploy com Docker Compose
- Indexação dos livros com monitoramento
- Uso da aplicação (web, telegram, agendamento)
- Monitoramento e métricas
- Troubleshooting completo
- Segurança e hardening
- Escalabilidade e performance tuning
- Checklist de deploy

Documentação de referência completa para desenvolvedores e operadores.

2026-11-01 10:49:54 -03:00

17 KiB

Raw Blame History

Build e Deployment Instructions

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

cp backend/.env.example .env

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

Abra o Telegram e procure por @BotFather
Envie /newbot
Siga as instruções:
- Dê um nome para o bot (ex: "EspiritismoBot")
- Dê um username único (ex: "espiritismo_bot")
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

Acesse a interface:
```
http://localhost:8000
```
Teste o Chat:
- Digite: "Qual é o princípio fundamental do espiritismo?"
- Clique em "Enviar"
- Receba resposta com fontes
Upload de PDF:
- Clique em "Upload PDF"
- Selecione arquivo PDF
- Clique em "Upload PDF"
- Confirme mensagem de sucesso
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

/start - Apresentação

/start

📚 Sistema RAG Espiritismo

Comandos disponíveis:
/start - Iniciar
/help - Ajuda
/status - Ver status
/books - Listar livros

/help - Lista de comandos

/help

📚 Sistema RAG Espiritismo

Comandos disponíveis:
/start - Iniciar
/help - Ajuda
/status - Ver status
/books - Listar livros

/status - Status do sistema

/status

📚 Status do Sistema RAG Espiritismo

Bot: Ativo
Chat ID: 123456789

Direcione uma pergunta sobre espiritismo para eu responder!

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

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

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

Usar Variáveis de Ambiente Seguras

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

Não Expor Portas Externas

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

Proteger Qdrant (se necessário)

qdrant:
  environment:
    - QDRANT_API_KEY=your_secret_key

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

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

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
});

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

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 ✅

17 KiB Raw Blame History