Anomalib 深度学习异常检测库：从入门到实践的全方位技术指南

一、什么是 Anomalib？

在工业制造、视频监控和医疗影像等领域，视觉异常检测是保障质量和安全的关键技术。然而，从零开始实现复杂的深度学习异常检测算法，往往需要大量的工程投入和专业背景。Anomalib 正是为破解这一难题而生——它是一个由 Intel OpenVINO 团队维护的开源深度学习库，旨在收集最先进的异常检测算法，供公共和私有数据集上的基准测试使用。

Anomalib 提供了大量预处理好的异常检测算法实现，全部源自近年来的前沿研究文献，同时配套一整套工具链，方便用户开发和实施自定义模型。该库专注于视觉异常检测，即检测并定位图像或视频中的异常区域。据最新发布的 v2.1.0 版本，Anomalib 新增了多款来自 CVPR 2025、ICASSP 2025 等顶会的 SOTA 模型，以及 MVTec AD 2、Real-IAD、VAD 等多个工业基准数据集，进一步巩固了其在异常检测领域的标杆地位。

Anomalib 的核心特性可以概括为以下几个方面：

  • 简洁而模块化的 API 与 CLI：统一支持训练、推理、基准测试和超参数优化，无论是新手快速上手还是老手深度定制都能得心应手。
  • 最大规模的公开算法与数据集集合：提供了业界最丰富的即用型深度学习异常检测算法和基准数据集。
  • 基于 Lightning 的模型实现：大幅减少样板代码，让开发者的精力聚焦于算法本质而非工程细节。
  • 面向边缘部署的 OpenVINO 导出能力：大多数模型可导出为 OpenVINO 中间表示 (IR) 格式，在 Intel 硬件上实现加速推理。
  • 丰富的推理工具集：内置 Torch、Lightning、Gradio 和 OpenVINO 等多种推理器，方便快速部署标准或自定义异常检测模型。

二、本地安装指南

Anomalib 的安装方式灵活多样，支持 uv 和 pip 安装，也可以指定硬件后端以获得最佳性能。以下为你梳理几种最常见的安装场景。

2.1 基础安装

最简单的安装方式是通过 pip 或 uv 从 PyPI 直接获取最新版本及其核心依赖：

# 使用 uv
uv pip install anomalib

# 或使用 pip
pip install anomalib

该命令将自动安装 PyTorch 的默认发行版，通常适用于 CPU 推理和标准 CUDA 环境。如果希望获得更灵活的硬件后端控制（例如指定 CUDA 版本、ROCm、Intel XPU 等），Anomalib 提供了额外安装选项：

# 仅 CPU 支持（兼容所有平台）
uv pip install "anomalib[cpu]"

# CUDA 12.6 支持（Linux/Windows + NVIDIA GPU）
uv pip install "anomalib[cu126]"

# ROCm 支持（Linux + AMD GPU）
uv pip install "anomalib[rocm]"

# Intel XPU 支持（Linux + Intel GPU）
uv pip install "anomalib[xpu]"

pip 同样支持以上额外选项，例如 pip install "anomalib[cu126]"。

2.2 全量安装

如果需要使用所有模型和完整功能，推荐使用全量安装，一次性安装好所有可选依赖（如 python-dotenv、open_clip_torch、tensorboard 等），避免后续运行时缺依赖报错：

pip install "anomalib[full]"

这种方式适合希望完整体验 Anomalib 全部能力的用户。

2.3 从源码安装

如果你计划修改 Anomalib 源码或跟踪最新开发进展，可以从 GitHub 克隆仓库并本地安装：

git clone https://github.com/open-edge-platform/anomalib.git
cd anomalib
pip install -e .

-e 参数以可编辑模式安装，方便实时修改代码。对于国内用户，也可以通过 Gitee 镜像加速克隆。

2.4 版本情况

截至 2026 年 5 月，Anomalib 的最新稳定版本为 v2.4.1，已从 GitHub 仓库发布多轮迭代。最新版本在数据迁移路径、依赖安全更新和 DDP 训练等方面持续优化，建议始终使用最新版本以获得最佳体验。

三、数据准备：支持的数据集与自定义数据

3.1 内置数据集

Anomalib 内置了大量可直接使用的公开基准数据集，涵盖工业检测、视频监控等多个场景：

  • MVTec AD：工业异常检测领域的经典基准数据集，包含 15 个品类（纹理类和物体类），每个品类均提供像素级标注掩码，广泛用于评估异常检测和定位算法的性能。
  • MVTec AD 2：全新升级版 MVTec 数据集，涵盖 8 类工业异常检测场景。
  • MVTec LOCO AD：面向逻辑约束异常检测的数据集，包含结构性和逻辑性两类异常。
  • Real-IAD：真实工业多视角异常检测数据集，用于多功能工业场景的基准测试。
  • VAD (Valeo Anomaly Dataset)：覆盖从极其明显到极其微妙的多样缺陷，适合评估模型对不同严重程度的检测能力。

除了实体数据集，Anomalib 还内置了类型安全的数据类系统，基于 Python 原生 dataclass 扩展而来，提供输入验证和便捷的类型转换功能，贯穿整个数据处理流水线。

3.2 使用自定义数据集

在实际项目中，我们通常需要在自己的数据集上训练模型。Anomalib 提供了 Folder 数据模块，支持三种类型的自定义数据处理：

  1. 仅包含正常与异常图像的数据集（适用于分类任务）。
  2. 包含正常/异常图像及对应掩码标注的数据集（适用于像素级分割评估）。
  3. 已预先划分为训练集和测试集的数据集。

自定义数据集的目录结构应遵循以下规范：

dataset/
├── good/           # 训练用正常样本
│   ├── 001.png
│   └── 002.png
└── anomaly/        # 异常样本（用于测试/验证）
    ├── 003.png
    └── 004.png

通过 Folder 数据模块加载自定义数据集后，Anomalib 会自动创建训练、验证、测试和预测数据集与数据加载器。

四、模型训练：CLI 与 Python API 双模式

Anomalib 同时提供命令行接口（CLI）和 Python API 两种训练方式。CLI 方式更适合快速上手、开箱即用；API 方式则赋予开发者更大的灵活性和定制空间。

4.1 CLI 命令行方式

使用 CLI 进行训练非常简单。以下以 PatchCore 模型为例：

# 使用默认配置训练 PatchCore 模型（MVTec AD 数据集）
anomalib train --model Patchcore --data anomalib.data.MVTec

# 指定特定品类训练
anomalib train --model Patchcore --data anomalib.data.MVTec --data.category transistor

# 使用配置文件训练，实现完全自定义
anomalib train --config path/to/config.yaml

训练完成后，模型权重将保存为 PyTorch Lightning（.ckpt）格式，可直接用于后续的推理与评估。

4.2 Python API 方式

对于需要深度定制的场景，Python API 提供了完整的灵活度：

from anomalib.data import MVTec
from anomalib.models import Patchcore
from anomalib.engine import Engine

# 初始化数据模块、模型和引擎
datamodule = MVTec(
    root="./datasets/MVTec/",
    category="bottle",
    image_size=256,
    train_batch_size=32,
    eval_batch_size=32,
    num_workers=8,
    task="segmentation",
)
model = Patchcore()
engine = Engine()

# 开始训练
engine.fit(datamodule=datamodule, model=model)

通过 API 方式，你可以灵活调整数据模块的每一个参数，自定义模型骨干网络，甚至完全替换训练流程的某个环节。

4.3 配置文件方式

Anomalib 还支持通过 YAML 配置文件详细指定数据、模型和训练器的所有参数：

dataset:
  name: MVTec
  format: folder
  path: "./datasets/MVTec/"
  category: "bottle"
  image_size: 256
  train_batch_size: 32
  eval_batch_size: 32

model:
  name: Padim
  backbone: resnet18
  input_size: 256
  layers:
    - layer1
    - layer2
    - layer3

trainer:
  accelerator: auto
  devices: 1
  max_epochs: 10

然后在代码中加载配置并启动训练：

from anomalib.engine import Engine
from anomalib.data import MVTec
from anomalib.config import get_anomalib_config

config = get_anomalib_config("config.yaml")
datamodule = MVTec(**config.dataset)
engine = Engine(**config.trainer)
engine.train()

配置文件方式将数据路径、模型选型、训练参数等集中管理，方便团队协作和实验追踪，也是生产环境中的推荐实践。

五、模型推理

Anomalib 支持多种推理方式，覆盖从本地测试到边缘部署的完整链路。

5.1 Lightning 推理

利用训练好的 checkpoint 文件直接进行推理：

from anomalib.data import MVTec
from anomalib.models import Patchcore
from anomalib.engine import Engine

datamodule = MVTec()
model = Patchcore()
engine = Engine()

predictions = engine.predict(
    datamodule=datamodule,
    model=model,
    ckpt_path="path/to/model.ckpt",
)

CLI 方式同样简洁：

anomalib predict --model anomalib.models.Patchcore \
    --data anomalib.data.MVTec \
    --ckpt_path path/to/model.ckpt

如果需要返回预测结果（如异常分数、异常热力图等），可添加 --return_predictions 参数。

5.2 模型导出与部署

Anomalib 支持将模型导出为 Torch、ONNX 和 OpenVINO 三种格式，方便在不同硬件平台上高效部署：

# 导出为 Torch 格式
anomalib export --model Padim --export_type torch --ckpt_path <PATH_TO_CHECKPOINT>

# 导出为 ONNX 格式
anomalib export --model Padim --export_type onnx --ckpt_path <PATH_TO_CHECKPOINT>

# 导出为 OpenVINO IR 格式（适合 Intel 硬件加速）
anomalib export --model Padim --export_type openvino --ckpt_path <PATH_TO_CHECKPOINT>

导出后，可以借助 OpenVINO Inferencer 或 PyTorch Inferencer 高效运行推理。多数模型支持导出为 OpenVINO 中间表示 (IR) 格式，在 Intel CPU/GPU/VPU 上获得数倍加速。此外，Anomalib 还内置了 Gradio 推理器，支持快速搭建 Web 演示界面。

六、更多功能特性

6.1 算法阵营

Anomalib 实现了丰富的算法家族，涵盖无监督和半监督两大类。支持的模型包括但不限于：

  • PatchCore：基于核心集采样的特征嵌入方法，高效且性能优异。
  • PaDiM (Patch Distribution Modeling)：通过多元高斯分布建模局部图像块的正常模式，实现精细的异常定位。
  • FastFlow：以 2D 归一化流为概率模型的快速且可解释的异常检测方法。
  • CFLOW-AD：基于条件归一化流的实时无监督异常定位方法。
  • DFKDE / DFM：基于深度特征核密度估计的无监督异常检测方法，无需复杂训练直接利用预训练特征统计检测异常。
  • DRÆM：基于判别训练的重建嵌入方法，结合合成数据生成与判别网络，在少样本场景中表现出色。
  • EfficientAD：面向边缘设备设计的轻量级异常检测模型，在保持高精度同时大幅降低推理开销。
  • U-Flow：集成U-Net风格的归一化流模型，专为高分辨率异常定位设计。

此外，深度学习方法还可搭配传统机器学习模块实现更丰富的后处理与结果分析。

6.2 实验结果与分析

官方提供了完整的基准测试工具，能够一键复现已知论文结果，自动生成包括 AUROC、F1 分数在内的详细指标报告。用户可以通过简单的 CLI 命令启动基准测试，对比不同模型在相同数据集上的表现差异：

# 使用基准测试工具在 MVTec AD 上运行 PaDiM 模型
anomalib benchmark --config path/to/benchmark_config.yaml

训练过程中生成的可视化结果包括异常热力图、预测掩码以及性能曲线，便于研究人员和工程师直观理解模型的优劣，并借此迭代优化检测策略。此外，Anomalib 还集成了超参数优化（HPO）功能，支持自动搜索最佳模型配置。

6.3 社区生态与发展

Anomalib 由 Intel 团队积极维护，拥有活跃的社区生态。截至目前，官方 GitHub 仓库已发布 41 个版本，拥有超过 1,200 个已关闭的问题和持续的 PR 贡献。用户可以通过 GitHub Discussions 和 Issues 与开发者直接互动、提交反馈或贡献代码。

该项目的学术论文 Anomalib: A Deep Learning Library for Anomaly Detection 已在 arXiv 上公开发布，读者可以引用该论文来支持使用 Anomalib 进行的学术研究。

七、总结

Anomalib 是目前工业界和学术界最全面、最活跃的视觉异常检测开源库之一。它提供了一套从数据准备、模型训练、推理部署到基准测试的完整工具链，极大地降低了异常检测技术的使用门槛。

快速回顾核心要点：

维度 关键特性
安装方式 pip/uv 一键安装，支持 CPU/CUDA/ROCm/XPU 多后端
训练方式 CLI 命令行 + Python API + YAML 配置文件三重方式
数据支持 MVTec AD、MVTec AD 2、Real-IAD 等内置数据集 + 自定义 Folder 格式
模型阵容 PaDiM、PatchCore、FastFlow、EfficientAD、CFLOW-AD 等 SOTA 算法
推理部署 支持 Torch/ONNX/OpenVINO 多格式导出，内置 Gradio/OpenVINO 推理器

无论你是刚入门异常检测的研究者，还是需要在产线上快速落地缺陷检测方案的工程师，Anomalib 都能为你提供开箱即用的强大支持。得益于其活跃的社区和持续的版本迭代，你可以始终站在异常检测技术的最前沿。

参考资料：Anomalib 官方文档 anomalib.readthedocs.io | GitHub 仓库 open-edge-platform/anomalib

# 深度学习 # 人工智能
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

Java 内存模型（JMM）深度解析

在一个线程内，书写在前面的操作先行发生于书写在后面的操作。虽然 CPU 会为了性能进行指令重排，但 JMM 承诺"单线程执行结果的正确性"（即 as-if-serial 语义）。

avatar AtomGit开源社区
cover

OpenAI 推出的 GPT-5.5 大模型@ACP#IX6012应用迭代

avatar AtomGit开源社区
cover

鸿蒙 Flutter 实战：video_compress 3.1.4 适配 3.27-ohos 全流程

avatar AtomGit开源社区