You need to agree to share your contact information to access this model

This repository is publicly accessible, but you have to accept the conditions to access its files and content.

滤光片外观质检 · 开箱即用推理包

暗场成像的 IR-CUT 滤光片裁片，判良品 / 不良，可选输出缺陷类型（划痕 / 麻点 / 崩边）。

推理端不需要 PyTorch、不需要 timm、不需要 GPU，只要 4 个 pip 包。

两个版本，v3 与 v4 并列

	v3（仓库根目录）	v4（`v4/` 目录）
换模型	要重新打包程序	拷一个目录 + 一条命令
预处理	归一化写死 `gwz`	由 `pack.json` 驱动
换错模型	静默出错	8 步闸门，带编号退出
状态	稳定，已在用	新增，未在产线跑过

v3 的一切保持原样，下面的说明继续有效。v4 是并列新增的，不影响现有用法。

v4 解决的是什么

v3 的 predict.py 把归一化写死成 gwz，而 filter_binary.json 里的 norm 字段被忽略。后果不是"换不了模型"，是更糟的——换上去会静默出错：

实测场景	结果
`imnet` 模型被喂 `gwz`	AUROC 0.9976→0.9940，漏检 7→23 张（3.3 倍），而误报两边都是 3
`gwz` 模型被喂 `imnet`	AUROC 0.9914→0.3542，排序翻转，185 张良品误报 141 张

第一行是关键：误报数一模一样，只有漏检在偷偷涨，看结果表永远发现不了。而本仓库 test AUROC 最高的模型（efficientnet_b0 / imnet = 0.9976）正好是 imnet 归一化的 ——它在 v3 下根本部署不了。

v4 怎么用

# CPU 版（80 MB）—— 不确定就用这个
wget https://huggingface.co/daipath/filter-inspection/resolve/main/v4/binaries/filter-predict-v4-portable
chmod +x filter-predict-v4-portable

# GPU 版（1.08 GB，内置 CUDA 12 运行库，目标机只需 NVIDIA 驱动）
# wget https://huggingface.co/daipath/filter-inspection/resolve/main/v4/binaries/filter-predict-v4-gpu

# 把模型包目录也拷下来（exe 里只内置了一个判废兜底包）
hf download daipath/filter-inspection --include "v4/models/*" --local-dir .
mv v4/models .

./filter-predict-v4-portable --list                    # 有哪些包、什么预处理、阈值从哪来
./filter-predict-v4-portable -i 图片目录/ -o 结果.xlsx

换模型：

cp -r 新包目录 models/               # 1. 拷进去
./filter-predict-v4-portable --verify 新包名          # 2. 8 步校验
./filter-predict-v4-portable --activate reject=新包名 # 3. 切换（可一条命令回滚）

详见 v4/README.md、v4/模型包手册.md 与 v4/binaries/README.md（三个二进制怎么选、glibc 要求、GPU 注意事项）。

三个二进制（共用同一套模型包，换模型流程完全一样）：

文件	体积	要求	实测速度
`filter-predict-v4-portable`	80 MB	GLIBC ≥ 2.28	20 张/秒
`filter-predict-v4-gpu`	1.08 GB	GLIBC ≥ 2.28 + CUDA 12.x 驱动	103 张/秒
`filter-predict-v4`	57 MB	GLIBC ≥ 2.38	20 张/秒

GPU 只快约 5 倍而非 200 倍——纯推理 4359 张/秒，但瓶颈已是预处理（纯 numpy 跑在 CPU）。另：GPU 与 CPU 分数不逐位相同（409 张 test 上判定 0 处不一致，分数最大差 7.0e-03，距阈值最近的图裕度 0.0185 = 2.6 倍）。产线固定用同一个二进制，别混用。

⚠ v4 与 v3 的分数不逐位相同。 v4 修正了一处训练/推理不一致（训练走 cv2.resize、 v3 走 PIL BILINEAR，两者内核语义不同）。判定层面 0/409 翻转、FP/FN/AUROC 不变，但分数最大差 0.0035、38/409 张 >1e-4。若已基于 v3 输出建了 SPC 基线，换 v4 需重新验收。

📚 完整文档

文件	内容
`docs/INDEX.md`	项目总索引：四个仓库怎么选、三个核心结论、数据一览
`docs/REPRODUCE.md`	完整复现指南：环境、数据准备、逐个实验的命令与预期数字
`docs/FILES.md`	逐文件使用说明：41 个脚本、结果表字段、51 个训练产物目录
`docs/RESULTS.md`	全部实验结果：42 个模型完整榜单、分割 vs 分类同口径对决
`docs/AUDIT.md`	诚实性审计：四道审计的原理与结果，为什么这次的高分是真的
`docs/CAVEATS.md`	⚠ 已知问题与边界，上线前必读（含我犯过的评估口径错误）
`docs/REPOS.md`	四个仓库逐一说明与下载方式

三种用法，任选

A. 零安装 —— 单个可执行文件（推荐）

目标机上不需要 Python、不需要装任何东西，下载一个文件就能跑。模型已打进二进制。

# 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 脚本（想改代码时用）

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），否则结果不可信。

单张图

python predict.py -i /path/to/filter_0001.png

  文件   : filter_0001.png
  判定   : 良品
  不良概率: 0.0060

python predict.py -i /path/to/images/ -o result.xlsx

输出表格：图片名 | 判定 | 不良概率 | 相对路径

附带缺陷类型

python predict.py -i images/ -o result.xlsx --with-type

多两列：缺陷类型 | 类型置信度（只对判为不良的填）

不想装 openpyxl

输出写 .csv 即可（UTF-8 BOM，Excel 直接双击能开）：

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

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

Downloads last month: -; Downloads are not tracked for this model. How to track

daipath
/

filter-inspection