RDK X5 工具链 PTQ 量化

要解决什么问题

在 RDK X5 上跑推理，通常不能直接把训练导出的 ONNX 丢进板端：需要走 D-Robotics OpenExplorer 的 PTQ 链路，产出 .bin（或 .hbm）并在 BPU 上执行。常见卡点包括：hb_mapper checker 报 unsupported op、校准集格式/数量不对导致统计错位、yaml 里输入类型与归一化和训练不一致、编译后 cosine similarity 偏低，以及 BPU 利用率或 latency 不达预期。本技能围绕 OE v1.2.8 (py310) 的模型无关 PTQ 工作流，把「ONNX → 可部署产物 → 精度/性能验证」串成可复用的步骤与查阅索引。

技能如何组织工作流

主流程按五步展开，并指向 references/ 下的专题文档：

1. 算子预检：在 OE Docker 内跑 hb_mapper checker，读 hb_mapper_checker.log 看 BPU/CPU 分布；不支持算子按 troubleshooting 做替换或 custom_op_method: register。
2. 校准数据：默认 nv12 路径；每张图一个 raw bytes 文件（tensor.tofile），不能用 .npy；数量建议 20 张起步，预处理 resize/通道顺序与训练对齐，归一化由 yaml 的 norm_type + scale_value 负责。
3. yaml 配置：四类必改项与 70+ 字段、输入类型矩阵见 yaml-reference.md。
4. 编译：Docker 内 hb_mapper makertbin，得到 .bin、定点 ONNX 与编译报告 html/log。
5. 验证：分类 cosine ≥ 0.99，检测/分割 ≥ 0.95；板端可选 hrt_model_exec；掉点走 accuracy-tuning.md，性能见 performance.md。

适用边界

• 仅覆盖 PTQ，不含 QAT；芯片范围是 RDK X5 + OE v1.2.8，不适用于 X3/Ultra/S100 等。
• 所有 hb_mapper* / hb_perf 必须在 OE Docker 内执行；端到端 YOLO 训练→量化→ROS2 部署应使用 RDK YOLO Toolkit。
• 若只需导出 ONNX、不做量化，应使用框架自带导出工具，而非本流程。