| # 完整复现指南 |
|
|
| 从零复现本项目的全部实验。按顺序执行即可。 |
|
|
| **总耗时**：数据准备约 20 分钟，全部训练约 14 小时（单张 RTX 4090）。 |
| 只想复现分类主线结论：约 3 小时。 |
|
|
| --- |
|
|
| ## 0. 硬件与环境 |
|
|
| 实测环境（结果就是在这上面跑出来的）： |
|
|
| | | | |
| |---|---| |
| | GPU | NVIDIA RTX 4090 24 GB | |
| | CUDA | 12.8 | |
| | Python | 3.12.3 | |
| | OS | Linux 6.8（Ubuntu 24.04 容器） | |
|
|
| ### 建环境 |
|
|
| ```bash |
| python3.12 -m venv /workspace/venvs/seg |
| source /workspace/venvs/seg/bin/activate |
| pip install -U pip |
| |
| pip install torch==2.11.0 torchvision --index-url https://download.pytorch.org/whl/cu128 |
| pip install timm==1.0.28 segmentation-models-pytorch==0.5.0 albumentations==2.0.8 \ |
| opencv-python-headless==5.0.0 numpy==2.4.4 pandas==3.0.5 \ |
| scipy scikit-learn pillow openpyxl tqdm huggingface_hub |
| ``` |
|
|
| 版本敏感度：`albumentations` 2.x 的 `PadIfNeeded(fill=…)` 参数名与 1.x 不同（1.x 是 `value=`）， |
| 脚本按 2.x 写。`timm` 需 ≥1.0 才有 `edgenext_small.usi_in1k` / `efficientvit_b1.r288_in1k`。 |
|
|
| ```bash |
| export HF_HOME=/workspace/hf_cache # timm 预训练权重缓存，避免重复下载 |
| export HF_HUB_DISABLE_XET=1 # 本容器里不加这条 HF 上传/下载会报 httpx 错 |
| ``` |
|
|
| --- |
|
|
| ## 1. 拿数据 |
|
|
| ```bash |
| cd /workspace/CV_Task/seg3/newdata |
| hf download daipath/filter-inspection-data --repo-type dataset --local-dir ./dl |
| ``` |
|
|
| 如果你要从**最原始的压缩包**开始（验证解包逻辑）： |
|
|
| ```bash |
| bash fetch_and_unpack.sh # 下 样本7_27.zip 并递归解包到 raw/ |
| ``` |
|
|
| `unpack.py` 会做两件不显然的事： |
| 1. **修 GBK 文件名**。zip 里中文名以 cp437 存储，按 `cp437 → gbk → gb18030 → big5` 顺序回退解码。不修的话目录名全是乱码，`pkg` 字段就废了。 |
| 2. **防 zip-slip**。拒绝解到 `raw/` 之外的路径。 |
|
|
| 解包后应得到 **3728 张 PNG + 1977 个 labelme JSON**，分布在 11 个包目录下。 |
|
|
| --- |
|
|
| ## 2. 清点与几何量测 |
|
|
| ```bash |
| python inventory.py # -> inventory.csv 3728 行 |
| python metrics_fix.py # -> metrics_fixed.csv 1948 行（仅已标注图） |
| ``` |
|
|
| ### `inventory.py` 里两条必须原样保留的正则 |
|
|
| ```python |
| RE_BATCH = re.compile(r'(?<![0-9])(38[0-9]{3})(?![0-9])') |
| RE_PMACH = re.compile(r'(?<![A-Za-z0-9])[Pp]([0-9]{2})([0-9]{6})?(?![0-9])') |
| ``` |
|
|
| **没有批次号 / 机器号的包，字段留空，不做任何默认填充。** |
| 11 个包里有 5 个没有机器号——如果你给它们编一个默认值，`group` 分组就会把不同来源的图混成一组，切分立刻泄漏。 |
|
|
| `FINE_VERT_THR = 30`：标注顶点数中位 ≥30 判为「精细描边」，否则「粗框」。 |
| 这条把 11 个包分成 labelme 3.3.10（顶点中位 80，精描）和 5.11.4（顶点中位 12，粗框）两档。 |
| `样本_38031` **两个版本混装**，要按版本拆开再用。 |
|
|
| ### `metrics_fix.py` 修掉的两个 bug |
| |
| 原版 `metrics.py` 有两处错： |
| 1. **circle 类型的 shape 被漏计**。labelme 的 `circle` 只存圆心+半径两点，原版按多边形算面积得 0。修法是展开成 24 边形再算。 |
| 2. **`tightness` 指标是错的**——它拿多边形面积除以外接框面积，但崩边缺陷的多边形大部分画在片体外，这个比值没有物理意义。换成两个真实可解释的量： |
| - `in_body_ratio`：多边形落在片体内的面积占比 |
| - `vert_density`：顶点数 / 周长，用来区分精描与粗框 |
|
|
| --- |
|
|
| ## 3. 切分 |
|
|
| ```bash |
| python build_splits.py # -> splits/splitA/{meta,dropped}.csv |
| # splits/splitB/{meta,dropped}.csv |
| ``` |
|
|
| ### 两套切分 |
|
|
| | | A 套（全混合） | B 套（跨批次） | |
| |---|---|---| |
| | 目的 | 常规泛化 | **换批次还灵不灵** | |
| | 做法 | 11 个包混合，8:1:1 分层 | `样本_38016_P08262014` **整包**当 test | |
| | train / val / test | 2768 / 434 / 409 | 2787 / 441 / 284 | |
| | test 良品 / 不良 | 185 / 224 | 185 / 99 | |
|
|
| 两套都从 3728 张里**剔除 117 张**： |
|
|
| | 原因 | 张数 | 说明 | |
| |---|---|---| |
| | `rare_class` | 83 | 「碎」64 + 「不可擦脏」19，整类排除 | |
| | `zero_shapes` | 28 | 有 json 但 `shapes` 为空数组，零监督 | |
| | `no_json` | 6 | 缺标注文件 | |
|
|
| 剩 3611 张。剔除清单在 `dropped.csv`，每行带原因，可复查。 |
|
|
| > 「碎」虽然被排除，但它在 [审计](AUDIT.md) 里当**未见类硬正样本**用——模型从没见过这类，能不能抓到是诚实性的关键证据。 |
|
|
| ### 分组规则（最重要的一条） |
|
|
| 分组单位是 **`group = pkg ‖ sess`**（包 ‖ 拍摄会话），**同一组的图绝不跨 split**。 |
|
|
| 288 个组，两套切分都实测 **0 组跨 split**。验证： |
|
|
| ```bash |
| python -c " |
| import pandas as pd |
| for s in ('A','B'): |
| d = pd.read_csv(f'splits/split{s}/meta.csv') |
| bad = d.groupby('group').split.nunique() |
| print(f'split{s}: {len(bad)} 组, 跨split的 {(bad>1).sum()} 组') |
| " |
| # 期望：splitA: 288 组, 跨split的 0 组 / splitB 同 |
| ``` |
|
|
| **不遵守这条，跑出来的数字会虚高。** 同一次拍摄的图之间相关性极强，随机分会让 val/test 里塞满 train 的近邻。 |
|
|
| --- |
|
|
| ## 4. 分割路线（历史主线，结论是「不如分类」） |
|
|
| ```bash |
| python train_v3.py splits/splitA 200 384 32 10 > splits/splitA/train.log 2>&1 |
| python train_v3.py splits/splitB 200 384 32 10 > splits/splitB/train.log 2>&1 |
| ``` |
|
|
| 约 3.5 小时 / 套。参数是 `<split目录> <epochs> <size> <batch> <workers>`。 |
|
|
| `train_v3.py` 相对 seg3 初版的改动，以及**为什么**： |
|
|
| | 改动 | 原因 | |
| |---|---| |
| | 全量 RAM 预载 | 图只有 300 px，3611 张全进内存约 1.2 GB，把 dataloader 从瓶颈里拿掉 | |
| | batch 32 + `channels_last` + bf16 | 吃满 4090；显存占用约 18 GB | |
| | 归一化换成灰世界 + z-score（`gwz`） | 数据存在采集配置色调漂移（B 通道逐日 15→8→5），ImageNet 固定均值方差顶不住 | |
| | 固定随机种子 42 | 可复现 | |
| | **加了 test 泄漏断言** | 见下 | |
|
|
| ```python |
| te_n = int((df.split == 'test').sum()) |
| assert 'test' not in set(tr_df.split) | set(va_df.split), 'test 泄漏进了训练/选型集' |
| ``` |
|
|
| **这条断言不要删。** 本项目上一代就栽在切分泄漏上，加断言比事后审计便宜得多。 |
|
|
| ### 评估 |
|
|
| ```bash |
| python eval_v3.py splits/splitA # -> eval_report.json, eval_{val,test}.csv, curve_{val,test}.csv |
| python eval_v3.py splits/splitB |
| ``` |
|
|
| 预期（`eval_report.json`）： |
|
|
| | | A 套 val | A 套 test | B 套 val | B 套 test | |
| |---|---|---|---|---| |
| | 三类合计 Dice | 0.6975 | 0.7432 | 0.7021 | 0.6802 | |
| | 划痕 Dice | 0.6366 | 0.6578 | 0.6502 | 0.5659 | |
| | 崩边 Dice | 0.7713 | 0.8489 | 0.7652 | 0.7811 | |
| | **麻点 Dice** | **0.4580** | **0.3728** | **0.4403** | **0.2609** | |
| | AUROC (`s_max`) | 0.9779 | 0.9922 | 0.9884 | 0.9749 | |
|
|
| 麻点 Dice 只有 0.26–0.46，是全局短板。`train_summary.json` 里 A 套最佳 epoch = 146 / 200， |
| 最后 20 epoch 的 val Dice 标准差 0.0047 —— **已收敛，不需要早停**。 |
|
|
| ### 增广消融 |
|
|
| ```bash |
| bash run_aug_ablation.sh 200 # 4 档 × 2 切分 = 8 个作业 |
| ``` |
|
|
| A 套结果（`splits/splitA/aug_compare.json`），`rec1`/`fp1` 是单阈值口径： |
|
|
| | 增广 | 平均 Dice | 单阈值检出 | 误报 | |
| |---|---|---|---| |
| | none | 0.5947 | 65.6% | 2 | |
| | **weak** | **0.6136** | **70.1%** | 2 | |
| | mid | 0.6061 | 59.4% | 2 | |
| | strong | 0.6086 | 56.7% | 3 | |
|
|
| **weak 最好，strong 反而更差。** 缺陷本身就是细微低对比结构，强增广会把它抹掉。 |
|
|
| ### 判据优化（几何规则） |
|
|
| ```bash |
| python measure_geom.py splits/splitA # -> geom_{val,test}.csv 逐图几何量 |
| python optimize_rules.py # -> rules_maxfp3.json, rules3_maxfp3.json |
| ``` |
|
|
| `rules_maxfp3.json` 里区分 **oracle**（阈值直接在 test 上调，作弊）和 **honest**（阈值在 val 上定）： |
|
|
| | | A 套 honest | A 套 oracle | B 套 honest | B 套 oracle | |
| |---|---|---|---|---| |
| | 单一像素阈值 | 71.4% (fp 5) | 49.6% (fp 3) | 69.7% (fp 5) | 65.7% (fp 3) | |
| | 7 维几何判据 | 64.3% (fp 7) | 74.6% (fp 3) | 76.8% (fp 7) | 85.9% (fp 3) | |
|
|
| 7 维是：划痕长度 L / 划痕面积 A / 麻点最大颗 P / 麻点直径 D / 崩边面积 C / 沿边弧长 E / 过角+面积 Cc。 |
|
|
| **注意 honest 与 oracle 的落差**：A 套几何判据 oracle 74.6% → honest 64.3%，掉 10 个点。 |
| 7 个自由度在 434 张 val 上调，过拟合是必然的。**这就是几何判据路线的天花板。** |
|
|
| --- |
|
|
| ## 5. 分类路线（推荐主线） |
|
|
| ### 第一阶段：骨干 × 增广 × 任务 |
|
|
| ```bash |
| EP=60 SZ=320 BS=32 CONC=2 bash run_cls_sweep.sh 1 # 选骨干 |
| EP=60 SZ=320 BS=32 CONC=2 bash run_cls_sweep.sh 2 # 扫增广 × 任务 × 切分 |
| ``` |
|
|
| 产出 18 个模型到 `splits/split{A,B}/cls/`。命名格式 `{task}_{backbone}_{aug}_{size}`。 |
|
|
| - `task`：`bin`（良/不良）或 `cls4`（良/划/麻/崩） |
| - `aug`：`none` / `weak` / `mid` / `strong` |
|
|
| ### 第二阶段：多轴消融 |
|
|
| ```bash |
| bash run_cls2.sh # 19 个作业，并发 3，约 4 小时 |
| ``` |
|
|
| `cls_train2.py` 支持 6 个正交轴： |
|
|
| | 轴 | 取值 | 设计意图 | |
| |---|---|---| |
| | `--sz` | 224 / 256 / 320 / 384 / 448 | 麻点在 224 px 下只有 109 px²，320 下 223 px²，448 下 437 px² | |
| | `--norm` | `gwz` / `imnet` / `zscore` | **`imnet` 是 seg3 初版用的，怀疑它是最大隐患** | |
| | `--aug` | `geo` / `photo` / `mid` / `mixup` / `cutmix` | 把几何增广与光度增广拆开单测 | |
| | `--loss` | `ce` / `ce_nols` / `focal` | 标签平滑的影响、类别不均衡 | |
| | `--bb` | resnet18 / regnety_016 / repvgg_a1 / edgenext_small / convnext_tiny(DINOv3) / efficientvit_b1 | 覆盖 CNN / ViT / 自监督 / 部署友好 | |
| | `--task` | `bin` / `cls4` | | |
| |
| ### 统一评测 |
| |
| ```bash |
| python cls_eval_all.py # -> cls_test_all.csv，42 个模型 |
| python cls_tta_ens.py splits/splitA # -> tta_ens.json，TTA×8 |
| ``` |
| |
| `cls_eval_all.py` 的 `rec@K` / `fp@K` 定义要看清楚： |
| |
| > **在 val 上搜一个阈值，使 val 误报 ≤ K；把这个阈值原样搬到 test。** |
| > `rec@K` 是 test 检出率，`fp@K` 是 **test 上实际发生的误报数**（不受 K 约束，可能超）。 |
| |
| 这是诚实口径。CSV 里还有 `imp_test`（test 口径不良桶良品率）和 `imp_line10`（换算到产线不良率 10%）。 |
| |
| 预期 top 结果（`cls_test_all.csv`）： |
| |
| | split | task | backbone | aug/norm | val AUROC | test AUROC | rec@3 | test fp | |
| |---|---|---|---|---|---|---|---| |
| | A | bin | efficientnet_b0 | mid/**imnet** | 0.9951 | **0.9976** | 94.6% | 3 | |
| | A | bin | efficientnet_b0 | cutmix/gwz | 0.9922 | 0.9975 | 95.5% | 4 | |
| | A | bin | mobilenetv3_large_100 | weak/gwz | 0.9917 | 0.9969 | 94.6% | 3 | |
| | A | bin | efficientnet_b0 | mid/gwz | 0.9936 | 0.9918 | **97.3%** | 4 | |
| | B | bin | resnet34 | mid/gwz | 0.9932 | 0.9862 | 94.9% | 7 | |
| |
| **两个反直觉的点，都要照实记：** |
| |
| 1. **`gwz` 没有优势。** 最高 test AUROC 是 `imnet`（0.9976）拿的。我此前推测 `gwz` 能扛色调漂移——**在 test 上没验证出来**，此结论已撤回。真要证明 `gwz` 的价值，得做色调漂移压力测试，本项目没做。 |
| 2. **`convnext_tiny.dinov3_lvd1689m` 彻底失败**（val AUROC 0.5132，test 0.5335 = 随机）。DINOv3 预训练权重在 60 epoch、4e-4 的配置下没收敛。不是说这个骨干不行，是这套超参不适配它。 |
| |
| TTA×8 最好成绩：`mobilenetv3_large_100 weak` **0.9969 → 0.9982**。 |
| 注意 TTA 并非总是有益：`mobilenetv3 none` 0.9959 → 0.9925（**掉了**）。 |
| |
| 四分类逐类召回（`cls4_resnet34_mid_320`，A 套 test）： |
| |
| | GT 类别 | 张数 | 判对 | 召回 | |
| |---|---|---|---| |
| | 划痕 | 133 | 117 | 88.0% | |
| | 崩边 | 68 | 64 | 94.1% | |
| | 良品 | 185 | 176 | 95.1% | |
| | 麻点 | 23 | 21 | **91.3%** | |
| |
| > `eval.json` 里 `confusion` 的存储方向是 **外层 key = 预测类，内层 key = 真实类**。 |
| > 读反了会得到完全不同的数字（比如把 88.0% 读成 94.4%）。 |
| |
| --- |
| |
| ## 6. 诚实性审计（**不要跳过**） |
| |
| ```bash |
| python cls_probe.py # -> cls_probe_all.csv |
| python cls_frozen_probe.py splits/splitA resnet34 320 # -> frozen_probe_resnet34_320.json |
| ``` |
| |
| 四道审计的原理、预期数字和判读方式见 [`AUDIT.md`](AUDIT.md)。 |
| |
| 一句话版本：**图像里确实带着可区分批次的信息（包分类准确率 92.7%），但模型没去用它**—— |
| 只见良品的 kNN（0.9634）反而**打败**了用了标签的线性探针（0.9461），说明标签解锁不了额外的捷径。 |
| |
| --- |
| |
| ## 7. 导出与打包部署 |
| |
| ```bash |
| python export_onnx.py # -> release/filter_binary.onnx + .json |
| # release/filter_4class.onnx + .json |
| ``` |
| |
| **`export_onnx.py` 里 `dynamo=False` 不能删。** 用新的 dynamo 导出器会把权重拆成独立的 |
| `.onnx.data` 文件，单文件分发就没了。 |
| |
| 打包成免安装可执行文件： |
| |
| ```bash |
| R=/workspace/CV_Task/seg3/newdata/release |
| pyinstaller --onefile --name filter-predict-cpu \ |
| --add-data "$R/filter_binary.onnx:." --add-data "$R/filter_binary.json:." \ |
| --add-data "$R/filter_4class.onnx:." --add-data "$R/filter_4class.json:." \ |
| --add-binary /workspace/miniconda3/lib/libstdc++.so.6:. \ |
| "$R/predict.py" |
| ``` |
| |
| **三个踩过的坑，照抄即可避免：** |
|
|
| 1. `--add-data` 的相对路径是**相对 specpath 解析**的，不是相对 cwd。用绝对路径 `$R/...`。 |
| 2. 打包后 `__file__` 指向 `/tmp/_MEIxxx`，模型找不到。`predict.py` 里的 `sys.frozen` / `_MEIPASS` 分支处理这个，别简化掉。 |
| 3. **`libstdc++.so.6` 必须显式打进去**。Ubuntu 24.04 的系统库要 GLIBC_2.38，目标机上没有就直接崩。 |
| miniconda 那份只要 glibc 2.26。全部 141 个打包 .so 审计下来最高需求 glibc 2.28。 |
| > 这个错的表象是 numpy 导入失败，**根因不是 numpy**。曾按 numpy 方向排查很久，是弯路。 |
| |
| GPU 版把 `onnxruntime` 换成 `onnxruntime-gpu`，且**必须钉版本**： |
| 1.28 要 CUDA 13，目标机是 CUDA 12.8 —— 用 `1.22.0`（py ≤ 3.12）或 `1.24.4`（py 3.14）。 |
| |
| --- |
| |
| ## 8. 生成报告 |
| |
| ```bash |
| python gen_report.py # 数据核查报告 |
| python gen_showcase.py # 分割效果展示 |
| python gen_nonzero_goods.py # 被模型报警的良品 |
| python gen_p10_report.py # 产线不良率 10% 判废纯度 |
| python precision_table.py # 判废纯度对照表 |
| ``` |
| |
| 5 份 HTML 的内容说明见 [`FILES.md`](FILES.md)。 |
| |
| --- |
| |
| ## 复现检查清单 |
| |
| 跑完对一下这几个数，对不上说明哪一步偏了： |
| |
| - [ ] `inventory.csv` **3728** 行 |
| - [ ] `splits/splitA/meta.csv` **3611** 行，`dropped.csv` **117** 行 |
| - [ ] 跨 split 的组 **0** 个（288 组） |
| - [ ] 分割 A 套 test 三类合计 Dice **≈0.743**，麻点 Dice **≈0.373** |
| - [ ] 分类 A 套 test AUROC 最高 **≈0.9976**（efficientnet_b0 / mid / imnet） |
| - [ ] 未见类「碎」检出 `sui` **≥0.92** |
| - [ ] 冻结特征 kNN test AUROC **≈0.9634** > 线性探针 **≈0.9461** |
| |
| 随机性说明：训练固定了种子 42，但 cuDNN 非确定性算子仍会带来 |
| **±0.005 量级的 AUROC 抖动**。这个噪声地板和榜单前 10 名之间的差距是同量级的 |
| ——**不要根据 0.001 的差异下结论**。要压过噪声需要多种子重复，本项目没做。 |
| |
