PaddleSeg QualityInspector 工业质检快速上手：Magnetic-Tile 缺陷检测+RoI分割+后处理全流程实战

• 人工智能
• 计算机视觉
• 预训练

本指南以 Magnetic-tile-defect-datasets（磁瓦表面缺陷数据集）为例，演示 PaddleSeg 仓库下工业质检全流程解决方案 QualityInspector 的完整使用链路：从数据集下载与格式转换，到目标检测与 RoI 分割模型的训练验证，再到「检测+RoI分割+后处理」串联方案的全流程预测，以及工业级过杀/漏检指标评估与后处理参数调优。读完本文，你将能够独立复现一套端到端的工业缺陷质检流水线，并掌握用规则后处理算子控制 NG/OK 判定、优化落地指标的方法。

1 QualityInspector 与快速开始前置知识

QualityInspector 是 PaddleSeg 仓库中面向工业质检场景的全流程解决方案开发工具，目标是把从数据标注到模型部署的工业质检应用做成"可配置、可评估、可调优"的闭环。与单独使用 PaddleSeg / PaddleDetection 不同，它额外补齐了三块工业场景刚需能力：

• 统一可配置的解决方案：支持检测、分割单模型，以及"检测+RoI分割+后处理"串联方案，通过修改 yml 配置即可组合视觉套件的模型；
• 工业级指标评估与调优：直接评估工业质检项目实际落地的过杀（Overkill）/漏检（Escape）指标，并可只调后处理规则参数实现指标一键调优，无需重新推理；
• 数据工具链：提供检测、分割 / RoI 分割任务的数据格式转化脚本，以及数据分析工具。

本快速开始文档以Magnetic-tile-defect-datasets公开数据集为样例数据，选用目标检测（Faster R-CNN + HRNet）+ RoI 分割（OCRNet + HRNet）+ 后处理的串联解决方案，展示完整的落地流程。所有命令均在PaddleSeg/contrib/QualityInspector/目录下执行。

2 安装说明

QualityInspector 的环境要求如下（详见 install.md）：

• PaddlePaddle（版本不低于 2.3）
• PaddleDetection、PaddleSeg
• 64 位操作系统，Python 3（3.5.1+/3.6/3.7/3.8/3.9）64 位版本
• pip/pip3（9.0.1+）64 位版本
• CUDA >= 10.1、cuDNN >= 7.6

克隆 PaddleSeg 仓库并进入 QualityInspector 目录：

git clone https://github.com/PaddlePaddle/PaddleSeg.git cd contrib/QualityInspector/

执行如下命令完成 PaddleDetection、PaddleSeg 等第三方库的安装：

pip install -r requirements.txt

安装完成后，后续所有数据准备、训练、验证、预测、评估命令均以PaddleSeg/contrib/QualityInspector/为当前工作目录。

3 准备数据集：三步完成工业数据格式化

工业数据集没有统一组织形式，QualityInspector 提供脚本把原始缺陷数据逐步转换成不同任务所需的训练格式。

3.1 下载原始数据集

建立dataset文件夹，前往 Magnetic-tile-defect-datasets 下载数据集并放置于./dataset/路径下。该数据集来自论文 "Saliency of magnetic tile surface defects"，收集了 6 类常见磁瓦图像（其中 Free 为正常 OK 图）并做了像素级标注。原始目录结构如下：

Magnetic-Tile-Defect | |--MT_Blowhole | |--Imgs | | |--exp1_xxx.jpg / exp1_xxx.png ... |--MT_Break | |--Imgs ... |--MT_Free | |--Imgs |--MT_Uneven | |--Imgs ...

3.2 转换为全图分割训练数据格式

运行 tools/dataset/MT_dataset.py 将原始数据转换为标准的 PaddleSeg 分割训练格式：

python3 tools/dataset/MT_dataset.py --dataset_path ./dataset/Magnetic-Tile-Defect --output_path ./dataset/MT_dataset/

转换后的数据集结构如下：

MT_dataset | |--images | |--train / val # exp1_xxx.jpg ... |--annos | |--train / val # exp1_xxx.png（像素级标注） |--train.txt / val.txt # 原图与标签图像的相对路径

其中train.txt、val.txt保存了原图及其对应标签图像的相对路径，PaddleSeg 的 Dataset 即通过该文件列表加载数据。

3.3 转为 COCO 格式供检测训练

检测任务需要 COCO 格式的 json 标注文件。运行 tools/convert_tools/convert_mask_to_coco.py：

python3 tools/convert_tools/convert_mask_to_coco.py --image_path dataset/MT_dataset/images/train --anno_path dataset/MT_dataset/annos/train --class_num 5 --label_file dataset/MT_dataset/mt_catIDs.json --output_name dataset/MT_dataset/train.json --suffix .png

说明：磁瓦缺陷共 5 类（除去背景），因此--class_num 5；命令执行后 json 保存在dataset/MT_dataset/train.json。将--image_path、--anno_path和--output_name中的train改为val再执行一次，即可得到验证集dataset/MT_dataset/val.json。

3.4 切割 RoI 区域供 RoI 分割训练

检测+RoI 分割方案需要把全图分割标签裁切为 RoI 区域。运行 tools/convert_tools/convert_mask_to_RoI.py：

python3 tools/convert_tools/convert_mask_to_roi.py --image_path dataset/MT_dataset/images/train --anno_path dataset/MT_dataset/annos/train --class_num 5 --output_path dataset/MT_dataset/RoI/train/ --suffix .png --to_binary

执行后数据保存在dataset/MT_dataset/RoI/train/，同样将train改为val得到验证集 RoI 分割数据。--to_binary表示将多类别标签二值化——RoI 分割模型只需区分"缺陷/非缺陷"，因此num_classes为 2。

更完整的参数说明可参考 数据准备详细教程 与 数据转换工具文档。

4 训练与验证检测 / 分割模型

数据就绪后，分别训练目标检测模型与 RoI 分割模型。两套算法配置文件分别位于configs/det/与configs/seg/下。

4.1 训练检测模型（Faster R-CNN + HRNet）

以 HRNet 为骨干的 Faster R-CNN 为例：

python3 tools/det/train.py -c configs/det/hrnet/faster_rcnn_hrnetv2p_w18_3x_defect.yml --use_vdl=true --vdl_log_dir=./vdl_dir/scalar --eval

多卡训练（以 2 卡为例）：

CUDA_VISIBLE_DEVICES=0,1 python3 -m paddle.distributed.launch tools/det/train.py -c configs/det/hrnet/faster_rcnn_hrnetv2p_w18_3x_defect.yml --use_vdl=true --vdl_log_dir=./vdl_dir/scalar --eval

训练模型保存在./output/faster_rcnn_hrnetv2p_w18_3x_defect/文件夹中。从 faster_rcnn_hrnetv2p_w18_3x_defect.yml 可以看到该配置基于defect_detection.yml数据集配置与faster_rcnn_hrnetv2p_w18.yml模型配置组合而成：epoch: 36、LearningRate.base_lr: 0.02、采用 PiecewiseDecay（milestones [8, 11]、gamma 0.1）+ LinearWarmup（start_factor 0.1、steps 1000）、TrainReader batch_size 16，BBoxPostProcess 使用 RCNNBox 解码 + MultiClassNMS（keep_top_k 100、score_threshold 0.2、nms_threshold 0.1）。

4.2 训练 RoI 分割模型（OCRNet + HRNet）

以 HRNet 为骨干的 OCRNet 为例，RoI 训练配置为 ocrnet_hrnetw18_RoI_defect_256x256_40k.yml：

python3 tools/seg/train.py --config configs/seg/ocrnet/ocrnet_hrnetw18_RoI_defect_256x256_40k.yml --do_eval --use_vdl --save_interval 100 --save_dir ./output/RoI/

多卡训练：

CUDA_VISIBLE_DEVICES=0,1 python3 -m paddle.distributed.launch --config configs/seg/ocrnet/ocrnet_hrnetw18_RoI_defect_256x256_40k.yml --do_eval --use_vdl --save_interval 100 --save_dir ./output/RoI/

关键配置项说明：

• train_path: dataset/MT_dataset/RoI/train/RoI.txt、val_path: dataset/MT_dataset/RoI/val/RoI.txt：RoI 分割训练/验证文件列表路径；
• num_classes: 2：二分类（缺陷/背景）；
• 模型type: OCRNet，骨干HRNet_W18（pretrained使用 hrnet_w18_ssld 预训练权重），backbone_indices: [0]；
• 训练增强：ResizeStepScaling（0.5~2.0，步长 0.25）、RandomPaddingCrop（256x256）、随机水平/垂直翻转、RandomDistort；
• 损失默认使用两个DiceLoss（weight [0.4, 0.6]，coef [1, 0.4]），针对缺陷与背景像素不均衡的场景；配置中同时保留了CrossEntropyLoss（weight [0.3, 0.7]）的注释版本可供切换；
• 优化器 SGD（momentum 0.9、weight_decay 4e-5），PolynomialDecay学习率（lr 0.001、power 0.9）。

训练模型保存在./output/RoI/中。

4.3 验证指标（AP / mIoU）

检测模型验证（-c指定配置文件，-o覆盖配置文件中的全局变量，如权重路径；当前仅支持单卡评估）：

python3 tools/det/eval.py -c configs/det/hrnet/faster_rcnn_hrnetv2p_w18_3x_defect.yml -o weights=./output/faster_rcnn_hrnetv2p_w18_3x_defect/model_final.pdparams

RoI 分割模型验证（使用训练中保存的best_model/model.pdparams）：

python3 tools/seg/val.py --config configs/seg/ocrnet/ocrnet_hrnetw18_RoI_defect_256x256_40k.yml --model_path ./output/RoI/best_model/model.pdparams

4.4 说明

为了简化，QualityInspector 只保留了部分算法配置文件，但 PaddleDetection / PaddleSeg 中集成的任意算法均可使用——只需将对应算法的 config 文件放入./configs/det/或./configs/seg/即可接入同一套训练、验证工具链。

5 全流程预测：检测+RoI分割+后处理串联推理

检测 AP、分割 mIoU 只能衡量单模型能力，工业落地更关心零件级的 NG/OK 判定。全流程预测通过tools/end2end/predict.py串联整条流水线，输出实例级与图像级的 NG/OK 信息。

5.1 准备全流程配置文件

全流程配置文件按模块化定义，包含环境（ENV）、流水线（PipeLine）、检测、分割/RoI 分割以及后处理等模块。configs/end2end/下提供了三种常用工业质检 PPL：

• e2e_det.yml：检测+后处理；
• e2e_seg.yml：分割+后处理；
• e2e_det_RoI_seg.yml：检测+RoI分割+后处理。

本案例选用./configs/end2end/e2e_det_RoI_seg.yml，完整内容如下：

ENV: device: gpu # 运行环境 output_dir: ./output_det_roi/ # 保存预测 json 和可视化图像的路径 save: True # 保存 json 文件 visualize: False # 是否可视化 PipeLine: - Detection: # 检测模块 config_path: ./configs/det/hrnet/faster_rcnn_hrnetv2p_w18_3x_defect.yml model_path: ./output/faster_rcnn_hrnetv2p_w18_3x_defect/model_final.pdparams score_threshold: 0.01 # 只输出置信度大于 0.01 的 bbox - CropSegmentation: # RoI 区域分割模块 pad_scale: 0.5 # 根据检测 box 裁剪 RoI 区域时边长扩大的倍数 config_path: ./configs/seg/ocrnet/ocrnet_hrnetw18_RoI_defect_256x256_40k.yml model_path: ./output/seg_roi/best_model/model.pdparams aug_pred: True # 是否多尺度+Flip 推理 - PostProcess: # 后处理模块（按顺序串联执行） - JudgeDetByScores: # 置信度判断 score_threshold: 1: 0.1 # {class_id: threshold}，低于阈值判为 OK 5: 0.2 - JudgeByLengthWidth: # 边长判断 len_thresh: 0 # 长或宽小于该值判为 OK - JudgeByArea: # 面积判断 area_thresh: 1: 10 # 分割像素数小于该值判为 OK

各模块参数作用：

• ENV.device：gpu/cpu等运行环境；save、visualize控制是否保存预测 json 与可视化图。
• Detection.score_threshold：检测阶段过滤低置信度 bbox，降低后处理负担。
• CropSegmentation.pad_scale：按检测框外扩比例裁剪 RoI，避免缺陷贴边被裁掉。
• PostProcess下的算子在 qinspector/ops/postprocess.py 中实现，按配置顺序依次对每个预测实例执行，任一规则判定为 OK 即将其isNG置 0：
  • JudgeDetByScores：score_threshold支持 dict（按category_id设置不同阈值）或单一数值，预测得分低于阈值判为 OK；
  • JudgeByLengthWidth：bbox 的 w（bbox[2]）或 h（bbox[3]）小于len_thresh判为 OK，用于过滤过小的检出；
  • JudgeByArea：存在area字段（分割方案输出）时按分割像素数判断，否则回退到 bbox 面积（w×h）判断，用于过滤面积过小的预测。

5.2 执行全流程预测

使用tools/end2end/predict.py对./dataset/MT_dataset/images/val下所有图像进行预测：

python3 tools/end2end/predict.py --config ./configs/end2end/e2e_det_RoI_seg.yml --input ./dataset/MT_dataset/images/val --output_dir ./output_det_roi/

--input也支持单张图像路径，例如：

python3 tools/end2end/predict.py --config ./configs/end2end/e2e_det_RoI_seg.yml --input ./dataset/MT_dataset/images/val/exp5_num_10250.jpg --output_dir ./output_det_roi/

脚本参数说明（源码见 tools/end2end/predict.py）：

脚本内部通过ArgsParser解析参数后构造Pipeline并调用pipeline.run(inputs)；设备选择逻辑会根据 Paddle 的编译选项自动回退（如未编译 CUDA 则落到 cpu）。

5.3 输出结果解析

执行后得到预测结果 json 与可视化文件，保存在./output_det_roi/。当ENV.save与ENV.visualize为True时，会看到：

Pipeline INFO: Save prediction to ./output_det_roi/output.json Pipeline INFO: Visualize prediction to ./output_det_roi/show/

output.json以每张输入图像路径为 key、预测结果为 value：

{ "dataset/MT_dataset/images/val/exp6_num_127730.png": { "isNG": 0, "pred": [] }, "dataset/MT_dataset/images/val/exp5_num_155415.jpg": { "isNG": 1, "pred": [ { "category_id": 2, "category_name": "Break", "bbox": [0.0, 6.75, 190.86, 78.03], "score": 0.28, "isNG": 1 }, { "category_id": 5, "category_name": "Uneven", "bbox": [0.0, 156.82, 195.0, 154.17], "score": 0.01, "isNG": 0 } ] } }

字段说明：

• isNG（图像级）：该图是否存在缺陷，1 为缺陷图，0 为正常图；
• pred：缺陷实例级预测结果列表，每项包含category_id（缺陷类别 id）、category_name（缺陷名）、bbox（x, y, w, h）、score（预测框得分）与实例级isNG；
• 若采用分割或检测+RoI 分割配置，输出中还会增加polygon和area字段（由分割分支产出，供面积类后处理算子使用）。

可视化图像中包含 box、polygon（使用分割时）、类别、置信度与 NG 信息。

6 全流程评估：过杀/漏检指标与 badcase 分析

模型的 AP/mIoU 无法直观评估一套工业质检方案是否可落地，QualityInspector 因此提供工业界常用的**过杀（Overkill）与漏检（Escape）**指标评估，并支持 badcase 可视化与后处理参数调优。

6.1 执行评估

对./dataset/MT_dataset/val.json（GT 为 COCO 格式）中的每一张图像进行评估，--pred_path为第 5 步全流程预测得到的output.json：

python3 tools/end2end/eval.py --input_path ./dataset/MT_dataset/val.json --pred_path ./output_det_roi/output.json --config ./configs/end2end/e2e_det_RoI_seg.yml --rules_eval --image_root ./

参数说明（源码见 tools/end2end/eval.py）：

6.2 三类核心指标解读

过杀指标（OK Evaluation）：对 GT 为 OK（正常）的图像，统计被判为 NG 的比例。

+----------+--------+----------+-------+-------+-------+--------+ | OK | ALL | Blowhole | Break | Crack | Fray | Uneven | +----------+--------+----------+-------+-------+-------+--------+ | Total | 318 | 318 | 318 | 318 | 318 | 318 | | OK | 267 | 316 | 306 | 318 | 318 | 281 | | NG | 51 | 2 | 12 | 0 | 0 | 37 | | Overkill | 16.04% | 0.63% | 3.77% | 0.00% | 0.00% | 11.64% | +----------+--------+----------+-------+-------+-------+--------+

Total是 OK 图像总数，Overkill = NG/Total，每个类别下的 NG 数指包含该类别 NG 预测 box/mask 的图像数量。

图像级漏检指标（Image-Level Escape）：对 GT 为 NG 的图像，统计没有任何 NG 预测的比例。

+--------------+-------+-----+----+--------+ | Image Level | Total | NG | OK | Escape | +--------------+-------+-----+----+--------+ | Lucky Result | 132 | 118 | 14 | 10.61% | +--------------+-------+-----+----+--------+

Total是 NG 图像总数，NG表示图像存在任意一个预测为 NG 的 box/mask（不关注位置或类别是否正确，可称作 Lucky Recall），OK表示图像无任何 NG 预测，Escape = OK/Total。

实例级别漏检指标（Instance-Level Escape）：对 GT 的每个缺陷实例，统计没有可匹配（iou 大于--iou_theshold）的 NG 预测的比例。

+----------+--------+----------+--------+--------+-------+--------+ | NG | ALL | Blowhole | Break | Crack | Fray | Uneven | +----------+--------+----------+--------+--------+-------+--------+ | Total | 151 | 39 | 41 | 24 | 13 | 34 | | NG | 127 | 36 | 31 | 20 | 12 | 28 | | OK | 24 | 3 | 10 | 4 | 1 | 6 | | Escape | 15.89% | 7.69% | 24.39% | 16.67% | 7.69% | 17.65% | +----------+--------+----------+--------+--------+-------+--------+

6.3 badcase 可视化输出

badcase 输出保存在output路径下，目录按过杀/漏检、类别、图像分层组织：

output | |--overkill # 过杀文件夹 | |--Break / Uneven ... # 预测出的过杀类别，内含可视化的过杀图像 |--escape # 漏检文件夹 | |--image_level # 图像级别漏检：图像没有任何预测结果 | |--instance_level # 实例级别漏检：图像上某个/多个缺陷漏检 | |--Break / Uneven ... # 漏检的真实缺陷类别，内含可视化图像

6.4 后处理参数调优（无需重新推理）

零件缺陷的判断标准常与缺陷位置、大小、长度等相关。为过滤不满足 NG 条件的检出、降低过杀，可在全流程 yml 中配置三种后处理算子（qinspector/ops/postprocess.py）：

• JudgeDetByScores：按置信度判断；
• JudgeByLengthWidth：按边长（bbox 宽或高）判断；
• JudgeByArea：按面积（分割像素数或 bbox 面积）判断。

调优流程：查看指标输出与 badcase 可视化后，修改./configs/end2end/e2e_det_RoI_seg.yml中PostProcess模块的参数，然后必须带上--config与--rules_eval重新执行评估命令，才能让新的后处理参数生效（模型预测结果无需重新计算）。

例如：初次评估发现 Uneven 类别过杀高达 11.64%，可调高JudgeDetByScores.score_threshold中第 5 类（Uneven）的阈值（如 0.01 → 0.2），重新评测后过杀明显下降：

+----------+-------+----------+-------+-------+-------+--------+ | OK | ALL | Blowhole | Break | Crack | Fray | Uneven | +----------+-------+----------+-------+-------+-------+--------+ | Total | 318 | 318 | 318 | 318 | 318 | 318 | | OK | 298 | 316 | 306 | 318 | 318 | 312 | | NG | 20 | 2 | 12 | 0 | 0 | 6 | | Overkill | 6.29% | 0.63% | 3.77% | 0.00% | 0.00% | 1.89% | +----------+-------+----------+-------+-------+-------+--------+

过杀从 16.04% 降到 6.29%，但通常伴随一定程度的漏失上升。用户可根据项目对漏失/过杀的目标要求，在阈值间做权衡迭代。

7 扩展阅读与注意事项

• 数据准备的完整细节（含MT_dataset.py转换逻辑、convert_mask_to_coco.py与convert_mask_to_RoI.py参数）见 prepare_data.md 与 conver_tools.md；
• 检测/分割训练的更多说明见 train_eval.md，全流程配置与预测/评估细节见 parse_config.md、predict.md、eval.md；
• 后续处理判断逻辑补充说明：GT 图像是否为 NG 的判断依据是输入 json 中是否存在标注框，有标注框即视为 NG 图像；
• QualityInspector 还支持无监督异常检测算法（详见 docs/uad/README.md），可与本案例的监督方案互为补充；
• 当前版本暂未支持端到端部署，模型部署可参考 PaddleDetection 与 PaddleSeg 的部署方案（如 deploy/python/infer.py 等）；
• 使用约束：文中命令与配置文件均以当前仓库（QualityInspector V0.5 预览版）为准，检测模型验证目前仅支持单卡评估。

• 人工智能
• 计算机视觉
• 预训练