SA-MoE-DefectDet

基于形态感知稀疏专家融合的钢材表面缺陷实时检测方法研究。

本项目围绕 NEU-DET + Ultralytics YOLO + SA-MoE 主线展开，目标不是把工程做成单纯的 RF-DETR 复现，而是先把钢材表面缺陷检测的完整主流程跑通，并在此基础上实现形态专家、轻量 Router、Top-k 稀疏激活和专家融合推理。

说明：本开源仓库默认不直接附带 NEU-DET 原始数据、训练权重和大体量运行产物；请根据文中给出的路径与脚本自行准备数据并复现实验。

1. 项目目标

本工程当前支持以下研究任务：

• 基于 NEU-DET 原始 XML 标注重建数据集，并重新生成 YOLO 格式标签
• 按 70/15/15 重新划分 train / val / test
• 训练 YOLO11n 与 YOLO11s baseline
• 训练三个形态专家模型：
  • expert_line：crazing, scratches
  • expert_point：inclusion, pitted_surface
  • expert_region：patches, rolled-in_scale
• 基于形态统计特征拟合轻量 Router
• 支持 Average / Top-1 / Top-2 / All Experts 多种专家激活模式
• 支持 NMS / WBF 两种融合方式
• 自动汇总实验表格、统计图、论文图和展示图
• 提供一个本地 UI，用于上传钢材表面图像并自动识别缺陷

2. 方法主线

完整流程如下：

1. 从原始 NEU-DET 的 XML 标注读取真值框。
2. 将图像与标注转换为标准 YOLO 检测格式。
3. 重新构建 70/15/15 数据集并生成配置文件。
4. 训练 YOLO11n、YOLO11s baseline。
5. 基于形态划分训练三类专家模型。
6. 从输入图像提取边缘密度、灰度标准差、拉普拉斯方差、局部方差等特征。
7. Router 输出三位专家的权重。
8. 按 Top-1 / Top-2 / All 激活专家并完成融合推理。
9. 输出检测结果、实验表格、可视化图与论文图。

3. 文件夹架构与作用

3.1 总体目录树

SA-MoE-DefectDet/
├─ configs/
│  ├─ datasets/
│  │  └─ neu_det_701515.yaml            # 主数据集 YAML
│  └─ experts/
│     ├─ expert_line.yaml               # 线状专家配置
│     ├─ expert_point.yaml              # 点状专家配置
│     └─ expert_region.yaml             # 区域专家配置
├─ data/
│  ├─ raw/
│  │  └─ neu_det_index/
│  │     ├─ dataset_index.csv           # 原始 XML/图像索引
│  │     ├─ index_summary.json          # 数据统计与校验摘要
│  │     ├─ split_manifest.json         # 固定随机种子的划分清单
│  │     └─ experts/                    # 各专家训练图像列表
│  └─ processed/
│     └─ neu_det_yolo_701515/
│        ├─ train/
│        │  ├─ images/
│        │  └─ labels/
│        ├─ val/
│        │  ├─ images/
│        │  └─ labels/
│        └─ test/
│           ├─ images/
│           └─ labels/
├─ results/
│  ├─ figures/                          # 论文图、统计图、展示图
│  ├─ predictions/                      # SA-MoE 推理标签、可视化、路由轨迹
│  ├─ router/                           # Router 特征、中心、统计结果
│  └─ tables/                           # 实验总表 CSV/Markdown
├─ runs/                                # Ultralytics 训练与验证原始产物
├─ scripts/                             # PowerShell 一键脚本
├─ src/
│  └─ sa_moe_defectdet/
│     ├─ app/                           # 本地 Gradio 演示 UI
│     ├─ data/                          # 数据转换、重划分、校验
│     ├─ eval/                          # 指标计算与结果汇总
│     ├─ infer/                         # 多专家推理与融合
│     ├─ router/                        # Router 特征提取与拟合
│     ├─ train/                         # baseline / expert 训练入口
│     └─ viz/                           # 论文图和展示图生成
├─ sa_moe_defectdet/                    # 兼容层，便于直接 python -m 运行
├─ pyproject.toml
├─ requirements.txt
└─ README.md

3.2 各目录详细说明

configs/

用于保存训练和推理所需的配置文件：

• configs/datasets/neu_det_701515.yaml
  • 定义主数据集路径、类别名、train/val/test
• configs/experts/*.yaml
  • 定义三位专家对应的数据子集与类别语义

data/raw/neu_det_index/

这是“原始数据索引层”，不存原始图像，而是保存从 XML 提取出来的结构化信息：

• dataset_index.csv
  • 每张图像、每个 XML、类别和框信息的索引表
• split_manifest.json
  • 固定随机种子后的数据划分清单，保证实验可复现
• index_summary.json
  • 数据数量、类别统计、样例框变换结果、划分校验信息
• experts/*.txt
  • 三个专家各自训练图像列表

data/processed/neu_det_yolo_701515/

这是正式用于训练和测试的 YOLO 数据集。
原始 NEU-DET 不会被改动，所有派生结果都放在这里：

• train/images, train/labels
• val/images, val/labels
• test/images, test/labels

当前主线数据集规模为：

• train: 1260
• val: 270
• test: 270

runs/

保存 Ultralytics 原生训练输出，偏“过程记录”：

• weights/best.pt, weights/last.pt
• results.csv, results.png
• confusion_matrix.png
• confusion_matrix_normalized.png
• train_batch*.jpg
• val_batch*_pred.jpg

这里更适合保留训练日志和原始结果。

results/

保存“可用于论文、答辩、汇总展示”的二次结果，偏“最终产出”：

• results/tables/
  • 总实验表
  • 各方法对比表
  • 消融实验表
• results/router/
  • Router 特征与专家中心
• results/predictions/
  • SA-MoE 推理标签
  • 可视化检测图
  • router_trace.json
• results/figures/
  • 正规论文中的统计图、流程图、热图、消融图、拼图等

一个很重要的区分是：

• runs/：训练工具原始输出
• results/：论文和汇报层面的整理结果

src/sa_moe_defectdet/

这是项目真正的源码目录：

• data/
  • 数据检查、XML 转 YOLO、70/15/15 重划分
• train/
  • baseline 与专家训练入口
• router/
  • 形态特征提取、Router 拟合、权重计算
• infer/
  • 多专家推理、Top-k 激活、NMS/WBF 融合
• eval/
  • mAP、Precision、Recall、AP 等指标计算与汇总
• viz/
  • 自动生成论文图与展示图
• app/
  • 本地缺陷识别 UI

根目录 sa_moe_defectdet/

这个目录不是重复源码，而是一个兼容层。
它的作用是让你在没有执行 pip install -e . 的情况下，也能直接在项目根目录运行：

python -m sa_moe_defectdet.data.prepare_neu_det

真正实现仍然在 src/sa_moe_defectdet/ 里。

4. 环境安装

建议在项目根目录执行：

python -m pip install -r requirements.txt

如果你使用可编辑安装方式：

python -m pip install -e .

如果需要 WBF：

python -m pip install ensemble-boxes

如果需要本地 UI：

python -m pip install gradio

5. 数据准备

原始数据默认路径：

C:\Users\a\Downloads\Steel-surface-defect-detection-main\Steel-surface-defect-detection-main\NEU-DET

执行数据重建与划分：

python -m sa_moe_defectdet.data.prepare_neu_det `
  --source "C:\Users\a\Downloads\Steel-surface-defect-detection-main\Steel-surface-defect-detection-main\NEU-DET" `
  --output "D:\archive\SA-MoE-DefectDet\data\processed\neu_det_yolo_701515" `
  --seed 42 `
  --overwrite

这一步会完成：

• 读取 XML 真值框
• 转换 YOLO 标签
• 构建 train / val / test
• 保存索引文件与划分清单
• 生成主数据集 YAML 和专家配置 YAML

6. 训练入口

6.1 YOLO11n baseline

python -m sa_moe_defectdet.train.run_baseline `
  --model yolo11n.pt `
  --data configs/datasets/neu_det_701515.yaml `
  --epochs 100 `
  --imgsz 224 `
  --batch 32 `
  --device 0 `
  --name baseline_yolo11n

6.2 YOLO11s baseline

python -m sa_moe_defectdet.train.run_baseline `
  --model yolo11s.pt `
  --data configs/datasets/neu_det_701515.yaml `
  --epochs 100 `
  --imgsz 224 `
  --batch 24 `
  --device 0 `
  --name baseline_yolo11s

6.3 三个形态专家

python -m sa_moe_defectdet.train.run_expert --expert line   --model yolo11n.pt --epochs 80 --device 0
python -m sa_moe_defectdet.train.run_expert --expert point  --model yolo11n.pt --epochs 80 --device 0
python -m sa_moe_defectdet.train.run_expert --expert region --model yolo11n.pt --epochs 80 --device 0

7. Router 与融合推理

拟合 Router：

python -m sa_moe_defectdet.router.fit_router

运行多专家融合：

python -m sa_moe_defectdet.infer.run_moe --mode average --fusion nms
python -m sa_moe_defectdet.infer.run_moe --mode top1    --fusion nms
python -m sa_moe_defectdet.infer.run_moe --mode top2    --fusion nms
python -m sa_moe_defectdet.infer.run_moe --mode all     --fusion nms
python -m sa_moe_defectdet.infer.run_moe --mode all     --fusion wbf

8. 结果汇总

生成实验总表：

python -m sa_moe_defectdet.eval.collect_results

输出：

• results/tables/experiment_results.csv
• results/tables/experiment_results.md

9. 论文图、统计图与展示图

生成全部图表：

python -m sa_moe_defectdet.viz.generate_figures

当前会输出一整套图到：

results/figures/

包括但不限于：

• method_pipeline.png
  • 方法总流程图，适合放在论文方法部分
• dataset_split_distribution.png
  • 数据集划分与目标级统计图
• class_gallery.png
  • 六类缺陷样例图板
• main_metrics_bar.png
  • 主结果柱状图
• accuracy_latency_tradeoff.png
  • 精度-延迟权衡图
• per_class_ap_heatmap.png
  • 各类别 AP 热图
• per_class_grouped_bar.png
  • 各类别 AP 分组柱状图
• ablation_panels.png
  • Top-k、融合方式、单模型/多专家消融图
• yolo_training_curves.png
  • YOLO11n 与 YOLO11s 收敛曲线对比
• confusion_matrix_panel.png
  • 两个 baseline 的归一化混淆矩阵对比
• router_pca.png
  • Router 特征空间投影图
• router_radar.png
  • 专家中心雷达图
• expert_center_heatmap.png
  • 专家中心热图
• router_weight_heatmap.png
  • 各类别平均路由权重热图
• expert_activation_frequency.png
  • Top-2 稀疏激活频次图
• router_feature_distributions.png
  • Router 特征分布图
• moe_visual_comparison_grid.jpg
  • 多种专家模式检测结果拼图
• experiment_dashboard.png
  • 汇报型综合大图

10. 本地自动识别 UI

启动本地界面：

python -m sa_moe_defectdet.app.demo --host 127.0.0.1 --port 7860

UI 支持：

• 上传钢材表面图像
• 切换 YOLO11n / YOLO11s / SA-MoE
• 切换 Average / Top-1 / Top-2 / All Experts
• 切换 NMS / WBF
• 输出检测图、候选框表格、Router 权重

11. 当前结果说明

当前工程已经跑通并保存了如下结果：

• baseline_yolo11n
• baseline_yolo11s
• expert_line_yolo11n
• expert_point_yolo11n
• expert_region_yolo11n
• moe_average_nms
• moe_top1_nms
• moe_top2_nms
• moe_all_nms
• moe_all_wbf

主表位于：

• results/tables/experiment_results.csv

12. 注意事项

• 不会修改或删除原始 NEU-DET 数据目录。
• 当前数据转换默认以 XML 为唯一真值来源。
• 少量图像含有多类框；当前划分采用“文件名前缀对应主类”的分层策略，同时保留全部目标框用于检测训练和评估。
• 如果 YOLO11s 显存不足，优先下调 batch，不要随意改动主线结构。
• 如果 WBF 依赖缺失或效果不稳定，可以先保留 NMS 作为主线实验结果。
• 如果你只想做论文图和展示图，优先关注 results/figures/、results/tables/ 和 README.md 这三部分。