From 7cb4ea0627a7736718e4e4a434d5cb3d1f3a05b8 Mon Sep 17 00:00:00 2001 From: Luiz Gustavo Costa Date: Sun, 1 Nov 2026 10:49:54 -0300 Subject: [PATCH] =?UTF-8?q?docs:=20Adicionar=20BUILD.md=20com=20instru?= =?UTF-8?q?=C3=A7=C3=B5es=20completas=20de=20build=20e=20deploy?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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. --- BUILD.md | 823 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 823 insertions(+) create mode 100644 BUILD.md diff --git a/BUILD.md b/BUILD.md new file mode 100644 index 0000000..a9ff335 --- /dev/null +++ b/BUILD.md @@ -0,0 +1,823 @@ +# Build e Deployment Instructions + +![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg) +![Python](https://img.shields.io/badge/Python-3.11-blue.svg) +![License](https://img.shields.io/badge/License-MIT-green.svg) + +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 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 + +```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: curl -O https://gpt4all.io/models/Llama-3-2-3B-Instruct-GGUF-Q4_0.gguf +``` + +### Opção 3: Script Automático + +```bash +#!/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 + +```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 + +```bash +cp backend/.env.example .env +``` + +### 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/getUpdates" + +# Procure pela chave "id" no resultado +# Exemplo: "id": 123456789 + +# Método 2: Usando uma URL no navegador +https://api.telegram.org/bot/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 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 + +```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 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 + +```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 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 + +```bash +# 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 + +```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 ✅