DetectionIA Pipeline

Este README explica como instalar Podman ou Docker, como usar a automação com o Makefile do projeto

Instalação do Podman ou Docker

Este projeto pode ser executado em containers usando Podman ou Docker.
Escolha uma das opções abaixo para instalar:

Podman

macOS (Homebrew):

brew install podman
podman machine init
podman machine start

Debian/Ubuntu:

sudo apt-get update
sudo apt-get install -y podman

Verifique:

podman --version
podman info

Docker

macOS (Docker Desktop):

brew install --cask docker
# Abra e inicie o Docker Desktop

Debian/Ubuntu (resumido):

sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg lsb-release
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmour -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io
sudo usermod -aG docker $USER
# Efetue logout/login para ativar o grupo docker

Verifique:

docker --version
docker info

Atenção: em servidores é comum usar Podman (rootless) ou Docker com permissões controladas. Escolha conforme a política de segurança do ambiente.

---

Automação com Make

O repositório inclui um Makefile para tarefas como construir imagens (create-image) e container (create-container). Comandos:

make create-image     # constrói a imagem usando o runtime configurado (docker/podman)
make create-container # controi o container para treinamento 
# dentro do container
./training.sh

Ajustes rápidos no Dockerfile

Se você estiver construindo em um servidor com GPU e encontra erros como "Package 'libgl1-mesa-glx' has no installation candidate", remova esse pacote do Dockerfile e substitua por 'libgl1'.

Exemplo alterado:

RUN apt-get update && apt-get install -y --no-install-recommends \
	 git \
	 build-essential \
	 libglib2.0-0 \
     libgl1 \
	 vim \
	 && rm -rf /var/lib/apt/lists/*

Estrutura do diretório

Raiz do projeto:

.
├── common
│   └── utils.py
├── data
│   ├── train
│   │   ├── images
│   │   │   ├── 2025-04-24-08-40-18_315.jpg
│   │   └── labels
│   │   │   ├── 2025-04-24-08-40-18_315.txt
│   └── val
│       ├── images
│       └── labels
├── networks
│   └── structures.py
├── notebooks
│   └── figures
│   └── results.ipynb
├── test
│   └── 20250915v1
│       ├── data.yaml
│       └── args.yaml
├── training.sh
├── Dockerfile
├── Makefile
├── main.py
├── test.sh
├── requirements.txt
├── yolo11m.pt
└── README.md

Comparação

Evolução do mAP50-95 no conjunto de validação interno para YOLOv8, YOLOv11 e Faster R-CNN.

Comparativo

Tabela consolidada: desempenho (mAP@50, mAP@50-95, Precision, Recall, F1), estabilidade, overfitting, eficiência, tempo de inferência, tamanho e razão de generalização.

Critério (resumo rápido):

mAP@50 / mAP@50-95: Qualidade global de detecção (localização + classificação).
Precision: Proporção de detecções corretas (baixa → muitos falsos positivos).
Recall: Cobertura dos objetos reais (baixa → muitos falsos negativos).
F1-score: Equilíbrio entre Precision e Recall.
Estabilidade: Desvio padrão dos últimos epochs (menor = treino consistente).
Overfitting (gap): Diferença (val - train) em loss de boxes (alto = risco de overajuste).
Eficiência: Época em que alcança 95% do melhor mAP (menor = mais rápido para ficar “quase ótimo”).
Tempo de inferência: Latência média por imagem (ms).
Tamanho do modelo: Peso em MB (impacta deploy).
Generalização: (mAP externo / mAP interno) — retenção de performance fora do domínio original.

Observações

Definições resumidas dos critérios calculados.

📂 Diretório app/

Este diretório contém a aplicação principal de serving via API REST, construída em FastAPI e empacotada em Docker.

---

📌 Descrição

• Automação Makefile.
• Comandos disponíveis (Makefile).

Comando	Descrição
make help	Mostra a ajuda com todos os comandos
make build	Build da imagem
make run	Rodar container sem GPU
make run-gpu	Rodar container com GPU NVIDIA
make shell	Acessar o shell do container
make stop	Parar o container
make clean	Remover imagem e containers parados
make lint	Checar estilo de código Python
make init	Instalar dependências locais

• Link para a pasta de modelos (SharePoint)