| --- |
| license: other |
| library_name: onnx |
| pipeline_tag: image-classification |
| tags: |
| - industrial |
| - defect-detection |
| - optical-filter |
| - quality-inspection |
| - onnx |
| --- |
| |
| # 滤光片外观质检 · 开箱即用推理包 |
|
|
| 暗场成像的 IR-CUT 滤光片裁片，判**良品 / 不良**，可选输出缺陷类型（划痕 / 麻点 / 崩边）。 |
|
|
| 推理端**不需要 PyTorch、不需要 timm、不需要 GPU**，只要 4 个 pip 包。 |
|
|
| --- |
|
|
| ## 📚 完整文档 |
|
|
| | 文件 | 内容 | |
| |---|---| |
| | [`docs/INDEX.md`](docs/INDEX.md) | **项目总索引**：四个仓库怎么选、三个核心结论、数据一览 | |
| | [`docs/REPRODUCE.md`](docs/REPRODUCE.md) | **完整复现指南**：环境、数据准备、逐个实验的命令与预期数字 | |
| | [`docs/FILES.md`](docs/FILES.md) | **逐文件使用说明**：41 个脚本、结果表字段、51 个训练产物目录 | |
| | [`docs/RESULTS.md`](docs/RESULTS.md) | **全部实验结果**：42 个模型完整榜单、分割 vs 分类同口径对决 | |
| | [`docs/AUDIT.md`](docs/AUDIT.md) | **诚实性审计**：四道审计的原理与结果，为什么这次的高分是真的 | |
| | [`docs/CAVEATS.md`](docs/CAVEATS.md) | ⚠ **已知问题与边界**，上线前必读（含我犯过的评估口径错误） | |
| | [`docs/REPOS.md`](docs/REPOS.md) | 四个仓库逐一说明与下载方式 | |
|
|
| --- |
|
|
| --- |
|
|
| ## 三种用法，任选 |
|
|
| ### A. 零安装 —— 单个可执行文件（推荐） |
|
|
| 目标机上**不需要 Python、不需要装任何东西**，下载一个文件就能跑。模型已打进二进制。 |
|
|
| ```bash |
| # CPU 版（145 MB，任何 x86_64 Linux 都能跑） |
| chmod +x binaries/filter-predict-cpu |
| ./binaries/filter-predict-cpu -i 图片目录/ -o result.xlsx |
| |
| # GPU 版（1.3 GB，自动用 CUDA；需要 NVIDIA 驱动 ≥ CUDA 12.x） |
| chmod +x binaries/filter-predict-gpu |
| ./binaries/filter-predict-gpu -i 图片目录/ -o result.xlsx |
| ``` |
|
|
| 实测速度：CPU **22 张/秒**，GPU（RTX 4090）**3608 张/秒**。 |
|
|
| ### B. Python 脚本（想改代码时用） |
|
|
| ```bash |
| pip install -r requirements.txt # onnxruntime numpy pillow openpyxl |
| python predict.py -i sample_images/ -o result.xlsx |
| ``` |
|
|
| ### C. 只要 ONNX，自己接 |
|
|
| `filter_binary.onnx` 输入 `float32[N,3,320,320]`，输出 `logits[N,2]`。 |
| 预处理必须与 `predict.py:preprocess()` 一致（等比缩放补零 → 灰世界白平衡 → 逐图 z-score），否则结果不可信。 |
|
|
| ### 单张图 |
| ```bash |
| python predict.py -i /path/to/filter_0001.png |
| ``` |
| ``` |
| 文件 : filter_0001.png |
| 判定 : 良品 |
| 不良概率: 0.0060 |
| ``` |
|
|
| ### 整个目录 → xlsx（递归扫描子目录） |
| ```bash |
| python predict.py -i /path/to/images/ -o result.xlsx |
| ``` |
| 输出表格：`图片名 | 判定 | 不良概率 | 相对路径` |
|
|
| ### 附带缺陷类型 |
| ```bash |
| python predict.py -i images/ -o result.xlsx --with-type |
| ``` |
| 多两列：`缺陷类型 | 类型置信度`（只对判为不良的填） |
|
|
| ### 不想装 openpyxl |
| 输出写 `.csv` 即可（UTF-8 BOM，Excel 直接双击能开）： |
| ```bash |
| python predict.py -i images/ -o result.csv |
| ``` |
|
|
| --- |
|
|
| ## 调判废松紧 |
|
|
| **只有一个参数可调：`--threshold`（不良概率的判废线）。** |
| 调高 → 判不良的更少，不良桶更纯，但漏检多。调低 → 抓得全，但误杀更多良品。 |
|
|
| 标定表（阈值在 val 集上定，test 锁箱只评一次；「产线 10%」是按产线不良率 10% 换算的）： |
|
|
| | 档位 | 阈值 | test 误报 | test 检出 | 不良桶混入良品 | 产线10%口径 | 每万片冤杀 | 每万片漏检 | |
| |---|---|---|---|---|---|---|---| |
| | 最严 | `0.787` | 4/185 | 95.5% | **1.83%** | 16.9% | 195 | 45 | |
| | 保守 | `0.509` | 8/185 | 98.7% | 3.49% | 28.3% | 389 | 13 | |
| | **平衡（默认）** | `0.459` | 8/185 | **99.1%** | 3.48% | 28.2% | 389 | 9 | |
| | 宽松 | `0.411` | 9/185 | 99.1% | 3.90% | 30.6% | 438 | 9 | |
| | 高召回 | `0.242` | 11/185 | 99.6% | 4.70% | 35.0% | 535 | 4 | |
|
|
| ```bash |
| python predict.py -i images/ -o r.xlsx --threshold 0.787 # 最严 |
| ``` |
|
|
| > **注意**：分数分布是双峰的，0.51~0.79 之间几乎是空的，所以中间档位区分度很低。 |
| > 真正有意义的选择是「最严 0.787」和「平衡 0.459」两档。 |
|
|
| --- |
|
|
| ## 模型与性能 |
|
|
| | | 判废模型 | 类型模型 | |
| |---|---|---| |
| | 文件 | `filter_binary.onnx` (16.8 MB) | `filter_4class.onnx` (85.1 MB) | |
| | 骨干 | mobilenetv3_large_100 (4.2M) | resnet34 (21.3M) | |
| | 输入 | 320×320 | 320×320 | |
| | 输出 | 良品 / 不良 | 良品 / 划痕 / 麻点 / 崩边 | |
| | test AUROC | **0.9913 ± 0.0049** | 0.9867 | |
| | test 平衡准确率 | 0.9746 | **0.9213** | |
|
|
| **速度**（实测，纯 CPU，无 GPU）：约 **20 张/秒**。有 GPU 会自动用（装 `onnxruntime-gpu` 即可），约 1500 张/秒。 |
|
|
| 四分类逐类召回（test）：划痕 88.0% / 崩边 94.1% / 良品 95.1% / 麻点 91.3% |
|
|
| --- |
|
|
| ## 这个模型可信吗 |
|
|
| **做过 4 道诚实性审计，全部通过：** |
|
|
| | 审计 | 结果 | |
| |---|---| |
| | 批次指纹强度 | 92% —— 图像里**确实**带着可区分批次的信息（有作弊空间） | |
| | **未见类「碎」检出** | **100%** —— 这一类整类从没进过训练，模型照样抓到 | |
| | 跨批次泛化 | 留整个批次当考卷，AUROC 0.9862 vs 同批次 0.9911，**只掉 0.005** | |
| | 冻结特征对照 | 只见良品的 kNN (0.9634) **打败** 用了标签的线性探针 (0.9461) —— 拿到标签没优势，说明没有可解锁的捷径 | |
|
|
| 这套审计不是形式：本项目上一代的图级分类模型曾拿到 AUROC=1.0，一测就发现它认的是"这张图来自哪个压缩包"，30 张目检干净的图全被打 0.999+。这一代是真的。 |
|
|
| --- |
|
|
| ## 已知边界（务必阅读） |
|
|
| - **验证样本量有限**：test 只有 185 张良品。0 误报的 95% 置信上界是 1.61%， |
| **无法证明产线级的低误杀率**。要证明误报率 <1%，需要约 300 张干净良品；<0.1% 需要约 3000 张。 |
| - **「不良桶混入良品」随产线不良率剧烈变化**。表里 test 口径 1.83%， |
| 换算到产线不良率 10% 就是 16.9%。**这个指标不是模型属性，必须绑定你的实际不良率才有意义。** |
| - **色调漂移未做压力测试**。原始数据存在采集配置的色调漂移（B 通道逐日 15→8→5）。 |
| 预处理里的逐图灰世界白平衡是为此设计的，但**没有在真实漂移上验证过**。 |
| 上线建议固定白平衡，并监控良品分数分布。 |
| - **不可擦拭脏污检出仅约 53%**。这一类"擦不擦得掉"是物理属性， |
| 单张图像原理上判不了，训练时已整类排除。 |
| - **训练数据的良品标签本身约 3.3% 存疑**（漏标的真缺陷）。误报数字受此影响。 |
| - 输入图假定是**已裁到单片边界的暗场图**，原始尺寸 300~360px 量级。整版图或明场图不适用。 |
|
|
| --- |
|
|
| ## 文件清单 |
|
|
| ``` |
| binaries/ |
| filter-predict-cpu 零安装可执行文件，145 MB，CPU，22 张/秒 |
| filter-predict-gpu 零安装可执行文件，1.3 GB，CUDA，3608 张/秒 |
| predict.py 推理脚本（需自备 4 个 pip 包） |
| filter_binary.onnx 判废模型 + filter_binary.json（含阈值标定表） |
| filter_4class.onnx 类型模型 + filter_4class.json |
| requirements.txt 4 个 pip 包 |
| sample_images/ 22 张样例图（来自锁箱 test，从未参与训练） |
| weights/ PyTorch 原始权重（.pt，需 timm + torch 才能加载） |
| results/ 全部实验结果表、训练曲线、逐图打分 |
| README.md 本文件 |
| ``` |
|
|
| 配套数据集：**https://huggingface.co/datasets/daipath/filter-inspection-data** |
|
|
