kkirchheim/pytorch-ood

📦 pytorch‑ood – PyTorch 用的分布外檢測

是什麼 – 一個基於 PyTorch 建構的 Python 庫，整合了大量 OOD（分布外）、開放集、新奇性檢測與異常檢測方法。提供即用型的檢測器、損失函數、資料集、模型架構（含預訓練權重）以及實用工具，並與 pytorch‑lightning 及其他 PyTorch 生態系統工具良好整合。

為何重要 – 檢測模型是否遇到與其訓練分佈不同的資料，是視覺系統、醫療 AI、自主代理等領域的核心安全問題。從文獻中逐一實作每種方法非常繁瑣；pytorch‑ood 提供單一、經過充分測試的 API，涵蓋超過 30 種已發表的技術，從經典的 Softmax 基準線到最新的能量基與 Transformer 基檢測器。

🎯 核心功能（如 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 等，有助於訓練對 OOD 輸入具魯棒性的模型。
模型與權重	在 CIFAR-10/100、ImageNet 等資料集上預訓練的 WideResNet-40-2、ResNet 等架構，權重與原始論文一致。
資料集與轉換	下載標準 OOD 基準（如 OpenOOD CIFAR-10 v1.5）的助手，以及取得文獻中使用的精確預處理流程。
實用工具	`OODMetrics` 用於計算 AUROC、AUPR、FPR@95TPR 等；對 logits/特徵進行快取以實現快速基準測試；可選整合 `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 是一個成熟、持續維護的工具箱，讓研究人員與實務者能以最少的樣板程式碼，將多種 OOD 檢測方法輕鬆整合至任何 PyTorch 模型中。它完全屬於 AI/ML 領域，是一個真正的軟體專案，而非精心整理的清單或教學合集。