RDK X5 四类模型文件完整区分 + 生成 & 使用示例

先做全局定义，杜绝概念混淆

1. ONNX：PC 通用原始模型（跨平台标准）
2. 旧版可执行 .bin（第一代地平线模型）：easy_dnn/bpu_infer_lib 加载，RDK X3、早期 X5 legacy 镜像使用
3. 新版可执行 .hbm（新一代地平线模型）：hb_dnn/hbm_runtime 标准格式，OS3.x 主推
4. 编译临时 .bin：hb_mapper 编译 hbm 过程自动产出，中间碎片，不可独立加载

核心时序链路 PyTorch 训练 → 导出 ONNX → PC OE Docker 执行 hb_mapper → 生成一批临时 bin 权重文件 → 打包封装 → hbm

旧方案：ONNX → 老版本工具链 → 生成第一代可执行 bin 模型（现已淘汰！！！）

一、ONNX 文件（PC 通用模型文件）

生成方式（PC，PyTorch 示例）

python

运行

# export_onnx.py
import torch
from ultralytics import YOLO

model = YOLO("yolov8n.pt")
# 导出ONNX，固定输入尺寸640×640
model.export(format="onnx", imgsz=640)

执行

bash

运行

python3 export_onnx.py
# 输出：yolov8n.onnx

可选优化（推荐）

bash

运行

onnxsim yolov8n.onnx yolov8n_simplified.onnx

使用方法

唯一用途：作为模型编译器hb_mapper的输入源。 不能直接在 RDK 开发板运行！

bash

运行

# 在地平线OE Docker内执行编译
hb_mapper makertbin --config yolov8_nv12.yaml --model-type onnx

二、第一代可执行模型：*.bin（legacy 旧格式，淘汰方案）

对应在 /app/model/basic/ 看到的 yolov8_640x640_nv12.bin

生成方式

使用 ** 老版本地平线工具链（OE1.x）** 编译 ONNX，现已不再推荐，新版 OE 不再支持输出此类 bin。

⚠️ 新版 OE v2.x（适配 RDK X5 bayes-e）无法生成该类 bin 模型。

使用方法（仅旧镜像 OS2.x + easy_dnn）

1. 将yolov8_640x640_nv12.bin传到 RDK X5
2. C++ 代码使用easy_dnn接口加载

cpp

运行

// 旧版legacy伪代码
EasyDNN dnn;
dnn.Init("yolov8_640x640_nv12.bin");
dnn.SetInputData(nv12_frame_buf);
dnn.Run();

兼容性红线

OS3.x 官方镜像通常移除libeasy_dnn.so，无法加载此类 bin，直接报错。新项目禁止使用。

三、hbm 新一代标准模型文件（当前主推）

生成流程：ONNX → hb_mapper → 临时 bin → 打包生成 hbm

步骤 1：准备编译配置 yaml（yolov8_nv12.yaml，RDK X5 固定 march: bayes-e）

yaml

model_parameters:
  onnx_model: 'yolov8n_simplified.onnx'
  march: 'bayes-e'    # RDK X5固定架构
  output_model_file: 'yolov8n_640_nv12.hbm'
input_parameters:
  input_name: 'images'
  input_type: 'nv12'
  input_layout: 'hwc'
  input_shape: [640,640,3]

步骤 2：在 OE Docker 中执行编译命令

bash

运行

hb_mapper makertbin --config yolov8_nv12.yaml --model-type onnx

编译过程磁盘文件变化：

1. 工具自动生成大量 临时.bin*（量化权重分片）
2. 全部参数整合封装 → 最终产出 yolov8n_640_nv12.hbm
3. 编译完成后临时 bin 可以直接删除，不再需要

使用方法（RDK X5 新版 TROS hb_dnn / Python hbm_runtime）

C++ 示例伪代码

cpp

运行

// 加载hbm模型
HbmModel model;
model.Load("yolov8n_640_nv12.hbm");
// 送入vio_capture输出的NV12图像buffer
model.SetInput(nv12_buf);
model.Infer();  // BPU硬件推理
model.GetOutput();

Python 示例

python

运行

from hbm_runtime import HbmRuntime
runtime = HbmRuntime("yolov8n_640_nv12.hbm")
runtime.infer(nv12_image_data)

四、编译过程产生的【临时 bin 文件】

生成时机

执行hb_mapper makertbin编译 ONNX 期间自动生成，文件名随机。

使用规则

1. 开发者不手动操作、不拷贝、不上板
2. 仅编译器内部读取，用于组装 hbm
3. 脱离编译环境单独使用无任何意义
4. hbm 生成成功即可全部删除

❌ 重大误区：不要混淆「临时 bin」和「legacy 可执行 bin 模型」！两者后缀相同、用途完全无关。

四类文件汇总对照表

表格

文件类型	产生位置	生成工具	RDK 板端能否直接推理	配套推理库
ONNX	PC 训练环境	PyTorch/TensorFlow 导出	❌ 不能	仅作编译输入
legacy 可执行 *.bin（第一代模型）	PC 旧版 OE1.x	老 hb_mapper	✅ OS2.x 旧镜像	easy_dnn / bpu_infer_lib
hbm（新一代标准模型）	PC 新版 OE2.x	hb_mapper	✅ OS3.x 全系列	hb_dnn / hbm_runtime
编译临时 *.bin	PC OE 编译目录	hb_mapper 运行时自动生成	❌ 不能独立运行	无，仅供编译器内部使用

极简开发推荐流程（新项目统一标准）

PyTorch 训练 → 导出 ONNX → OE Docker hb_mapper 编译 → 丢弃临时 bin → 获得 hbm → RDK X5 hb_dnn 加载推理

答辩口述精简总结

ONNX 是 PC 端训练导出的通用模型，作为编译输入；

早期旧工具链可编译生成 legacy 格式 bin 模型，搭配 easy_dnn 运行，现已淘汰；

当前标准方案使用新版 hb_mapper 编译 ONNX，编译中途生成若干临时 bin 权重文件，最终封装输出 hbm；

hbm 是 RDK X5 新一代标准模型，通过 hb_dnn 库加载驱动 BPU 推理，推荐所有新项目使用。