@libs-scripts-mep/mpai/README.md

Inference MPAI client

# MPAI — Métodos e Processos com IA

Ferramenta para captura de imagens, treinamento e inferência com modelos YOLOv8 (Ultralytics) utilizando exclusivamente o Roboflow para gerenciamento de datasets.

## ✨ Funcionalidades
- Captura de imagens com controle de parâmetros da câmera.
- Treinamento de modelos YOLOv8.
- Inferência em imagens e streaming de vídeo.

## 📦 Instalação
```bash
npm install @libs-scripts-mep/mpai
```

## 🔁 Atualização
```bash
npm update @libs-scripts-mep/mpai
```

## 🧹 Desinstalação
```bash
npm uninstall @libs-scripts-mep/mpai
```

## 🧪 Ambiente Virtual (opcional, mas recomendado)
Crie um ambiente virtual para o projeto. O ambiente virtual pode ser ativado manualmente na raiz do projeto.

> ⚠️ Para os comandos de ativação, **não** use o bash. Utilize o CMD ou PowerShell no terminal integrado do VS Code.

```bash
python -m venv .venv
```

### Ativação:
> ⚠️ A ativação deve ser feita sempre que abrir o VS Code. Caso contrário, o ambiente global será usado.

**PowerShell:**
```powershell
.venv\Scripts\Activate.ps1
```

**CMD:**
```bash
.venv\Scripts\activate
```

**Bash/Linux:**
```bash
source .venv/bin/activate
```

## ⚙️ Dependências (Python)

A recomendação é instalar as dependências de acordo com o uso da biblioteca na estação. Por exemplo, se for uma estação de inferência, instale apenas as dependências de inferência, se for para treinamento, apenas as dependências de treinamento. 

É altamente recomendado utilizar a estação de treinamento dedicada disponível na sala dos servidores da inova, devido ao potente hardware disponível pra essa tarefa. 

Se necessário, entre em contato com a TI para acessa-la.

### Para Inferência
> 💡 Recomendado: execute `inference/infer_deps.py` para instalar dependências compatíveis automaticamente (detecta e usa ambiente virtual, se existir). 

Ou instale manualmente se preferir:

```bash
pip install opencv-python pillow numpy ultralytics pyyaml websockets
```

### Para Treinamento
⚠️ Se estiver usando GPU, instale primeiro a versão do PyTorch compatível, por exemplo, essa é a versão compatível com a GPU `RTX 5070`:

```bash
pip3 install --pre torch torchvision --index-url https://download.pytorch.org/whl/nightly/cu129
```

Depois, execute o arquivo `model_training/train_deps_GPU.py`.

### 🛑 Ignorando dataset no Git
Adicione o seguinte ao `.gitignore` do repositório do script:

```
node_modules/@libs-scripts-mep/mpai/dataset/*
!node_modules/@libs-scripts-mep/mpai/dataset/**/.gitkeep
!node_modules/@libs-scripts-mep/mpai/dataset/**/*.yaml
```

## 🏋️‍♂️ Treinamento
### Modelos disponíveis
| Modelo   | Tamanho | Velocidade       | Precisão      | Indicação                     |
|----------|---------|------------------|---------------|-------------------------------|
| yolov8n  | ~6 MB   | 🔥 Muito rápido  | Baixa         | Testes, dispositivos embarcados |
| yolov8s  | ~11 MB  | ⚡ Rápido        | Média-baixa   | Tempo real, baixa latência    |
| yolov8m  | ~25 MB  | ⚖️ Balanceado    | Média         | GPU ou CPU robusta            |
| yolov8l  | ~45 MB  | 🐢 Mais lento    | Alta          | Workstations com GPU          |
| yolov8x  | ~65 MB  | 🐌 Lento         | Muito alta    | GPUs potentes                 |

> Este projeto suporta apenas o modo **detect**.

### Exemplo de treinamento:
```python
# model_training/train.py

from ultralytics import YOLO
from multiprocessing import freeze_support

model = YOLO("yolov8n.pt")

if __name__ == '__main__':
    freeze_support()
    model.train(
        data='dataset/data.yaml',
        epochs=100,
        imgsz=640,
        batch=8,
        project='runs',
        name='meu_projeto',
        exist_ok=True,
        augment=True,
        degrees=5,
        scale=0.3,
        fliplr=0.5,
        flipud=0.1,
        device='0'  # Use '0' para GPU ou 'cpu' para CPU
    )
```

### Parâmetros importantes
- **data**: Caminho do arquivo `data.yaml` gerado pelo Roboflow.
- **batch**: Depende da RAM ou VRAM (tente 8 ou 16).
- **imgsz**: Resolução da imagem.
- **device**: `"cpu"` ou `"0"` (GPU).
- **augment**: Habilita técnicas como rotação, flip e escala.
- **pretrained**: Usar pesos base (default: `True`).

## 🔍 Inferência
Use o script `mpai-server.py` para disponibilizar o modelo treinado via serviço HTTP e o `mpai-client.js` para enviar imagens (base64) e receber as detecções.