J6工具链模型X86推理方式说明

X86 推理是指 开发机（X86 CPU/GPU）上针对不同阶段的模型：ONNX模型、Hbir模型和hbm模型，进行相应的推理验证。绝大多数的推理验证不需要实际开发板，但是使用hbm_infer需要"board_ip"来连续开发板。以下是工具链常见的几种推理方式说明。

ONNX模型

HBRuntime推理库

HBRuntime是地平线提供的一套x86端模型推理库，支持PTQ链路各阶段产出的ONNX模型进行推理，并通过dict的数据格式传入推理接口中。

使用流程详见如下链：HBRuntime推理库。

使用示例如下：

ORTExecutor

ORTExecutor 是 HMCT（Horizon Model Convert Toolkit）提供的 ONNX 模型推理封装接口，底层基于onnxruntime。

Hbir 模型 (.bc)

编译器feed接口

feed() 是 hbdk4.compiler 中 Function 对象的方法，用于对 hbir（即.bc 模型）进行推理。

接口信息详见：模型推理使用示例

需要注意的是feed()只接受 np.ndarray 和 torch.Tensor 两种 Python 对象类型。.npy的输入数据不能直接传给该接口，需要先 np.load() 加载成 np.ndarray。该接口所需要的输入格式和输出格式一致，均包装成字典。使用示例如下：

HBRuntime推理库

使用流程详见如下链：HBRuntime推理库。

推理的原理是基于hbdk4 的 load() + function.feed()。因此需要注意hbdk的版本是否匹配。使用示例如下：

hrt_model_exec

hrt_model_exec详细介绍与使用示例请参考 hrt_model_exec工具介绍 。

该工具推理功能支持多输入模型的推理，支持图片输入、二进制文件输入、文本文件输入及NumPy数组文件输入，输入数据用逗号隔开。 模型的输入信息可以通过 model_info 进行查看。

hrt_model_exec工具模型输入说明详见：模型输入说明章节。

X86 仿真环境使用 hrt_model_exec 工具推理 quantized.bc，但需要 hbdk4相关的库 和 hrt_model_exec（UCP）的版本要匹配，如：UCP 3.14.7 配套 HBDK 4.9.7。

需要注意的是，板端的hrt_model_exec不支持推理quantized.bc。

该命令还有以下两个关键的参数配置：

• --dump_format来控制模型的输出格式，默认为bin的输出。

• --dump_precision控制txt 格式时的小数精度，默认 9 位。

UCP推理库(C++)

注意：X86 上推理hbm是指令级仿真，速度非常慢。推荐推理 quantized.bc，定点部分和 hbm 二进制一致。

X86 仿真环境使用 UCP 推理接口推理 hbm 模型前，需要设置 HB_UCP_SIM_PLATFORM_TYPE 环境变量用以指定要模拟的 BPU 架构。

UCP 推理接口使用示例请参考 模型推理应用开发指导 章节。

hbm 模型

注意：X86 上推理hbm是指令级仿真，速度非常慢。推荐推理 quantized.bc，定点部分和 hbm 二进制一致。因此只建议使用3.1节的方式进行推理。其他方法仅做示例补充，了解即可。

hbm_infer

hbm_infer是一个X86+板端联合通信模式的Validation工具，在X86端使用Python代码做模型前后处理工作，由板端Server执行实际推理过程，用于提升模型精度评测效率，降低开发成本。和其他的python推理接口一样传入的数据形状只需要和模型的输入validShape 一致即可，不需要padding。

使用流程详见如下链接：hbm_infer工具

用户只需传 host + local_hbm_path 即可一键完成 SSH部署 + 文件上传 + gRPC连接。使用demo如下：

使用该工具推理需要注意输入的合法性检查以及数据预处理相关操作：

1. 合法检查：

   1. 名称检查：input dict 的 key 必须与 get_input_info() 返回的输入名称完全匹配。

   2. 类型检查：不显式做数据类型强制转换，需要用户保证 tensor_type与模型预期一致。

   3. shape 检查：需要用户确保 shape 与模型的 valid_shape 匹配，动态维度用 input_valid_shape 或 input_stride 指定。

2. 数据预处理建议：

   1. 对于 NV12 等 Pyramid/Resizer 输入，hbm_infer 不会自动做颜色空间转换或归一化，用户需按 input_type_rt 准备好数据（如将 RGB 转为 Y/UV 分量的 NV12 格式）。

   2. 如果配置了 mean_value/scale_value，这些归一化由模型内部完成，用户不需要手动减均值除方差。

编译器feed接口（不推荐）

feed() 是 hbdk4.compiler 中 Function 对象的方法，用于对hbm模型进行推理。

接口信息详见：模型推理使用示例

1. 合法检查（由 hbdk runtime 做）：

   1. 数据类型校验：输入的 numpy dtype 必须与模型预期的 tensor_type 兼容。

   2. Shape 校验：静态维度必须完全匹配；动态维度同样需要满足 shape 约束，不匹配时会抛出异常。

   3. 数量校验：输入 tensor 的数量必须与模型定义一致。

   4. 没有隐式的布局转换（NCHW/NHWC），需要用户按模型预期准备。

2. 数据预处理：同 hbm_infer的相关方式。

HBRuntime推理库（不推荐）

HBRuntime是地平线提供的一套x86端模型推理库，支持对地平线工具链转换过程中产出的HBM模型进行推理，并通过dict的数据格式传入推理接口中。HBRuntime是X86端推理库，你传入的数据形状只需要和模型的输入一致即可，不需要padding。

使用流程详见如下链：HBRuntime推理库。

HB_HBMRuntime 底层会加载 hbdk4-runtime 的动态库，因此需要注意hbdk的版本是否匹配。使用示例如下：

1. 合法检查：

   1. 输入 tensor 数量检查：feed dict 中提供的输入数量必须与模型输入数量一致。

   2. 输入名称匹配：feed 的 key 必须匹配模型注册的输入名称。

   3. 数据类型对齐：如果 feed 的数据类型与模型预期的 tensor_type 不匹配，runtime 会尝试隐式转换或报错。

   4. Shape 校验：静态 shape 必须完全匹配；动态 shape 需要满足 valid_shape 约束。

2. 数据预处理：同 hbm_infer的相关方式。

hrt_model_exec（仅推荐模型信息查看）

hrt_model_exec使用方式和板端相同，但需要配置HB_UCP_SIM_PLATFORM_TYPE环境变量用以指定要模拟的 BPU 架构

具体可参考：hrt_model_exec infer使用示例。

推理接口的详细链接如下：模型推理

鉴于 hbm 在 X86 端推理速度较慢，因此只建议在 X86端查看model_info。

具体可参考：hrt_model_exec model_info使用示例