6.2.2.2. 模型编译命令（hb_mapper makertbin）

该命令根据配置文件和模型的种类，会生成ONNX量化模型以及仿真上板情况的runtime模型，完成模型转换过程。

6.2.2.2.1. 使用方法

hb_mapper makertbin提供两种模式，开启 fast-perf 模式和不开启 fast-perf 模式。

fast-perf 模式开启后，会在转换过程中生成可以在板端运行最高性能的bin模型，工具内部主要进行以下操作：

• 将BPU可执行算子尽可能运行在BPU上（即可通过yaml文件中node_info参数指定在BPU上运行的算子）。

• 删除模型首尾可删除的CPU算子，包括：Quantize/Dequantize、Transpose、Cast、Reshape等。

• 以性能最高的O3优化等级编译模型。

hb_mapper makertbin的使用方法（不开启fast-perf模式）：

hb_mapper makertbin --config ${config_file}  \
                    --model-type  ${model_type}

hb_mapper makertbin的使用方法（开启fast-perf模式）：

hb_mapper makertbin --fast-perf --model ${caffe_model/onnx_model} --model-type ${model_type} \
                    --proto ${caffe_proto} \
                    --march ${march} \
                    --input-shape ${input_node_name} ${input_shape}

注意

请注意，如您需要开启fast-perf模式，由于该模式下，工具会使用内置的高性能配置，请勿对 --config 参数进行配置。

6.2.2.2.2. 命令行参数

hb_mapper makertbin的命令行参数：

--help

显示帮助信息并退出。

-c, --config

模型编译的配置文件，为yaml格式。

--model-type

caffe 或者 onnx。

--fast-perf

开启fast-perf模式，该模式开启后，会在转换过程中生成可以在板端运行最高性能的bin模型，方便您用于后续的模型性能评测。

如您开启了fast-perf模式，还需要进行如下配置：

--model Caffe或ONNX浮点模型文件。

--proto 用于指定Caffe模型prototxt文件。

--march BPU的微架构。若使用X/J3系列处理器则设置为 bernoulli2，若使用J5处理器则设置为 bayes，默认值为 bayes。

-i, --input-shape 可选参数，指定模型的输入节点的shape信息，目前此配置仅在开启fast-perf时生效。使用方式为：

• 指定单个输入节点的shape信息，使用方式为 --input-shape input_1 1x3x224x224。

• 指定多个输入节点的shape信息，使用方式为 --input-shape input_1 1x3x224x224 --input-shape input_2 1x3x224x224。

注意

如您未指定 --input-shape 参数，此时工具将仅支持动态输入节点第一维为[-1, 0, ?]的模型，默认会将动态输入节点的第一维设置为1。

编译产生的log文件会储存在命令执行路径下面，名称为 hb_mapper_makertbin.log。

6.2.2.2.3. 配置文件模板

一份完整的配置文件模板如下：

注解

此处配置文件仅作展示，在实际模型配置文件中 caffe_model 与 onnx_model 两种只存在其中之一。

即，要么是Caffe模型，要么是ONNX模型。即 caffe_model + prototxt 或者 onnx_model 二选一。

# 模型参数组
model_parameters:
  # 原始Caffe浮点模型描述文件
  prototxt: '***.prototxt'

  # 原始Caffe浮点模型数据模型文件
  caffe_model: '****.caffemodel'

  # 原始Onnx浮点模型文件
  onnx_model: '****.onnx'

  # 转换的目标处理器架构
  march: 'bayes'

  # 模型转换输出的用于上板执行的模型文件的名称前缀
  output_model_file_prefix: 'mobilenetv1'

  # 模型转换输出的结果的存放目录
  working_dir: './model_output_dir'

  # 指定转换后混合异构模型是否保留输出各层的中间结果的能力
  layer_out_dump: False

  # 指定模型的输出节点
  output_nodes: "OP_name"

  # 批量删除某一类型的节点
  remove_node_type: "Dequantize"

  # 删除指定名称的节点
  remove_node_name: "OP_name"

# 输入信息参数组
input_parameters:
  # 原始浮点模型的输入节点名称
  input_name: "data"

  # 原始浮点模型的输入数据格式（数量/顺序与input_name一致）
  input_type_train: 'bgr'

  # 原始浮点模型的输入数据排布（数量/顺序与input_name一致）
  input_layout_train: 'NCHW'

  # 原始浮点模型的输入数据尺寸
  input_shape: '1x3x224x224'

  # 网络实际执行时，输入给网络的batch_size, 默认值为1
  input_batch: 1

  # 在模型中添加的输入数据预处理方法
  norm_type: 'data_mean_and_scale'

  # 预处理方法的图像减去的均值, 如果是通道均值，value之间必须用空格分隔
  mean_value: '103.94 116.78 123.68'

  # 预处理方法的图像缩放比例，如果是通道缩放比例，value之间必须用空格分隔
  scale_value: '0.017'

  # 转换后混合异构模型需要适配的输入数据格式（数量/顺序与input_name一致）
  input_type_rt: 'yuv444'

  # 输入数据格式的特殊制式
  input_space_and_range: 'regular'

  # 转换后混合异构模型需要适配的输入数据排布（数量/顺序与input_name一致），若input_type_rt配置为nv12，则此处参数不需要配置
  input_layout_rt: 'NHWC'

# 校准参数组
calibration_parameters:
  # 模型校准使用的标定样本的存放目录
  cal_data_dir: './calibration_data'

  # 指定校准数据二进制文件的数据存储类型。
  cal_data_type: 'float32'

  # 开启图片校准样本自动处理（skimage read; resize到输入节点尺寸）
  #preprocess_on: False

  # 校准使用的算法类型
  calibration_type: 'kl'

  # max 校准方式的参数
  max_percentile: 1.0

  # 强制指定OP在CPU上运行
  run_on_cpu: "OP_name"

  # 强制指定OP在BPU上运行
  run_on_bpu: "OP_name"

  # 指定是否针对每个channel进行校准
  per_channel: False

# 编译参数组
compiler_parameters:
  # 编译策略选择
  compile_mode: 'latency'

  # 是否打开编译的debug信息
  debug: True

  # 模型运行核心数
  core_num: 1

  # 模型编译的优化等级选择
  optimize_level: 'O2'

  # 指定名称为data的输入数据来源
  input_source: {"data": "pyramid"}

  # 指定模型的每个function call的最大可连续执行时间
  max_time_per_fc: 1000

  # 指定编译模型时的进程数
  jobs: 8

# 自定义算子参数组
custom_op:
  # 自定义op的校准方式
  custom_op_method: register

  # 自定义OP的实现文件, 该文件可由模板生成, 详情见自定义OP相关文档
  op_register_files: sample_custom.py

  # 自定义OP实现文件所在的文件夹, 请使用相对路径
  custom_op_dir: ./custom_op

注解

在配置march为bayes，即在J5处理器上使用hb_mapper makertbin时，如您将优化等级optimize_level配置为O3， hb_mapper makerbin默认提供缓存能力。即在您第一次在上述场景下使用hb_mapper makerbin对模型进行编译时，会自动创建缓存文件cache.json， 后续在您的working_dir不变的情况下，在重复编译时会自动调用此文件，降低您的编译时间。

配置文件主要包含模型参数组、输入信息参数组、校准参数组、编译参数组和自定义算子参数组。 在您的配置文件中，每个参数组位置都需要存在，具体参数分为可选和必选，可选参数可以不配置。

以下是具体参数信息，参数会比较多，我们依照上述的参数组次序介绍。 可选/必选表示该参数项在配置文件中是否必须进行配置。

6.2.2.2.4. 配置文件具体参数信息

6.2.2.2.4.1. 模型参数组

编 号	参数名称	参数配置说明	可选/ 必选
1	prototxt	参数作用：指定Caffe浮点模型的prototxt文件名称。 取值范围：模型路径。 默认配置：无。 参数说明：在 hb_mapper makertbin 的 model-type 为 caffe 时必须配置。	Caffe模型 必选
2	caffe_model	参数作用：指定Caffe浮点模型的caffemodel文件名称。 取值范围：模型路径。 默认配置：无。 参数说明：在 hb_mapper makertbin 的 model-type 为 caffe 时必须配置。	Caffe模型 必选
3	onnx_model	参数作用：指定ONNX浮点模型的onnx文件名称。 取值范围：模型路径。 默认配置：无。 参数说明：在 hb_mapper makertbin 的 model-type 为 onnx 时必须配置。	ONNX模型 必选
4	march	参数作用：指定产出混合异构模型需要支持的平台架构。 取值范围：'bayes' 或 'bernoulli2'。 默认配置： 无。 参数说明： 两个可选配置值依次对应J5和X3&J3处理器， 根据您使用的平台选择。	必选
5	output_model_file_prefix	参数作用：指定转换产出混合异构模型的名称前缀。 取值范围：无。 默认配置：'model'。 参数说明：输出的定点模型文件的名称前缀。	可选
6	working_dir	参数作用：指定模型转换输出的结果的存放目录。 取值范围：无。 默认配置：'model_output'。 参数说明：若该目录不存在，则工具会自动创建目录。	可选
7	layer_out_dump	参数作用：指定混合异构模型是否保留输出中间层值的能力。 取值范围：True、False。 默认配置：False。 参数说明：输出中间层的值是调试需要用到的手段， 常规状态下请不要开启。 注意： 请您注意，在layer_out_dump为True时，暂时不支持配置input_source为resizer。	可选
8	output_nodes	参数作用：指定模型的输出节点。 取值范围：模型中的节点名称。 默认配置：无。 参数说明：此参数用于支持您指定节点作为模型输出， 设置值需为模型中的具体节点名称。 多个值的配置方法请参考 param_value配置。	可选
9	remove_node_type	参数作用：设置删除节点的类型。 取值范围："Quantize"、"Transpose"、"Dequantize"、 "Cast"、"Reshape"、"Softmax"。不同类型用 ; 分割。 默认配置：无。 参数说明：不设置或设置为空不影响模型转换过程。 此参数用于支持您设置待删除节点的类型信息。 被删除的节点必须在模型的开头或者末尾, 与模型的输入或输出连接。 注意： 待删除节点会按顺序依次删除，并动态更新模型结构； 同时在节点删除前还会判断该节点是否位于模型的输入输出处。 因此节点的删除顺序很重要。	可选
10	remove_node_name	参数作用：设置删除节点的名称。 取值范围：模型中待删除的节点名称，不同名称用 ; 分割。 默认配置：无。 参数说明：不设置或设置为空不影响模型转换过程。 此参数用于支持您设置待删除节点的类型信息。 被删除的节点必须在模型的开头或者末尾，与模型的输入或输出连接。 注意： 待删除节点会按顺序依次删除，并动态更新模型结构； 同时在节点删除前还会判断该节点是否位于模型的输入输出处。 因此节点的删除顺序很重要。	可选
11	set_node_data_type	参数作用：配置指定op的输出数据类型为int16。 取值范围：支持配置int16的算子范围您可参考 工具链算子支持约束列表。 默认配置：无。 参数说明：在模型转换过程中，大多数op的默认输入输出数据类型为int8， 通过该参数可以指定特定op的输出数据类型为int16（在满足一定的约束条件下）。 int16相关说明详见 int16配置说明 部分的描述。 具体算子int16支持情况详见 工具链算子支持约束列表 。 注意： 该参数相关功能已合并至 node_info 参数中。	可选
12	debug_mode	参数作用：保存用于精度debug分析的校准数据。 取值范围："dump_calibration_data"。 默认配置：无。 参数说明：该参数作用为保存用于精度debug分析的校准数据，数据格式为.npy。 该数据通过np.load()可直接送入模型进行推理。 若不设置此参数，您也可自行保存数据并使用精度debug工具进行精度分析。	可选
13	node_info	参数作用：支持配置指定OP的输入输出数据类型为int16 以及强制指定算子在CPU或BPU上运行。 取值范围：支持配置int16的算子范围您可参考 工具链算子支持约束列表。 可指定在CPU或BPU运行的算子需为模型中包含的算子。 默认配置：无。 参数说明：基于减少yaml中的参数的原则，我们将 set_node_data_type 、 run_on_cpu 和 run_on_bpu 三个参数的能力融合到本参数中， 并在此基础上扩充支持配置指定op输入数据类型为int16的能力。 node_info 参数使用方式： 仅指定OP运行在BPU/CPU上（下以BPU为例，CPU方法一致）： node_info: { "node_name": { 'ON': 'BPU', } } 仅配置节点数据类型： node_info: 'node_name1:int16;node_name2:int16' 多个值的配置方法请参考 param_value配置。 指定OP运行在BPU上，同时配置OP的输入输出数据类型： node_info: { "node_name": { 'ON': 'BPU', 'InputType': 'int16', 'OutputType': 'int16' } } ‘InputType’: ‘int16’代表指定算子的所有输入数据类型为int16。 如需指定算子特定输入的InputType，可在InputType后通过指定数字来进行配置。如： ‘InputType0’: ‘int16’代表指定算子的第一个输入数据类型为int16， ‘InputType1’: ‘int16’代表指定算子的第二个输入数据类型为int16，以此类推。 注意： ‘OutputType’ 不支持指定算子特定输出的OutputType，配置后对算子的所有输出生效， 不支持配置 ‘OutputType0’ 、 ‘OutputType1’等。	可选

6.2.2.2.4.2. 输入信息参数组

编 号	参数名称	参数配置说明	可选/ 必选
1	input_name	参数作用：指定原始浮点模型的输入节点名称。 取值范围：单输入时 "" 或输入节点名称，多输入时 "input_name1; input_name2; input_name3..."。 默认配置：无。 参数说明：浮点模型为单输入模型时不需要配置， 多输入模型时必须配置以保证后续类型及校准数据输入顺序的准确性。 多个值的配置方法请参考 param_value配置。	单输入时 可选 多输入时 必选
2	input_type_train	参数作用：指定原始浮点模型的输入数据类型。 取值范围： 'rgb'、 'bgr'、 'yuv444'、'gray'、 'featuremap'。 默认配置：无。 参数说明：每一个输入节点都需要配置一个确定的输入数据类型， 存在多个输入节点时，设置的节点顺序需要与 input_name 里的顺序严格保持一致。 多个值的配置方法请参考 param_value配置。 数据类型的选择请参考： 转换内部过程解读 部分的介绍。	必选
3	input_layout_train	参数作用：指定原始浮点模型的输入数据排布。 取值范围：'NHWC' 、 'NCHW'。 默认配置：无。 参数说明：每一个输入节点都需要配置一个确定的输入数据排布， 这个排布必须与原始浮点模型所采用的数据排布相同。存在多个输入节点时， 设置的节点顺序需要与 input_name 里的顺序严格保持一致。 多个值的配置方法请参考 param_value配置。 什么是数据排布请参考： 转换内部过程解读 部分的介绍。	必选
4	input_type_rt	参数作用：转换后混合异构模型需要适配的输入数据格式。 取值范围：'rgb' 、 'bgr' 、 'yuv444' 、 'nv12' 、 'gray' 、 'featuremap'。 默认配置：无。 参数说明：这里是指明您需要使用的数据格式。 不要求与原始模型的数据格式一致。 但是需要注意在边缘平台喂给模型的数据是使用这个格式。 每一个输入节点都需要配置一个确定的输入数据类型，存在多个输入节点时， 设置的节点顺序需要与 input_name 里的顺序严格保持一致。 多个值的配置方法请参考 param_value配置。 数据类型的选择请参考： 转换内部过程解读 部分的介绍。	必选
5	input_layout_rt	参数作用：转换后混合异构模型需要适配的输入数据排布。 取值范围： 'NCHW' 、 'NHWC'。 默认配置：无。 参数说明：每一个输入节点都需要配置一个确定的输入数据排布。 这个输入是您希望给混合异构模型指定的排布。 不合适的输入数据的排布设置将会影响性能， 存在多个输入节点时，设置的节点顺序需要与 input_name 里的顺序严格保持一致。 多个值的配置方法请参考 param_value配置。 什么是数据排布请参考： 转换内部过程解读 部分的介绍。	可选
6	input_space_and_range	参数作用：指定输入数据格式的特殊制式。 取值范围： 'regular'、 'bt601_video'。 默认配置： 'regular'。 参数说明：这个参数是为了适配不同ISP输出的yuv420格式， 在相应 input_type_rt 为 nv12 时，该配置才有效。 regular 是常见的yuv420格式，数值范围为 [0,255]； bt601_video 是另一种视频制式yuv420，数值范围为 [16,235]。 更多关于bt601的信息可以通过网络资料进行了解。 bt601_video 仅在 input_type_train 配置为 bgr 或 rgb 时支持指定。 注意： 在没有明确需要的情况下，您不要配置此参数。	可选
7	input_shape	参数作用：指定原始浮点模型的输入数据尺寸。 取值范围：无。 默认配置：无。 参数说明：shape的几个维度以 x 连接，例如 '1x3x224x224'。 原始浮点模型只有一个输入节点情况时可以不配置， 工具会自动读取模型文件中的尺寸信息。 配置多个输入节点时，设置的节点顺序需要与 input_name 里的顺序严格保持一致。 多个值的配置方法请参考 param_value配置。	可选
8	input_batch	参数作用：指定转换后混合异构模型需要适配的输入batch数量。 取值范围：1-4096。 默认配置：1。 参数说明：这里input_batch为转换后混合异构bin模型输入batch数量， 但不影响转换后onnx的模型的输入batch数量。 此参数不配置时默认为1。 注意： 此参数仅在单输入且 input_shape 第一维为1的时候可以使用。 此参数仅在原始onnx模型本身支持多batch推理时才能生效。 但是由于算子情况复杂，若在模型转换过程中， 遇到提示模型不支持配置input_batch参数的转换失败log， 请您尝试直接导出一个多batch的onnx模型并正确配置校准数据大小重新进行转换 （此时不再需要配置此参数）。	可选
9	norm_type	参数作用：在模型中添加的输入数据预处理方法。 取值范围： 'data_mean_and_scale' 、 'data_mean' 、 'data_scale' 、 'no_preprocess'。 默认配置：'no_preprocess'。 参数说明： no_preprocess 表示不添加任何数据预处理； data_mean 表示提供减均值预处理； data_scale 表示提供乘scale系数预处理； data_mean_and_scale 表示提供先减均值再乘scale系数前处理。 输入节点多于一个时，设置的节点顺序需要与 input_name 里的顺序严格保持一致， 多个值的配置方法请参考 param_value配置。 配置该参数的影响请参考： 转换内部过程解读 部分的介绍。 注意： 当 input_type_rt 配置为featuremap非四维输入时， norm_type只能配置为no_preprocess。	可选
10	mean_value	参数作用：指定预处理方法的图像减去的均值。 取值范围：无。 默认配置：无。 参数说明：当 norm_type 存在 data_mean_and_scale 或 data_mean 时需要配置该参数。 对于每一个输入节点而言，存在两种配置方式。 第一种是仅配置一个数值，表示所有通道都减去这个均值； 第二种是提供与通道数量一致的数值（这些数值以空格分隔开）， 表示每个通道都会减去不同的均值。 配置的输入节点数量必须与 norm_type 配置的节点数量一致。 如果存在某个节点不需要 mean 处理，则为该节点配置 'None'。 多个值的配置方法请参考 param_value配置。	可选
11	scale_value	参数作用：指定预处理方法的数值scale系数。 取值范围：无。 默认配置：无。 参数说明：当 norm_type 存在 data_mean_and_scale 或 data_scale 时需要配置该参数。 对于每一个输入节点而言，存在两种配置方式。 第一种是仅配置一个数值，表示所有通道都乘以这个系数； 第二种是提供与通道数量一致的数值（这些数值以空格分隔开）， 表示每个通道都会乘以不同的系数。 配置的输入节点数量必须与 norm_type 配置的节点数量一致。 如果存在某个节点不需要 scale 处理，则为该节点配置 'None'。 多个值的配置方法请参考 param_value配置。	可选

input_type_rt/ input_type_train补充说明

地平线的计算平台架构，在设计时为了提升性能，做了两点假设：

1. 假设输入的数据都是int8的量化数据。

2. 摄像头获取到的数据是nv12。

因此，如果您在模型训练时使用rgb(NCHW)输入格式，但是想使这个模型能够高效处理nv12数据，只需要在模型转换时做如下配置：

input_parameters:
    input_type_rt: 'nv12'
    input_type_train: 'rgb'
    input_layout_train: 'NCHW'

小技巧

若您在训练模型时使用gray格式，而实际使用中输入的数据格式为nv12格式， 则可以将模型转换时的 input_type_rt 及 input_type_train 均配置为 gray， 在嵌入式应用开发时仅使用nv12的y通道地址作为输入即可。

除了将输入数据转换为nv12，我们还支持您在训练和runtime infer时使用不同的rgb-order。 工具会根据 input_type_rt 和 input_type_train 指定的数据格式自动添加数据转换节点，根据地平线的实际生产经验， 并不是任意type组合都是需要的，为了避免您误用， 我们只开放了一些固定的type组合如下表(Y为已支持类型，N为暂不支持类型，表格中第一行是 input_type_rt 中支持的类型，第一列是 input_type_train 支持的类型)：

input_type_train \ input_type_rt	nv12	yuv444	rgb	bgr	gray	featuremap
yuv444	Y	Y	N	N	N	N
rgb	Y	Y	Y	Y	N	N
bgr	Y	Y	Y	Y	N	N
gray	N	N	N	N	Y	N
featuremap	N	N	N	N	N	Y

注解

为了配合计算平台对于输入数据类型的要求（int8），减小推理开销， 对于 input_type_rt 类型为 rgb(NHWC/NCHW)/bgr(NHWC/NCHW) 的配置， 转换工具转换出的模型，其输入数据类型均为 int8。 也就是说，对于常规的图像数据，需要-128使用（该操作在API中已自动进行，无需再进行该操作）。

在转换得到的最终产出bin模型中， input_type_rt 到 input_type_train 是一个内部的过程， 您只需要关注 input_type_rt 的数据格式即可。 正确理解每种 input_type_rt 的要求，对于嵌入式应用准备推理数据很重要，以下是对 input_type_rt 每种格式的说明：

• rgb、bgr和gray都是比较常见的图像格式，注意每个数值都采用UINT8表示。

• yuv444是一种常见的图像格式，注意每个数值都采用UINT8表示。

• nv12是常见的yuv420图像格式，每个数值都采用UINT8表示。

• nv12有个比较特别的情况是 input_space_and_range 设置 bt601_video 时， 较于常规nv12情况，它的数值范围由[0,255]变成了[16,235]，每个数值仍然采用UINT8表示。 请注意， bt601_video 仅在 input_type_train 为 bgr 或 rgb 时支持通过 input_space_and_range 进行配置。

• featuremap适用于以上列举格式不满足您需求的情况，此type每个数值采用float32表示。例如雷达和语音等模型处理就常用这个格式。

小技巧

以上 input_type_rt 与 input_type_train 是固化在工具链的处理流程中，如果您非常确定不需要转换， 将两个 input_type 设置成一样就可以了，一样的 input_type 会做直通处理，不会影响模型的实际执行性能。

同样的，数据前处理也是固化在流程中，如果您不需要做任何前处理，通过 norm_type 配置关闭这个功能即可，不会影响模型的实际执行性能。

6.2.2.2.4.3. 校准参数组

编 号	参数名称	参数配置说明	可选/ 必选
1	cal_data_dir	参数作用：指定模型校准使用的标定样本的存放目录。 取值范围：无。 默认配置：无。 参数说明：目录内校准数据需要符合输入配置的要求。 具体请参考 校准数据准备 部分的介绍。配置多个输入节点时， 设置的节点顺序需要与 input_name 里的顺序严格保持一致。 多个值的配置方法请参考 param_value配置。 当calibration_type为 load、 skip 时，cal_data_dir无需配置。 注意： 为了方便您的使用，如果未发现cal_data_type的配置，我们将根据文件夹 后缀对数据类型进行配置。如果文件夹后缀以 _f32 结尾，则认为数据 类型是float32，否则认为数据类型是uint8。 当然，我们强烈建议您通过cal_data_type参数对数据类型进行约束。	可选
2	cal_data_type	参数作用：指定校准数据二进制文件的数据存储类型。 取值范围：'float32'、'uint8'。 默认配置：无。 参数说明：指定模型校准时使用的二进制文件的数据存储类型。 没有指定值的情况下将会使用文件夹名字后缀来做判断。 多个值的配置方法请参考 param_value配置。	可选
3	preprocess_on	参数作用：开启图片校准样本自动处理。 取值范围： True 、 False。 默认配置： False。 参数说明：该选项仅适用于4维图像输入的模型， 非4维模型不要打开该选项。 在启动该功能时，cal_data_dir 目录下存放的都是jpg/bmp/png 等图片数据，工具会使用skimage读取图片， 并resize到输入节点需要的尺寸。 为了保证校准的效果，建议您保持该参数关闭。 使用的影响请参考 校准数据准备 部分的介绍。	可选
4	calibration_type	参数作用：校准使用的算法类型。 取值范围：'default'、'mix'、'kl'、'max' 、 'load' 和 'skip'。 默认配置：'default'。 参数说明： kl 和 max 都是公开的校准量化算法， 其基本原理可以通过网络资料查阅。 使用 load 方式校准时, qat模型必须是通过plugin 导出的模型。详情参见 使用QAT量化感知训练方案进一步提升模型精度 。 default 是一个自动搜索的策略， 会尝试从系列校准量化参数中获得一个相对效果较好的组合。 mix 是一个集成多种校准方法的搜索策略， 能够自动确定量化敏感节点，并在节点粒度上从不同的校准方法 中挑选出最佳方法，最终构建一个融合了多种校准方法优势的组合校准方式。 如果您使用的是QAT导出的模型，则应选择 load。 建议您先尝试 default， 如果最终的精度结果不满足预期， 再根据 PTQ模型精度调优 章节的建议配置不同的校准参数。 若您只想尝试对模型性能进行验证，但对精度没有要求， 则可以尝试 skip 方式进行校准。 该方式会使用max+内部生成的随机校准数据进行校准， 不需要您准备校准数据，比较适合初次尝试对模型结构进行验证。 注意： 使用skip方式时，因其使用max+内部生成的随机校准数据进行校准， 得到的模型不可用于精度验证。	可选
5	max_percentile	参数作用：该参数为 max 校准方法的参数，用以调整 max 校准的截取点。 取值范围： 0.0 ~ 1.0。 默认配置： 1.0。 参数说明：此参数仅在 calibration_type 为 max 时有效。 常用配置选项有：0.99999/0.99995/0.99990/0.99950/0.99900。 建议您先尝试 calibration_type 配置 default， 如果最终的精度结果不满足预期， 再根据 PTQ模型精度调优 部分建议调整该参数。	可选
6	per_channel	参数作用：控制是否针对featuremap的每个channel进行校准。 取值范围： True 、 False。 默认配置： False。 参数说明： calibration_type 设置非default、非mix时有效。 建议您先尝试 default， 如果最终的精度结果不满足预期， 再根据 PTQ模型精度调优 部分建议调整该参数。	可选
7	run_on_cpu	参数作用：强制指定算子在CPU上运行。 取值范围：模型中的节点名称。 默认配置：无。 参数说明：CPU上虽然性能不及BPU，但是提供的是float精度计算。 如果您确定某些算子需要在CPU上计算， 可以通过该参数指定。 设置值为模型中的具体节点名称。 多个值的配置方法请参考 param_value配置。 注意： 该参数相关功能已合并至 node_info 参数中。	可选
8	run_on_bpu	参数作用：强制指定OP在BPU上运行。 取值范围：模型中的节点名称。 默认配置：无。 参数说明：为了保证最终量化模型的精度，少部分情况下， 转换工具会将一些具备BPU计算条件的算子放在CPU上运行。 如果您对性能有较高的要求，愿意以更多一些量化损失为代价， 则可以通过该参数明确指定算子运行在BPU上。 设置值为模型中的具体节点名称。 多个值的配置方法请参考 param_value配置。 注意： 该参数相关功能已合并至 node_info 参数中。	可选
9	optimization	参数作用：此参数为您提供一些调优可配置选项， 通过该参数可配置不同的模式对模型精度/性能进行调优。 取值范围：set_model_output_int8、 set_model_output_int16、 set_{NodeKind}_input_int16、 set_{NodeKind}_output_int16、 set_Softmax_input_int8、 set_Softmax_output_int8、 asymmetric、 bias_correction、 lstm_batch_last。 注：此处Nodekind为标准ONNX算子类型写法如Conv，Mul，Sigmoid等（区分大小写）。 具体请参考onnx官方op文档或 工具链算子支持约束列表。 默认配置：无。 参数说明： 注：具体算子类型的int16支持情况可参考 工具链算子支持约束列表。 指定值为set_model_output_int8时，设置模型为int8格式低精度输出。 指定值为set_model_output_int16时，设置模型为int16格式低精度输出。 指定值为set_{NodeKind}_input_int16时， 会将模型中某类算子输入量化成int16， 如出现因节点上下文不支持int16的情况，则会回退int8计算并打印log。 指定值为set_{NodeKind}_output_int16时， 会将模型中某类算子输出量化成int16， 如出现因节点上下文不支持int16的情况，则会回退int8计算并打印log。 指定值为set_Softmax_input_int8/set_Softmax_output_int8时，由于当前softmax 默认为float计算非量化节点。 这两个指定值会将softmax算子量化成int8并在BPU上计算。 二者没有使用上的区别。 指定值为asymmetric时，会尝试开启非对称量化，在某些模型上可以提升量化精度。 在calibration_type配置为default时， 该参数将由算法自动选择，此时无法显性配置。 指定值为bias_correction时，使用BiasCorrection量化方法， 在部分模型上可以提升量化精度。 指定值为lstm_batch_last时，针对J5 BPU，对于LSTM的batch-input size较大时， 可以将batch维度转换到W维度进行计算（保障等价性），更贴合硬件计算逻辑， 一些场景下可以实现对J5 BPU推理性能加速的效果。 由于模型部署推理性能与多种层次的优化有关， 因此此方法无法保证一定可以实现性能加速效果。	可选

preprocess_on补充说明

• 如果指定配置参数 preprocess_on=True：

  工具可通过该设置 preprocess_on 为 True 来自动完成的校准图片的前处理。 该模式下需在 cal_data_dir 中指定校准JPEG图片的存放路径。 则在模型校准时，工具内部会通过skimage方式读入的JPEG图片，通过skimage resize的方式缩放图片到配置文件指定的 input_shape， 并把图像格式调整为 input_type_rt 指定的格式。

  举一个例子，假如输入的JPEG图像的尺寸为608x608，则通过默认的预处理后，图像被缩放为224x224， 图像的内存格式调整为bgr(NCHW)的格式，像素值调整为0-255范围。

  默认的预处理，请参考如下代码：

  def data_transformer(norm_type, input_dim, input_type_train):
      image_width = input_dim[2]
      image_height = input_dim[1]
      transformers = [
          ResizeTransformer((image_height, image_width)),
          HWC2CHWTransformer(),  # to CXHXW
          RGB2BGRTransformer(),
      ]
  
      transformers.append(ScaleTransformer(255))
  

• 如果指定配置参数 preprocess_on=False：

  您需要自行处理图片，将图片处理为 input_type_train 指定的格式，并且将数据以二进制形式保存为文件。 工具内部会自动增加从 input_type_train 到 input_type_rt 的格式转换。

  注解

  文件格式为： Row-major order 的uint8/float32数据存储。

6.2.2.2.4.4. 编译参数组

编 号	参数名称	参数配置说明	可选/ 必选
1	compile_mode	参数作用：编译策略选择。 取值范围： 'latency'、 'bandwidth'、 'balance'。 默认配置： 'latency'。 参数说明： latency 以优化推理时间为目标。 bandwidth 以优化ddr的访问带宽为目标。 balance 平衡优化目标latency和bandwidth，设置为此项需指定balance_factor。 如果模型没有严重超过预期的带宽占用，建议您使用 latency 策略。	可选
2	balance_factor	参数作用：当compile_mode被指定为balance时，用于指定balance比率。 取值范围：0-100。 默认配置：无。 参数说明：该参数仅在compile_mode被指定为balance时配套使用， 其余模式下配置不生效。 配置为0即为带宽最优，对应compile_mode为bandwidth的编译策略。 配置为100即为性能最优，对应compile_mode为latency的编译策略。	可选
3	debug	参数作用：是否打开编译的debug信息。 取值范围： True 、 False。 默认配置： True。 参数说明：默认开启该参数的场景下， 模型的静态分析的性能结果将保存在模型中。 您可以在模型成功转换后生成的静态性能评估文件html页和hb_perf时产生的html页内， 在Layer Details选项卡中查看模型逐层BPU算子的性能信息， 包括计算量、原始算子输出shape、对齐后的算子输出shape、计算耗时、 数据搬运耗时以及以及编译后layer活跃时间段 （不代表该layer执行时间，通常为多个layer交替/并行执行）。	可选
4	core_num	参数作用：模型运行核心数。 取值范围： 1、 2。 默认配置： 1。 参数说明：地平线平台支持利用多个加速器核心同时完成一个推理任务。 多核心适用于输入尺寸较大的情况， 理想状态下的双核速度可以达到单核的1.5倍左右。 如果您的模型输入尺寸较大，对于模型速度有极致追求， 可以配置 core_num=2。 该选项在J5上仅支持配置为1!	可选
5	optimize_level	参数作用：模型编译的优化等级选择。 取值范围： 'O0' 、 'O1' 、 'O2' 、 'O3'。 默认配置：'O0'。 参数说明：优化等级可选范围为 O0 ~ O3。 O0 不做任何优化, 编译速度最快，优化程度最低。 O1 - O3 随着优化等级提高， 预期编译后的模型的执行速度会更快， 但是所需编译时间也会变长。 正常用于生产和验证性能的模型， 必须使用 O3 级别优化才能保证得到最优性能。 某些流程验证或精度调试过程中， 可以尝试使用更低级别优化加快过程速度。	可选
6	input_source	参数作用：设置上板bin模型的输入数据来源。 取值范围： ddr, pyramid, resizer。 默认配置： 无，默认会根据input_type_rt的值从可选范围中自动选择： input_type_rt配置为nv12或gray时，input_source默认自动选择为pyramid。 input_type_rt配置为其他值时，input_source默认自动选择为ddr。 该参数配置为resizer时，input_type_rt仅支持配置为nv12或gray。 参数说明：这个参数是适配工程环境的选项， 建议您已经全部完成模型检查后再配置。 ddr 表示数据来自内存，pyramid 和 resizer 表示来自处理器上的固定硬件。 在具体的工程环境中适配resizer数据源需要调用专有接口， 请您参考 hbDNNRoiInfer接口说明。 此参数配置有些特殊，例如模型输入名称为 data, 数据源为内存(ddr), 则此处应该配置值为 {"data": "ddr"}。	可选
7	max_time_per_fc	参数作用：指定模型的每个function call的最大可连续执行时间(单位μs)。 取值范围：0或1000-4294967295。 默认配置：0。 参数说明：编译后的数据指令模型在BPU上进行推理计算时， 它将表现为1个或者多个function-call（BPU的执行粒度）的调用。 取值为0代表不做限制。 该参数用来限制每个function-call最大的执行时间, 模型只有在单个function-call执行完时才有机会被抢占。 详情参见 模型优先级控制 部分的介绍。 注意： 此参数仅用于实现模型抢占功能，如无需实现该功能则可以忽略。 模型抢占功能仅支持在板端实现，不支持模拟器实现。	可选
8	jobs	参数作用：设置编译bin模型时的进程数。 取值范围：机器支持的最大核心数范围内。 默认配置：无。 参数说明：在编译bin模型时，用于设置进程数。 一定程度上可提高编译速度。	可选
9	advice	参数作用：用于提示模型编译后预估的耗时增加的情况，单位是微秒。 取值范围：自然数。 默认配置：无。不设置或设置为0则表示不开启。 参数说明：模型在编译过程中，工具链内部会进行耗时分析。而实际过程中， 如算子做数据对齐等操作时会导致耗时有所增加，设置该参数后， 当某个OP的实际计算耗时与理论计算耗时的偏差大于您指定的值时，会打印相关log， 包括耗时变化的信息、数据对齐前后的shape以及padding比例等信息。	可选

6.2.2.2.4.5. 自定义算子参数组

编 号	参数名称	参数配置说明	可选/ 必选
1	custom_op_method	参数作用：自定义算子策略选择。 取值范围：register。 默认配置：无。 参数说明：目前仅支持register策略，具体使用请参考 自定义算子开发。	可选
2	op_register_files	参数作用：指定自定义算子的Python实现文件名称。 取值范围：无。 默认配置：无。 参数说明：多个文件可用 ; 分隔，算子如何实现请参考 自定义算子开发。	可选
3	custom_op_dir	参数作用：指定自定义算子的Python实现文件存放路径。 取值范围：无。 默认配置：无。 参数说明：如果自定义算子的Python实现文件与工作目录在同一目录下，可不做设置。 设置路径时，请使用相对路径。	可选

6.2.2.2.5. param_value配置

具体参数的设置形式为：param_name:  'param_value' ，参数存在多个值时使用 ';' 符号分隔： param_name:  'param_value1; param_value2; param_value3' 。

小技巧

当模型为多输入模型时，强烈建议您将 input_shape 等参数们显式的写出，以免造成参数对应顺序上的错误。

注意

请注意，如果设置 input_type_rt 为 nv12 ，则模型的输入尺寸中不能出现奇数。

6.2.2.2.6. int16配置说明

在模型转换的过程中，模型中的大部分算子都会被量化到int8进行计算，而通过配置 node_info 参数， 可以详细指定某个op的输入/输出数据类型为int16计算（具体支持的算子范围可参考 工具链算子支持约束列表）， 基本原理如下：

在您配置了某个op输入/输出数据类型为int16后，模型转换内部会自动进行op输入输出上下文（context）int16配置的更新和检查。 例如，当配置op_1输入/输出数据类型为int16时，实际上潜在同时指定了op_1的上/下一个op需要支持以int16计算。 对于不支持的场景，模型转换工具会打印log提示该int16配置组合暂时不被支持并回退到int8计算。