# 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 日志
```

## int8 产物位置

最终的 X5 **int8** 模型就是：

```text
x5_quantization/mapper_output_bpu/best_bpu_bayese_640x640_nv12.bin
```

本机完整路径：

```text
/Users/chenyouyuan/cyy_ws/smart_car_2026/model/x5_quantization/mapper_output_bpu/best_bpu_bayese_640x640_nv12.bin
```

对应的量化配置是 `x5_quantization/best_bpu_int8.yaml`，量化检查信息在
`x5_quantization/mapper_output_bpu/best_bpu_bayese_640x640_nv12_quant_info.json`。

## 重新量化

需要 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` 检查模型元数据，再用真实相机输入验证
检测精度和端到端延迟。