INSTALACAO.md

🛠️ Guia de Instalação - LoRA Trainer Funcional

📋 Pré-requisitos

Sistema Operacional

• Linux: Ubuntu 20.04+ (recomendado)
• Windows: Windows 10/11 com WSL2
• macOS: macOS 12+ (limitado, sem GPU)

Hardware

• GPU: NVIDIA com 6GB+ VRAM (obrigatório)
• RAM: 16GB+ (recomendado)
• Armazenamento: 20GB+ livres
• CPU: Qualquer CPU moderno

Software

• Python: 3.8 a 3.11
• CUDA: 11.8 ou 12.1
• Git: Para clonar repositórios

🚀 Instalação Local

Método 1: Instalação Completa

# 1. Clone o repositório
git clone <repository-url>
cd lora_trainer_hf

# 2. Crie ambiente virtual
python -m venv venv
source venv/bin/activate  # Linux/Mac
# ou
venv\Scripts\activate     # Windows

# 3. Instale dependências
pip install -r requirements.txt

# 4. Execute a aplicação
python app.py

Método 2: Instalação com Conda

# 1. Crie ambiente conda
conda create -n lora_trainer python=3.10
conda activate lora_trainer

# 2. Instale PyTorch com CUDA
conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia

# 3. Clone e instale
git clone <repository-url>
cd lora_trainer_hf
pip install -r requirements.txt

# 4. Execute
python app.py

🐳 Instalação com Docker

Dockerfile Incluído

# 1. Build da imagem
docker build -t lora-trainer .

# 2. Execute o container
docker run -p 7860:7860 --gpus all lora-trainer

Docker Compose

version: '3.8'
services:
  lora-trainer:
    build: .
    ports:
      - "7860:7860"
    volumes:
      - ./data:/tmp/lora_training
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

☁️ Deploy no Hugging Face Spaces

Configuração do Space

1. Crie um novo Space:

   • Vá para huggingface.co/new-space
   • Escolha "Gradio" como SDK
   • Selecione hardware com GPU

2. Configure o Space:

   # space_config.yml
   title: LoRA Trainer Funcional
   emoji: 🎨
   colorFrom: blue
   colorTo: purple
   sdk: gradio
   sdk_version: 4.0.0
   app_file: app.py
   pinned: false
   hardware: t4-medium  # ou a100-large
   

3. Upload dos arquivos:

   • app.py
   • requirements.txt
   • README.md
   • Pasta sd-scripts/

Configuração de Hardware

Hardware	VRAM	RAM	Recomendado Para
CPU Basic	0GB	16GB	Apenas teste
T4 Small	16GB	15GB	Projetos pequenos
T4 Medium	16GB	30GB	Projetos médios
A10G Small	24GB	30GB	Projetos grandes
A100 Large	40GB	80GB	Projetos profissionais

🔧 Configuração de Dependências

Dependências Principais

# Core ML
torch>=2.0.0
torchvision>=0.15.0
diffusers>=0.21.0
transformers>=4.25.0
accelerate>=0.20.0

# LoRA Training
safetensors>=0.3.0
huggingface-hub>=0.16.0
xformers>=0.0.20
bitsandbytes>=0.41.0

# Interface
gradio>=4.0.0

# Utilities
Pillow>=9.0.0
opencv-python>=4.7.0
numpy>=1.21.0
toml>=0.10.0
tqdm>=4.64.0

Instalação Manual de Dependências

# PyTorch (ajuste para sua versão CUDA)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# Diffusers e Transformers
pip install diffusers transformers accelerate

# Otimização
pip install xformers bitsandbytes

# Interface
pip install gradio

# Utilitários
pip install safetensors huggingface-hub Pillow opencv-python numpy toml tqdm

🐛 Solução de Problemas de Instalação

Erro: CUDA não encontrado

# Verifique instalação CUDA
nvidia-smi
nvcc --version

# Reinstale PyTorch com CUDA
pip uninstall torch torchvision torchaudio
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

Erro: xFormers não compatível

# Instale versão específica
pip install xformers==0.0.20

# Ou compile do código fonte
pip install -U xformers --index-url https://download.pytorch.org/whl/cu118

Erro: Memória insuficiente

# Aumente swap (Linux)
sudo fallocate -l 8G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Configure variáveis de ambiente
export PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:512

Erro: Dependências conflitantes

# Limpe cache pip
pip cache purge

# Crie ambiente limpo
python -m venv fresh_env
source fresh_env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

🔒 Configuração de Segurança

Variáveis de Ambiente

# .env
HUGGINGFACE_TOKEN=your_token_here
WANDB_API_KEY=your_wandb_key
CUDA_VISIBLE_DEVICES=0
PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:512

Limitações de Recursos

# No app.py
import resource

# Limite de memória (8GB)
resource.setrlimit(resource.RLIMIT_AS, (8*1024*1024*1024, -1))

# Limite de processos
resource.setrlimit(resource.RLIMIT_NPROC, (100, -1))

📊 Verificação da Instalação

Script de Teste

# test_installation.py
import torch
import diffusers
import transformers
import gradio as gr
import safetensors

print("✅ Verificando instalação...")
print(f"Python: {sys.version}")
print(f"PyTorch: {torch.__version__}")
print(f"CUDA disponível: {torch.cuda.is_available()}")
print(f"GPU: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'Não disponível'}")
print(f"Diffusers: {diffusers.__version__}")
print(f"Transformers: {transformers.__version__}")
print(f"Gradio: {gr.__version__}")
print("✅ Instalação verificada!")

Teste de GPU

# test_gpu.py
import torch

if torch.cuda.is_available():
    device = torch.device("cuda")
    x = torch.randn(1000, 1000).to(device)
    y = torch.randn(1000, 1000).to(device)
    z = torch.mm(x, y)
    print(f"✅ GPU funcionando: {torch.cuda.get_device_name(0)}")
    print(f"VRAM total: {torch.cuda.get_device_properties(0).total_memory / 1024**3:.1f} GB")
    print(f"VRAM livre: {torch.cuda.memory_reserved(0) / 1024**3:.1f} GB")
else:
    print("❌ GPU não disponível")

🚀 Otimização de Performance

Configurações de Sistema

# Aumentar limites de arquivo
echo "* soft nofile 65536" >> /etc/security/limits.conf
echo "* hard nofile 65536" >> /etc/security/limits.conf

# Otimizar scheduler
echo "performance" > /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

Configurações PyTorch

# No início do app.py
import torch
torch.backends.cudnn.benchmark = True
torch.backends.cuda.matmul.allow_tf32 = True
torch.backends.cudnn.allow_tf32 = True

📝 Logs e Monitoramento

Configuração de Logs

import logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('lora_trainer.log'),
        logging.StreamHandler()
    ]
)

Monitoramento de Recursos

# Instalar htop e nvidia-ml-py
pip install nvidia-ml-py3 psutil

# Monitorar em tempo real
watch -n 1 nvidia-smi

🔄 Atualizações

Atualizar Dependências

# Atualizar requirements
pip install --upgrade -r requirements.txt

# Atualizar kohya-ss
cd sd-scripts
git pull origin main

Backup de Configurações

# Backup de modelos e configurações
tar -czf backup_$(date +%Y%m%d).tar.gz /tmp/lora_training/

---

Nota: Para suporte adicional, consulte a documentação oficial do kohya-ss e a comunidade Hugging Face.