PTQ配置文件详解

芯链情报局 · 2023 年9 月 1 日 02:57

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 参数具体说明 将对所有参数一一展开介绍，帮助大家更全面地了解其使用场景和配置方法；

3 性能/精度相关参数 将归纳整理所有与性能/精度相关的参数，请确保正确配置，避免形成错误的评测结果；

4 特性功能参数 将针对大家常用的一些功能特性抽离出对应参数，进行组合介绍，帮助大家更好地了解地平线 PTQ 工具链的能力。

1 参数总表

参数名称

参数作用

可选/必选

默认值

支持平台

模型参数组

prototxt

指定 Caffe 浮点模型的 prototxt 文件名称

两种模型二选一

/

XJ3、J5

caffe_model

指定 Caffe 浮点模型的 caffemodel 文件名称

/

XJ3、J5

onnx_model

指定 ONNX 浮点模型的 onnx 文件名称

/

XJ3、J5

march

指定产出混合异构模型需要支持的平台架构

必选

/

XJ3、J5

output_model_file_prefix

指定转换产出混合异构模型的名称前缀

可选

model

XJ3、J5

working_dir

指定模型转换输出的结果的存放目录

可选

model_output

XJ3、J5

layer_out_dump

指定混合异构模型是否保留输出中间层值的能力

可选

False

XJ3、J5

output_nodes

指定模型的输出节点

可选

/

XJ3、J5

remove_node_type

设置删除节点的类型

可选

/

XJ3、J5

remove_node_name

设置删除节点的名称

可选

/

XJ3、J5

debug_mode

保存用于精度 debug 分析的校准数据

可选

/

XJ3、J5

set_node_data_type

指定算子 int16 输出，其功能已合入 node_info

可选

/

J5

node_info

指定算子 int16 输入输出，或强制算子在 CPU 或 BPU 上运行

可选

/

J5

输入信息参数组

input_name

指定原始浮点模型的输入节点名称

可选

/

XJ3、J5

input_type_train

指定原始浮点模型的输入数据类型

必选

/

XJ3、J5

input_layout_train

指定原始浮点模型的输入数据排布

必选

/

XJ3、J5

input_type_rt

转换后混合异构模型需要适配的输入数据格式

必选

/

XJ3、J5

input_layout_rt

转换后混合异构模型需要适配的输入数据排布

可选

/

XJ3、J5

input_space_and_range

指定输入数据格式的特殊制式

可选

regular

XJ3、J5

input_shape

指定原始浮点模型的输入数据尺寸

可选

/

XJ3、J5

input_batch

指定转换后混合异构模型需要适配的输入 batch 数量

可选

1

XJ3、J5

norm_type

在模型中添加的输入数据预处理方法

可选

no_preprocess

XJ3、J5

mean_value

指定预处理方法的图像减去的均值

可选

/

XJ3、J5

scale_value

指定预处理方法的数值 scale 系数

可选

/

XJ3、J5

校准参数组（所有参数并非独立可选，不能都不配置）

cal_data_dir

指定模型校准使用的标定样本的存放目录

可选

/

XJ3、J5

cal_data_type

指定校准数据二进制文件的数据存储类型

可选

/

XJ3、J5

preprocess_on

开启图片校准样本自动处理

可选

False

XJ3、J5

calibration_type

校准使用的算法类型

可选

default

XJ3、J5

max_percentile

用于调整 max 校准的截取点

可选

1.0

XJ3、J5

per_channel

是否对 featuremap 的每个 channel 分别校准

可选

False

XJ3、J5

run_on_cpu

强制算子 CPU 运行，其功能已合入 node_info

可选

/

XJ3、J5

run_on_bpu

强制算子 BPU 运行，其功能已合入 node_info

可选

/

XJ3、J5

optimization

提供多种性能/精度的调优手段

可选

/

XJ3、J5

编译参数组（要求至少有一个参数，不能都不配置）

compile_mode

编译策略选择

可选

latency

XJ3、J5

balance_factor

balance 编译策略时的比例系数

可选

/

J5

debug

是否打开编译的 debug 信息

可选

False

XJ3、J5

core_num

模型运行核心数

可选

1

XJ3、J5

optimize_level

模型编译的优化等级选择

可选

O0

XJ3、J5

input_source

设置上板 bin 模型的输入数据来源

可选

/

XJ3、J5

max_time_per_fc

指定模型每个 function-call 的最大可连续执行时间(单位μs)

可选

0

XJ3、J5

jobs

编译 bin 模型时的进程数

可选

/

XJ3、J5

advice

提示模型编译后预估的耗时增加的情况(单位μs)

可选

/

XJ3、J5

自定义算子参数组（可以都不配置）

custom_op_method

自定义算子策略选择

可选

/

XJ3、J5

op_register_files

自定义算子的 Python 实现文件名称

可选

/

XJ3、J5

custom_op_dir

自定义算子的 Python 实现文件存放路径

可选

/

XJ3、J5

2 参数具体说明

2.1 模型参数组

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

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

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

output_model_file_prefix: mobilenetv1_224x224_nv12

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

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

layer_out_dump: False # 若配置为True，则_quantized_model.onnx如下

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

output_nodes: ‘conv5_6/sep; conv6/dw’ # 直接配置节点名称即可

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

remove_node_type: “Softmax; Dequantize” # 或
remove_node_name: “prob; fc7_1_HzDequantize”

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

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

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

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

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

node_info: {
“Reshape_134”: {
‘ON’: ‘BPU’,
‘OutputType’: ‘int16’
}
}

2.2 输入信息参数组

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

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

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

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

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

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

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

input_batch: 4

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

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。

norm_type: data_mean_and_scale; data_mean_and_scale; data_mean_and_scale
mean_value: 123.68; 116.78; 103.94
scale_value: 0.017; 0.017; 0.017

2.3 校准参数组

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 保持顺序一致，上例多输入模型的配置如下：

cal_data_dir: ./calibration_data_b; ./calibration_data_g; ./calibration_data_r
cal_data_type: uint8; uint8; uint8

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

preprocess_on: False
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，其他参数不配置。

calibration_type: default # 建议优先尝试 default、mix

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

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

run_on_bpu: xxx; xxx # 配置算子名称，多个算子通过；隔开
optimization 为可选参数，无默认值，用于提供一些性能/精度的调优手段，具体如下表：

配置项

作用

XJ3

J5

set_model_output_int8

设置模型为 int8 低精度输出

支持

支持

set_model_output_int16

设置模型为 int16 低精度输出

不支持

支持

set_{NodeKind}_input_int16

指定某类算子输入/输出 int16 量化，如因节点上下文导致不支持，则会自动回退 int8 计算并打印 log

不支持

支持

set_{NodeKind}_output_int16

不支持

支持

set_Softmax_input_int8

将 Softmax 算子量化成 int8 并在 BPU 上计算

不支持

支持

set_Softmax_output_int8

不支持

支持

asymmetric

尝试开启非对称量化，在某些模型上可以提升量化精度；default 校准时会由算法自动选择，无法显性配置

不支持

支持

bias_correction

使用 BiasCorrection 量化方法，在部分模型上可以提升量化精度

不支持

支持

lstm_batch_last

针对 J5 BPU，当 LSTM 算子的 batch-input size 较大时，可以将 batch 维度转换到 W 维度进行计算（保障等价性），更贴合硬件计算逻辑，一些场景下可以实现推理性能加速

不支持

支持

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

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

2.4 编译参数组

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

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

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

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

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

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

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

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

advice: 1 # 通常不配置

2.5 自定义参数组

custom_op_method、 op_register_files、custom_op_dir 均为可选参数，且无默认值，分别用于指定 CPU 自定义算子的使用策略（目前仅支持 register），Python 实现文件的名称和存放路径。具体还请参考：自定义算子开发（J5 链接；XJ3 链接）。

3 性能/精度相关参数

3.1 性能相关参数

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

模型参数组

march

配置错误会导致编译出其他平台模型，其算子支持和性能预估都会存在较大偏差

layer_out_dump

开启会导致模型每一层都输出，严重影响性能，请配置为 False

output_nodes

配置后会增加输出节点，降低一定的性能，非必需节点请勿随意配置

remove_node_type

目前支持删除的节点基本都运行在 CPU 上，通过合入前后处理等操作，可以提升整体性能；反量化节点合入后处理的详细说明可见：反量化节点的融合实现[注1]

remove_node_name

输入信息参数组

input_batch

针对大算力的 J5 平台，我们更建议小模型使用 batch 模式推理，从而提升计算/访存比，更多信息可见本文 4.4 节

校准参数组

run_on_cpu

主要用于精度调优，但将算子回退至 CPU 一定会降低性能，一是其执行效率远低于 BPU，二是 CPU 和 BPU 间的调度会增加量化/反量化计算（CPU执行），所以应尽量少用

run_on_bpu

将某些符合约束的 CPU 算子指定在 BPU 上运行，通常能够提升性能，但会引入一定精度损失，请综合考虑

optimization

提供模型低精度输出、lstm 特定场景优化等性能调优手段

编译参数组

compile_mode

默认配置为 latency 优先，但若存在严重超过预期的带宽占用，可配置为 bandwidth，此时性能会有所降低

core_num

仅 XJ3 支持配置为 2，可在输入尺寸较大时得到 1.5 倍左右的 latency 加速，但双核模型的端侧推理会同时占用两个 BPU 核心，其他模型无法同时运行，请综合考虑

optimize_level

部署应用时请用 O3 编译，虽然编译时间最长，但性能最佳

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

3.2 精度相关参数

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

输入信息参数组

input_space_and_range

不同配置的数据范围不一样，请正确配置

norm_type

数据归一化操作，请和模型训练/推理时保持一致

mean_value

scale_value

校准参数组

preprocess_on

开启后工具会基于 skimage 读取图像并直接 resize ，若与训练/推理时的预处理操作不一致，会引入误差

run_on_bpu

指定某些算子运行在 BPU 上，通常能提升性能，但会降低精度

若已检查参数配置和 pipeline 代码均正确，可进行校准方式调试，推荐优先尝试 default 和 mix；若仍不满足预期，可使用精度 debug工具（J5 链接；XJ3 链接，也可参考社区文章：PTQ精度Debug工具）进行分析，并使用如下参数进行调优：

模型参数组

debug_mode

保存用于精度 debug 分析的校准数据

node_info

提供 int16 和 run_on_cpu 的配置能力

校准参数组

calibration_type

除了 default、mix，还支持 max、kl 校准

max_percentile

用于调整 max 校准截取点，常用配置包括 0.99999/ 0.99995/ 0.99990/ 0.99950/ 0.99900

per_channel

开启后会对 featuremap 的每个 channel 分别校准，可配合 max、kl 使用

run_on_cpu

通常用于将量化敏感节点回退至 CPU 提升计算精度

optimization

提供 int16、BiasCorrection 等多种精度调优手段

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

4 特性功能参数

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

4.1 快速性能验证

为了方便大家快速转换模型、验证性能，地平线提供了 preprocess_on、skip 两个参数帮助大家省去校准数据的准备环节。其中：

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

hb_mapper makertbin --fast-perf --march bayes --model model.onnx --model-type onnx

4.2 前处理归一化

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

模型源码片段：

def base_transform(img, size, mean, std):
    x = cv2.resize(img, (size, size)).astype(np.float32)
    x /= 255.
    x -= mean
    x /= std
    return x
    
class BaseTransform:
    def __init__(self, size, mean=(0.406, 0.456, 0.485), std=(0.225, 0.224, 0.229)):
        self.size = size
        self.mean = np.array(mean, dtype=np.float32)
        self.std = np.array(std, dtype=np.float32)

换算参数值：

norm_data = ( data/255 - mean ) / std
          = ( data - 255*mean ) * ( 1/(255*std) )

Yaml 配置：

norm_type: 'data_mean_and_scale'
mean_value: '103.53 116.28 123.675'            # 255*mean
scale_value: '0.01742919 0.017507 0.01712475'  # 1/(255*std)

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

4.3 前处理Resize

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

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

4.4 batch模型

地平线支持将模型编译为 batch 模型，该功能主要应用于小模型场景，用于提升模型推理时的计算/访存比。相比于 XJ3，batch 模式在大算力的 J5 平台上会有更好的收益。您可参考用户手册的相关章节编译多 batch 模型（J5 链接；XJ3 链接），并参考社区文章 Batch模型推理进行板端部署。

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

4.5 带宽优化

除了性能和精度指标，带宽占用也是我们在系统方案中必须关注的一个指标。仅针对 BPU 模型部分，其带宽占用可通过 html 静态性能评估文件（模型转换后自动生成）获取。如下即为 04_detection/03_yolov5x 模型基于 latency 策略编译得到静态性能，可见其单帧推理的读写带宽约为 172.19 MB，直方图中峰值带宽为 9.81 GB/s。

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

compile_mode

balance_factor

latency (ms)

单帧读写带宽 (MB)

峰值带宽 (GB/s)

latency

/

25.01

172.19

9.81

balance

2

32.23

150.39

8.66

bandwidth

/

48.5

143.6

6.45

4.6 推理抢占

在模型部署层面，地平线支持通过 hbDNNTaskPriority 参数（J5 链接；XJ3 链接）控制推理任务的优先级，配置为最高 255 的即为抢占任务。而 Yaml 中的 max_time_per_fc 参数可将低优模型进一步拆分成多个 function-call，从而让抢占细粒更加精细。更多信息可见：模型优先级控制（J5 链接；XJ3 链接）。

4.7 重新获取模型转换参数

当我们丢失 yaml 文件，只有最后生成的 bin 模型文件时，地平线工具链也支持使用 hb_model_info 工具（J5 链接；XJ3 链接）重新获取该模型转换编译时的版本信息和参数配置，在 x86 平台执行以下命令即可：

hb_model_info xxx.bin

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

结束语

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

相麻SUMIRE · 2024 年4 月 24 日 01:41

第三个调优案例 PTQ精度调优手段—YOLOv8x设置Int16量化看不了

CauchyKesai · 2023 年12 月 1 日 10:26

宝藏博客

PTQ配置文件详解

目录

4.7 重新获取模型转换参数-

1 参数总表

2 参数具体说明

2.1 模型参数组

2.2 输入信息参数组

input_space_and_range: # 通常不配置

2.3 校准参数组

2.4 编译参数组

max_time_per_fc: # 通常不配置

jobs: # 通常不配置

advice: 1 # 通常不配置

2.5 自定义参数组

3 性能/精度相关参数

3.1 性能相关参数

3.2 精度相关参数

4 特性功能参数

4.1 快速性能验证

4.2 前处理归一化

4.3 前处理Resize

4.4 batch模型

4.5 带宽优化

4.6 推理抢占

4.7 重新获取模型转换参数

结束语