3. Calibrator

3.1. Calibrator简介¶

使用前请先在SGS_IPU_SDK ⽬录下运⾏以下脚本，输出Library的路径（已经做过该步骤可忽略）：

cd ~/SGS_IPU_SDK
source cfg_env.sh

3.2. Calibrator工具使用说明¶

3.2.1 Calibrator工具使用示例¶

进入到该工具目录，执行：

python3 calibrator.py \
-i ~/SGS_Models/resource/detection/coco2017_calibration_set32 \
-m ~/SGS_Models/tensorflow/ssd_mobilenet_v1/ssd_mobilenet_v1_float.sim \
-n ~/SGS_Models/tensorflow/ssd_mobilenet_v1/ssd_mobilenet_v1.py \
--input_config ~/SGS_Models/tensorflow/ssd_mobilenet_v1/input_config.ini \
--num_process 20

python3 calibrator.py \
-i ~/SGS_Models/resource/detection/file.list \
-m ~/SGS_Models/tensorflow/ssd_mobilenet_v1/ssd_mobilenet_v1_float.sim \
-n ~/SGS_Models/tensorflow/ssd_mobilenet_v1/ssd_mobilenet_v1.py \
--input_config ~/SGS_Models/tensorflow/ssd_mobilenet_v1/input_config.ini \
--num_process 20

3.2.2 Calibrator工具使用参数说明¶

(1) 必选参数

• -i或--image: 指定转换模型所需的图片文件路径。

• -m或--model：指定chapter2中转换出的浮点网络模型文件路径。

• --input_config：指定input_config.ini文件路径。

• -n或--preprocess : 指定前处理方法，与图片前处理方法相关。

(2) 可选参数

• -o或--output: 指定定点网络模型输出路径。

• --num_process: 进程数，同时运行的进程数。(不加该参数默认为10个进程)。

• --quant_level: 选择量化等级。

3.3. 图片前处理方法¶

下面以caffe_resnet18网络为例，对编写图片前处理文件进行说明：

(1) 前处理文件使用示例

import cv2
import numpy as np

def get_image(img_path, resizeH=224, resizeW=224, resizeC=3, norm=True, meanB=104.0, meanG=117.0, meanR=123.0, std=1.0, rgb=False, nchw=False):
    img = cv2.imread(img_path, flags=-1)
    if img is None:
        raise FileNotFoundError('No such image: {}'.format(img_path))

    try:
        img_dim = img.shape[2]
    except IndexError:
        img_dim = 1
    if img_dim == 4:
        img = cv2.cvtColor(img, cv2.COLOR_BGRA2BGR)
    elif img_dim == 1:
        img = cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)
    img_float = img.astype('float32')
    img_norm = cv2.resize(img_float, (resizeW, resizeH), interpolation=cv2.INTER_LINEAR)

    if norm and (resizeC == 3):
        img_norm = (img_norm - [meanB, meanG, meanR]) / std
        img_norm = img_norm.astype('float32')
    elif norm and (resizeC == 1):
        img_norm = (img_norm - meanB) / std
        img_norm = img_norm.astype('float32')
    else:
        img_norm = np.round(img_norm).astype('uint8')

    if rgb:
        img_norm = cv2.cvtColor(img_norm, cv2.COLOR_BGR2RGB)

    if nchw:
        # NCHW
        img_norm = np.transpose(img_norm, axes=(2, 0, 1))

    return np.expand_dims(img_norm, 0)

def image_preprocess(img_path, norm=True):
    return get_image(img_path, norm=norm)

(2) image_preprocess函数说明：

使用image_preprocess函数调用，此处务必按照该方法书写。

def image_preprocess(img_path, norm=True):
    return get_image(img_path, norm=norm)

编写图片处理函数（函数名称不限），返回np.array 格式的图片数据，函数必须包含2个参数：

• 图片路径

• 归一化标记（norm=True）

  归一化标记是为了区分网络模型是否是浮点模型, 赋值为True即可，后继转换以及验证过程中均无需进行任何修改操作。

  (因为在浮点网络模型阶段，图片的归一化需要在送进网络前处理好。但是定点网络模型和离线网络模型已经包含了input_config.ini文件的设置信息，能够将图片数据自行做归一化处理，因此送进网络模型的数据不需要做归一化，这与在SigmaStar硬件上处理方式相同。)

(3) 更详细的图片前处理函数示例，请参考 附录 前处理和配置文件注意要点，将提供几下几种输入格式的模型前处理示例：

① training_input_formats和input_formats均为RGB或者均为BGR的模型前处理

② training_input_formats为GRAY和input_formats为GRAY的模型前处理

③ training_input_formats为RGB或BGR或GRAY和input_formats为YUV_NV12的模型前处理

④ training_input_formats和input_formats均为RAWDATA_S16_NHWC或者均为RAWDATA_F32_NHWC的模型前处理

3.4. calibrator_custom.calibrator简介¶

(1) calibrator_custom.calibrator是基于Python的快速量化和转换模型的模块。使用calibrator_custom.calibrator可以更方便灵活的对多输入、多段网络进行量化和转换。

(2) 目前基于的docker环境，提供Python3.7的预编译的Python模块。

(3) 使用 calibrator_custom.calibrator 时，需要给定float.sim模型的路径和对应的input_config.ini的路径，用于创建calibrator的实例。参数给定错误，将无法成功创建calibrator实例，并返回ValueError。使用方法和相关API接口如下：

import calibrator_custom
model_path = './mobilenet_v2_float.sim'
input_config_path = './input_config.ini'
model = calibrator_custom.calibrator(model_path, input_config_path)

(4) 对于多输入、多段网络同时转换时，提供calibrator_custom.SIM_Calibrator，calibrator_custom.SIM_Calibrator是已经实现好的class，当中只有forward方法未实现，使用时仅需实现该方法，即可转换完成。详情请参考 calibrator_custom.SIM_Calibrator。

3.4.1 calibrator_custom.calibrator方法¶

• (1) get_input_details: 返回网络模型信息

使用get_input_details可以得到网络模型详细信息, 以list形式返回结果。

① 获取网络模型输入信息list

input_details = model.get_input_details()
>>> print(input_details)
[{'index': 0, 'shape': array([ 1, 513, 513, 3], dtype=int32), 'name': 'sub_7', 'dtype': <class 'numpy.float32'>}]

返回的list中根据模型输入个数包含以下dict信息：

index: 输入Tensor序号

name: 输入Tensor名称

shape: 输入Tensor的形状

dtype: 输入Tensor的数据类型

② 获取网络模型输出信息list

output_details = model.get_output_details()
>>> print(output_details)
[{'index': 0, 'shape': array([ 1, 257, 257, 30], dtype=int32), 'name': 'MobilenetV2/Conv/Conv2D', 'dtype': <class 'numpy.float32'>}]

返回的list中根据模型输出个数包含以下dict信息：

index: 输出Tensor序号

name: 输出Tensor名称

shape: 输出Tensor的形状

dtype: 输出Tensor的数据类型

• (2) set_input: 设置网络模型输入数据

model.set_input(0, img_data)

• (3) invoke: 模型运行一次

model.invoke()

• (4)get_output: 获取网络模型输出数据

result = model.get_output(0)

• (5) get_tensor_details: 返回网络模型每个Tensor的信息（list）

tensor_details = model.get_tensor_details()
>>>print(tensor_details)
[{'dtype': 'FLOAT32', 'name': 'MobilenetV2/Conv/Conv2D', 'qtype': 'INT16', 'shape': array([ 1, 257, 257, 30], dtype=int32)}, {'dtype': 'FLOAT32', 'name': 'MobilenetV2/Conv/Conv2D_bias', 'qtype': 'INT16', 'shape': array([ 2, 30], dtype=int32)}, {'dtype': 'FLOAT32', 'name': 'MobilenetV2/Conv/weights/read', 'qtype': 'INT8', 'shape': array([30, 3, 3, 3], dtype=int32)}, {'dtype': 'FLOAT32', 'name': 'sub_7', 'qtype': 'UINT8', 'shape': array([ 1, 513, 513, 3], dtype=int32)}]

返回的list中根据模型Tensor个数包含以下dict信息：

name: Tensor名称

shape: Tensor的形状

dtype: Tensor的数据类型

qtype: 定点模型该Tensor可能的数据类型（quantization type）

3.4.2 calibrator_custom.SIM_Calibrator¶

(1) calibrator_custom.SIM_Calibrator简介

对于多输入、多段网络同时转换时，提供calibrator_custom.SIM_Calibrator，方便进行简单定义后，统一转换。calibrator_custom.SIM_Calibrator是已经实现好的class，当中只有forward方法未实现，使用时仅需实现该方法，即可转换完成。

(2) calibrator_custom.SIM_Calibrator使用方法

下面以SGS_IPU_SDK/Scripts/examples/sim_calibrator.py为例，说明calibrator_custom.SIM_Calibrator的使用方法：

① 定义forward方法：

import calibrator_custom
class Net(calibrator_custom.SIM_Calibrator):
    def __init__(self):
        super().__init__()
        self.model = calibrator_custom.calibrator(model_path, input_config)
    def forward(self, x):
        out_details = self.model.get_output_details()
        self.model.set_input(0, x)
        self.model.invoke()
        result_list = []
        for idx in range(len(out_details)):
            result = self.model.get_output(idx)
            result_list.append(result)
        return result_list

② 创建calibrator_custom.SIM_Calibrator的实例:

net = Net()

③ calibrator_custom.utils.image_preprocess_func使用预先定义好的前处理方法获取img_gen：

preprocess_func = calibrator_custom.utils.image_preprocess_func(model_name)

def image_generator(folder_path, preprocess_func):
    images = [os.path.join(folder_path, img) for img in os.listdir(folder_path)]
    for image in images:
        img = preprocess_func(image)
        yield [img]
img_gen = image_generator('./images', preprocess_func)

④ 调用calibrator_custom.SIM_Calibrator的convert方法：

net.convert(img_gen, fix_model=[out_model_path])

3.4.3 calibrator_custom.calibrator导入量化参数规则¶

3.4.3.1. 算子量化策略和方法说明¶

• (1) Conv2D的量化方法

  ① Conv2D的量化分为Inputs、Weights和Outputs，目前支持8bit，16bit量化。
  
  ② 如果使用8bit量化，Conv2D的输入为UINT8（相当于INT9的表达能力），Weights为INT8；如果使用16bit量化，Conv2D的输入和Weights均为INT16。
  
  ③ Weights的min和max值的个数由kernel的个数决定，输入和输出的min和max值的个数由输入输出的C维度决定。
  
  ④ 根据统计得到的Inputs、Weights和Outputs的min和max值，首先提前将Weights量化到定点数据，保存在fixed的网络内部，再在网络运行时动态量化输入和输出数据。
  

• (2) DepthwiseConv2D的量化方法

  ① DepthwiseConv2D的量化分为输入、Weights和输出，目前支持8bit，16bit量化。
  
  ② 如果使用8bit量化，DepthwiseConv2D的输入为UINT8（相当于INT9的表达能力），Weights为INT8；如果使用16bit量化，DepthwiseConv2D的输入和Weights均为INT16。
  
  ③ Weights、输入和输出的min和max值的个数均由对应Tensor的C维度决定。
  
  ④ 根据统计得到的输入、Weights和输出的min和max值，首先提前将Weights量化到定点数据，保存在fixed的网络内部，再在网络运行时动态量化输入和输出数据。
  

• (3) 其他Op量化方法

  ① 网络中其他算子的量化min和max均基于C维度数量，仅支持16bit量化。
  
  ② 调用calibrator_custom.calibrator的get_tensor_details方法可以从qtype中得知该Tensor在定点模型时的data type。
  

3.4.3.2. 量化参数的内容¶

基于上述量化的策略和方法，需要为Tensor提供如下信息：

1. Tensor的名字（name）[str]

2. 算子类型提供对应数量的min，max。[list]

3. 量化bit位。[int]

4. 常量Tensor数据（data）（可选）[numpy.ndarray]

下表展示了对应的参数方式，整个参数为list，其中每个item是一个dict，包含上述信息。

[
    {
        "name": "FeatureExtractor/MobilenetV2/Conv2d_0/weights",
        "min": [-4.555312, -2.876907, -1.234419],
        "max": [7.364561, 3.960804, 6.0],
        "bit": 8
    },
    {...},
    ...
]

示例SGS_IPU_SDK/Scripts/examples/sim_calibrator.py中已完成了参数导入，可以提供json和pkl文件的读取和导入。

3.4.3.2.1 量化模型量化参数导出工具¶

量化模型量化参数导出工具位置 SGS_IPU_SDK/Scripts/examples/save_quant_param.py 使用示例：

python3 save_quant_param.py \
-m fixed.sim \
--output_mode {JSON,Pickle}

3.4.3.3. 导入量化数据流程¶

3.5. torch_calibrator简介¶

(1) torch_calibrator工具的位置在 SGS_IPU_SDK/Scripts/calibrator/torch_calibrator.py。

(2) torch_calibrator是基于Pytorch开发的新一代量化工具，与旧工具链相比，有以下特性：

- 支持使用GPU，同等级的算法在GPU环境下量化速度更快（需配合使用Nvidia® GPU Docker）；

- 支持4/8bit混合量化算法，对于有条件的模型在8bit量化的基础上继续向下压缩，进一步提高运行效率；

- 支持更复杂的量化标定算法，量化精度进一步得到提升，对小模型（mobilenet系列、shufflenet系列、nanodet系列等）提升效果更为明显。

(3) torch_calibrator是对3.1 calibrator工具的补充。当模型参数量较小，使用3.1 calibrator工具无法达到满意的精度时；或者模型参数量较大，期待使用4bit量化减小模型大小，可以使用torch_calibrator工具。

3.5.1. torch_calibrator工具使用说明¶

(1) 工具使用示例

python3 torch_calibrator.py \
-i ilsvrc2012_calibration_set100 \
-m caffe_mobilenet_v2_float.sim \
--input_config input_config.ini \
--quant_config quant_config.yaml \
-n caffe_mobilenet_v2.py \
-q Q2

(2) 工具使用参数说明

① 必选参数

-i,--image : 标定数据集图像路径，100张训练图片。

-m, --model : 浮点网络模型文件路径。

--input_config : input_config.ini文件路径。

--quant_config : 量化参数(yaml格式)文件路径，后面会详细介绍该文件的配置方法和用途。

-n, --preprocess : 模型预处理文件（py文件）路径。

-q, --q_mode : 量化选项，后面会详细介绍。

② 可选参数

-o, --ouptut : 模型输出路径。指定定点网络模型输出位置：指定到文件夹，将自动以浮点网络模型文件前缀命名，后接fixed.sim；指定到具体路径和文件名，将以指定路径和文件名命名定点网络模型；不指定该参数，将以浮点网络模型文件路径储存定点网络模型。

--cal_batchsize : 标定数据集的batchsize，一般情况下等于数据集个数；如果标定数据集十分庞大或模型结构特殊无法在batchsize != 1的情况下推理，则可以设置这个参数。默认为100。

3.5.2. torch_calibrator量化选项¶

3.5.3. torch_calibrator量化参数(yaml格式)文件¶

(1) 文件内容展示

QUANT_CONFIG:
  retrain_iter_num: 40
  device: 'cuda:0'
  mixed_precisions: [4, 8]
  use_preset_min_max_bit: 0
  mp_rate: 0.6

PRESET_MIN_MAX_BIT: # preset tensor min/max and bit
  [
    {name: "126", min: null, max: null, bit: 8},
    {name: "layer1.0.conv1.weight", min: null, max: null, bit: 8}
  ]

• retrain_iter_num：每层重训练迭代次数

  如果该项不写则默认为40，部分轻量级模型可能需要更多的迭代次数。

• device：指定GPU/CPU

  如果不给则会自动寻找空闲的GPU。若无GPU则会自动调用CPU。

  若指定cpu运算，填写为'cpu'即可。

• use_preset_min_max_bit：是否使用手工预设的min/max/bit信息

  如果该项为1，则会使用下方手动设置的信息；如果该项为0或不写，则不会使用下方的信息。

• mixed_precisions: 混合量化模式

  可选[4, 8]，[8, 16]。如果不填，默认是[4, 8]。仅在Q13、Q23的模式生效。

• mp_rate：混合量化指定的压缩率

  如未指定或不在[0.5, 1]的范围内，则会自动推荐一个压缩率。该参数会配合mixed_precisions，生成4/8bit或8/16bit的模型。仅在Q13、Q23的模式下生效。

  如果自动推荐的压缩率满足精度要求，可通过以0.05步长下调压缩率，满足精度要求的同时提升模型性能。

  如果自动推荐的压缩率不满足精度要求，可通过以0.05步长上调压缩率，提升模型量化精度。

• PRESET_MIN_MAX_BIT：可以预设某个Tensor的min/max/bit信息

  详见量化策略和方法，Tensor名字以float.sim模型中为准。需要将use_preset_min_max_bit设为1。