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.
This commit is contained in:
lgcosta committed
1 parent
8934476331
commit
7cb4ea0627
1 file changed
+823
@@ -0,0 +1,823 @@
|
||||
# Build e Deployment Instructions
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
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<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 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 ✅
|
||||
Reference in new issue
Block a user