Dumoura/vit-attention-steering-lab

ViT Attention Steering Lab

Experimento de pesquisa em interpretabilidade adversarial interna: usar steering vectors (representation engineering) para manipular mapas de Attention Rollout / Grad-Rollout no encoder de visão CLIP ViT, e medir se a explicação se desacopla da decisão (embedding / similaridade com imagem-alvo).

Projeto irmão de `clip-vit-art` — aquele foca em visualização artística (ONNX); este usa PyTorch + hooks para intervenção causal.

Hipótese

Se heatmaps de atenção fossem causalmente fiéis ao mecanismo de decisão:

1. 1.Perturbar K (ou Q) numa camada intermediária moveria o rollout
2. 2.Só se a decisão também mudasse — ou o rollout resistiria

Observar mapa muda + embedding estável → fragilidade da explicação como evidência de auditoria.

Pipeline

Pares contrastivos (natural vs. região mascarada)
        ↓
steering_vector = mean(K_redirect) - mean(K_natural)
        ↓
forward hook: K' = K + α · steering_vector
        ↓
Attention Rollout / Grad-Rollout (implementação manual)
        ↓
Métricas: Spearman, IoU, Δ embedding, Δ sim(imagem-alvo), deletion/insertion
        ↓
Relatório Markdown + painéis visuais

Estrutura

vit-attention-steering/
├── vit_steer/
│   ├── model.py       # CLIP ViT wrapper (HuggingFace)
│   ├── hooks.py       # Captura e steering em K/Q
│   ├── steering.py    # Vetor contrastivo + aplicação
│   ├── rollout.py     # Attention Rollout + Grad-Rollout manual
│   ├── metrics.py     # IoU, Spearman, deletion/insertion
│   ├── visualize.py   # Painéis lado a lado
│   └── report.py      # Relatório Markdown
├── scripts/
│   └── run_experiment.py
├── reports/
└── outputs/

Instalação

cd vit-attention-steering
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Requer download do openai/clip-vit-base-patch16 (~600 MB na primeira execução).

Uso

# Demo com imagens sintéticas
python scripts/run_experiment.py

# Suas imagens + camadas
python scripts/run_experiment.py --images foto1.jpg foto2.jpg --layers 4 6 8 --alpha 2.0

# Grad-Rollout + readout por imagem-alvo
python scripts/run_experiment.py --method grad --use-target-readout --target-image alvo.jpg

Saídas:

• —outputs/panels/ — imagem | rollout original | rollout steered | diff
• —reports/report_*.md — tabela de métricas + interpretação

Parâmetros documentados (afetam resultado)

Readout visual (sem texto)

Similaridade CLIP entre embedding da imagem perturbada e imagem-alvo — modalidade puramente visual, alinhado à proposta de leitura por imagem em vez de prompt textual.

Limitações atuais

• —Contrastive redirect via máscara central (baseline simples); substituir por máscaras SAM/segmentação
• —Grad-Rollout simplificado (pesos via grad nos patch tokens)
• —Não inclui classificador ImageNet (fácil extensão para DeiT)

Referências

• —Abnar & Zuidema — Attention Flow / Rollout
• —Ghorbani et al. — Adversarial fragility of saliency
• —Turner et al., Zou et al. — Activation steering
• —Projeto base artístico: clip-vit-art

Licença

MIT — pesos CLIP seguem OpenAI / Hugging Face.