MANUAL_DE_USO.md

# 📖 Manual de Uso - LoRA Trainer Funcional

## 🎯 Visão Geral

Este LoRA Trainer é uma ferramenta **100% funcional** baseada no kohya-ss sd-scripts que permite treinar modelos LoRA reais para Stable Diffusion. A ferramenta foi desenvolvida especificamente para funcionar no Hugging Face Spaces e oferece todas as funcionalidades necessárias para um treinamento profissional.

## 🚀 Início Rápido

### Passo 1: Instalação das Dependências
1. Acesse a aba "🔧 Instalação"
2. Clique em "📦 Instalar Dependências"
3. Aguarde a instalação completa (pode levar alguns minutos)

### Passo 2: Configuração do Projeto
1. Vá para a aba "📁 Configuração do Projeto"
2. Digite um nome único para seu projeto (ex: "meu_lora_anime")
3. Escolha um modelo base ou insira uma URL personalizada
4. Clique em "📥 Baixar Modelo"

### Passo 3: Preparação do Dataset
1. Organize suas imagens em uma pasta local
2. Para cada imagem, crie um arquivo .txt com o mesmo nome
3. Compacte tudo em um arquivo ZIP
4. Faça upload na seção "📊 Upload do Dataset"
5. Clique em "📊 Processar Dataset"

### Passo 4: Configuração dos Parâmetros
1. Acesse a aba "⚙️ Parâmetros de Treinamento"
2. Ajuste os parâmetros conforme sua necessidade
3. Use as configurações recomendadas como ponto de partida

### Passo 5: Treinamento
1. Vá para a aba "🚀 Treinamento"
2. Clique em "📝 Criar Configuração de Treinamento"
3. Clique em "🎯 Iniciar Treinamento"
4. Acompanhe o progresso em tempo real

### Passo 6: Download dos Resultados
1. Acesse a aba "📥 Download dos Resultados"
2. Clique em "🔄 Atualizar Lista de Arquivos"
3. Selecione e baixe seu LoRA treinado

## 📋 Requisitos do Sistema

### Mínimos
- **GPU**: NVIDIA com 6GB VRAM
- **RAM**: 8GB
- **Espaço**: 5GB livres

### Recomendados
- **GPU**: NVIDIA com 12GB+ VRAM
- **RAM**: 16GB+
- **Espaço**: 20GB+ livres

## 🎨 Preparação do Dataset

### Estrutura Recomendada
```
meu_dataset/
├── imagem001.jpg
├── imagem001.txt
├── imagem002.png
├── imagem002.txt
├── imagem003.webp
├── imagem003.txt
└── ...
```

### Formatos Suportados
- **Imagens**: JPG, PNG, WEBP, BMP, TIFF
- **Captions**: TXT (UTF-8)

### Exemplo de Caption
```
1girl, long hair, blue eyes, school uniform, smile, outdoors, cherry blossoms, anime style, high quality
```

### Dicas para Captions
- Use vírgulas para separar tags
- Coloque tags importantes no início
- Seja específico mas conciso
- Use tags consistentes em todo o dataset

## ⚙️ Configuração de Parâmetros

### Parâmetros Básicos

#### Resolução
- **512px**: Padrão, mais rápido, menor uso de memória
- **768px**: Melhor qualidade, moderado
- **1024px**: Máxima qualidade, mais lento

#### Batch Size
- **1**: Menor uso de memória, mais lento
- **2-4**: Equilibrado (recomendado)
- **8+**: Apenas para GPUs potentes

#### Épocas
- **5-10**: Para datasets grandes (50+ imagens)
- **10-20**: Para datasets médios (20-50 imagens)
- **20-30**: Para datasets pequenos (10-20 imagens)

### Parâmetros Avançados

#### Learning Rate
- **1e-3**: Muito alto, pode causar instabilidade
- **5e-4**: Padrão, bom para a maioria dos casos
- **1e-4**: Conservador, para datasets grandes
- **5e-5**: Muito baixo, treinamento lento

#### Network Dimension
- **8-16**: LoRAs pequenos, menos detalhes
- **32**: Padrão, bom equilíbrio
- **64-128**: Mais detalhes, arquivos maiores

#### Network Alpha
- Geralmente metade do Network Dimension
- Controla a força do LoRA
- Valores menores = efeito mais sutil

### Tipos de LoRA

#### LoRA Clássico
- Menor tamanho de arquivo
- Bom para uso geral
- Mais rápido para treinar

#### LoCon
- Melhor para estilos artísticos
- Mais camadas de aprendizado
- Arquivos maiores

## 🎯 Configurações por Tipo de Projeto

### Para Personagens/Pessoas
```
Imagens: 15-30 variadas
Network Dim: 32
Network Alpha: 16
Learning Rate: 1e-4
Épocas: 10-15
Batch Size: 2
```

### Para Estilos Artísticos
```
Imagens: 30-50 do estilo
Tipo: LoCon
Network Dim: 64
Network Alpha: 32
Learning Rate: 5e-5
Épocas: 15-25
Batch Size: 1-2
```

### Para Objetos/Conceitos
```
Imagens: 10-25
Network Dim: 16
Network Alpha: 8
Learning Rate: 5e-4
Épocas: 8-12
Batch Size: 2-4
```

## 🔧 Solução de Problemas

### Erro de Memória (CUDA OOM)
**Sintomas**: "CUDA out of memory"
**Soluções**:
- Reduza o batch size para 1
- Diminua a resolução para 512px
- Use mixed precision fp16

### Treinamento Muito Lento
**Sintomas**: Progresso muito lento
**Soluções**:
- Aumente o batch size (se possível)
- Use resolução menor
- Verifique se xFormers está ativo

### Resultados Ruins/Overfitting
**Sintomas**: LoRA não funciona ou muito forte
**Soluções**:
- Reduza o learning rate
- Diminua o número de épocas
- Use mais imagens variadas
- Ajuste network alpha

### Erro de Configuração
**Sintomas**: Falha ao criar configuração
**Soluções**:
- Verifique se o modelo foi baixado
- Confirme que o dataset foi processado
- Reinicie a aplicação

## 📊 Monitoramento do Treinamento

### Métricas Importantes
- **Loss**: Deve diminuir gradualmente
- **Learning Rate**: Varia conforme scheduler
- **Tempo por Época**: Depende do hardware

### Sinais de Bom Treinamento
- Loss diminui consistentemente
- Sem erros de memória
- Progresso estável

### Sinais de Problemas
- Loss oscila muito
- Erros frequentes
- Progresso muito lento

## 💾 Gerenciamento de Arquivos

### Estrutura de Saída
```
/tmp/lora_training/projects/meu_projeto/
├── dataset/          # Imagens processadas
├── output/           # LoRAs gerados
├── logs/            # Logs do treinamento
├── dataset_config.toml
└── training_config.toml
```

### Arquivos Gerados
- **projeto_epoch_0001.safetensors**: LoRA da época 1
- **projeto_epoch_0010.safetensors**: LoRA da época 10
- **logs/**: Logs detalhados do TensorBoard

## 🎨 Uso dos LoRAs Treinados

### No Automatic1111
1. Copie o arquivo .safetensors para `models/Lora/`
2. Use na prompt: `<lora:nome_do_arquivo:0.8>`
3. Ajuste o peso (0.1 a 1.5)

### No ComfyUI
1. Coloque o arquivo em `models/loras/`
2. Use o nó "Load LoRA"
3. Conecte ao modelo

### Pesos Recomendados
- **0.3-0.6**: Efeito sutil
- **0.7-1.0**: Efeito padrão
- **1.1-1.5**: Efeito forte

## 🔄 Melhores Práticas

### Antes do Treinamento
1. **Qualidade sobre Quantidade**: 20 imagens boas > 100 ruins
2. **Variedade**: Use ângulos, poses e cenários diferentes
3. **Consistência**: Mantenha estilo consistente nas captions
4. **Backup**: Salve configurações que funcionaram

### Durante o Treinamento
1. **Monitore**: Acompanhe o progresso regularmente
2. **Paciência**: Não interrompa sem necessidade
3. **Recursos**: Monitore uso de GPU/RAM

### Após o Treinamento
1. **Teste**: Experimente diferentes pesos
2. **Compare**: Teste épocas diferentes
3. **Documente**: Anote configurações que funcionaram
4. **Compartilhe**: Considere compartilhar bons resultados

## 🆘 Suporte e Recursos

### Documentação Adicional
- [Guia Oficial kohya-ss](https://github.com/kohya-ss/sd-scripts)
- [Documentação Diffusers](https://huggingface.co/docs/diffusers)
- [Comunidade Stable Diffusion](https://discord.gg/stable-diffusion)

### Logs e Debug
- Verifique os logs em `/tmp/lora_training/projects/seu_projeto/logs/`
- Use TensorBoard para visualizar métricas
- Salve configurações que funcionaram bem

### Limitações Conhecidas
- Requer GPU NVIDIA com CUDA
- Modelos grandes podem precisar de mais memória
- Treinamento pode ser lento em hardware limitado

---

**Nota**: Esta ferramenta é para fins educacionais e de pesquisa. Use responsavelmente e respeite direitos autorais das imagens utilizadas.