Skip to content

joaoPAndrade/ensemble

BranchesTags

Repository files navigation

Ensemble — Segmentação de Displasia Epitelial Oral

Implementação computacional do pipeline de segmentação semântica binária utilizando ensemble de 12 arquiteturas de deep learning (ResNet50, VGG16, MobileNetV3-Large e SegFormer) com Transfer Learning, Validação Cruzada 10-Fold e 8 métodos de agregação por ensemble.

Especificações do Ambiente Testado

Componente Detalhes
SO CachyOS (Arch Linux rolling)
CPU AMD Ryzen 5 5500 (6 núcleos / 12 threads)
RAM 16 GB DDR4
GPU AMD Radeon RX 7600 (8 GB VRAM, RDNA 3, gfx1102)
Python (sistema) 3.14.4
Ambiente venv isolado (Python 3.11 recomendado via pyenv ou pythonX.Y)

Importante: O PyTorch com suporte ROCm não é compatível com Python 3.14 na data deste guia. Use Python 3.11 no venv.

Pré-requisitos do Sistema

1. Instalar dependências de sistema (ROCm + ferramentas)

No CachyOS/Arch Linux, execute como root ou com sudo:

# Atualizar sistema
sudo pacman -Syu

# Instalar dependências base de compilação e Python 3.11
sudo pacman -S --needed base-devel git wget curl

# Instalar Python 3.11 (necessário para o venv com PyTorch ROCm)
sudo pacman -S --needed python311

# Instalar pacotes ROCm para AMD RX 7600 (RDNA 3 / gfx1102)
sudo pacman -S --needed \
    rocm-hip-sdk \
    rocm-opencl-runtime \
    hip-runtime-amd \
    rocm-smi-lib \
    rocminfo \
    miopen-hip

# Instalar OpenCV e dependências de imagem do sistema
sudo pacman -S --needed \
    opencv \
    python-opencv \
    libpng \
    libjpeg-turbo \
    libtiff

# Verificar instalação do ROCm
rocminfo | grep -E "Name|gfx"

Nota: Se o rocm-hip-sdk não estiver disponível diretamente, use o repositório extra ou AUR:

# Via AUR (usar yay ou paru)
yay -S rocm-hip-sdk rocm-opencl-runtime miopen-hip

2. Configurar grupo de usuário para GPU AMD

# Adicionar seu usuário ao grupo render e video (acesso à GPU)
sudo usermod -aG render,video $USER

# Reiniciar sessão ou fazer logout/login para aplicar
# Verificar:
groups $USER

Criação do Ambiente Virtual (venv com Python 3.11)

Todos os comandos a seguir devem ser executados dentro do diretório ensemble/.

# Navegar até o diretório do projeto
cd /home/jandrade/Documents/projeto/ensemble

# Verificar se Python 3.11 está disponível
python3.11 --version
# Esperado: Python 3.11.x

# Criar o ambiente virtual isolado com Python 3.11
python3.11 -m venv .venv

# Ativar o ambiente virtual
source .venv/bin/activate

# Verificar que o venv está ativo (o prompt deve mudar para (.venv))
which python
# Deve mostrar: /home/jandrade/Documents/projeto/ensemble/.venv/bin/python

# Atualizar pip dentro do venv
pip install --upgrade pip setuptools wheel

Instalação das Dependências Python

3. Instalar PyTorch com suporte ROCm (AMD GPU)

Crítico: Use o índice oficial do PyTorch para ROCm. Não instale o PyTorch padrão do PyPI — ele não terá suporte à GPU AMD.

# Certificar que o venv está ativo
source .venv/bin/activate

# Instalar PyTorch + torchvision com suporte ROCm 6.2
# (compatível com AMD RX 7600 / RDNA 3 / gfx1102)
pip install torch torchvision \
    --index-url https://download.pytorch.org/whl/rocm6.2

# Verificar instalação e suporte à GPU
python -c "
import torch
print('PyTorch:', torch.__version__)
print('ROCm disponível:', torch.cuda.is_available())
print('Dispositivos GPU:', torch.cuda.device_count())
if torch.cuda.is_available():
    print('GPU:', torch.cuda.get_device_name(0))
"

Saída esperada:

PyTorch: 2.x.x+rocm6.2
ROCm disponível: True
Dispositivos GPU: 1
GPU: AMD Radeon RX 7600

Se a GPU não aparecer, consulte a seção Solução de Problemas.

4. Instalar demais dependências Python

# Certificar que o venv está ativo
source .venv/bin/activate

# Bibliotecas de visão computacional e processamento de imagem
pip install \
    opencv-python-headless==4.10.0.84 \
    Pillow==10.4.0

# Ciência de dados e machine learning
pip install \
    numpy==1.26.4 \
    scikit-learn==1.5.2 \
    scipy==1.14.1

# Progresso e utilidades
pip install \
    tqdm==4.67.1

# (Opcional) Jupyter para experimentos interativos
pip install \
    jupyter \
    ipykernel \
    matplotlib \
    seaborn

5. Criar arquivo requirements.txt (referência completa)

O arquivo requirements.txt abaixo reflete todas as dependências do projeto:

# PyTorch ROCm — instalar separadamente via --index-url
# pip install torch torchvision --index-url https://download.pytorch.org/whl/rocm6.2

# Visão computacional
opencv-python-headless==4.10.0.84
Pillow==10.4.0

# Ciência de dados
numpy==1.26.4
scikit-learn==1.5.2
scipy==1.14.1

# Utilidades
tqdm==4.67.1

Para instalar via requirements.txt (após instalar PyTorch separadamente):

pip install -r requirements.txt

Configuração de Variáveis de Ambiente (AMD ROCm)

Antes de executar o projeto, as seguintes variáveis de ambiente devem ser configuradas. O script script_execucao_amd.sh já faz isso automaticamente.

Variável Valor Motivo
HSA_OVERRIDE_GFX_VERSION 11.0.0 RX 7600 = gfx1102, mapeado como gfx1100 para compatibilidade ROCm
PYTORCH_HIP_ALLOC_CONF max_split_size_mb:128 Limita fragmentação de blocos de memória a 128 MB (previne OOM com 8 GB VRAM)
MIOPEN_LOG_LEVEL 4 Desativa logs verbosos do driver MIOpen

Para configurar manualmente no terminal atual:

export HSA_OVERRIDE_GFX_VERSION=11.0.0
export PYTORCH_HIP_ALLOC_CONF="max_split_size_mb:128"
export MIOPEN_LOG_LEVEL=4

Para tornar permanente, adicione ao seu ~/.bashrc ou ~/.zshrc:

echo 'export HSA_OVERRIDE_GFX_VERSION=11.0.0' >> ~/.bashrc
echo 'export PYTORCH_HIP_ALLOC_CONF="max_split_size_mb:128"' >> ~/.bashrc
echo 'export MIOPEN_LOG_LEVEL=4' >> ~/.bashrc
source ~/.bashrc

Estrutura de Diretórios e Dataset

Estrutura do projeto

ensemble/
├── .venv/                        # Ambiente virtual (criado por você)
├── ensembles/
│   ├── __init__.py
│   └── ensemble_aggregator.py    # Métodos de agregação (8 estratégias)
├── main/
│   └── main.py                   # Script principal do pipeline
├── models/
│   ├── __init__.py
│   └── base_models.py            # 12 arquiteturas (ResNet50/VGG16/MobileNet/SegFormer)
├── preprocessing/
│   ├── __init__.py
│   ├── color_space_generator.py  # Conversão RGB/HSV
│   ├── dataset_handler.py        # Dataset PyTorch on-the-fly
│   ├── image_cropper.py          # Remoção de bordas (450→448px)
│   ├── image_padder.py           # Padding vertical (250→256px)
│   ├── image_reader.py           # Leitura e pareamento de imagens/máscaras
│   └── mask_binarizer.py         # Binarização de máscaras
├── utils/
│   ├── __init__.py
│   ├── device.py                 # Detecção e gerenciamento de GPU/VRAM
│   └── metrics_calculator.py    # Métricas de segmentação (F1, Dice, IoU...)
├── requirements.txt
├── script_execucao_amd.sh        # Script de execução otimizado para RX 7600
└── README.md

Estrutura esperada do dataset

O script espera o seguinte layout de diretórios:

data/
└── OralEpitheliumDB/
    ├── healthy/                  # Imagens de tecido saudável
    │   ├── imagem_001.jpg        # Imagem histológica original (450×250 px)
    │   ├── imagem_001.tiff       # Máscara anotada correspondente
    │   ├── imagem_002.jpg
    │   ├── imagem_002.tiff
    │   └── ...
    └── severe/                   # Imagens com displasia severa
        ├── imagem_001.jpg
        ├── imagem_001.tiff
        └── ...

Resolução original das imagens: 450×250 pixels
Resolução após pré-processamento: 448×256 pixels (crop 1px nas bordas + padding 3px no topo/base)

Execução do Projeto

Opção 1 — Script otimizado (recomendado para RX 7600)

cd /home/jandrade/Documents/projeto/ensemble

# Ativar o venv
source .venv/bin/activate

# Executar usando o script que já configura as variáveis ROCm
bash script_execucao_amd.sh

Opção 2 — Execução manual com parâmetros customizados

cd /home/jandrade/Documents/projeto/ensemble

# Ativar o venv
source .venv/bin/activate

# Configurar variáveis ROCm
export HSA_OVERRIDE_GFX_VERSION=11.0.0
export PYTORCH_HIP_ALLOC_CONF="max_split_size_mb:128"
export MIOPEN_LOG_LEVEL=4

# Executar o pipeline
python main/main.py \
    --data_path "./data/OralEpitheliumDB" \
    --output_path "./results" \
    --epochs 50 \
    --batch_size 4 \
    --learning_rate 1e-4 \
    --use_amp

Parâmetros disponíveis

Parâmetro Padrão Descrição
--data_path ./data Caminho para o dataset
--output_path ./results Diretório de saída dos resultados
--epochs 50 Número de épocas de treinamento
--batch_size 4 Tamanho do batch (4 cabe em 8 GB VRAM com AMP)
--learning_rate 1e-4 Taxa de aprendizado inicial
--num_folds 10 Número de folds para validação cruzada
--use_amp flag Habilita Precisão Mista FP16 (recomendado para RDNA 3)

Saídas Geradas

Após a execução, o diretório results/ conterá:

results/
├── results.json                  # Métricas finais (médias ± desvio padrão dos 10 folds)
└── visual_evaluations/           # Imagens de diagnóstico visual (apenas fold 1)
    ├── visual_sample0_model1_ResNet50_ResNet50.png
    ├── visual_sample0_model5_VGG16_VGG16.png
    ├── visual_sample0_model9_MobileNet_MobileNet.png
    └── visual_sample0_model12_SegFormer_MobileNet.png

Legenda das imagens de avaliação visual:

Cor Significado
Preto Verdadeiro Negativo (fundo classificado corretamente)
Branco Verdadeiro Positivo (lesão classificada corretamente)
Verde Falso Positivo (previu lesão onde era fundo)
Vermelho Falso Negativo (previu fundo onde era lesão)

Solução de Problemas

GPU não detectada (torch.cuda.is_available() retorna False)

# 1. Verificar se os drivers AMD estão carregados
lsmod | grep amdgpu

# 2. Verificar se o ROCm enxerga a GPU
rocminfo | grep "gfx\|Name"

# 3. Verificar permissões do grupo render
ls -la /dev/kfd /dev/dri/
# Usuário deve estar no grupo render e video

# 4. Certificar que as variáveis de ambiente estão definidas
echo $HSA_OVERRIDE_GFX_VERSION   # deve mostrar: 11.0.0

# 5. Testar se o PyTorch encontra o backend HIP
python -c "import torch; print(torch.version.hip)"

Segmentation Fault ao iniciar o PyTorch

# Definir HSA_OVERRIDE_GFX_VERSION ANTES de importar PyTorch
# A variável DEVE estar definida antes de qualquer import torch
export HSA_OVERRIDE_GFX_VERSION=11.0.0
python main/main.py ...

Out of Memory (OOM) durante treinamento

# Reduzir o batch size para 2
python main/main.py --batch_size 2 --use_amp ...

# Ou ajustar o limite do alocador de memória
export PYTORCH_HIP_ALLOC_CONF="max_split_size_mb:64"

ModuleNotFoundError para alguma biblioteca

# Certificar que o venv está ativo
source .venv/bin/activate
which python  # deve mostrar o caminho do .venv

# Reinstalar a dependência específica
pip install nome_da_biblioteca

Python 3.11 não encontrado

# Verificar versões disponíveis no sistema
ls /usr/bin/python*

# Se não tiver python3.11, instalar via pacman
sudo pacman -S python311

# Ou via pyenv (mais flexível)
curl https://pyenv.run | bash
pyenv install 3.11.9
pyenv local 3.11.9
python -m venv .venv

Erro ao carregar pesos ImageNet (download falhou)

# Os pesos são baixados automaticamente pelo torchvision (~100 MB por modelo)
# Definir diretório de cache explícito
export TORCH_HOME=/home/jandrade/.cache/torch
mkdir -p $TORCH_HOME

# Verificar conectividade
curl -I https://download.pytorch.org

Resumo das Bibliotecas Utilizadas

Biblioteca Versão Finalidade
torch ≥2.0 (ROCm 6.2) Framework de deep learning + suporte à GPU AMD
torchvision ≥0.15 (ROCm 6.2) Pesos pré-treinados ImageNet (ResNet50, VGG16, MobileNetV3)
numpy 1.26.4 Operações numéricas e manipulação de arrays
opencv-python-headless 4.10.0.84 Leitura/escrita de imagens, conversão de espaço de cor
scikit-learn 1.5.2 KFold (validação cruzada)
scipy 1.14.1 Dependência interna do scikit-learn
Pillow 10.4.0 Suporte adicional a formatos de imagem (.tiff)
tqdm 4.67.1 Barras de progresso

Checklist Rápido

# 1. Instalar ROCm no sistema
sudo pacman -S rocm-hip-sdk rocm-opencl-runtime miopen-hip

# 2. Adicionar usuário ao grupo render
sudo usermod -aG render,video $USER && newgrp render

# 3. Criar venv com Python 3.11
python3.11 -m venv .venv && source .venv/bin/activate

# 4. Instalar PyTorch ROCm
pip install torch torchvision --index-url https://download.pytorch.org/whl/rocm6.2

# 5. Instalar demais dependências
pip install numpy==1.26.4 opencv-python-headless==4.10.0.84 scikit-learn==1.5.2 Pillow==10.4.0 tqdm==4.67.1

# 6. Configurar variáveis de ambiente
export HSA_OVERRIDE_GFX_VERSION=11.0.0
export PYTORCH_HIP_ALLOC_CONF="max_split_size_mb:128"
export MIOPEN_LOG_LEVEL=4

# 7. Verificar GPU
python -c "import torch; print('GPU OK:', torch.cuda.is_available(), torch.cuda.get_device_name(0))"

# 8. Executar o pipeline
bash script_execucao_amd.sh

Referências

About

Repositório com as implementações utilizadas na aplicação e avaliação do método proposto na dissertação de mestrado.

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages