4.1.2.2. hb_mapper 工具

hb_mapper 工具是一个将浮点模型映射为量化模型，并附带验证功能的工具。 hb_mapper 包括三个子命令 checker、 makertbin 和 infer。 它们分别提供了的模型检查、模型转换，以及各阶段卷积层向量输出的功能。 接下来的内容逐一介绍上述子命令。

4.1.2.2.1. 模型检查命令（hb_mapper checker）

在实际工程中，由于并非所有浮点模型均能够转为量化模型，因此在转换之前需要进行一次检查， 这个 check 过程，会走一遍模型转换的过程，但是对于比较耗时的步骤，进行了简化处理。 该命令在完成模型的检查后，会输出检查结果和 OP 在设备上的部署情况。

hb_mapper checker 的使用方法：

hb_mapper checker --model-type ${model_type} \
                  --march ${march} \
                  --proto ${caffe_proto} \
                  --model ${caffe_model/onnx_model} \
                  --input-shape ${input_node_name} ${input_shape} \
                  --output ${output}

hb_mapper checker的命令行参数：

--help

显示帮助信息并退出。

--model-type

转换的模型类型，目前支持 caffe 或者 onnx。

--march

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

--proto

用于指定 Caffe 模型的 prototxt 文件。

--model

Caffe 或 ONNX 浮点模型文件。

--input-shape

可选参数，输入模型的输入节点以及该节点的输入的 shape，其 shape 以 x 分隔，e.g. data 1x3x224x224。

--output

该参数已经废弃，log 信息存储于 hb_mapper_checker.log 中。

注解

如您在使用 check 过程中发现 The converted model node information 提示结果和在使用 makertbin 过程中得到的 The converted model node information 提示结果不一致， 可能是因为在做 check 的过程中，实际上是有一个默认的 yaml 配置的，而如果您在进行转换前进行了 yaml 的配置，一些参数的不同可能会导致此种情况的发生， 可能会导致此种情况发生的 yaml 配置参数包括： norm_type 、 mean_value 、 scale_value 、 calibration_type 、 run_on_bpu 、 run_on_cpu 、 optimization 、 set_node_data_type 、 node_info 。

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

该命令根据配置文件和模型的种类，会生成 ONNX 量化模型以及仿真上板情况的 runtime 模型。 具体的配置文件设置及各参数的含义，请参考 配置文件模板 和 配置文件具体参数信息 章节的介绍。

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 参数进行配置。

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 的微架构。若使用 X3 系列处理器则设置为 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。

4.1.2.2.3. 模型推理命令（hb_mapper infer）

注意

• hb_mapper infer 受 onnxruntime 限制，不支持动态的 shape infer，因此要求输入的模型 shape 信息明确。

• 该工具不支持 infer 含有 shape 信息为 ? 的模型。

• 该工具仅支持输入为四维且输出小于等于四维的非 featuremap 模型。

该命令利用浮点和量化模型进行推理，并保存推理结果到 --output-dir 指定的目录里面。

为了验证分析模型编译是否正确，可将配置文件中 layer_out_dump 设置为 True，它将会输出 conv 和输出节点的推理结果， 之后可以借助向量比较工具来分析模型编译的正确与否。

hb_mapper infer 的使用方式：

hb_mapper infer --config ${config_file} \
                --model-file ${quantized_model_file}  \
                --model-type ${caffe/onnx} \
                --image-file ${input_node} ${image_file} \
                --input-layout ${input_layout} \
                --output-dir ${quantized_output_dir}

在使用 hb_mapper infer 命令时，请输入与 hb_mapper makertbin 命令相同的配置文件，以保证输入数据处理的部分的设置是相同的。 简单地说，您在 hb_mapper makertbin 时使用的校准数据是什么样的图片或数据，那么在 hb_mapper infer 时也需要使用相同格式的图片或数据。

注意

您使用 hb_mapper infer 命令时输入数据的选择与配置文件中以下输入数据配置部分有关：

• preprocess_on: True，则工具可以接收 JPEG 图片，自动进行 resize 等预处理，并转化成 input_type_rt 的格式。

• preprocess_on: False，则只能接收已经处理好，储存为二进制格式的图片文件，因此预处理需要用户自己完成， 并把图片转化成相应的二进制文件。(请参考脚本 02_preprocess.sh)。

hb_mapper infer的命令行参数：

--help

显示帮助信息并退出。

-c, --config

模型编译时的配置文件。

--model-file

进行推理的模型文件，可以是浮点和量化 ONNX 模型。

--model-type

指定推理的原始浮点模型类型，可指定为 caffe 或 onnx。

--image-file

输入节点名称和其对应的用于推理的图像文件。

--input-layout

模型输入的 layout（此为可选参数）。

--output-dir

推理结果的保存路径，如果是量化模型，推理结果为反量化的浮点数据。

输出内容在 output_dir 目录里，输出文件命名规则： ${layername}_float.bin。

4.1.2.2.4. 关键配置参数 calibration_parameters.preprocess_on 介绍

calibration_parameters:
    # 模型量化的参考图像的存放目录，图片格式支持JPEG、BMP等格式，输入的图片
    # 应该是使用的典型场景，一般是从测试集中选择20~100张图片，另外输入
    # 的图片要覆盖典型场景，不要是偏僻场景，如过曝光、饱和、模糊、
    # 纯黑、纯白等图片
    # 若有多个输入，则应使用';'进行分隔
    cal_data_dir: './calibration_data_bgr_f32'
    # 当输入的图片文件尺寸和模型训练的尺寸不一致，并且preprocess_on为True时，则将采用默认预处理方法(skimage resize)，
    # 将输入图片缩放或者裁减到指定尺寸，否则，需要用户提前把图片处理为训练时的尺寸
    # preprocess_on: False

如果用户指定配置参数 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 数据存储。

4.1.2.2.5. 配置文件参考样例

4.1.2.2.5.1. 参考配置文件以及说明

配置文件采用 yaml 格式进行配置，详细信息请参考各个参数的注释：

# 模型转化相关的参数
model_parameters:
    # Caffe浮点网络数据模型文件
    caffe_model: '../../../01_common/model_zoo/mapper/classification/mobilenet/mobilenet.caffemodel'
    # Caffe网络描述文件
    prototxt: '../../../01_common/model_zoo/mapper/classification/mobilenet/mobilenet_deploy.prototxt'
    # 适用BPU架构
    march: "bernoulli2"
    # 指定模型转换过程中是否输出各层的中间结果，如果为True，则输出所有层的中间输出结果，
    layer_out_dump: False
    # 日志文件的输出控制参数，
    # debug输出模型转换的详细信息
    # info只输出关键信息
    # warn输出警告和错误级别以上的信息
    working_dir: 'model_output'
    # 模型转换输出的用于上板执行的模型文件的名称前缀
    output_model_file_prefix: 'mobilenetv1_224x224_nv12'


# 模型输入相关参数, 若输入多个节点, 则应使用';'进行分隔, 使用默认缺省设置则写None
input_parameters:
    # (可不填) 模型输入的节点名称, 此名称应与模型文件中的名称一致, 否则会报错, 不填则会使用模型文件中的节点名称
    input_name: "data"
    # 网络实际执行时，输入给网络的数据格式，包括 nv12/rgb/bgr/yuv444/gray/featuremap,
    # 如果输入的数据为yuv444, 模型训练用的是bgr(NCHW)，则hb_mapper将自动插入YUV到BGR(NCHW)转化操作
    input_type_rt: 'nv12'
    # 转换后混合异构模型需要适配的输入数据排布，可设置为：NHWC/NCHW
    # 若input_type_rt配置为nv12，则此处参数不需要配置
    #input_layout_rt: ''
    # 网络训练时输入的数据格式，可选的值为rgb/bgr/gray/featuremap/yuv444
    input_type_train: 'bgr'
    # 网络训练时输入的数据排布, 可选值为 NHWC/NCHW
    input_layout_train: 'NCHW'
    # 模型网络的输入大小, 以'x'分隔, 不填则会使用模型文件中的网络输入大小，否则会覆盖模型文件中输入大小
    # input_shape: ''
    # 网络输入的预处理方法，主要有以下几种：
    # no_preprocess 不做任何操作
    # data_mean 减去通道均值mean_value
    # data_scale 对图像像素乘以data_scale系数
    # data_mean_and_scale 减去通道均值后再乘以scale系数
    norm_type: 'data_mean_and_scale'
    # 图像减去的均值, 如果是通道均值，value之间必须用空格分隔
    mean_value: 103.94 116.78 123.68
    # 图像预处理缩放比例，如果是通道缩放比例，value之间必须用空格分隔
    scale_value: 0.017

calibration_parameters:
    # 模型量化的参考图像的存放目录，图片格式支持JPEG、BMP等格式，输入的图片
    # 应该是使用的典型场景，一般是从测试集中选择20~100张图片，另外输入
    # 的图片要覆盖典型场景，不要是偏僻场景，如过曝光、饱和、模糊、纯黑、纯白等图片
    # 若有多个输入节点, 则应使用';'进行分隔
    cal_data_dir: './calibration_data_bgr_f32'
    # 校准数据二进制文件的数据存储类型，可选值为：float32, uint8. 若有多个输入节点, 则应使用';'进行分隔
    cal_data_type: 'float32'
    # 如果输入的图片文件尺寸和模型训练的尺寸不一致时，并且preprocess_on为true，
    # 则将采用默认预处理方法(skimage resize)，
    # 将输入图片缩放或者裁减到指定尺寸，否则，需要用户提前把图片处理为训练时的尺寸
    # preprocess_on: False
    # 模型量化的算法类型，支持default、mix、kl、max、load，通常采用default即可满足要求,
    # default 是一个自动搜索的策略，会尝试从系列校准量化参数中获得一个相对效果较好的组合。
    # 建议您先尝试 default，如果最终的精度结果不满足预期可进一步尝试mix,
    # mix是一个集成多种校准方法的搜索策略，能够自动确定量化敏感节点，并在节点粒度上从不同的校准方法中挑选出最佳方法。
    # 如果default和mix的精度结果均不满足预期再尝试用kl或max并详细调整量化参数进行精度调优，
    # kl和max是模型量化的算法类型，通常采用KL即可满足要求。
    # 当使用QAT导出模型时，此参数则应设置为load。
    calibration_type: 'default'

# 编译器相关参数
compiler_parameters:
    # 编译策略，支持bandwidth和latency两种优化模式;
    # bandwidth以优化ddr的访问带宽为目标；
    # latency以优化推理时间为目标
    compile_mode: 'latency'
    # debug默认为True，即打开编译器的debug模式，能够输出性能仿真的相关信息，如帧率、DDR带宽占用等
    debug: True
    # 编译模型指定核数，不指定默认编译单核模型, 若编译双核模型，将下边注释打开即可
    # core_num: 2
    # 优化等级可选范围为O0~O3
    # O0不做任何优化, 编译速度最快，优化程度最低,
    # O1-O3随着优化等级提高，预期编译后的模型的执行速度会更快，但是所需编译时间也会变长。
    # 推荐用O2做最快验证
    optimize_level: 'O3'

4.1.2.2.5.2. 关于 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 的支持类型，可以参考(Y 为已支持类型，N 为暂不支持类型)：

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 中已自动进行，用户无需再进行该操作）。