Add YOLOv26n RDK X5 model and quantized artifacts

2026-08-07 11:15:41 +08:00
commit 7931375c8e
92 changed files with 24515 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,116 @@
+# YOLOv26n RDK X5 模型与量化产物
+
+这是基于 YOLOv26n 训练得到的检测模型，以及按 D-Robotics RDK X5 官方
+`rdk_x5` 模型仓库流程生成的 BPU 量化产物。
+
+官方参考：
+
+- <https://github.com/D-Robotics/rdk_model_zoo/tree/rdk_x5>
+- <https://developer.d-robotics.cc/rdk_doc/Algorithm_Application/model_zoo/model_zoo_intro>
+
+## 模型信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 浮点模型 | `best.onnx` |
+| ONNX IR / opset | IR 6 / opset 11 |
+| 输入 | `images`, `[1, 3, 640, 640]`, RGB |
+| 类别数 | 4 |
+| 类别名称 | `QR_code`, `line`, `end`, `roadblock` |
+| 原始 ONNX 输出 | `output0`, `[1, 300, 6]` |
+| BPU 输入 | NV12, 640x640 |
+| BPU 输出 | 三尺度 `(cls, box)` 原始特征，共 6 个 NHWC 张量 |
+
+原始 `best.onnx` 包含 YOLOv26 的端到端后处理。为了减少 BPU 与 CPU 之间的
+切换，`x5_quantization/best_bpu.onnx` 只保留检测网络和原始检测头，移除了
+TopK、Gather、索引解码以及最终检测结果拼接。后处理在 CPU 上执行：分类
+sigmoid、置信度筛选、LTRB 解码和 NMS。
+
+## 目录内容
+
+```text
+best.onnx                                      # 原始浮点 ONNX
+x5_quantization/
+  best_bpu.onnx                                # 裁剪后的 BPU 友好 ONNX
+  best_bpu_int8.yaml                           # hb_mapper 配置
+  mapper_output_bpu/
+    best_bpu_bayese_640x640_nv12.bin           # X5 可加载模型
+    *_quant_info.json                           # 输出量化参数
+    *_quantized_model.onnx                     # 量化检查模型
+  calibration_data/                            # 50 个 RGB/CHW/float32 校准输入
+  prepare_calibration.py                       # 生成校准输入
+  extract_yolo26_bpu.py                        # 裁剪 YOLOv26 后处理
+  postprocess_yolo26.py                        # CPU 后处理
+  quantize_x5.sh                               # Docker 一键量化
+  checker.log / mapper.log                     # checker 和 makertbin 日志
+```
+
+## 重新量化
+
+需要 Docker Desktop 和已加载的镜像：
+
+```text
+openexplorer/ai_toolchain_ubuntu_20_x5_cpu:v1.2.8
+```
+
+在本目录的上一级执行：
+
+```bash
+cd /Users/chenyouyuan/cyy_ws/smart_car_2026/model
+./x5_quantization/quantize_x5.sh
+```
+
+脚本会从 `../dataset` 的 `images/train` 和 `images/vel` 中均匀抽取 50 张图片，
+直接 resize 到 640x640，保存为 RGB、CHW、float32；`data_scale=1/255` 由
+`hb_mapper` 配置完成。量化目标为 `bayes-e`，默认 int8，编译优化等级为 O3，
+并启用 `set_Softmax_input_int8,set_Softmax_output_int8`。
+
+## BPU 输出与 CPU 后处理
+
+模型输出顺序固定为：
+
+```text
+cls_s8, box_s8, cls_s16, box_s16, cls_s32, box_s32
+```
+
+形状分别为：
+
+```text
+cls_s8 / box_s8     [1, 80, 80, 4]
+cls_s16 / box_s16   [1, 40, 40, 4]
+cls_s32 / box_s32   [1, 20, 20, 4]
+```
+
+可以直接复用 `x5_quantization/postprocess_yolo26.py`：
+
+```python
+from x5_quantization.postprocess_yolo26 import postprocess
+
+boxes, scores, class_ids = postprocess(
+    [cls_s8, box_s8, cls_s16, box_s16, cls_s32, box_s32],
+    classes=4,
+    score_threshold=0.25,
+    iou_threshold=0.7,
+)
+```
+
+返回的框坐标位于 640x640 模型坐标系。如果板端前处理使用 letterbox，需要
+根据实际缩放比例和 padding 将坐标映射回原始相机分辨率。
+
+## 量化结果
+
+`hb_mapper checker` 和 `hb_mapper makertbin` 均已通过。编译器对 X5 的估计延迟
+为 `8.913 ms`，最终 `.bin` 大小约 `3.7 MB`。输出余弦相似度如下：
+
+| 输出 | Cosine Similarity |
+| --- | ---: |
+| `cls_s8` | 0.985422 |
+| `box_s8` | 0.989597 |
+| `cls_s16` | 0.989395 |
+| `box_s16` | 0.993338 |
+| `cls_s32` | 0.998478 |
+| `box_s32` | 0.999024 |
+
+上述延迟是 Docker 中 OpenExplore 编译器的估计值，不是 X5 实板实测值。部署前
+应在板端用 `hrt_model_exec model_info` 检查模型元数据，再用真实相机输入验证
+检测精度和端到端延迟。