P4s：模型审计 —— 移出零引用模型，修掉代码里三处悬空 best.pt

先回答"这些模型到底有没有人用"，用全仓库引用扫描判定，不靠猜：在用 yolo/detect_best_0.onnx + .engine ← paths.yolo_weights 在用 hole_insert/detect_best_1.onnx ← hole_detect.weights / workpiece_weights 零引用 detect_hc90（pt/onnx/engine） ← 只剩注释里的历史说明零引用 detect_yolo26_gongjian.pt 零引用 detect_best（onnx/engine） ← 仅代码兜底候选，而那个候选是 .pt，不存在所以 detect_hc90 不需要修复，是不用的东西：连同另两个一起移出仓库。注意**二进制权重被 gitignore**，删掉就找不回来了，因此是移出到 ~/ros2-models-unused-20260923/ 而非 rm。搬回 models/ 即可被 list 重新发现。顺手挖出并修掉三处悬空引用（和之前 site.yaml 里那个 best.pt 同一类问题）： - hole_detector.weights_from_site：兜底路径写死 models/hole_insert/best.pt（不存在） - hole_detector._default_model_path：三个候选路径**全都不存在**，函数却 `return candidates[0]`，于是永远返回不存在的 best.pt；报错路径看着很合理，极易被误判成"文件被误删"。现改为以 site.yaml 为准，再退到规范模型。 - config/hole_insert.yaml 顶部注释同样写的是 best.pt 新增 test_hole_detector.py（8 项）锁住这个回归。测试刻意**不断言文件存在** ——二进制不进 git，新克隆的仓库里 models/ 是空的——只断言解析结果指向规范模型名。体检从 4 处问题降到 0：bash scripts/weights.sh doctor --check-engines → "没有发现问题" 测试 233 项通过；18 个包构建通过。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-23 13:08:11 +08:00
parent 2b77ec127d
commit d289168dd0
12 changed files with 153 additions and 86 deletions
@@ -214,8 +214,10 @@ bash ~/ros2/scripts/weights.sh doctor --check-engines
 bash scripts/weights.sh convert models/yolo/<名字>.onnx --name <名字> --to engine --force
 ```

-> 实测本仓库里的 `detect_hc90.engine` 就是这样失效的（用旧版 TensorRT 构建，
-> 当前 10.13 无法加载）。另外两个 engine 正常。
+> 本仓库实测过一次：`detect_hc90.engine` 用旧版 TensorRT 构建，当前的 10.13 直接
+> 加载不了，而 ONNX 完全正常。该模型已作为零引用模型移出仓库
+> （见 `models/yolo/README.md`），但这个坑对**任何**要长期存放的 engine 都成立：
+> 重装环境之后，第一件事就是 `doctor --check-engines`。

 **「类名显示成 `class_0`」**

@@ -9,22 +9,21 @@

 ## 现状

- `detect_best_1.onnx` —— 工件检测模型，被 `hole_detect.workpiece_weights` 使用。
+- `detect_best_1.onnx` —— 被 `hole_detect.workpiece_weights` 使用（`two_stage` 后端）。
+  这是本目录唯一在用的模型。

-## 历史遗留（已知问题）
+## 已修掉的悬空引用

-`config/site.yaml` 的这两处仍指向一个**不存在**的文件 `models/hole_insert/best.pt`：
+`config/site.yaml` 的 `paths.hole_weights` 与 `hole_detect.weights` 原先都指向
+**不存在**的文件 `models/hole_insert/best.pt`。`backend: two_stage` 时这两处不被读取，
+所以一直没暴露；一旦切成 `backend: yolo` 就会启动失败。

-```yaml
-paths:
-  hole_weights: ".../models/hole_insert/best.pt"     # ← 文件不存在
-hole_detect:
-  weights: ".../models/hole_insert/best.pt"          # ← 文件不存在
-```
+现已改为实际存在的 `detect_best_1.onnx`。同一个悬空的 `best.pt` 还藏在代码里
+（`hole_detector.py` 的 `weights_from_site` / `_default_model_path`，那里三个候选
+路径全都不存在，函数却总会返回第一个），也一并修成了以 site.yaml 为准、
+再退到实际存在的模型。

-`backend: two_stage` 时这两处不会被读，所以现在不影响运行；但一旦切成
-`backend: yolo` 就会启动失败。用 `bash ~/ros2/scripts/weights.sh doctor`
-能查出来。要么把真实权重按命名规则放进本目录，要么把这两处配置删掉。
+改权重相关路径后，用 `bash ~/ros2/scripts/weights.sh doctor` 复查悬空引用。

 ## 加新模型 / 看标签

@@ -38,6 +38,19 @@ bash ~/ros2/scripts/weights.sh labels detect_best_0
 bash ~/ros2/scripts/weights.sh labels detect_best_0 --set "工件,通止规"
 ```

+## 工作区里有哪些模型
+
+只保留**真正在用**的两个，避免 `weights.sh list` 被无用模型干扰、也避免误选到废模型：
+
+| 模型 | 用途 |
+|---|---|
+| `yolo/detect_best_0.onnx` + `.engine` | 工件/跟踪模型，即 `config/site.yaml → paths.yolo_weights` |
+| `hole_insert/detect_best_1.onnx` | 孔/工件检测，即 `hole_detect.weights` 与 `workpiece_weights` |
+
+曾经在这里、现已移出仓库的模型（`detect_hc90`、`detect_best`、`detect_yolo26_gongjian`）
+是零引用的历史遗留，二进制权重不进 git，所以是**移出到备份目录**而非直接删除；
+需要时搬回本目录即可，`weights.sh list` 会自动重新发现。
+
 ## 排错

 ```bash
@@ -46,9 +59,5 @@ bash ~/ros2/scripts/weights.sh doctor --check-engines

 `engine` 和 TensorRT 版本绑死：换过 TensorRT 后旧 engine 会加载失败，重导即可
 （`convert <同名>.onnx --name <名字> --to engine --force`）。
-
-## 历史遗留
-
-`active.pt` 是个指向 `detect_hc90.pt` 的符号链接，早期用来"切换当前模型"，
-现在没有任何节点会读它 —— 换模型请改 `config/site.yaml` 的 `paths.yolo_weights`。
-留着只是不想动别人的文件，可以安全删除。
+**注意 `doctor` 能查出这类静默失效** —— engine 反序列化返回空时不会报错，
+只会安静地不退任何检测框，很容易被当成"模型效果差"。
@@ -1,16 +0,0 @@
-# 模型类别标签（class names）
-#
-# 一个模型对应一份标签，放在权重旁边、同名前缀：
-#   detect_best_0.engine  ← 权重
-#   detect_best_0.labels.yaml  ← 本文件
-#
-# 写法：names 下面一行一个类名，第 1 行对应类别 0，第 2 行对应类别 1，依次类推。
-# 改完保存即生效，不需要重新转换模型、也不用重启环境（重跑节点即可）。
-#
-# 命令行查看/修改（推荐，不用手改本文件）：
-#   bash ~/ros2/scripts/weights.sh labels <模型名>
-#   bash ~/ros2/scripts/weights.sh labels <模型名> --set "工件,通止规"
-
-model: detect_best
-names:
-  - workpiece
@@ -1,16 +0,0 @@
-# 模型类别标签（class names）
-#
-# 一个模型对应一份标签，放在权重旁边、同名前缀：
-#   detect_best_0.engine  ← 权重
-#   detect_best_0.labels.yaml  ← 本文件
-#
-# 写法：names 下面一行一个类名，第 1 行对应类别 0，第 2 行对应类别 1，依次类推。
-# 改完保存即生效，不需要重新转换模型、也不用重启环境（重跑节点即可）。
-#
-# 命令行查看/修改（推荐，不用手改本文件）：
-#   bash ~/ros2/scripts/weights.sh labels <模型名>
-#   bash ~/ros2/scripts/weights.sh labels <模型名> --set "工件,通止规"
-
-model: detect_hc90
-names:
-  - workpiece
@@ -1,16 +0,0 @@
-# 模型类别标签（class names）
-#
-# 一个模型对应一份标签，放在权重旁边、同名前缀：
-#   detect_best_0.engine  ← 权重
-#   detect_best_0.labels.yaml  ← 本文件
-#
-# 写法：names 下面一行一个类名，第 1 行对应类别 0，第 2 行对应类别 1，依次类推。
-# 改完保存即生效，不需要重新转换模型、也不用重启环境（重跑节点即可）。
-#
-# 命令行查看/修改（推荐，不用手改本文件）：
-#   bash ~/ros2/scripts/weights.sh labels <模型名>
-#   bash ~/ros2/scripts/weights.sh labels <模型名> --set "工件,通止规"
-
-model: detect_yolo26_gongjian
-names:
-  - gongjian