kkirchheim/pytorch-ood

📦 pytorch‑ood – PyTorch를 위한 분포 외 탐지

무엇인가요 – PyTorch 기반으로 구축된 분포 외(OOD), 오픈셋, 신기성 탐지, 이상 탐지 방법을 대량으로 통합한 Python 라이브러리입니다. 사용 가능한 검출기, 손실 함수, 데이터셋, 모델 아키텍처(사전 학습된 가중치 포함), 그리고 유틸리티를 제공하며, pytorch‑lightning 및 기타 PyTorch 생태계 도구와 원활하게 작동합니다.

왜 중요한가요 – 모델이 훈련 분포와 다른 데이터를 보고 있는지를 탐지하는 것은 비전 시스템, 의료 AI, 자율 에이전트 등에서 핵심적인 안전 문제입니다. 문헌의 각 방법을 별도로 구현하는 것은 번거롭습니다. pytorch‑ood는 고전적인 소프트맥스 기준선부터 최신 에너지 기반 및 트랜스포머 기반 검출기까지 30개 이상의 공개된 기법을 하나의 신뢰할 수 있는 API로 제공합니다.

🎯 핵심 기능 (README에 기재된 내용)

카테고리	제공되는 기능
검출기	OpenMax, MC-Dropout, MaxSoftmax, ODIN, Mahalanobis(단층 및 다층), GRAM, Energy-Based, GradNorm, ReAct, ViM, ASH, SHE, NNGuide, GEN, fDBD, VRA, NAC-UE, SCALE, NCI 등 다수(2024–2025 년 논문 포함).
손실 함수	Objectosphere, Center Loss, Outlier Exposure 등 분포 외 입력에 강건한 모델을 훈련하는 데 유용합니다.
모델 및 가중치	CIFAR-10/100, ImageNet 등에서 사전 학습된 WideResNet-40-2, ResNet 등 아키텍처와 원 논문과 일치하는 가중치 제공.
데이터셋 및 변환	표준 OOD 벤치마크(예: OpenOOD CIFAR-10 v1.5) 다운로드 도구 및 문헌에서 사용된 정확한 전처리 파이프라인 제공.
유틸리티	AUROC, AUPR, FPR@95TPR 등을 계산하는 `OODMetrics`; 빠른 벤치마크 실행을 위한 로짓/특징 캐싱; `torchmetrics`, `pandas`, `scikit-learn`, `segmentation-models-pytorch`와의 선택적 통합.
호환성	일반 PyTorch, `pytorch-lightning`, 세그멘테이션 라이브러리와 호환; 빠른 실험을 위한 Binder 데모 노트북 제공.

🛠️ 설치

pip install pytorch-ood

필수 종속성: torch, torchvision, scipy, torchmetrics. 선택적 추가 기능 (필요 시 설치):

scikit-learn – ViM 및 k-NN 검출기 필요.
gdown – 일부 큰 모델 파일 자동 다운로드에 사용.
pandas – 벤치마크 예제에서 사용.
segmentation-models-pytorch – 이상 세그멘테이션 데모용.

🚀 빠른 시작 예제 (README에서)

from pytorch_ood.detector import EnergyBased
from pytorch_ood.utils import OODMetrics
from pytorch_ood.model import load_model, load_transform

# 1️⃣ 사전 학습된 WideResNet-40-2 (CIFAR-10, Energy-Based 손실로 훈련) 로드
model = load_model("wrn-40-2/cifar10/energy/s1").cuda()
preprocess = load_transform("wrn-40-2/cifar10/energy/s1")

# 2️⃣ 검출기 생성
detector = EnergyBased(model)

# 3️⃣ OOD 샘플의 레이블이 < 0인 DataLoader에서 평가
metrics = OODMetrics()
for x, y in data_loader:
    x = preprocess(x).cuda()
    scores = detector(x)               # 값이 클수록 이상도가 높음
    metrics.update(scores, y)

print(metrics.compute())  # AUROC, AUPR 등을 출력

이 라이브러리는 고수준의 벤치마크 API도 제공합니다(Benchmarks (Beta) 섹션 참조). 표준 OOD 세트에서 여러 검출기를 자동으로 중간 특징을 캐시하며 평가할 수 있습니다.

📚 문서 및 지원

전체 문서: https://pytorch-ood.readthedocs.io
Binder 데모 노트북: https://mybinder.org/v2/gh/kkirchheim/pytorch-ood/dev?labpath=notebooks/mnist_binder_demo.ipynb
리포지토리에는 사용 질문, 버그 보고, 기여를 위한 템플릿이 제공됩니다.

📖 인용

연구에서 pytorch-ood를 사용할 경우, CVPR-2022 워크숍 논문을 인용해 주세요:

@inproceedings{kirchheim2022pytorch,
  title={Pytorch-ood: A library for out-of-distribution detection based on pytorch},
  author={Kirchheim, Konstantin and Filax, Marco and Ortmeier, Frank},
  booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition},
  pages={4351--4360},
  year={2022}
}

✅ 결론

pytorch-ood는 최소한의 부가 코드로 어떤 PyTorch 모델에도 다양한 OOD 탐지 방법을 쉽게 통합할 수 있는 성숙하고 지속적으로 유지 관리되는 도구 상자입니다. AI/ML 분야에 특화된 진정한 소프트웨어 프로젝트이며, 커스터마이징된 목록이나 튜토리얼 모음이 아닙니다.