# 算法权重模块（models/）

这个目录放**算法模型权重**和它们的**类别标签**。机器人软件里"算法"和"机械/电气"
变化节奏完全不同：机械改一次要几个月，模型换一版可能一周几次。所以这一块单独
成模块，有自己的一套约定和工具，改模型不需要动任何 C++/节点代码。

> **要改这个模块的人，先读完本文。** 下面是规则，不是建议。

---

## 1. 目录长什么样

```
models/
├── README.md              ← 本文（模块规则）
├── staging/               ← 非标准格式先丢这里，等转换
│   ├── .gitkeep
│   └── done/              ← 转换完成后源文件自动归档到这里
├── yolo/                  ← 一个"分组"（就是个子目录，名字随意）
│   ├── detect_best_0.onnx
│   ├── detect_best_0.engine
│   └── detect_best_0.labels.yaml
└── hole_insert/
    ├── detect_best_1.onnx
    └── detect_best_1.labels.yaml
```

**分组**只是一个子目录名，用来分门别类，没有程序语义。默认用 `yolo`。

---

## 2. 命名规则（重要）

同一个模型的**所有格式 + 标签**必须用**同一个名字主干**、放在**同一个目录**：

| 文件 | 作用 | 进 git？ |
|---|---|---|
| `<名字>.pt` | PyTorch 原始权重 | 否 |
| `<名字>.onnx` | 中间格式，CPU 推理后端也用 | 否 |
| `<名字>.engine` | TensorRT 引擎，GPU 推理用 | 否 |
| `<名字>.labels.yaml` | **类别标签** | **是** |

因为推理代码是按"同目录同主干"去找配套文件的（`resolve_weights` 找 `.engine`，
标签找 `.labels.yaml`）。所以：

- ✅ `detect_best_0.onnx` + `detect_best_0.engine` + `detect_best_0.labels.yaml`
- ❌ `detect_best_0.onnx` + `detect_best_0_fp16.engine`（名字对不上，找不到）
- ❌ `detect_best_0.onnx` + `labels_detect_best_0.yaml`（标签名对不上）

**一份标签服务同一个模型的所有格式。** 换 `.pt`→`.engine` 后端时类名不会变。

---

## 3. 标签（class names）

### 为什么要有单独的标签文件

模型输出的是**类别索引**（0/1/2…），要翻译成人看得懂的名字。这件事原先没有统一
做法，三种后端各来一套，而且**TensorRT 那一环会把标签弄丢**。

丢的原因是硬的：TensorRT 引擎要用 `trt.OnnxParser` 重新构建，而
**当前安装的 TensorRT（10.13）Python API 根本没有 metadata 读写接口** ——
`INetworkDefinition` / `IBuilderConfig` / `ICudaEngine` 上都没有任何 metadata 方法。
实测二进制里搜一下就能看出来：

```
detect_best_0.engine   搜不到 "workpiece"   → 标签已丢
```

丢了的后果很隐蔽：读不到名字时代码会退化成把索引当名字用（类名变成 `"0"`），
而预览界面又不画类名 —— **没有任何地方看得出标签丢了**。

所以标签放在**旁边的文本文件**里。它不是"退而求其次"，而是唯一可行且有好处：

1. **可修改** —— 改标签不用重新转换模型，存盘即生效；
2. **跨格式统一** —— `.pt`/`.onnx`/`.engine` 共用一份，换后端名字不变。

### 写法

`<名字>.labels.yaml`：

```yaml
model: detect_best_0        # 可选，写对了能帮你发现"标签文件拷错了模型"
names:
  - workpiece               # 第 1 行 = 类别 0
  - tongzhigui              # 第 2 行 = 类别 1
```

第 1 行对应类别 0，第 2 行对应类别 1，依次类推。也认这些写法（从别处拷配置常见）：

```yaml
names: {0: workpiece, 1: tongzhigui}   # 字典形式（Ultralytics data.yaml 风格）
```
```yaml
names: "workpiece, tongzhigui"         # 逗号串
```
```yaml
workpiece                              # 纯文本，一行一个（classes.txt 风格，注释行以 # 开头）
```

### 读取优先级

```
<名字>.labels.yaml  >  ONNX 内嵌 metadata  >  模型内嵌 metadata  >  占位符 class_0
```

旁挂文件**必须**赢，因为它是人能改的那一份。否则"我明明改了标签为什么不生效"
会变成一个很难查的问题。

全都读不到时会用占位名 `class_0`、`class_1`…，并且**打一条 warning**。
刻意不用裸数字 `"0"` —— 那个和"真的有个叫 0 的类"分不出来。

### 怎么改 / 怎么看

```bash
bash scripts/weights.sh labels detect_best_0                        # 看
bash scripts/weights.sh labels detect_best_0 --set "工件,通止规"      # 直接改
bash scripts/weights.sh labels detect_best_0 --set-file classes.txt  # 从文本文件导入
bash scripts/weights.sh labels detect_best_0 --from-model            # 把模型内嵌标签抄出来变成可编辑
bash scripts/weights.sh labels detect_best_0 --json                  # 给程序读
bash scripts/weights.sh labels detect_best_0 --clear                 # 删掉，回到模型内嵌
```

改完**重跑一下节点**就生效，不用重新转换模型、不用重建 engine。

---

## 4. 加一个新模型（完整流程）

### 步骤 1：把原始文件丢进 staging

不管它原来叫什么、什么格式，先扔进 `models/staging/`：

```bash
cp ~/下载/best_v3_final\(1\).pt ~/ros2/models/staging/
```

### 步骤 2：一条命令转换 + 改名 + 归位

```bash
bash ~/ros2/scripts/weights.sh convert staging/best_v3_final\(1\).pt --name workpiece --group yolo
```

这条命令会：

1. `--name workpiece` → 产出统一叫 `workpiece.onnx` / `workpiece.engine`（**自动改名**）
2. 依次跑 `PT → ONNX → engine`（TensorRT 只能由 ONNX 构建，所以中间产物必出）
3. 把产出放到 `models/yolo/`（**自动归位**）
4. **顺带把标签落成 `workpiece.labels.yaml`**（从源模型内嵌 metadata 抄）
5. 把 staging 里的源文件挪到 `models/staging/done/`（staging 永远是一份"待办清单"）

常用选项：

| 选项 | 用途 |
|---|---|
| `--to onnx` | 只要 ONNX，不建 engine（不需要 GPU） |
| `--to engine` | 只要 engine（仍会先产出 onnx 做中间产物） |
| `--imgsz 640` | 输入尺寸（默认取 `config/site.yaml` 的 `yolo.imgsz`） |
| `--labels "工件,通止规"` | 顺手写标签 |
| `--group <分组>` | 输出到别的子目录 |
| `--force` | 覆盖已存在的产出（不加则拒绝覆盖，防误删） |
| `--dry-run` | 只看计划，不动文件 |
| `--no-fp16` | engine 不用 FP16 |
| `--keep-staging` | 保留 staging 里的源文件 |

### 步骤 3：让配置指向它

改 `config/site.yaml`：

```yaml
paths:
  yolo_weights: "/home/USER/ros2/models/yolo/workpiece.onnx"   # 写 onnx；engine 会自动找同名的
yolo:
  backend: "tensorrt"    # tensorrt / onnx / auto
  imgsz: 640             # 必须等于该模型的输入尺寸
```

> 写 `.onnx` 路径即可。`backend: tensorrt` 时程序会自动找同名的 `.engine`；
> 写 `.pt` 也一样能找到 `.engine`。所以换后端不用改配置。

### 步骤 4：确认

```bash
bash ~/ros2/scripts/weights.sh list      # 模型在不在、标签读不读得出来
bash ~/ros2/scripts/weights.sh doctor    # 体检
```

---

## 5. 体检与排错

```bash
bash ~/ros2/scripts/weights.sh doctor --check-engines
```

会检查：

- 每个模型的标签来源；缺标签的会指出期望的文件名
- **engine 能不能被当前 TensorRT 加载**（见下）
- `config/site.yaml` 里指向不存在的文件的**悬空引用**
- `backend: tensorrt` 但同名 `.engine` 不存在（启动会直接失败）
- staging 里有没有待转换的文件

### 常见问题

**「engine 明明在，启动却说加载失败」**

**引擎和 TensorRT 版本是绑死的。** 换了 TensorRT（重装环境、升级 CUDA）
之后旧引擎会直接反序列化失败，报 `incompatible serialization version` 之类。
表现是"文件在、大小也对，就是不能用"。用 `doctor --check-engines` 能查出来，
重导一次即可：

```bash
bash scripts/weights.sh convert models/yolo/<名字>.onnx --name <名字> --to engine --force
```

> 实测本仓库里的 `detect_hc90.engine` 就是这样失效的（用旧版 TensorRT 构建，
> 当前 10.13 无法加载）。另外两个 engine 正常。

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

标签没配上。`weights.sh labels <名字>` 会告诉你缺什么，然后
`--from-model` 或 `--set` 补一份。

**「同一个模型，换个后端类名就变了」**

不该发生。如果出现了，说明少了 `.labels.yaml`，各后端的回退来源不一致。
补上旁挂文件即可。

**「`convert` 说目标已存在」**

默认不覆盖，防止把别人的模型冲掉。确认要覆盖加 `--force`。

---

## 6. 规则（改动本模块时必须遵守）

1. **二进制不进 git。** 靠 `.gitignore` 的通配规则挡住。新加分组不用改 `.gitignore`。
2. **`.labels.yaml` 要进 git。** 它是配置，体积小，是团队间的唯一事实来源。
3. **不要把类名写死在代码里。** 一律走 `arm_application.model_labels`。
   已清理过的反例：`onnx_workpiece.py` 里曾硬编码 `{0: "workpiece"}`，
   `hole_detect_hough.py` 里曾硬编码框上画的字 `"gongjian"`（而真类名是 `workpiece`）。
4. **不要在"就地"改权重名字来换模型。** 用 `weights.sh convert --name`，
   让工具保证"名字主干一致 + 同目录"这条不变量。
5. **不要手工搬 engine 到别的目录或改名。** 改名会切断和 onnx/标签的关联。
6. **新增推理后端时，标签必须走 `model_labels.read_labels()`**，
   否则又会造出一个"某个后端读不到标签"的坑。
7. **`models/staging/` 不是永久存储。** 它只放"待转换"的东西。

---

## 7. 代码在哪

| 位置 | 作用 |
|---|---|
| `arm_application/model_labels.py` | 标签读写、来源优先级、占位符（纯逻辑，无 ROS） |
| `arm_application/weights_layout.py` | 目录布局、模型发现、转换链规划（纯逻辑，无 ROS） |
| `scripts/weights.py` | 命令行实现（转换真正干活的地方） |
| `scripts/weights.sh` | 薄封装：准备环境 → 转发给 `weights.py` |
| `scripts/export_yolo_trt.sh` | **旧命令**，现在转发到 `weights.sh`，保持兼容 |
| `arm_application/yolo_detector.py` | 运行时加载模型 + `resolve_class_labels()` |
| `arm_application/onnx_workpiece.py` | ONNX Runtime 后端，读标签同样走 `model_labels` |

测试：`src/arm_application/test/test_model_labels.py`（标签）、
`test_weights_layout.py`（布局/发现/CLI）。

---

## 8. 相关文档

- `docs/SITE_CONFIG.md` —— `paths.yolo_weights` / `yolo.backend` 等配置项
- `docs/WORKSPACE.md` —— 工作区总览
- `docs/TRACKING.md` —— 换模型要同时改哪几处