Anomalib RealIAD Datamodule：以 PyTorch Lightning 加载 Real-IAD 工业异常检测数据集

Anomalib RealIAD Datamodule：以 PyTorch Lightning 加载 Real-IAD 工业异常检测数据集

【免费下载链接】anomalibAn anomaly detection library comprising state-of-the-art algorithms and features such as experiment management, hyper-parameter optimization, and edge inference.项目地址: https://gitcode.com/GitHub_Trending/an/anomalib

本文围绕 Anomalib 中的RealIADDatamodule 展开，介绍如何下载并准备需要作者审批授权的 Real-IAD 工业异常检测数据集、配置类别与分辨率等核心参数，并从源码层面解析其元数据解析、数据划分与任务类型推断的实现机制。读完本文后，你可以直接在 API 或 YAML 配置中构建 Real-IAD 训练/测试流程，并理解底层RealIADDataset如何把 JSON 元数据转化为可训练的样本表。

1. RealIAD Datamodule 概述

Real-IAD 是一个大规模工业异常检测数据集，包含 30 类工业物体，每类均包含正常（OK）与异常（NG）样本，且每个物体从 5 个不同的相机视角（C1–C5）拍摄。Anomalib 通过 PyTorch Lightning 风格的 DataModule 封装了该数据集，模块定义位于 src/anomalib/data/datamodules/image/realiad.py，并在 src/anomalib/data/datamodules/image/init.py 中导出，因此可以直接from anomalib.data import RealIAD使用。

与 MVTec AD 等可以目录约定直接推断样本的数据集不同，Real-IAD 的样本组织以JSON 元数据文件为核心：train/test 的样本列表、图像路径、掩码路径、异常类别和相机视角都记录在 JSON 中。Datamodule 的构造函数签名与完整参数说明如下（源自模块 docstring 与源码签名，见 realiad.py#L156-L172）：

其中 30 个可选类别和 4 个分辨率档位是硬编码在底层数据集模块中的常量（src/anomalib/data/datasets/image/realiad.py#L47-L79）：

• 分辨率：RESOLUTIONS = ("256", "512", "1024", "raw")，对应realiad_256、realiad_512、realiad_1024目录及原始分辨率目录；
• 类别：audiojack、bottle_cap、button_battery、end_cap、eraser、fire_hood、mint、mounts、pcb、phone_battery、plastic_nut、plastic_plug、porcelain_doll、regulator、rolled_strip_base、sim_card_set、switch、tape、terminalblock、toothbrush、toy_brick、toy、transistor1、u_block、usb_adaptor、usb、vcpill、wooden_beads、woodstick、zipper。

2. 数据集目录结构

模块 docstring 中明确给出了 Real-IAD 的目录布局（realiad.py#L12-L22），下载完成后根目录应包含以下子目录：

Real-IAD/ ├── realiad_256/ # 256x256 分辨率图像 │ └── CATEGORY/ # 如 audiojack、button_battery 等 │ ├── OK/ # 正常样本 │ │ └── SXXXX/ # 样本 ID │ │ └── CATEGORY_XXXX_OK_CX_TIMESTAMP.jpg │ └── NG/ # 异常样本 │ └── DEFECT_TYPE/ # 缺陷类型 │ └── SXXXX/ │ ├── CATEGORY_XXXX_NG_CX_TIMESTAMP.jpg │ └── CATEGORY_XXXX_NG_CX_TIMESTAMP_mask.png ├── realiad_512/ # 512x512 分辨率图像 ├── realiad_1024/ # 1024x1024 分辨率图像 └── realiad_jsons/ # JSON 元数据文件 ├── realiad_jsons/ # 基础元数据（多视角） ├── realiad_jsons_sv/ # 单视角元数据 └── realiad_jsons_fuiad/ # FUIAD 系列元数据（0.0/0.1/0.2/0.4 版本）

从结构可以看出三点关键事实：

1. 图像按分辨率 → 类别 → OK/NG → 样本 ID分层组织，异常样本按缺陷类型再细分目录；
2. 文件名编码了类别_ID_OK|NG_视角C1-C5_时间戳，异常样本额外附带_mask.png分割掩码；
3. 样本的 train/test 归属不靠目录名，而是由 JSON 元数据决定。

3. 下载与准备数据集：需要作者审批授权

Real-IAD 不随 Anomalib 分发，且需要数据集作者审批后才能访问。Datamodule 的prepare_data方法（realiad.py#L206-L233）会检查root下是否存在任一必需目录（realiad_256/realiad_512/realiad_1024或各realiad_jsons*目录），若全部缺失则抛出RuntimeError，错误信息即为完整的下载指引，由 get_download_instructions 函数格式化生成。该指引的核心内容如下：

申请访问流程：Real-IAD 数据集托管在 Hugging Face 上（数据集标识为REAL-IAD/Real-IAD）。由于需要审批，你需要：

1. 注册 Hugging Face 账号；
2. 打开该数据集页面，点击 "Access Repository" 并填写申请表；
3. 等待数据集作者审批通过；
4. 审批通过后下载并解压到目标目录。

下载方式一：Hugging Face CLI（推荐）

# 安装 CLI pip install huggingface_hub # 登录 huggingface-cli login # 下载数据集到 root 目录 huggingface-cli download \ --repo-type dataset \ --local-dir ./datasets/Real-IAD REAL-IAD/Real-IAD \ --include="*" \ --token YOUR_HF_TOKEN

下载方式二：手动下载：在审批通过后进入数据集页面手动下载全部文件，并解压到 root 目录。

注意事项：

• 将YOUR_HF_TOKEN替换为你的 Hugging Face 访问令牌（在个人设置页的 tokens 页面生成）；
• 该数据集以 Creative Commons Attribution-NonCommercial-ShareAlike 4.0（CC BY-NC-SA 4.0）协议发布，使用前请遵守其非商业与相同方式共享条款；
• resolve_dataset_root（src/anomalib/utils/path.py#L118-L129）决定了 root 的最终取值：显式传入root时直接使用，传None时回退到 anomalib 数据集缓存目录下的Real-IAD。

4. 实操示例：构建与使用 RealIAD Datamodule

以下示例继承自模块 docstring 的官方用法（realiad.py#L93-L146），全部可复制运行（前提是数据集已就位）。

4.1 默认配置创建

from anomalib.data import RealIAD datamodule = RealIAD() # root=./datasets/Real-IAD, category=audiojack, resolution=256 datamodule.setup() i, data = next(enumerate(datamodule.train_dataloader())) data.keys() # dict_keys(['image_path', 'label', 'image', 'mask_path', 'mask']) data["image"].shape # torch.Size([32, 3, 256, 256])

4.2 切换类别与分辨率

字符串与整数分辨率等价，Datamodule 内部会把整数resolution转为字符串（realiad.py#L190-L194）：

# 使用字符串分辨率 datamodule = RealIAD( category="button_battery", resolution="512", ) # 使用整数分辨率 datamodule = RealIAD( category="button_battery", resolution=1024, )

4.3 选择不同的 JSON 元数据

json_path支持{category}占位符，初始化时会被格式化为实际类别名（src/anomalib/data/datasets/image/realiad.py#L201-L206）。常用组合：

# 基础元数据（多视角） datamodule = RealIAD( json_path="realiad_jsons/realiad_jsons/{category}.json", ) # 单视角元数据 datamodule = RealIAD( json_path="realiad_jsons/realiad_jsons_sv/{category}.json", ) # FUIAD v0.4 元数据（筛选子集） datamodule = RealIAD( json_path="realiad_jsons/realiad_jsons_fuiad_0.4/{category}.json", ) # 自定义元数据文件 datamodule = RealIAD( json_path="path/to/custom/metadata.json", )

4.4 从测试集派生验证集

datamodule = RealIAD( val_split_mode=ValSplitMode.FROM_TEST, val_split_ratio=0.1, )

5. 通过 YAML 配置使用

Anomalib 的流水线（pipeline）体系支持以 YAML 配置实例化任意 DataModule，仓库提供的官方配置见 examples/configs/data/realiad.yaml：

class_path: anomalib.data.RealIAD init_args: root: ./datasets/Real-IAD category: audiojack resolution: 256 train_batch_size: 32 eval_batch_size: 32 num_workers: 8 test_split_mode: none val_split_mode: same_as_test train_augmentations: null val_augmentations: null test_augmentations: null augmentations: null

这份配置与构造函数默认值一一对应，即"开箱默认"的加载方式：audiojack类别、256 分辨率、32 batch、不使用增强、test_split_mode: none（直接使用 JSON 中的 test 划分）、val_split_mode: same_as_test（验证集与测试集相同）。由于class_path采用anomalib.data.RealIAD这一公开路径，你可以将该配置作为基准，按需覆盖category、resolution或json_path等init_args字段。

6. 源码解析：从 Datamodule 到样本 DataFrame

6.1 Datamodule 层的职责

RealIAD继承自AnomalibDataModule（src/anomalib/data/datamodules/base/image.py#L59-L94），自身只负责三件事：

1. 参数校验：构造函数中检查category in CATEGORIES与resolution in RESOLUTIONS，否则抛出带可选值列表的ValueError（realiad.py#L197-L204）；
2. 数据就位检查：prepare_data在训练前验证数据集目录存在（前文第 3 节已述）；
3. 构建子数据集：_setup分别以Split.TRAIN与Split.TEST创建两个RealIADDataset（realiad.py#L235-L249），随后基类的setup会进一步执行_create_test_split与_create_val_split，按test_split_mode/val_split_mode对样本表做动态切分。

值得注意：RealIAD没有覆写test_dataloader的增强/合成逻辑，test_split_mode默认为NONE——也就是说，JSON 元数据里的 test 列表就是测试集本身，这是该数据集区别于 MVTec AD（常需from_dir/synthetic模式）的重要特性。

6.2 RealIADDataset：解析 JSON 元数据

底层RealIADDataset（src/anomalib/data/datasets/image/realiad.py#L82-L230）在初始化时完成以下工作：

1. 校验category与resolution（同 Datamodule 层，因为 Dataset 也可独立使用）；
2. 将json_path中的{category}占位符格式化后拼接root，若文件不存在抛出FileNotFoundError；
3. 加载 JSON 并校验结构：元数据必须是dict且至少包含train或test键，否则抛出ValueError（realiad.py#L216-L219）；
4. 依据分辨率定位类别目录：self.root / f"realiad_{resolution}" / category，然后调用make_realiad_dataset生成样本表。

make_realiad_dataset（realiad.py#L233-L294）是样本组织的核心逻辑：

• 按split从元数据取train或test列表；若split为None则合并两者；
• 每条样本转换为四列 DataFrame：image_path（类别目录下的相对路径）、mask_path（无掩码时为空串）、label_index（anomaly_class == "OK"为正常，否则为异常）、split（train/test）；
• 任务类型推断：若所有样本mask_path均为空，samples.attrs["task"]置为classification，否则为segmentation（realiad.py#L291-L292）。这意味着使用单视角或 FUIAD 元数据、且样本不带掩码时，同一 Dataset 也能支撑仅分类头的训练，任务类型由数据本身决定。

6.3 与基类增强机制的衔接

基类AnomalibDataModule.setup在构建子集后会调用_update_augmentations：若模型 PreProcessor 提供 transform，则把其中的Resize提取出来前置到数据增强链中，保证 resize 发生在 collate 之前，以降低 DataLoader worker 的共享内存占用（src/anomalib/data/datamodules/base/image.py#L166-L200）。因此给RealIAD传train_augmentations时，只需关注裁剪、翻转等图像内容级增强，尺寸归一化会与模型变换自动协调。

7. 测试验证：单测与模拟数据

仓库用两条链路验证了上述机制：

• Datamodule 单测tests/unit/data/datamodule/image/test_realiad.py：继承通用图像 Datamodule 测试基类_TestAnomalibImageDatamodule，以category="audiojack"、resolution=256、num_workers=0构造RealIAD，先prepare_data后setup，并声明其数据配置文件即examples/configs/data/realiad.yaml——这意味着 CI 会按该 YAML 的默认配置校验整个加载流程；
• 模拟数据集生成tests/helpers/data.py#L595-L649：_generate_dummy_realiad_dataset按真实约定生成realiad_256/audiojack/图像、realiad_jsons/realiad_jsons/元数据，其中 NG 样本同时写出图像与_mask.png掩码，JSON 中记录image_path、mask_path、anomaly_class、camera_view、timestamp字段。对比该生成逻辑与make_realiad_dataset的解析字段，可以确认元数据的最小必需字段为image_path、mask_path、anomaly_class三项。

8. 实践要点与限制

结合源码实现，使用 RealIAD Datamodule 时应注意：

1. 必须手动下载：prepare_data只做存在性检查并给出指引，Anomalib 不提供该数据集的自动下载器；且访问需作者审批，首次准备数据的等待时间不可控；
2. JSON 元数据是必需的：make_realiad_dataset对metadata is None直接抛出ValueError，不能像某些数据集那样仅靠目录约定；自定义元数据时字段需与解析逻辑对齐；
3. 默认验证集即测试集：val_split_mode默认SAME_AS_TEST，如需独立验证集请显式设置FROM_TEST并指定val_split_ratio；
4. 分辨率档位有限：只接受256/512/1024/raw四档，其他值会触发ValueError；图像目录名realiad_{resolution}与档位一一绑定；
5. 许可合规：CC BY-NC-SA 4.0 意味着衍生作品需以相同协议共享且限于非商业用途，商用场景需另行评估。

9. 小结

RealIADDatamodule 通过 "JSON 元数据 + 分辨率目录 + 类别目录" 三要素组织 Real-IAD 数据集：Datamodule 层负责参数校验与目录就位检查，底层RealIADDataset负责元数据解析、样本表构建与任务类型推断，基类AnomalibDataModule则统一了 split 与增强逻辑。借助 examples/configs/data/realiad.yaml 或 API 直接实例化，即可把该数据集接入 Anomalib 的训练与推理流水线；核心源码集中在 src/anomalib/data/datamodules/image/realiad.py 与 src/anomalib/data/datasets/image/realiad.py，可进一步对照阅读。

【免费下载链接】anomalibAn anomaly detection library comprising state-of-the-art algorithms and features such as experiment management, hyper-parameter optimization, and edge inference.项目地址: https://gitcode.com/GitHub_Trending/an/anomalib