目录

• 1 参数总表
  
• 2 参数具体说明
  
  • 2.1 模型参数组
    
  • 2.2 输入信息参数组
    
  • 2.3 校准参数组
    
  • 2.4 编译参数组
    
  • 2.5 自定义参数组
    
• 3 性能/精度相关参数
  
  • 3.1 性能相关参数
    
  • 3.2 精度相关参数
    
• 4 特性功能参数
  
  • 4.1 快速性能验证
    
  • 4.2 前处理归一化
    
  • 4.3 前处理Resize
    
  • 4.4 batch模型
    
  • 4.5 带宽优化
    
  • 4.6 推理抢占
    
  • 4.7 重新获取模型转换参数
    
    

大家使用地平线 PTQ 工具链进行模型转换时，都需要对应地配置一份 Yaml 文件，通过一些参数来告诉工具应该如何解析、校准和编译模型。下面我们将基于 J5 OE-v1.1.62 版本和 XJ3 OE-v2.6.2 版本详细介绍 Yaml 配置文件，官方说明文档请参考您当前版本的对应章节。

1 参数总表

2 参数具体说明

2.1 模型参数组

1. prototxt、caffe_model、onnx_model 用于配置模型文件。caffe1.0 模型仅配置 prototxt 和 caffe_model；ONNX 模型仅配置 onnx_model。例如 ONNX 模型配置：

2. march 为必选参数，用于指定编译后生成的 .bin 模型需要部署的平台架构。J5 平台需配置为 bayes，XJ3 平台需配置为 bernoulli2。例如 J5 平台模型配置为：

3. output_model_file_prefix 为可选参数，用于配置产出模型文件的名称前缀，默认值为 model。例如配置 mobilenetv1_224x224_nv12，那么工具产出的所有 ONNX 和 bin 模型文件均以此为前缀：

4. working_dir 为可选参数，用于配置产出物存放的路径，默认值为 model_output。若该目录当前不存在，则工具会自动创建。

5. layer_out_dump 为可选参数，用于指定混合异构模型是否保留输出中间层的能力。如果配置为 True，则从 ***_quantized_model.onnx 模型开始会为每一层都增加输出节点，如下图所示。该功能主要用于配合 vec_diff 向量比较工具（J5 链接；XJ3 链接）使用，但由于该工具增加的输出节点过多，所以其实不太推荐。如果需要比对整个模型在开发机 python 端和开发板 C++ 端的一致性，更建议使用 hb_verifier 工具（J5 链接；XJ3 链接）；如果需要比对某一层的输出，则建议使用下一个 output_nodes 参数。

6. output_nodes 为可选参数，用于指定模型的输出节点。以 03_classification/01_mobilenet 分类模型为例，若配置如下，则从 _original_float.onnx 模型开始即会增加这两个输出节点。

7. remove_node_type、remove_node_name 为可选参数，无默认值。用于将模型首/尾部，与输入/输出相连接的某种或某个算子，从模型中删除。目前支持删除的节点类型包括 “Quantize”、“Dequantize”、“Cast”、“Transpose”、“Reshape”、“Softmax”。其中，Quantize 和 Dequantize 节点无法从转换日志中查看到节点名称，需要使用 hb_perf 工具（J5 链接；XJ3 链接）可视化 bin 模型查看。以下提供了两种配置方式（请注意节点顺序），均可删除 mobilenetv1 模型尾部的 Softmax 和 Dequantize 节点。

删除成功后可在转换日志中查看到如下打印：

hb_perf 可视化删除节点前后的 bin 模型：

注意，Quantize、Dequantize 节点默认集成在模型中使用 CPU 计算，但更加高效的方式是删除后合入前后处理代码中，避免冗余的数据遍历操作。更多说明可见：反量化节点的融合实现。

8. debug_mode 为可选参数，无默认值。该参数用于配合精度 debug工具（J5 链接；XJ3 链接，也可参考社区文章：PTQ精度Debug工具）使用，分析时应配置如下：

9. node_info 为 J5专用 的可选参数，且 仅支持 ONNX 模型。该参数用于配置指定算子的输入输出数据类型为 int16，以及强制指定某些算子在 CPU 或 BPU 上运行。具体支持配置的算子请见算子约束列表（J5 链接；XJ3 链接）。例如通过如下配置，可将 03_classification/10_vargconvnet 模型尾部的 Reshape 算子合入上层 Conv，并以 int16 精度输出。

2.2 输入信息参数组

本节将以 05_miscellaneous/04_multi_input_example 多输入模型为例进行说明

1. input_name 用于指定模型输入节点的名称。当原始模型只有一个输入节点时，可以不配置，工具自动解析；多输入时则必须配置，如本例为：

2. input_shape 用于指定模型输入节点的数据尺寸。当模型输入为静态尺寸则为选配，工具自动解析；若模型输入为动态尺寸，则必须配置。且模型若为多输入，还应与 input_name 保持顺序一致。本例为静态尺寸，可以不配置，也可以按序配置如下：

3. input_type_train、input_layout_train 为必选参数，用于配置模型训练时的输入数据类型和排布。若模型为多输入，还应与 input_name 保持顺序一致。上例可配置为：

4. input_type_rt 、input_layout_rt 用于配置 .bin 模型部署时 runtime 数据的类型和排布，前者为必选，后者为可选参数。若模型为多输入，还应与 input_name 保持顺序一致。上例可配置为：

5. input_space_and_range 为可选参数，用于配置 input_type_rt: nv12 时的数据制式。若配置为 regular，则数据范围是 [0, 255]；若配置为 bt601_video，则数据范围有一定压缩，是 [16, 235]。该参数默认值为 regular，通常都无需配置。

6. input_batch 为可选参数，默认值为 1。当模型为单输入，且 input_shape 第一维为 1 时，可使用该参数将模型编译为 batch 模型，目前支持配置范围为 [1-4096]。例如想编译一个 batch4 的单输入模型，可配置如下，更多信息可见本文 4.4 节。

注：多输入模型尚不支持 input_batch 参数配置，但 batch 的多输入模型支持配置 input_shape 参数说明其 batch 大小。

7. norm_type、mean_value、scale_value 为可选参数，用于配置输入数据的归一化操作，并将其插入在模型前端进行 BPU 加速。其中：

• norm_type 默认值为 no_preprocess，所以若不配置，则表示不进行任何预处理，mean_value、scale_value 均失效；否则需对应配置。
• 更多配置方式说明可见用户手册对应章节（J5 链接；XJ3 链接），本文 4.2 章节 也提供了一个具体示例，说明如何从训练代码换算到 yaml 中应该配置的参数值。如下为上例多输入模型的参数配置，其第一个输入节点的归一化操作即为 (x - 123.68) * 0.017。

2.3 校准参数组

1. cal_data_dir、cal_data_type 用于指定校准数据存储的路径和类型。其中：
   • 若下文 calibration_type 校准方式为 load 或 skip，则两个参数均可以不配置；
   • 若校准数据为 JPEG 原图，且下文 preprocess_on 配置为 True，则 cal_data_type 可以不配置；
   • 若校准数据经过预处理，并以 np.tofile 保存（更多可见：图片校准数据准备问题介绍与处理），则 cal_data_type 会告知工具应以 float32 还是 uint8 类型读取；若未配置，并在非 load/skip 校准方式下，则工具会解析存储文件夹名称的后缀是否为 _f32 来判断数据读取类型。当 cal_data_type 配置与后缀名冲突时，其优先级更高。
   • 若模型为多输入，则两个参数应与 input_name 保持顺序一致，上例多输入模型的配置如下：

2. preprocess_on 为可选参数，默认值为 False，且仅适用于 4 维图像输入的模型，表示工具是否对图片进行自动处理，包括使用 skimage 读取图片，并 resize 到输入节点尺寸，用户可根据情况选择使用，通常为 False。

3. calibration_type、max_percentile、per_channel 都用于配置模型的校准方式，其中：

   • 若都不配置，则默认会以 default 方式进行校准搜索；

   • 建议优先尝试 default（J5 链接；XJ3 链接）和 mix（J5 链接；XJ3 链接）校准，日志中会打印搜索到的校准方式。若校准结果不理想，建议参考该文章进行分析和调优：模型精度验证及调优建议；

   • max_percentile 仅能配合 max 校准使用，用于调整截取点，默认值为 1，常用配置包括 0.99999/ 0.99995/ 0.99990/ 0.99950/ 0.99900；

   • per_channel 可以配合任意非 default/mix 方式使用，用于控制是否针对 featuremap 的每个 channel 进行校准；

   • 若模型为 QAT 导出模型，则 calibration_type 配置为 load，其他参数不配置。

4. run_on_cpu 为可选参数，无默认值，用于将指定算子强行从 BPU 回退至 CPU 使用 float32 类型进行计算，通常可以提升精度，但会降低性能，需综合考虑。模型精度不理想时，可基于 debug工具（J5 链接；XJ3 链接，也可参考社区文章：PTQ精度Debug工具）寻找量化敏感节点尝试回退。

5. run_on_bpu 为可选参数，无默认值。某些算子出于精度考虑（J5 链接；XJ3 链接），或者因为被动量化逻辑（社区文章：模型转换工具链中的主动量化和被动量化逻辑），会默认运行在 CPU 上；但若符合 BPU 约束条件，也可以通过该参数强行指定在 BPU 上加速，通常可以提升性能，但会降低精度，需综合考虑。支持指定的算子可以在 算子约束列表（J5 链接；XJ3 链接）中通过 Ctrl+F 寻找“run_on_bpu”关键字获取。

6. optimization 为可选参数，无默认值，用于提供一些性能/精度的调优手段，具体如下表：

1. 上表 {Nodekind} 为标准 ONNX 算子类型写法，例如：Conv，Mul，Sigmoid 等（区分大小写）。 具体请参考 ONNX官方OP文档 或 算子约束列表（J5 链接；XJ3 链接）

2. BPU 若以 Conv 结尾，默认会以 int32 高精度输出，其他算子均为 int8 低精度输出

2.4 编译参数组

1. compile_mode 为可选参数，默认值为 latency。该参数用于选择编译策略以优化 性能（latency）、带宽（bandwidth），还是平衡两者（balance）为目标。若配置为 balance，就需要对应配置如下 balance_factor 参数。通常模型如果没有严重超过预期的带宽占用，建议优先使用 latency 编译策略。

2. balance_factor 为可选参数，无默认值。若 compile_mode 配置为 balance，则必须对应配置此参数：配置为 0 即为带宽最优，对应 bandwidth 策略；配置为 100 即为性能最优，对应 latency 策略。更多说明可见本文 4.5 节。
3. debug 为可选参数，默认值为 False，但建议配置为 True，编译后会在 html 静态性能评估文件中增加逐层的信息打印，可以帮助分析性能瓶颈。该参数开启后不会影响模型的推理性能，但会极少量地增加模型文件大小。

4. core_num 为可选参数，默认值为 1。目前 J5 仅支持单核模型，可以不配置。XJ3 支持配置为 2，利用多个 BPU 核心同时完成一个推理任务，理想情况下，可在输入尺寸较大时得到 1.5 倍左右的 latency 加速。

5. optimize_level 为可选参数，用于配置模型编译的优化等级，共有 O0～O3 四个选项，默认值为 O0，即不做任何优化，编译速度最快。O1 至 O3 随着等级升高，会有更大的优化搜索空间，更长的编译时间，以及预期更好的模型性能。前期验证功能建议使用低等级编译，最后部署需使用 O3 编译。

6. input_source 为可选参数，无默认值，用于设置 .bin 模型的输入数据来源，工具默认会根据 input_type_rt 参数的值自动适配，通常无需用户手动配置。但针对 nv12/ gray 输入的模型，若在部署时希望使用 hbDNNRoiInfer 接口（J5 链接；XJ3 链接），由 BPU 自动完成 ROI 抠图 + Resize（非等比例，直接 Resize）功能，则需要显性配置，参考如下：

7. max_time_per_fc 为可选参数，用于指定模型每个 function-call（BPU的执行粒度）的最大可连续执行时间，单位 μs。编译后的模型在 BPU 上推理时，会表现为 1 个或多个 function-call，默认值 0 表示不做任何限制；若配置 [1000, 4294967295] 范围内的其他值，则会限制每个 function-call 的最大执行时间，模型只有在单个function-call 执行完时才有机会被抢占。详细信息可见：模型优先级控制（J5 链接；XJ3 链接）。

8. jobs 为可选参数，无默认值，用于指定模型编译时的进程数，需控制在机器支持的最大核心数范围内，一定程度上可加速编译时间，通常不配置。

9. advice 为可选参数，无默认值，用于提示模型编译后预估的耗时增加的情况，单位 μs，不配置或配置为 0 时表示不开启。因为 BPU 在实际推理时，会对模型每一层有跨距对齐的要求，导致某些不满足的 OP 需要做 padding 操作，所以若配置其他任意正整数开启该功能，则工具会在编译过程中进行模型耗时分析，当某个 OP 的实际计算耗时与预估计算耗时偏差大于指定值时，就会打印相关 log，包括耗时变化、数据对齐前后的 shape、以及 padding 比例等信息。

2.5 自定义参数组

3 性能/精度相关参数

3.1 性能相关参数

Yaml 参数中与模型性能相关的主要参数和影响如下，请基于使用场景正确配置：

*
[注1]* 反量化节点的融合实现

3.2 精度相关参数

当模型量化精度不符合预期时，请优先检查如下参数是否正确配置：

以下文章也提供了多个精度调优案例，以供参考：

1. PTQ精度调优手段-设置bias_correction

2. PTQ精度调优手段—设置Int16量化

3. PTQ精度调优手段—YOLOv8x设置Int16量化

4. 【PTQ精度debug示例】mnasnet_1.0_96精度问题分析

5. 【PTQ精度debug示例】repvgg_b2_deploy精度问题分析

6. 【PTQ精度debug示例】MobileVit_s精度问题分析

4 特性功能参数

本章节将针对常用的一些特性功能进行几种说明，帮助大家更好地理解和使用工具链，发挥其应有的功能。

4.1 快速性能验证

1. preprocess_on 参数 仅适用于 4 维图像输入的模型，仍然要求准备好 JPEG 原始图片数据，但工具会自动完成 skimage 图片读取，并 resize 到输入节点尺寸。开启后无需再配置 norm_type、mean_value、scale_value、cal_data_type 参数；
2. skip 参数适用于任何输入模型，无需再准备任何校准数据，工具会自动生成随机数据，并基于 max 方式校准，所以无需再配置 norm_type、mean_value、scale_value、cal_data_dir、cal_data_type 等参数。但显而易见，skip 校准的模型无法用于精度验证。
3. 另外，J5 工具链 OE-v1.1.52 版本（XJ3 暂不支持）新增 fast-perf 功能，可以帮助用户跳过 yaml 配置，直接编译出性能最佳模型，其使用方法如下：

4.2 前处理归一化

对于图片输入模型，其训练和部署通常都不会直接输入 [0, 255] 范围的数据，而是将其归一化至 [-1, 1] 等类似区间，从而更有利于训练及量化。地平线工具链支持将数据归一化操作集成进模型前端，并通过 BPU 加速推理。以下示例说明了如何从训练代码换算至 yaml 中对应的参数值。

模型源码片段：

换算参数值：

Yaml 配置：

若您已通过 Yaml 配置将数据归一化集成进模型，那么请勿在模型外部重复操作，避免二次归一化。

4.3 前处理Resize

数据除了归一化，通常还会进行 Resize 操作，地平线目前提供了如下 3 种实现方式：

1. 在 XJ3/J5 平台的视频通路上，均提供了 Pyramid 金字塔硬件，能够对摄像头采集的大分辨率数据执行 ROI 抠图 + Resize 操作，也是我们优先推荐、性能最高的方式。更多信息可见：J5 全流程示例解读；
2. 对于上游模型检测出的 Bounding Box，使用 input_source 参数编译出的 resizer 模型（只支持 nv12/ gray 输入），可以使用 hbDNNRoiInfer 接口自动完成抠图 + Resize + 模型推理。更多信息可见：resizer模型使用与部署；
3. 另外，J5 工具链 OE-v1.1.49b 版本新增 DSP 算子 hbDSPRoiResize，支持抠图 + 等比例 Resize。更多信息可见：在J5上使用DSP进行RoiResize。

4.4 batch模型

额外补充：
小模型在端侧部署也支持批量处理，从而减少 CPU 中断开销，可见：多模型批量推理。

4.5 带宽优化

同理可得该模型在如下编译策略下的指标，其中 balance 策略为 J5 平台 PTQ 工具链 OE-v1.1.62 版本新增功能，大家在实际使用中，可以根据模型情况进行调试，选择性能和带宽折中的方案。

4.6 推理抢占

4.7 重新获取模型转换参数

执行后终端会有如下日志打印，本地也会生成 hb_model_info.log 的日志文件：

结束语

最后，非常感谢大家能抽出时间看到这里，也希望这篇文档能帮助您更好地理解和使用地平线 PTQ 工具链的使用方式！