xzhou/ModelTrainEval
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
46 Commits 1 Branch 0 Tags
9aa87d31a62342d60155c38454c3ffb353e6a68a
Commit Graph
16 Commits
Author SHA1 Message Date
Shaun ZhouandClaude Opus 5 9aa87d31a6 feat(localization): SHAP Partition 定位方法，并把每图框数上限默认收紧为 1 
新增基于 SHAP Partition explainer 的定位，与 Grad-CAM 形成互补对照：

- engine/shap_explain.py：对目标类别求 SHAP 归因（只保留正贡献），以及方框平滑。
  遮挡用数值 masker 而非教程里的 inpaint_telea——后者依赖 opencv，而我们的图已做过
  逐图标准化，用 0（即该图均值）遮挡语义更干净
- scripts/shap_boxes.py：按类别抽样生成标签，并输出「原图 | Grad-CAM | SHAP」并排图
- shap 放入可选依赖组：uv sync --group explain

实测（225 张，每类 15）：SHAP 在小目标类别上明显更准，框面积占比
blackdot 0.019 vs 0.269（14 倍）、mosquito 0.030 vs 0.173、whitedot 0.076 vs 0.253。
原因是 Grad-CAM 受限于 8x8 特征图（每格 16x16 像素），几像素的黑点根本不可分辨。
代价是单张 0.55 秒，全量 11k 张约 1.7 小时，而 Grad-CAM 全量只要 2 分钟。

调参时发现的坑：SHAP 第一版全部出 0 框，因为沿用了给 8x8 调的
min_area_ratio=0.02（在 128x128 上等于 328 像素）。参数不能跨分辨率照搬，
SHAP 默认改为 0.002。

--max-boxes 两个脚本都默认改为 1（原为 2）：一张裁片通常只对应一处缺陷。
库函数 cam_to_boxes 的默认值同步收紧，相关测试改为显式传参而不依赖默认值。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-10 16:10:50 +08:00
Shaun ZhouandClaude Opus 5 fc7136fddf feat: 用 Grad-CAM 从分类模型生成弱监督框标签 
分类模型只学过"是什么缺陷"，Grad-CAM 把分类分数对卷积特征的梯度当作通道重要性，
加权求和得到空间热力图，阈值化 + 连通域外接矩形即得到框标签，输出 YOLO 格式，
可直接接入既有的检测训练链路。

- engine/gradcam.py：整批一次 backward 的 Grad-CAM（各样本只回传自己那一类的分数）、
  numpy 实现的 4-邻接连通域标记（不为这一处引入 scipy/opencv）、CAM 转归一化框
- scripts/gradcam_boxes.py：遍历数据集生成标签，并输出「原图 | 热力图 | 叠加+框」
  三联图供人工核对；框的类别取自图片所在目录而非模型预测

两处按实图定下的默认值：
- --stage 默认 6（layer3, 8×8）。layer4 只有 4×4 太粗，layer2 响应太散导致 40% 出不了框
- --peak-ratio 0.75：次要连通域峰值需达全局最大值的 75%，否则会在无缺陷的角落刷假框；
  实测把两框比例从 53% 降到 20%

全量 11,212 张已生成：61.8% 出 1 框、35.2% 出 2 框、3.0% 无框，每类留 25 张可视化。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-10 15:46:30 +08:00
Shaun ZhouandClaude Opus 5 33d28dcc7c feat(cluster): clusters/ 默认改用硬链接，便于直接在 runs/ 下继续分子类 
软链接记的是绝对路径，从服务器拷到本机后全部失效，也不便于直接在 runs/ 下整理。
硬链接不占额外磁盘却表现得和真实文件一样：看图软件能开、可以随意挪动、建子目录
继续分子类，整个目录拷到别的机器也不会断链。

- 新增 link_mode: hard（默认）/ sym / copy；跨文件系统时 hard 自动退回软链并警告
- 落盘后打印各方式的条目数，便于确认实际用的是哪种
- export_clusters.py 适配硬链接：条目本身就是原图，但路径在 runs/ 下、名字还带
  0125_ 排序前缀。按 inode 反查 assignments.csv 还原原图路径，这样导出的文件名与
  --prefix-parent 才能拿到真正的来源目录；查不到则剥掉前缀后用文件名索引兜底

实测：14,579 张跑聚类后 clusters/ 全为硬链接（nlink=2、可直接打开）；
把簇改名、建子目录挪图后再导出，排序前缀已剥除、来源目录正确还原为「反面纵黑点」，
120 张内容与原图逐字节一致。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-10 12:04:08 +08:00
Shaun ZhouandClaude Opus 5 f8654f447b feat(export): 改为按 clusters/ 目录导出，并重定位失效的软链 
原来按 assignments.csv 导出，反映的是聚类当时的划分；而 clusters/ 目录会被人工
整理——挪动分错的图、把 cluster_03 改名成 grease。现在以整理后的目录为准。

- 扫描 clusters/ 下的子目录，目录名即类别名并原样保留（不再是数字编号）
- 文件名用原图的名字，去掉 clusters/ 里的 NNNN_ 排序前缀
- 失效软链的重定位：读出链接目标，按其中的 data/ 段落到本机 --source-root 上；
  再不行用文件名在源目录里兜底索引（惰性构建，用不到就不扫盘）。
  从服务器拷回来的 clusters/ 软链全部指向 /home/deep/... 在本机失效，这是常态
- 解析不到的条目列出并中止，--skip-missing 可忽略
- manifest 记录类别、每张图的原始路径与被跳过的条目

在真实目录上验证：11,212 张、15 个类别，软链 100% 失效但全部重定位成功，
导出后抽查 200 张与原图逐字节一致。跨数据集的数字文件名（blue/113.bmp 与
pearlescent/113.bmp）会被重名检查拦下，--prefix-parent 可化解。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-10 11:26:02 +08:00
Shaun ZhouandClaude Opus 5 9b31473b27 feat(export): 支持把原父目录名作为文件名前缀 
新增 --prefix-parent：复制时把图片原来的父目录名拼到文件名前
（grease/abc.png -> grease_abc.png）。导出后目录只剩簇号，来源信息本来会丢失，
加前缀能留住它，人工核对时一眼看出某张图原本在哪个目录。

- 重名检查改为按**目标文件名**判重：加前缀后原本会撞车的文件可能就不撞了；
  不加前缀而撞车时，报错会提示可以试试这个开关
- manifest.json 记下 prefix_parent，导出的 file 字段也用实际写出的文件名

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-08 15:26:00 +08:00
Shaun ZhouandClaude Opus 5 506fde0290 fix(cluster): 配置层级写错不再静默忽略，并始终打印生效的超参 
聚类配置里 optimizer/epochs 等键都在 `simclr:` 段下。写到顶层会被完全忽略、
不报任何错——用户改了 lr 却毫无反应，极难排查。同样的坑还有：改了基类
configs/cluster/film.yaml 的 simclr.optimizer，但运行的是子配置
film_simclr_resnet18.yaml，子配置里的同名键会盖掉基类的修改。

- 顶层出现 optimizer / scheduler / epochs / temperature / projection /
  save_interval / resume / checkpoint / log_interval 时警告并给出正确写法
- method != simclr 却写了 simclr: 段时提示该段不会生效
- SimCLRTrainer 初始化时无条件打印实际生效的 epochs / temperature /
  optimizer / scheduler，不再只在续训时才打印
- 修掉一处假差异：旧存档没有 scheduler_cfg 字段时会误报 "scheduler None -> cosine"，
  那是"不知道"而非"当时没有调度器"

已验证 --set 覆盖、直接改 yaml、旧格式存档三条路径下 lr/weight_decay 均正常生效。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-07 19:11:31 +08:00
Shaun ZhouandClaude Opus 5 0f5bb4a5c0 feat(cluster): 加 --train-only，自监督训练与聚类可分两步跑 
engine/simclr.py 与 engine/cluster.py 本来就互不引用，唯一接口是
simclr_backbone.pth；耦合只在 CLI——method=simclr 会训练完直接聚类。
此前"只聚类"可以用 simclr.checkpoint 做到，"只训练"没有办法。

- --train-only：训练存完权重即退出，不抽特征也不聚类，并打印下一步的聚类命令
- 与 method=pretrained / simclr.checkpoint / --sweep-k 组合时立刻报错说明原因，
  而不是跑完才发现没有产出
- 典型用法：GPU 机器上 --train-only 跑几十小时，之后拿权重反复调 k，每次约 1 分钟

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-07 11:38:59 +08:00
Shaun ZhouandClaude Opus 5 5d395b7c25 chore: 数据迁到 data/raw/ 后同步所有路径引用 
原始数据从 data/<数据集> 移到了 data/raw/<数据集>。

- 聚类配置的 dataset.root：film / pearlescent 均改为 data/raw/ 下
- 检测配置的 img_dir 与 label_dir 注释同步
- README、data/README、算法文档、流程图（含重新渲染的 PNG）与各脚本
  docstring 里的路径示例一并更新
- data/README 补充目录约定：原始数据只读放 data/raw/，
  export_clusters.py 的派生数据集放在 data/ 下与 raw/ 平级
- 顺手把 unlabeled 数据集加进 datasets/__init__.py：此前它没在包初始化时注册，
  build_dataset({"name": "unlabeled"}) 只有在别处先 import 过该模块时才可用

迁移后重跑全量聚类，结果与迁移前逐项一致（轮廓 0.3255、稳定性 0.9641、
簇大小 [4507, 3795, 4849, 1428]）。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-07 11:19:42 +08:00
Shaun ZhouandClaude Opus 5 f8a52c9382 feat(scripts): 按聚类结果导出数据集 
新增 scripts/export_clusters.py：读聚类产出的 assignments.csv，把原图复制成
data/<源目录名>_<骨架标签>_cluster_k<簇数>/，子目录用从 0 开始的数字编号。

- 复制真实文件（copy2 保留修改时间），不建软链、不改名
- 目录名自动推导：源目录名取各路径的公共父目录，骨架标签取自 summary.json 的
  feature_source；--tag / --out 可覆盖
- manifest.json 记录来源 run、特征配置与每张图的原始路径，便于追溯
- 保护：源文件缺失、同簇内重名（保持原名会互相覆盖）直接报错；
  目标目录非空需显式 --overwrite；--dry-run 只打印计划
- 聚类产出的 summary.json 新增 feature_source 字段（method / backbone /
  feature_stages），供上面的自动命名与日后追溯

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-06 13:17:53 +08:00
Shaun ZhouandClaude Opus 5 e4bd794025 feat(cluster): 输出簇分布图，直观展示簇间距离 
在 preview 拼图的同级目录生成 cluster_scatter.png：
- 左：聚类空间的 PCA 二维投影，散点按簇着色 + 质心标记，标题标注两个主成分的方差占比
- 右：质心两两距离矩阵（在聚类空间里算，不是投影后），带数值标注

投影用 PCA 而不是 t-SNE/UMAP——后两者为了把簇拉开会扭曲簇间距离，
而这张图的目的就是看距离。

- ClusterResult 新增 points 字段，保留 KMeans 实际使用的空间供可视化复用，
  质心与散点用同一组主成分变换，避免质心飘到簇外
- summary.json 新增 centroid_distances
- 新增 scatter 配置块（enabled / max_points / point_size / alpha / figsize / dpi）
- 中文字体按 PingFang / Noto Sans CJK 等顺序探测，找不到自动退回英文标签，
  不会画成豆腐块
- 新增依赖 matplotlib

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-04 15:09:35 +08:00
Shaun ZhouandClaude Opus 5 345dee50da feat(simclr): 支持断点续训，恢复优化器与调度器状态 
此前 simclr.checkpoint 的语义是"有权重就跳过训练"，没有真正的续训：
中途停掉再启动只能从头再来，或者放弃已训的轮次。

- 新增 simclr_last.pth：骨架 + 投影头 + 优化器 + 调度器 + scaler + epoch + step，
  与给下游用的 simclr_backbone.pth 并存，两者在同一时机落盘
- 新增 simclr.resume：载入完整状态从下一个 epoch 接着练。只恢复权重不恢复动量与
  cosine 进度的话，续训时损失会先反弹一段
- resume 与 checkpoint 互斥（同时给直接报错）；拿只含骨架的 simclr_backbone.pth
  去 resume 会给出可操作的报错，提示改用 checkpoint
- 续训轮数已达计划值时不再训练，只打警告

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-03 09:34:55 +08:00
Shaun ZhouandClaude Opus 5 be6173c746 feat(simclr): 接入 SwanLab 可视化，并补上本地看板缺失的依赖 
- SimCLRTrainer 记录 simclr/loss、loss_avg、lr（按 step）与 epoch_loss、
  epoch_seconds、gpu_mem_peak_mb（按 epoch），超参为完整 yaml 配置；
  正常结束与 KeyboardInterrupt 两条路径都会 finish()
- 配置新增 simclr.swanlab（字段同 train.swanlab），默认 mode: local，
  不需要登录，日志写到 <work_dir>/swanlog
- 依赖改为 swanlab[dashboard]：此前 `swanlab watch` 在干净环境里会报
  "Please install the swanboard package"，README 里检测训练那节的看板命令
  同样受影响，现已随 uv sync 装好
- README 补齐本地看板/云端/离线补传三种用法与端口、局域网参数

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-03 09:24:39 +08:00
Shaun ZhouandClaude Opus 5 b6f83fcad0 fix(simclr): 周期性落盘，中途中断不再丢失训练成果 
此前 fit() 只在全部 epoch 跑完后才保存骨架，一次跑到 epoch 12 被停掉后
13 分钟的训练全部作废。

- 每 save_interval（默认 5）个 epoch 保存一次骨架
- 捕获 KeyboardInterrupt，中断时先落盘再返回
- 聚类脚本改用 resolve_device，自监督分支不再有 GPU 守卫

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-02 21:43:35 +08:00
Shaun ZhouandClaude Opus 5 141cb907f2 feat: 支持 cuda / mps / cpu 三后端，Mac 上可用 MPS 训练 
移除"训练必须有 Nvidia GPU"的硬性守卫，改为按后端能力分派。

- utils/device: resolve_device("auto") 按 cuda > mps > cpu 挑最快的可用后端；
  显式指定不可用的后端时直接报错，不会悄悄退回 CPU——训练慢几十倍却不吭声是最坏的情况
- AMP 随后端取默认值：CUDA 开、MPS 关。MPS 上 autocast 数值正常但实测更慢
  （tiny_conv @128²：fp32 76 ms/步、fp16 90 ms、bf16 108 ms），需要时 amp: true 可强开
- PeakMemory 统一显存峰值统计：CUDA 读内置计数器，MPS 无峰值 API 改用逐 step 采样
  （是下界，日志与产出里已标注）
- profile_inference 支持 MPS，并提示 torch.profiler 没有 MPS 的 ProfilerActivity，
  算子明细只反映 CPU 侧下发耗时
- train.py / eval.py 新增 --device，配置默认改为 auto
- check_env 改为列出全部可用后端与 auto 的选择结果

实测：tiny_conv 训练在 MPS 上比 CPU 快约 32 倍。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-02 21:43:35 +08:00
Shaun ZhouandClaude Opus 5 f433e5cf59 feat: 未分类样本的无监督聚类（多 stage 特征 + KMeans，可选 SimCLR） 
把 data/film 下所有图片拉平做聚类，不使用任何目录名，簇数由 num_clusters 决定。

预处理针对该批数据的实际情况（14.5k 张已裁好的缺陷小图，中位 152x113，
宽高比 0.24~39.9）：尺寸与亮度都是 ROI 裁剪和光照的产物、不是缺陷属性，
因此拉伸到 128x128（不用 letterbox，其填充比例等价于编码了宽高比）并逐图 z-score。

- cluster: torch 实现的 kmeans++/Lloyd（含空簇处理与 n_init）、PCA、轮廓系数、
  NMI 稳定性、多 stage 特征提取；不引 scikit-learn
- 白化默认关闭：CNN 特征谱极陡（λ1/λ32≈165x），白化会把噪声方向抬到与信号同权，
  实测最大簇一度吃掉 96% 的样本
- simclr: NT-Xent 自监督预训练，用项目自己的卷积骨架，权重可直接初始化 DefectNet；
  属于训练，走 require_cuda() 守卫
- 产出 assignments.csv、summary.json、按簇的软链目录与代表样本拼图，供人工核对

全量 14,579 张：轮廓系数 0.326、换种子稳定性 0.964，CPU 约 100 秒。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-02 17:55:47 +08:00
Shaun ZhouandClaude Opus 5 4b1147ed8f feat(scripts): 数据转换、ONNX 导出与推理性能分析 
- convert_annotations: labelme / VOC -> YOLO txt，顺带生成 data.yaml
- split_dataset: 切分成 images/{train,val} 与 labels/{train,val}，默认建软链不复制数据
- export_onnx: 导出部署用 ONNX，CPU 可跑，缺依赖时提示 `uv sync --group export`
- profile_inference: torch.profiler 测单帧延迟/FPS、CUDA 显存峰值与算子级明细
- check_env: Python / PyTorch / Nvidia GPU 自检

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-02 17:55:20 +08:00