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 领域，是一个真正的软件项目，而非精心整理的列表或教程合集。