3. 用户界面

本章介绍用户的使用界面, 包括转换模型的基本过程, 和各类工具的使用方法。

3.1. 模型转换过程

基本操作过程是用 model_transform.py 将模型转成mlir文件,然后用 model_deploy.py 将mlir转成对应的model。以 somenet.onnx 模型为例,操作步骤如下:

# To MLIR
$ model_transform.py \
    --model_name somenet \
    --model_def  somenet.onnx \
    --test_input somenet_in.npz \
    --test_result somenet_top_outputs.npz \
    --mlir somenet.mlir

# To Float Model
$ model_deploy.py \
   --mlir somenet.mlir \
   --quantize F32 \ # F16/BF16
   --processor BM1684X \
   --test_input somenet_in_f32.npz \
   --test_reference somenet_top_outputs.npz \
   --model somenet_f32.bmodel

3.1.1. 支持图片输入

当用图片做为输入的时候, 需要指定预处理信息, 如下:

$ model_transform.py \
    --model_name img_input_net \
    --model_def img_input_net.onnx \
    --input_shapes [[1,3,224,224]] \
    --mean 103.939,116.779,123.68 \
    --scale 1.0,1.0,1.0 \
    --pixel_format bgr \
    --test_input cat.jpg \
    --test_result img_input_net_top_outputs.npz \
    --mlir img_input_net.mlir

3.1.2. 支持多输入

当模型有多输入的时候, 可以传入1个npz文件, 或者按顺序传入多个npy文件, 用逗号隔开。如下:

$ model_transform.py \
    --model_name multi_input_net \
    --model_def  multi_input_net.onnx \
    --test_input multi_input_net_in.npz \ # a.npy,b.npy,c.npy
    --test_result multi_input_net_top_outputs.npz \
    --mlir multi_input_net.mlir

3.1.3. 支持INT8对称和非对称

如果需要转INT8模型, 则需要进行calibration。如下:

$ run_calibration.py somenet.mlir \
    --dataset dataset \
    --input_num 100 \
    -o somenet_cali_table

传入校准表生成模型, 如下:

$ model_deploy.py \
   --mlir somenet.mlir \
   --quantize INT8 \
   --calibration_table somenet_cali_table \
   --processor BM1684X \
   --test_input somenet_in_f32.npz \
   --test_reference somenet_top_outputs.npz \
   --tolerance 0.9,0.7 \
   --model somenet_int8.bmodel

3.1.4. 支持混精度

当INT8模型精度不满足业务要求时, 可以尝试使用混精度, 先生成量化表, 如下:

$ run_qtable.py somenet.mlir \
    --dataset dataset \
    --calibration_table somenet_cali_table \
    --processor BM1684X \
    -o somenet_qtable

然后将量化表传入生成模型, 如下:

$ model_deploy.py \
   --mlir somenet.mlir \
   --quantize INT8 \
   --calibration_table somenet_cali_table \
   --quantize_table somenet_qtable \
   --processor BM1684X \
   --model somenet_mix.bmodel

3.1.5. 支持量化模型TFLite

支持TFLite模型的转换, 命令参考如下:

 # TFLite转模型举例
 $ model_transform.py \
     --model_name resnet50_tf \
     --model_def  ../resnet50_int8.tflite \
     --input_shapes [[1,3,224,224]] \
     --mean 103.939,116.779,123.68 \
     --scale 1.0,1.0,1.0 \
     --pixel_format bgr \
     --test_input ../image/dog.jpg \
     --test_result resnet50_tf_top_outputs.npz \
     --mlir resnet50_tf.mlir

$ model_deploy.py \
    --mlir resnet50_tf.mlir \
    --quantize INT8 \
    --processor BM1684X \
    --test_input resnet50_tf_in_f32.npz \
    --test_reference resnet50_tf_top_outputs.npz \
    --tolerance 0.95,0.85 \
    --model resnet50_tf_1684x.bmodel

3.1.6. 支持Caffe模型

# Caffe转模型举例
$ model_transform.py \
    --model_name resnet18_cf \
    --model_def  ../resnet18.prototxt \
    --model_data ../resnet18.caffemodel \
    --input_shapes [[1,3,224,224]] \
    --mean 104,117,123 \
    --scale 1.0,1.0,1.0 \
    --pixel_format bgr \
    --test_input ../image/dog.jpg \
    --test_result resnet50_cf_top_outputs.npz \
    --mlir resnet50_cf.mlir

3.2. 工具参数介绍

3.2.1. model_transform.py

用于将各种神经网络模型转换成MLIR文件, 支持的参数如下:

表 3.1 model_transform 参数功能

参数名

必选?

说明

model_name

指定模型名称

model_def

指定模型定义文件, 比如 .onnx.tflite.prototxt 文件

model_data

指定模型权重文件, caffe模型需要, 对应 .caffemodel 文件

input_shapes

指定输入的shape, 例如 [[1,3,640,640]] ; 二维数组, 可以支持多输入情况

input_types

指定输入的类型, 例如int32; 多输入用 , 隔开; 不指定情况下默认处理为float32

keep_aspect_ratio

在Resize时是否保持长宽比, 默认为false; 设置时会对不足部分补0

mean

图像每个通道的均值, 默认为 0.0,0.0,0.0

scale

图片每个通道的比值, 默认为 1.0,1.0,1.0

pixel_format

图片类型, 可以是rgb、bgr、gray、rgbd四种情况, 默认为bgr

channel_format

通道类型, 对于图片输入可以是nhwc或nchw, 非图片输入则为none, 默认是nchw

output_names

指定输出的名称, 如果不指定, 则用模型的输出; 指定后用该指定名称做输出

add_postprocess

将后处理融合到模型中, 指定后处理类型, 目前支持yolov3、yolov3_tiny、yolov5和ssd后处理

test_input

指定输入文件用于验证, 可以是图片或npy或npz; 可以不指定, 则不会正确性验证

test_result

指定验证后的输出文件

excepts

指定需要排除验证的网络层的名称, 多个用 , 隔开

onnx_sim

onnx-sim 的可选项参数,目前仅支持 skip_fuse_bn 选项,用于关闭 batch_norm 和 Conv 层的合并

mlir

指定输出的mlir文件名称和路径

debug

保存可用于debug的模型

tolerance

模型转换的余弦与欧式相似度的误差容忍度,默认为0.99,0.99

cache_skip

是否在生成相同mlir/bmodel时跳过正确性的检查

dynamic_inputs

指定动态输入名,例如input1,input2

inputs_is_shape

shape信息作为一个输入操作数

resize_dims

图像缩放到指定的固定尺寸h/w,缺省时为输入图像本身尺寸

pad_value

图片缩放时边框填充大小

pad_type

图片缩放时的填充类型,有normal, center

preprocess_list

输入是否需要做预处理的选项,例如:’1,3’ 表示输入1&3需要进行预处理, 缺省代表所有输入要做预处理

转成mlir文件后, 会生成一个 ${model_name}_in_f32.npz 文件, 该文件是后续模型的输入文件。

3.2.2. run_calibration.py

用少量的样本做calibration, 得到网络的校准表, 即每一层op的threshold/min/max。

支持的参数如下:

表 3.2 run_calibration 参数功能

参数名

必选?

说明

指定mlir文件

dataset

指定输入样本的目录, 该路径放对应的图片, 或npz, 或npy

data_list

指定样本列表, 与dataset必须二选一

input_num

指定校准数量, 如果为0, 则使用全部样本

tune_num

指定微调样本数量, 默认为10

tune_list

指定微调样本文件

histogram_bin_num

直方图bin数量, 默认2048

o

输出calibration table文件

debug_cmd

debug cmd

校准表的样板如下:

# genetated time: 2022-08-11 10:00:59.743675
# histogram number: 2048
# sample number: 100
# tune number: 5
###
# op_name    threshold    min    max
images 1.0000080 0.0000000 1.0000080
122_Conv 56.4281803 -102.5830231 97.6811752
124_Mul 38.1586478 -0.2784646 97.6811752
125_Conv 56.1447888 -143.7053833 122.0844193
127_Mul 116.7435987 -0.2784646 122.0844193
128_Conv 16.4931355 -87.9204330 7.2770605
130_Mul 7.2720342 -0.2784646 7.2720342
......

它分为4列: 第一列是Tensor的名字; 第二列是阈值(用于对称量化); 第三列第四列是min/max, 用于非对称量化。

3.2.3. run_qtable.py

使用 run_qtable.py 生成混精度量化表, 相关参数说明如下:

表 3.3 run_qtable.py 参数功能

参数名

必选?

说明

指定mlir文件

dataset

指定输入样本的目录, 该路径放对应的图片, 或npz, 或npy

data_list

指定样本列表, 与dataset必须二选一

calibration_table

输入校准表

processor

指定模型将要用到的平台, 支持BM1688/BM1684X/BM1684/CV186X/CV183X/CV182X/CV181X/CV180X/BM1690

input_num

指定输入样本数量, 默认用10个

expected_cos

指定网络输出的期望cos值, 默认0.99

global_compare_layers

指定全局对比层,例如 layer1,layer2 或 layer1:0.3,layer2:0.7

fp_type

指定精度类型,默认auto

base_quantize_table

指定量化表

loss_table

输出Loss表, 默认为full_loss_table.txt

o

输出混精度量化表

混精度量化表的样板如下:

# genetated time: 2022-11-09 21:35:47.981562
# sample number: 3
# all int8 loss: -39.03119206428528
# processor: BM1684X  mix_mode: F32
###
# op_name   quantize_mode
conv2_1/linear/bn F32
conv2_2/dwise/bn  F32
conv6_1/linear/bn F32

它分为2列: 第一列对应layer的名称, 第二列对应量化模式。

同时会生成loss表, 默认为 full_loss_table.txt, 样板如下:

# genetated time: 2022-11-09 22:30:31.912270
# sample number: 3
# all int8 loss: -39.03119206428528
# processor: BM1684X  mix_mode: F32
###
No.0 : Layer: conv2_1/linear/bn Loss: -36.14866065979004
No.1 : Layer: conv2_2/dwise/bn  Loss: -37.15774385134379
No.2 : Layer: conv6_1/linear/bn Loss: -38.44639046986898
No.3 : Layer: conv6_2/expand/bn Loss: -39.7430411974589
No.4 : Layer: conv1/bn          Loss: -40.067259073257446
No.5 : Layer: conv4_4/dwise/bn  Loss: -40.183939139048256
No.6 : Layer: conv3_1/expand/bn Loss: -40.1949667930603
No.7 : Layer: conv6_3/expand/bn Loss: -40.61786969502767
No.8 : Layer: conv3_1/linear/bn Loss: -40.9286363919576
No.9 : Layer: conv6_3/linear/bn Loss: -40.97952524820963
No.10: Layer: block_6_1         Loss: -40.987406969070435
No.11: Layer: conv4_3/dwise/bn  Loss: -41.18325670560201
No.12: Layer: conv6_3/dwise/bn  Loss: -41.193763415018715
No.13: Layer: conv4_2/dwise/bn  Loss: -41.2243926525116
......

它代表对应的Layer改成浮点计算后, 得到的输出的Loss。

3.2.4. model_deploy.py

将mlir文件转换成相应的model, 参数说明如下:

表 3.4 model_deploy 参数功能

参数名

必选?

说明

mlir

指定mlir文件

processor

指定模型将要用到的平台, 支持BM1688/BM1684X/BM1684/CV186X/CV183X/CV182X/CV181X/CV180X/BM1690

quantize

指定默认量化类型, 支持F32/F16/BF16/INT8

quant_input

指定输入数据类型是否与量化类型一致,例如int8模型指定quant_input,那么输入数据类型也为int8,若不指定则为F32

quant_output

指定输出数据类型是否与量化类型一致,例如int8模型指定quant_input,那么输出入数据类型也为int8,若不指定则为F32

quant_input_list

选择要转换的索引,例如 1,3 表示第一个和第三个输入的强制转换

quant_output_list

选择要转换的索引,例如 1,3 表示第一个和第三个输出的强制转换

quantize_table

指定混精度量化表路径, 如果没有指定则按quantize类型量化; 否则优先按量化表量化

fuse_preprocess

指定是否将预处理融合到模型中,如果指定了此参数,则模型输入为uint8类型,直接输入resize后的原图即可

calibration_table

指定校准表路径, 当存在INT8量化的时候需要校准表

ignore_f16_overflow

打开时则有F16溢出风险的算子依然按F16实现;否则默认会采用F32实现, 如LayerNorm

tolerance

表示 MLIR 量化后的结果与 MLIR fp32推理结果余弦与欧式相似度的误差容忍度,默认为0.8,0.5

test_input

指定输入文件用于验证, 可以是图片或npy或npz; 可以不指定, 则不会正确性验证

test_reference

用于验证模型正确性的参考数据(使用npz格式)。其为各算子的计算结果

excepts

指定需要排除验证的网络层的名称, 多个用,隔开

op_divide

cv183x/cv182x/cv181x/cv180x only, 尝试将较大的op拆分为多个小op以达到节省ion内存的目的, 适用少数特定模型

model

指定输出的model文件名称和路径

debug

是否保留中间文件

asymmetric

指定做int8非对称量化

dynamic

动态编译

includeWeight

tosa.mlir 的 includeWeight

customization_format

指定模型输入帧的像素格式

compare_all

指定对比模型所有的张量

num_device

用于并行计算的设备数量,默认1

num_core

用于并行计算的智能视觉深度学习处理器核心数量,默认1

skip_validation

跳过检查 bmodel 的正确性

merge_weight

将权重与之前生成的 cvimodel 合并为一个权重二进制文件,默认否

model_version

如果需要旧版本的cvimodel,请设置版本,例如1.2,默认latest

q_group_size

每组定量的组大小,仅用于 W4A16 定量模式,默认0

compress_mode

指定模型的压缩模式:”none”,”weight”,”activation”,”all”。支持bm1688, 默认为”none”,不进行压缩

cache_skip

是否在生成相同mlir/bmodel时跳过正确性的检查

aligned_input

是否输入图像的宽/通道是对齐的,仅用于CV系列芯片的VPSS输入对齐

group_by_cores

layer groups是否根据core数目进行强制分组, 可选auto/true/false, 默认为auto

opt

LayerGroup优化类型,可选1/2, 默认为2

addr_mode

设置地址分配模式[‘auto’, ‘basic’, ‘io_alone’, ‘io_tag’], 默认为auto

disable_layer_group

是否关闭LayerGroup

do_winograd

是否使用WinoGrad卷积, 仅用于BM1684平台

3.2.5. model_runner.py

对模型进行推理, 支持mlir/pytorch/onnx/tflite/bmodel/prototxt。

执行参考如下:

$ model_runner.py \
   --input sample_in_f32.npz \
   --model sample.bmodel \
   --output sample_output.npz \
   --out_fixed

支持的参数如下:

表 3.5 model_runner 参数功能

参数名

必选?

说明

input

指定模型输入, npz文件

model

指定模型文件, 支持mlir/pytorch/onnx/tflite/bmodel/prototxt

dump_all_tensors

开启后对导出所有的结果, 包括中间tensor的结果

out_fixed

开启后当出现int8类型定点数时不再自动转成float32类型进行打印

3.2.6. npz_tool.py

npz在TPU-MLIR工程中会大量用到, 包括输入输出的结果等等。npz_tool.py用于处理npz文件。

执行参考如下:

# 查看sample_out.npz中output的数据
$ npz_tool.py dump sample_out.npz output

支持的功能如下:

表 3.6 npz_tool 功能

功能

描述

dump

得到npz的所有tensor信息

compare

比较2个npz文件的差异

to_dat

将npz导出为dat文件, 连续的二进制存储

3.2.7. visual.py

量化网络如果遇到精度对比不过或者比较差, 可以使用此工具逐层可视化对比浮点网络和量化后网络的不同, 方便进行定位和手动调整。

执行命令可参考如下:

# 以使用9999端口为例
$ visual.py \
  --f32_mlir netname.mlir \
  --quant_mlir netname_int8_sym_tpu.mlir \
  --input top_input_f32.npz --port 9999

支持的功能如下:

表 3.7 visual 功能

功能

描述

f32_mlir

fp32网络mlir文件

quant_mlir

量化后网络mlir文件

input

测试输入数据, 可以是图像文件或者npz文件

port

使用的TCP端口, 默认10000, 需要在启动docker时映射至系统端口

host

使用的host ip地址, 默认0.0.0.0

manual_run

启动后是否自动进行网络推理比较, 默认False, 会自动推理比较

注意:需要在model_deploy.py阶段打开 --debug 选项保留中间文件供visual.py使用,工具的详细使用说明见(可视化工具visual说明)。

3.2.8. gen_rand_input.py

在模型转换时,如果不想额外准备测试数据(test_input),可以使用此工具生成随机的输入数据,方便模型验证工作。

基本操作过程是用 model_transform.py 将模型转成mlir文件, 此步骤不进行模型验证;接下来,用 gen_rand_input.py 读取上一步生成的mlir文件,生成用于模型验证的随机测试数据; 最后,再次使用 model_transform.py 进行完整的模型转换和验证工作。

执行的命令可参考如下:

# 模型初步转换为mlir文件
$ model_transform.py \
    --model_name yolov5s  \
    --model_def ../regression/model/yolov5s.onnx \
    --input_shapes [[1,3,640,640]] \
    --mean 0.0,0.0,0.0 \
    --scale 0.0039216,0.0039216,0.0039216 \
    --keep_aspect_ratio \
    --pixel_format rgb \
    --output_names 350,498,646 \
    --mlir yolov5s.mlir

# 生成随机测试数据,这里生成的是伪测试图片
$ gen_rand_input.py \
    --mlir yolov5s.mlir \
    --img --output yolov5s_fake_img.png

# 完整的模型转换和验证
$ model_transform.py \
    --model_name yolov5s  \
    --model_def ../regression/model/yolov5s.onnx \
    --input_shapes [[1,3,640,640]] \
    --mean 0.0,0.0,0.0 \
    --scale 0.0039216,0.0039216,0.0039216 \
    --test_input yolov5s_fake_img.png    \
    --test_result yolov5s_top_outputs.npz \
    --keep_aspect_ratio \
    --pixel_format rgb \
    --output_names 350,498,646 \
    --mlir yolov5s.mlir

更详细的使用方法可参考如下:

# 可为多个输入分别指定取值范围
$ gen_rand_input.py \
  --mlir ernie.mlir \
  --ranges [[0,300],[0,0]] \
  --output ern.npz

# 可为输入指定type类型,如不指定,默认从mlir文件中读取
$ gen_rand_input.py \
  --mlir resnet.mlir \
  --ranges [[0,300]] \
  --input_types si32 \
  --output resnet.npz

# 指定生成随机图片,不指定取值范围和数据类型
$ gen_rand_input.py \
    --mlir yolov5s.mlir \
    --img --output yolov5s_fake_img.png

支持的功能如下:

表 3.8 gen_rand_input 功能

参数名

必选?

说明

mlir

指定输入的mlir文件名称和路径

img

用于CV任务生成随机图片,否则生成npz文件。默认图片的取值范围为[0,255],数据类型为’uint8’,不通过’ranges’或’input_types’更改。

ranges

指定模型输入的取值范围,以列表形式表现,如[[0,300],[0,0]]。如果指定生成图片,则不需要指定取值范围,默认[0,255]。其他情况下,需要指定取值范围。

input_types

指定模型输入的数据类型,如si32,f32。目前仅支持 ‘si32’ 和 ‘f32’ 类型。如果不填,默认从mlir中读取。如果指定生成图片,则不需要指定数据类型,默认’uint8’。

output

指定输出的名称

注意:CV相关模型通常会对输入图片进行一系列预处理,为保证模型正确性验证通过,需要用’–img’生成随机图片作为输入,不能使用随机npz文件作为输入。 值得关注的是,随机输入可能会引起模型正确性验证对比不通过,特别是NLP相关模型,因此建议优先使用真实的测试数据。

3.2.9. model_tool

该工具用于处理最终的模型文件”bmodel”或者”cvimodel”,以下均以”xxx.bmodel”为例,介绍该工具的主要功能。

  1. 查看bmodel的基本信息

执行参考如下:

$ model_tool --info xxx.bmodel

显示模型的基本信息,包括模型的编译版本,编译日期,模型中网络名称,输入和输出参数等等。 显示效果如下:

bmodel version: B.2.2+v1.7.beta.134-ge26380a85-20240430
chip: BM1684X
create time: Tue Apr 30 18:04:06 2024

kernel_module name: libbm1684x_kernel_module.so
kernel_module size: 3136888
==========================================
net 0: [block_0]  static
------------
stage 0:
input: input_states, [1, 512, 2048], bfloat16, scale: 1, zero_point: 0
input: position_ids, [1, 512], int32, scale: 1, zero_point: 0
input: attention_mask, [1, 1, 512, 512], bfloat16, scale: 1, zero_point: 0
output: /layer/Add_1_output_0_Add, [1, 512, 2048], bfloat16, scale: 1, zero_point: 0
output: /layer/self_attn/Add_1_output_0_Add, [1, 1, 512, 256], bfloat16, scale: 1, zero_point: 0
output: /layer/self_attn/Transpose_2_output_0_Transpose, [1, 1, 512, 256], bfloat16, scale: 1, zero_point: 0
==========================================
net 1: [block_1]  static
------------
stage 0:
input: input_states, [1, 512, 2048], bfloat16, scale: 1, zero_point: 0
input: position_ids, [1, 512], int32, scale: 1, zero_point: 0
input: attention_mask, [1, 1, 512, 512], bfloat16, scale: 1, zero_point: 0
output: /layer/Add_1_output_0_Add, [1, 512, 2048], bfloat16, scale: 1, zero_point: 0
output: /layer/self_attn/Add_1_output_0_Add, [1, 1, 512, 256], bfloat16, scale: 1, zero_point: 0
output: /layer/self_attn/Transpose_2_output_0_Transpose, [1, 1, 512, 256], bfloat16, scale: 1, zero_point: 0

device mem size: 181645312 (weight: 121487360, instruct: 385024, runtime: 59772928)
host mem size: 0 (weight: 0, runtime: 0)
  1. 合并多个bmodel

执行参考如下:

$ model_tool --combine a.bmodel b.bmodel c.bmodel -o abc.bmodel

将多个bmodel合并成一个bmodel,如果bmodel中存在同名的网络,则会分不同的stage。

  1. 分解成多个bmodel

执行参考如下:

$ model_tool --extract abc.bmodel

将一个bmodel分解成多个bmodel,与combine命令是相反的操作。

  1. 显示权重信息

执行参考如下:

$ model_tool --weight xxx.bmodel

显示不同网络的各个算子的权重范围信息,显示效果如下:

net 0 : "block_0", stage:0
-------------------------------
tpu.Gather : [0x0, 0x40000)
tpu.Gather : [0x40000, 0x80000)
tpu.RMSNorm : [0x80000, 0x81000)
tpu.A16MatMul : [0x81000, 0x2b1000)
tpu.A16MatMul : [0x2b1000, 0x2f7000)
tpu.A16MatMul : [0x2f7000, 0x33d000)
tpu.A16MatMul : [0x33d000, 0x56d000)
tpu.RMSNorm : [0x56d000, 0x56e000)
tpu.A16MatMul : [0x56e000, 0x16ee000)
tpu.A16MatMul : [0x16ee000, 0x286e000)
tpu.A16MatMul : [0x286e000, 0x39ee000)
==========================================
net 1 : "block_1", stage:0
-------------------------------
tpu.Gather : [0x0, 0x40000)
tpu.Gather : [0x40000, 0x80000)
tpu.RMSNorm : [0x80000, 0x81000)
tpu.A16MatMul : [0x81000, 0x2b1000)
tpu.A16MatMul : [0x2b1000, 0x2f7000)
tpu.A16MatMul : [0x2f7000, 0x33d000)
tpu.A16MatMul : [0x33d000, 0x56d000)
tpu.RMSNorm : [0x56d000, 0x56e000)
tpu.A16MatMul : [0x56e000, 0x16ee000)
tpu.A16MatMul : [0x16ee000, 0x286e000)
tpu.A16MatMul : [0x286e000, 0x39ee000)
==========================================
  1. 更新权重

执行参考如下:

# 将src.bmodel中网络名为src_net的网络,在0x2000位置的权重,更新到dst.bmodel的dst_net的0x1000位置
$ model_tool --update_weight dst.bmodel dst_net 0x1000 src.bmodel src_net 0x2000

可以实现将模型权重进行更新。比如某个模型的某个算子权重需要更新,则将该算子单独编译成bmodel,然后将其权重更新到原始的模型中。