anomalib 模型训练完全指南从 Engine API 到 Folder 自定义数据集与 CLI 实战【免费下载链接】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 的anomalib-training技能文档系统讲解如何在 anomalib 中完成一次完整的模型训练从 Python API 使用anomalib.engine.Engine封装 LightningTrainer训练标准基准数据集如 MVTecAD到用Folderdatamodule 零代码训练自定义目录数据集再到通过anomalibCLI 一条命令完成训练与配置覆盖。读完本文你将掌握 Engine 的核心方法调用链、Folder 目录结构的组织规范、Trainer 参数的传入方式含 XPU 加速以及调试训练时的结果目录定位技巧。训练总入口一切训练都经由Engine在 anomalib 中无论是 Python API 还是 CLI所有训练流程都统一经过anomalib.engine.Engine—— 它是 PyTorch LightningTrainer的一层封装负责在标准训练/测试流程之上叠加异常检测特有的逻辑指标计算与日志、checkpoint 保存、模型导出、分布式训练支持等。从 engine.py 的类定义可以看到Engine的核心构造参数是callbacks、logger、default_root_dir以及通过**kwargs透传的全部 LightningTrainer参数。这种设计意味着没有独立的 Trainer 配置对象 需要构造——你需要的一切训练行为accelerator、devices、strategy、max_epochs、logger、callbacks、enable_checkpointing、val_check_interval、barebones等都是Engine(**kwargs)的普通关键字参数会被直接缓存并最终用于实例化底层Trainer见 engine.py 的_setup_trainer。Python API 训练标准基准数据集MVTecAD使用标准基准数据集训练是验证 anomalib 流程的最快方式。以 MVTecAD 为例完整流程如下from anomalib.data import MVTecAD from anomalib.models import Patchcore from anomalib.engine import Engine datamodule MVTecAD(root./datasets/MVTecAD, categorybottle, train_batch_size32) model Patchcore() engine Engine() # 任何 Lightning Trainer kwarg 都可以放在这里 engine.fit(modelmodel, datamoduledatamodule) results engine.test(modelmodel, datamoduledatamodule)MVTecAD指定数据集根目录与子类categorytrain_batch_size控制训练批次大小Patchcore()直接实例化模型无需额外配置engine.fit(...)完成训练engine.test(...)在测试集上评估并返回结果字典列表每个 dataloader 一个 dict。Engine 的核心方法Engine围绕训练生命周期提供以下关键方法签名详见 engine.py方法作用关键参数fit(model, datamodule...)训练拟合模型train_dataloaders/val_dataloaders/datamodule/ckpt_pathtrain(...)一次调用完成 fit test与 fit 相同的参数另加test_dataloaderstest(modelNone, datamodule...)在测试集上评估dataloaders/ckpt_path/verbosepredict(modelNone, datamodule..., dataset..., data_path...)推理预测支持传dataset或data_path图片路径/文件夹一个重要约定如果在test/predict中省略model/datamoduleEngine 会自动复用之前传给fit的那一份。例如先engine.fit(modelmodel, datamoduledatamodule)再直接engine.test()即可。predict的data_path参数还支持直接指向单张图片或一个文件夹见 engine.py内部会将其包装为PredictDataset再构建 DataLoader。Python API 训练自定义数据Folder datamodule当你的数据以普通文件夹形式组织无需编写任何数据集代码时使用Folderdatamodule 即可。其目录布局约定为root/normal_dir/*正常样本、root/abnormal_dir/*异常样本可选以及root/mask_dir/*逐像素分割掩码可选。该结构在 folder.py 的 docstring 中有明确说明root/ ├── normal_dir/ │ ├── image1.png │ └── image2.png ├── abnormal_dir/ │ ├── image3.png │ └── image4.png └── mask_dir/ ├── mask3.png └── mask4.png对应的训练代码from anomalib.data import Folder from anomalib.models import Padim from anomalib.engine import Engine datamodule Folder( namecustom, # 必填 —— 用作 datamodule 的显示名称 root./datasets/custom, normal_dirgood, # 必填 abnormal_dirdefect, # 可选启用异常测试/评估样本 mask_dirmask, # 可选启用像素级分割评估 train_batch_size32, eval_batch_size32, num_workers8, ) model Padim() engine Engine() engine.fit(modelmodel, datamoduledatamodule)Folder 的目录组织规则与参数细节从 Folder 构造函数 可以梳理出完整的参数语义normal_dir必填正常训练图像所在目录abnormal_dir可选异常图像目录提供后测试/评估集才包含异常样本使图像级分类指标有意义normal_test_dir可选专门用于测试集的独立正常图像目录mask_dir可选与异常图像一一对应的掩码目录提供后评估从图像级分类切换为像素级分割指标normal_split_ratio默认 0.2在没有独立正常测试图像时从正常训练图像中切出测试集的比例test_split_mode默认TestSplitMode.FROM_DIR/test_split_ratio默认 0.2测试集划分方式与比例val_split_mode默认ValSplitMode.FROM_TEST/val_split_ratio默认 0.5验证集划分方式与比例extensions纳入的图像扩展名过滤train_batch_size默认 32、eval_batch_size默认 32、num_workers默认 8控制数据加载seed划分数据集时使用的随机种子。如果只有正常训练图像、且测试集也是正常或无标注图像直接省略abnormal_dir和mask_dir。此时Folder会通过test_split_ratio从正常训练图像中按比例切出一部分作为测试集仍然能产生合法的 train/test 划分。若你有专门用于测试的正常图像目录则用normal_test_dir指定。Folder在内部通过FolderDataset构建 train/test 数据见 folder.py其训练集和测试集 batch 都会包含image、label、mask、image_path、mask_path字段便于后续可视化和调试。CLI 命令行训练除了 Python APIanomalib 提供了基于 jsonargparse 的完整 CLI入口为anomalib命令实现位于 cli.py 的AnomalibCLI类。常用训练命令如下# 标准数据集默认参数 anomalib train --model Patchcore --data anomalib.data.MVTecAD # 覆盖 datamodule 字段 anomalib train --model Patchcore --data anomalib.data.MVTecAD --data.category transistor # 覆盖 trainer 字段max_epochs 对梯度训练模型如 Stfpm 才有意义 anomalib train --model anomalib.models.Stfpm --data anomalib.data.MVTecAD --trainer.max_epochs 3 # 从 CLI 训练自定义 Folder 数据集 anomalib train --model Padim --data anomalib.data.Folder \ --data.name custom --data.root ./datasets/custom \ --data.normal_dir good --data.abnormal_dir defect # 从配置文件启动jsonargparse可与上面任意覆盖项组合 anomalib train --config path/to/config.yamlCLI 的接线原理--model/--data之所以既能接受短名Padim又能接受完整类路径anomalib.models.Padim、anomalib.data.Folder是因为AnomalibCLI通过parser.add_subclass_arguments将AnomalibModule和AnomalibDataModule暴露为 jsonargparse 的 subclass 参数见 cli.py。CLI 还支持以下子命令见 cli.pytrain拟合模型后紧接着调用 testpredict对模型进行推理--data可传数据集类路径或直接传图片/文件夹路径export将模型导出为 ONNX 或 OpenVINO 格式fit/validate/test对应 Lightning Trainer 的原始子命令install安装 anomalib 的完整或可选依赖。命令行里通过--trainer.max_epochs 3这样的点号路径直接覆盖 Trainer 参数通过--data.category transistor覆盖 datamodule 字段所有覆盖项都可以与--config配置文件组合使用。选择 accelerator / devices含 Intel XPU加速器与设备选择同样是标准的 Lightning 关键字参数直接传给Engine(...)即可acceleratorgpu|cpu|xpu选择计算后端devices1使用的设备数量。针对 Intel XPU 这一特殊后端anomalib 在anomalib.engine命名空间中专门导出了SingleXPUStrategy与XPUAccelerator见 engine/init.py组合方式如下from anomalib.engine import Engine, SingleXPUStrategy, XPUAccelerator engine Engine(strategySingleXPUStrategy(), acceleratorXPUAccelerator())对应的底层实现位于 accelerator/xpu.py 与 strategy/xpu_single.py。在 CLI 中同样可以通过--trainer.accelerator xpu --trainer.strategy ...风格的参数完成配置。训练中的常见坑Gotchas1. 非梯度模型也会走engine.fit(...)并非所有模型都通过梯度下降训练——像Padim、Patchcore这类免训练training-free模型同样需要调用engine.fit(...)此时Engine/Trainer只会执行构建记忆库所需的单次 epoch不需要任何特殊代码。但需要注意这些模型通过各自的trainer_arguments属性覆盖默认训练参数。例如 Padim 的 trainer_arguments 返回{max_epochs: 1, val_check_interval: 1.0, num_sanity_val_steps: 0, devices: 1}。Engine 内部通过_TrainerArgumentsCache在实例化 Trainer 前用模型参数覆盖用户传入值并打印类似Overriding max_epochs from 100 with 1 for Padim的日志见 engine.py。因此对这类模型你传给Engine的max_epochs会被模型自身的trainer_arguments覆盖——想控制训练轮数请选择 Stfpm、Cflow 等真正梯度训练的模型。2.mask_dir决定评估粒度Folder的mask_dir是图像级分类指标与像素级分割指标之间的开关只有传入mask_dir才会启用像素级 ground-truth 评估。仅当你确实拥有逐像素掩码标注时才传入该参数否则应省略。3. 结果输出到哪里default_root_dir训练的产出物checkpoint、日志、可视化图像统一写入Engine的default_root_dir默认值为results即当前目录下的results文件夹。Engine 的_setup_workspace会按模型名 / 数据集名 / category的层级嵌套子目录见 engine.py并额外生成版本化目录。调试训练运行异常时应优先到这个目录下排查results/ └── Padim/ └── custom/ └── (category)/ ├── weights/lightning/ # 模型 checkpoint ├── images/ # 可视化输出 └── ... # 日志等在 CLI 中可通过--default_root_dir覆盖该路径见 cli.py。源码级自检清单Reviewer / self-check结合 anomalib-training 技能文档 的检查项在编写或调试训练脚本时可逐条核对Engine(...)接收的是 Trainer 覆盖参数普通 kwargs而不是手工构造的Trainer对象Folder 数据集训练时normal_dir以及如适用abnormal_dir/mask_dir与实际磁盘目录布局一致CLI 调用使用的anomalib.data.Class/anomalib.models.Class路径确实在anomalib命名空间中导出模型与 datamodule 的导出机制分别见.agents/skills/anomalib-adding-a-model/SKILL.md与.agents/skills/anomalib-adding-a-datamodule/SKILL.md。相关资源anomalib-training 技能文档本文依据的原始技能说明Engine 源码Engine 完整实现与所有方法签名Folder datamodule 源码Folder 参数与目录结构定义AnomalibCLI 源码CLI 子命令与参数解析实现XPU 加速实现Intel XPU 加速器与单卡策略源码MVTecAD datamodule标准基准数据集的 datamodule 实现可作为自定义数据集的参考模板。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 anomalib 模型训练完全指南：从 Engine API 到 Folder 自定义数据集与 CLI 实战
anomalib 模型训练完全指南从 Engine API 到 Folder 自定义数据集与 CLI 实战【免费下载链接】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 的anomalib-training技能文档系统讲解如何在 anomalib 中完成一次完整的模型训练从 Python API 使用anomalib.engine.Engine封装 LightningTrainer训练标准基准数据集如 MVTecAD到用Folderdatamodule 零代码训练自定义目录数据集再到通过anomalibCLI 一条命令完成训练与配置覆盖。读完本文你将掌握 Engine 的核心方法调用链、Folder 目录结构的组织规范、Trainer 参数的传入方式含 XPU 加速以及调试训练时的结果目录定位技巧。训练总入口一切训练都经由Engine在 anomalib 中无论是 Python API 还是 CLI所有训练流程都统一经过anomalib.engine.Engine—— 它是 PyTorch LightningTrainer的一层封装负责在标准训练/测试流程之上叠加异常检测特有的逻辑指标计算与日志、checkpoint 保存、模型导出、分布式训练支持等。从 engine.py 的类定义可以看到Engine的核心构造参数是callbacks、logger、default_root_dir以及通过**kwargs透传的全部 LightningTrainer参数。这种设计意味着没有独立的 Trainer 配置对象 需要构造——你需要的一切训练行为accelerator、devices、strategy、max_epochs、logger、callbacks、enable_checkpointing、val_check_interval、barebones等都是Engine(**kwargs)的普通关键字参数会被直接缓存并最终用于实例化底层Trainer见 engine.py 的_setup_trainer。Python API 训练标准基准数据集MVTecAD使用标准基准数据集训练是验证 anomalib 流程的最快方式。以 MVTecAD 为例完整流程如下from anomalib.data import MVTecAD from anomalib.models import Patchcore from anomalib.engine import Engine datamodule MVTecAD(root./datasets/MVTecAD, categorybottle, train_batch_size32) model Patchcore() engine Engine() # 任何 Lightning Trainer kwarg 都可以放在这里 engine.fit(modelmodel, datamoduledatamodule) results engine.test(modelmodel, datamoduledatamodule)MVTecAD指定数据集根目录与子类categorytrain_batch_size控制训练批次大小Patchcore()直接实例化模型无需额外配置engine.fit(...)完成训练engine.test(...)在测试集上评估并返回结果字典列表每个 dataloader 一个 dict。Engine 的核心方法Engine围绕训练生命周期提供以下关键方法签名详见 engine.py方法作用关键参数fit(model, datamodule...)训练拟合模型train_dataloaders/val_dataloaders/datamodule/ckpt_pathtrain(...)一次调用完成 fit test与 fit 相同的参数另加test_dataloaderstest(modelNone, datamodule...)在测试集上评估dataloaders/ckpt_path/verbosepredict(modelNone, datamodule..., dataset..., data_path...)推理预测支持传dataset或data_path图片路径/文件夹一个重要约定如果在test/predict中省略model/datamoduleEngine 会自动复用之前传给fit的那一份。例如先engine.fit(modelmodel, datamoduledatamodule)再直接engine.test()即可。predict的data_path参数还支持直接指向单张图片或一个文件夹见 engine.py内部会将其包装为PredictDataset再构建 DataLoader。Python API 训练自定义数据Folder datamodule当你的数据以普通文件夹形式组织无需编写任何数据集代码时使用Folderdatamodule 即可。其目录布局约定为root/normal_dir/*正常样本、root/abnormal_dir/*异常样本可选以及root/mask_dir/*逐像素分割掩码可选。该结构在 folder.py 的 docstring 中有明确说明root/ ├── normal_dir/ │ ├── image1.png │ └── image2.png ├── abnormal_dir/ │ ├── image3.png │ └── image4.png └── mask_dir/ ├── mask3.png └── mask4.png对应的训练代码from anomalib.data import Folder from anomalib.models import Padim from anomalib.engine import Engine datamodule Folder( namecustom, # 必填 —— 用作 datamodule 的显示名称 root./datasets/custom, normal_dirgood, # 必填 abnormal_dirdefect, # 可选启用异常测试/评估样本 mask_dirmask, # 可选启用像素级分割评估 train_batch_size32, eval_batch_size32, num_workers8, ) model Padim() engine Engine() engine.fit(modelmodel, datamoduledatamodule)Folder 的目录组织规则与参数细节从 Folder 构造函数 可以梳理出完整的参数语义normal_dir必填正常训练图像所在目录abnormal_dir可选异常图像目录提供后测试/评估集才包含异常样本使图像级分类指标有意义normal_test_dir可选专门用于测试集的独立正常图像目录mask_dir可选与异常图像一一对应的掩码目录提供后评估从图像级分类切换为像素级分割指标normal_split_ratio默认 0.2在没有独立正常测试图像时从正常训练图像中切出测试集的比例test_split_mode默认TestSplitMode.FROM_DIR/test_split_ratio默认 0.2测试集划分方式与比例val_split_mode默认ValSplitMode.FROM_TEST/val_split_ratio默认 0.5验证集划分方式与比例extensions纳入的图像扩展名过滤train_batch_size默认 32、eval_batch_size默认 32、num_workers默认 8控制数据加载seed划分数据集时使用的随机种子。如果只有正常训练图像、且测试集也是正常或无标注图像直接省略abnormal_dir和mask_dir。此时Folder会通过test_split_ratio从正常训练图像中按比例切出一部分作为测试集仍然能产生合法的 train/test 划分。若你有专门用于测试的正常图像目录则用normal_test_dir指定。Folder在内部通过FolderDataset构建 train/test 数据见 folder.py其训练集和测试集 batch 都会包含image、label、mask、image_path、mask_path字段便于后续可视化和调试。CLI 命令行训练除了 Python APIanomalib 提供了基于 jsonargparse 的完整 CLI入口为anomalib命令实现位于 cli.py 的AnomalibCLI类。常用训练命令如下# 标准数据集默认参数 anomalib train --model Patchcore --data anomalib.data.MVTecAD # 覆盖 datamodule 字段 anomalib train --model Patchcore --data anomalib.data.MVTecAD --data.category transistor # 覆盖 trainer 字段max_epochs 对梯度训练模型如 Stfpm 才有意义 anomalib train --model anomalib.models.Stfpm --data anomalib.data.MVTecAD --trainer.max_epochs 3 # 从 CLI 训练自定义 Folder 数据集 anomalib train --model Padim --data anomalib.data.Folder \ --data.name custom --data.root ./datasets/custom \ --data.normal_dir good --data.abnormal_dir defect # 从配置文件启动jsonargparse可与上面任意覆盖项组合 anomalib train --config path/to/config.yamlCLI 的接线原理--model/--data之所以既能接受短名Padim又能接受完整类路径anomalib.models.Padim、anomalib.data.Folder是因为AnomalibCLI通过parser.add_subclass_arguments将AnomalibModule和AnomalibDataModule暴露为 jsonargparse 的 subclass 参数见 cli.py。CLI 还支持以下子命令见 cli.pytrain拟合模型后紧接着调用 testpredict对模型进行推理--data可传数据集类路径或直接传图片/文件夹路径export将模型导出为 ONNX 或 OpenVINO 格式fit/validate/test对应 Lightning Trainer 的原始子命令install安装 anomalib 的完整或可选依赖。命令行里通过--trainer.max_epochs 3这样的点号路径直接覆盖 Trainer 参数通过--data.category transistor覆盖 datamodule 字段所有覆盖项都可以与--config配置文件组合使用。选择 accelerator / devices含 Intel XPU加速器与设备选择同样是标准的 Lightning 关键字参数直接传给Engine(...)即可acceleratorgpu|cpu|xpu选择计算后端devices1使用的设备数量。针对 Intel XPU 这一特殊后端anomalib 在anomalib.engine命名空间中专门导出了SingleXPUStrategy与XPUAccelerator见 engine/init.py组合方式如下from anomalib.engine import Engine, SingleXPUStrategy, XPUAccelerator engine Engine(strategySingleXPUStrategy(), acceleratorXPUAccelerator())对应的底层实现位于 accelerator/xpu.py 与 strategy/xpu_single.py。在 CLI 中同样可以通过--trainer.accelerator xpu --trainer.strategy ...风格的参数完成配置。训练中的常见坑Gotchas1. 非梯度模型也会走engine.fit(...)并非所有模型都通过梯度下降训练——像Padim、Patchcore这类免训练training-free模型同样需要调用engine.fit(...)此时Engine/Trainer只会执行构建记忆库所需的单次 epoch不需要任何特殊代码。但需要注意这些模型通过各自的trainer_arguments属性覆盖默认训练参数。例如 Padim 的 trainer_arguments 返回{max_epochs: 1, val_check_interval: 1.0, num_sanity_val_steps: 0, devices: 1}。Engine 内部通过_TrainerArgumentsCache在实例化 Trainer 前用模型参数覆盖用户传入值并打印类似Overriding max_epochs from 100 with 1 for Padim的日志见 engine.py。因此对这类模型你传给Engine的max_epochs会被模型自身的trainer_arguments覆盖——想控制训练轮数请选择 Stfpm、Cflow 等真正梯度训练的模型。2.mask_dir决定评估粒度Folder的mask_dir是图像级分类指标与像素级分割指标之间的开关只有传入mask_dir才会启用像素级 ground-truth 评估。仅当你确实拥有逐像素掩码标注时才传入该参数否则应省略。3. 结果输出到哪里default_root_dir训练的产出物checkpoint、日志、可视化图像统一写入Engine的default_root_dir默认值为results即当前目录下的results文件夹。Engine 的_setup_workspace会按模型名 / 数据集名 / category的层级嵌套子目录见 engine.py并额外生成版本化目录。调试训练运行异常时应优先到这个目录下排查results/ └── Padim/ └── custom/ └── (category)/ ├── weights/lightning/ # 模型 checkpoint ├── images/ # 可视化输出 └── ... # 日志等在 CLI 中可通过--default_root_dir覆盖该路径见 cli.py。源码级自检清单Reviewer / self-check结合 anomalib-training 技能文档 的检查项在编写或调试训练脚本时可逐条核对Engine(...)接收的是 Trainer 覆盖参数普通 kwargs而不是手工构造的Trainer对象Folder 数据集训练时normal_dir以及如适用abnormal_dir/mask_dir与实际磁盘目录布局一致CLI 调用使用的anomalib.data.Class/anomalib.models.Class路径确实在anomalib命名空间中导出模型与 datamodule 的导出机制分别见.agents/skills/anomalib-adding-a-model/SKILL.md与.agents/skills/anomalib-adding-a-datamodule/SKILL.md。相关资源anomalib-training 技能文档本文依据的原始技能说明Engine 源码Engine 完整实现与所有方法签名Folder datamodule 源码Folder 参数与目录结构定义AnomalibCLI 源码CLI 子命令与参数解析实现XPU 加速实现Intel XPU 加速器与单卡策略源码MVTecAD datamodule标准基准数据集的 datamodule 实现可作为自定义数据集的参考模板。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考