8. 一键生成离线网络模型

8.1. SGS_Converter简介¶

SGS_Converter	说明
工具位置	SGS_IPU_SDK/Scripts/ConvertTool/SGS_converter.py
工具作用	将模型一键转换为SGS离线网络模型
使用须知	① 支持从`tensorflow_graphdef`，`tensorflow_savemodel`，`keras`，`tflite`，`caffe`，`onnx` 六种框架模型转换	不同框架模型一键转换的使用方法
	② `需配置input config`信息	详见 input config配置信息设置

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

cd ~/SGS_IPU_SDK
source cfg_env.sh

8.2. 不同框架模型一键转换为SGS离线网络模型的使用方法¶

下面是SGS_Converter目前支持的platform information：

python3 SGS_converter.py -h
usage: SGS_converter.py [-h]
                        {tensorflow_graphdef,tensorflow_savemodel,keras,tflite,caffe,onnx,debug}
                        ...

Convert Tool

positional arguments:
  {tensorflow_graphdef,tensorflow_savemodel,keras,tflite,caffe,onnx,debug}
                        platform info
    tensorflow_graphdef
                        tensorflow graphdef commands
    tensorflow_savemodel
                        tensorflow save_model commands
    keras               keras commands
    tflite              tflite commands
    caffe               caffe commands
    onnx                onnx commands
    debug               debug commands

optional arguments:
  -h, --help            show this help message and exit

不同平台模型转换为SGS离线网络模型的所需参数信息略有不同，如果想进一步了解各个平台转换所需要的参数信息，可以执行 python3 SGS_converter.py {platform} –h进行查看。下面将简单介绍各个平台转换所需的具体信息和查看指令：

8.2.1 caffe 框架指令¶

1、information：

python3 SGS_converter.py caffe -h
usage: SGS_converter.py caffe [-h]
    --model_file MODEL_FILE
    --weight_file WEIGHT_FILE
    --input_config INPUT_CONFIG
    -i IMAGE_FILE
    -n PREPROCESS
    [--input_shapes INPUT_SHAPES]
    [--output_file OUTPUT_FILE]
    [--export_models]

optional arguments:
  -h, --help            show this help message and exit
  --model_file MODEL_FILE
                        SavedModel directory to convert
   --weight_file WEIGHT_FILE
                        Full filepath of tflite file containing the caffe
  -n PREPROCESS, --preprocess PREPROCESS
                        Name of model to select image preprocess method
  --input_config INPUT_CONFIG
                        Input config path.
  -i IMAGE_FILE, --image IMAGE_FILE
                        Image / Directory containing images path / Image_list
                        for multi_input model.
  --input_shapes INPUT_SHAPES
                        Shapes corresponding to --input_arrays, colon-
                        separated. For many models each shape takes the form
                        batch size, input array height, input array width,
                        input array depth. (default None)
  --output_file OUTPUT_FILE
                        Full filepath of img file.
  --export_models       export models of debug/float/cmodel_float/fix

2、相关参数说明：

(1) 必选参数：

--model_file: 指定需进行转换的caffe模型文件路径。
--weight_file: 指定需进行转换的caffe权重文件路径。
--input_config: input_config.ini文件路径。

该文件为input tensor的配置信息。
-i: 指定转换模型所需的图片文件路径。

使用须知

支持使用单张图片路径进行传参，也支持图片文件夹路径，或存储图片路径列表的文件。使用路径列表形式时可参考如下方式：
- 网络模型为单输入时：
  
  -i ~/SGS_IPU_SDK/image_test/2007000364.jpg
- 网络模型为多输入时：
  
  -i _{/SGS_IPU_SDK/image_test/2007000364.jpg,}/SGS_IPU_SDK/image_test/ILSVRC2012_test_00000002.bmp

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

详见Calibrator:图片前处理方法。
--output_file: 指定生成的img文件。

(2) 可选参数：
--export_models: 指定转换模型时保存各个阶段的文件，不使用该参数则只生成离线网络文件。
--inplace_input_buf: RAWDATA_F32_NHWC 是否替换并覆盖原始输入buf.

使用须知

training_input_formats 和 input_formats 配置为 RAWDATA_F32_NHWC 且使用 --batch_mode的one_buf模式时才可以配置此参数。
可选True/False，默认为True。
True: 替换并覆盖原始输入buf。
False: 保留原始输入buf。

--q: 当使用torch_calibrator量化float模型时，需要制定此参数。

具体设置哪些量化选项详见Calibrator:torch_calibrator简介。
--quant_config: 当设置--q参数时，需要通过此参数传入quant_config.yaml量化参数文件。

量化参数文件quant_config.yaml格式详见Calibrator:torch_calibrator简介。

3、工具使用示例：

python3 SGS_converter.py caffe \
--model_file caffe_resnet50_conv.prototxt \
--weight_file caffe_resnet50_conv.caffemodel \
--input_config input_config.ini \
-i file.list
-n preprocess.py
--export_models
--output_file resnet50.img

8.2.2 onnx 框架指令¶

1、information：

python3 SGS_converter.py onnx -h
usage: SGS_converter.py onnx [-h]
    --model_file MODEL_FILE
    --input_config INPUT_CONFIG
    -i IMAGE_FILE
    -n PREPROCESS
    [--input_shapes INPUT_SHAPES]
    [--output_file OUTPUT_FILE]
    [--export_models]

optional arguments:
  -h, --help            show this help message and exit
  --model_file MODEL_FILE
                        SavedModel directory to convert
  -n PREPROCESS, --preprocess PREPROCESS
                        Name of model to select image preprocess method
  --input_config INPUT_CONFIG
                        Input config path.
  -i IMAGE_FILE, --image IMAGE_FILE
                        Image / Directory containing images path / Image_list
                        for multi_input model.
  --input_shapes INPUT_SHAPES
                        Shapes corresponding to --input_arrays, colon-
                        separated. For many models each shape takes the form
                        batch size, input array height, input array width,
                        input array depth. (default None)
  --output_file OUTPUT_FILE
                        Full filepath of img file path.
  --export_models       export models of debug/float/cmodel_float/fix

2、相关参数说明：

(1) 必选参数：

--model_file: 指定需进行转换的caffe模型文件路径。
--input_shapes: Onnx模型输入shape.

dimention 之间以逗号( , )分隔，shape个数和inputs 个数对应，多个shape之间以冒号( : )分隔。
--input_config: input_config.ini文件路径。

该文件为input tensor的配置信息。
-i: 指定转换模型所需的图片文件路径。

使用须知

支持使用单张图片路径进行传参，也支持图片文件夹路径，或存储图片路径列表的文件。使用路径列表形式时可参考如下方式：
- 网络模型为单输入时：
  
  -i ~/SGS_IPU_SDK/image_test/2007000364.jpg
- 网络模型为多输入时：
  
  -i _{/SGS_IPU_SDK/image_test/2007000364.jpg,}/SGS_IPU_SDK/image_test/ILSVRC2012_test_00000002.bmp

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

详见Calibrator:图片前处理方法。
--output_file: 指定生成的img文件。

(2) 可选参数：

--export_models: 指定转换模型时保存各个阶段的文件，不使用该参数则只生成离线网络文件。
--inplace_input_buf: RAWDATA_F32_NHWC 是否替换并覆盖原始输入buf.

使用须知

training_input_formats 和 input_formats 配置为 RAWDATA_F32_NHWC 且使用 --batch_mode的one_buf模式时才可以配置此参数。
可选True/False，默认为True。
True: 替换并覆盖原始输入buf。
False: 保留原始输入buf。

--q: 当使用torch_calibrator量化float模型时，需要制定此参数。

具体设置哪些量化选项详见Calibrator:torch_calibrator简介。
--quant_config: 当设置--q参数时，需要通过此参数传入quant_config.yaml量化参数文件。

量化参数文件quant_config.yaml格式详见Calibrator:torch_calibrator简介。

3、工具使用示例：

python3 ~/SGS_IPU_SDK/Scripts/ConvertTool/SGS_converter.py onnx
--model_file  ~/SGS_Models/onnx/onnx_mobilenet_v2/onnx_mobilenet_v2.onnx \
--input_shapes 1,3,224,224 \
--input_config ~/SGS_Models/onnx/onnx_mobilenet_v2/input_config.ini \
-i file.list
-n preprocess.py
--export_models
--output_file onnx_mobilenet_v2.img

Note

1.如果onnx模型中带有后处理的算子，请先去除，目前只支持主干网络的转换。如果是由其他框架生成的onnx模型，请务必注意在转换模型时关闭生成后处理的选项。

8.2.3 tflite 框架指令¶

1、information：

python3 SGS_converter.py tflite -h
usage: SGS_converter.py tflite [-h]
    --model_file MODEL_FILE
    --input_config INPUT_CONFIG
    -i IMAGE_FILE
    -n PREPROCESS
    [--input_shapes INPUT_SHAPES]
    [--output_file OUTPUT_FILE]
    [--export_models]

optional arguments:
  -h, --help            show this help message and exit
  --model_file MODEL_FILE
                        SavedModel directory to convert
  -n PREPROCESS, --preprocess PREPROCESS
                        Name of model to select image preprocess method
  --input_config INPUT_CONFIG
                        Input config path.
  -i IMAGE_FILE, --image IMAGE_FILE
                        Image / Directory containing images path / Image_list
                        for multi_input model.
  --input_shapes INPUT_SHAPES
                        Shapes corresponding to --input_arrays, colon-
                        separated. For many models each shape takes the form
                        batch size, input array height, input array width,
                        input array depth. (default None)
  --output_file OUTPUT_FILE
                        Full filepath of img file path.
  --export_models       export models of debug/float/cmodel_float/fix

2、相关参数说明：

(1) 必选参数：

--model_file: 指定需进行转换的模型文件路径。

输入的模型为tflite格式文件路径(必须为非量化模型)。
--input_config: input_config.ini文件路径。

该文件为input tensor的配置信息。
-i: 指定转换模型所需的图片文件路径。

使用须知

支持使用单张图片路径进行传参，也支持图片文件夹路径，或存储图片路径列表的文件。使用路径列表形式时可参考如下方式：
- 网络模型为单输入时：
  
  -i ~/SGS_IPU_SDK/image_test/2007000364.jpg
- 网络模型为多输入时：
  
  -i _{/SGS_IPU_SDK/image_test/2007000364.jpg,}/SGS_IPU_SDK/image_test/ILSVRC2012_test_00000002.bmp

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

详见Calibrator:图片前处理方法。
--output_file: 指定生成的img文件。

(2) 可选参数：

--export_models: 指定转换模型时保存各个阶段的文件，不使用该参数则只生成离线网络文件。
--inplace_input_buf: RAWDATA_F32_NHWC 是否替换并覆盖原始输入buf.

使用须知

training_input_formats 和 input_formats 配置为 RAWDATA_F32_NHWC 且使用 --batch_mode的one_buf模式时才可以配置此参数。
可选True/False，默认为True。
True: 替换并覆盖原始输入buf。
False: 保留原始输入buf。

--q: 当使用torch_calibrator量化float模型时，需要制定此参数。

具体设置哪些量化选项详见Calibrator:torch_calibrator简介。
--quant_config: 当设置--q参数时，需要通过此参数传入quant_config.yaml量化参数文件。

量化参数文件quant_config.yaml格式详见Calibrator:torch_calibrator简介。

3、工具使用示例：

python3 SGS_converter.py tflite \
--model_file Debug_save_model_float.tflite \
--input_config input_config.ini \
-i file.list
-n preprocess.py
--output_file save_model_float.img

8.2.4 tensorflow_graphdef 框架指令¶

1、information：

python3 SGS_converter.py tensorflow_graphdef -h
usage: SGS_converter.py tensorflow_graphdef [-h]
    --graph_def_file MODEL_FILE
    --input_config INPUT_CONFIG
    -i IMAGE_FILE
    -n PREPROCESS
    [--input_shapes INPUT_SHAPES]
    [--output_file OUTPUT_FILE]
    [--export_models]


optional arguments:
  -h, --help            show this help message and exit
  --graph_def_file MODEL_FILE
                        Full filepath of file containing frozen GraphDef
  --input_config INPUT_CONFIG
                        Input config path.
  -i IMAGE_FILE, --image IMAGE_FILE
                        Image / Directory containing images path / Image_list
                        for multi_input model.
  -n PREPROCESS, --preprocess PREPROCESS
                        Name of model to select image preprocess method
  --input_shapes INPUT_SHAPES
                        Shapes corresponding to --input_arrays, colon-
                        separated. For many models each shape takes the form
                        batch size, input array height, input array width,
                        input array depth. (default None)
  --output_file OUTPUT_FILE
                        Full filepath of img file path.
  --export_models       export models of debug/float/cmodel_float/fix

2、相关参数说明：

(1) 必选参数：

--model_file: 指定需进行转换的输入模型路径。

为TensorFlow frozen的graphdef的pb格式文件路径。
--input_config: input_config.ini文件路径。

该文件为input tensor的配置信息。
--input_shapes: 指定网络输入Tensor的shape。

格式为NHWC，dimention 之间以逗号( , )分隔；需注意shape个数和inputs个数对应，多个shape之间以冒号( : )分隔。
-i: 指定转换模型所需的图片文件路径。

使用须知

支持使用单张图片路径进行传参，也支持图片文件夹路径，或存储图片路径列表的文件。使用路径列表形式时可参考如下方式：
- 网络模型为单输入时：
  
  -i ~/SGS_IPU_SDK/image_test/2007000364.jpg
- 网络模型为多输入时：
  
  -i _{/SGS_IPU_SDK/image_test/2007000364.jpg,}/SGS_IPU_SDK/image_test/ILSVRC2012_test_00000002.bmp

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

详见Calibrator:图片前处理方法。
--output_file: 指定生成的img文件。

(2) 可选参数：

--export_models: 指定转换模型时保存各个阶段的文件，不使用该参数则只生成离线网络文件。
--inplace_input_buf: RAWDATA_F32_NHWC 是否替换并覆盖原始输入buf.

使用须知

training_input_formats 和 input_formats 配置为 RAWDATA_F32_NHWC 且使用 --batch_mode的one_buf模式时才可以配置此参数。
可选True/False，默认为True。
True: 替换并覆盖原始输入buf。
False: 保留原始输入buf。

--q: 当使用torch_calibrator量化float模型时，需要制定此参数。

具体设置哪些量化选项详见Calibrator:torch_calibrator简介。
--quant_config: 当设置--q参数时，需要通过此参数传入quant_config.yaml量化参数文件。

量化参数文件quant_config.yaml格式详见Calibrator:torch_calibrator简介。

3、工具使用示例：

python3 SGS_converter.py tensorflow_graphdef \
--graph_def_file yolo_v3_7/yolo_v3_7.pb \
--input_config input_config.ini \
--input_shapes 1,299,299,3 \
-i file.list
-n yolo_v3_7.py
--output_file yolo_v3_7.img

8.2.5 tensorflow_savemodel 框架指令¶

1、information：

python3 SGS_converter.py tensorflow_savemodel -h
usage: SGS_converter.py tensorflow_savemodel [-h]
    --saved_model_dir MODEL_FILE
    --input_config INPUT_CONFIG
    -i IMAGE_FILE
    -n PREPROCESS
    [--input_shapes INPUT_SHAPES]
    [--output_file OUTPUT_FILE]
    [--export_models]

optional arguments:
  -h, --help            show this help message and exit
  --saved_model_dir MODEL_FILE
                        SavedModel directory to convert
  -n PREPROCESS, --preprocess PREPROCESS
                        Name of model to select image preprocess method
  --input_config INPUT_CONFIG
                        Input config path.
  -i IMAGE_FILE, --image IMAGE_FILE
                        Image / Directory containing images path / Image_list
                        for multi_input model.
  --input_shapes INPUT_SHAPES
                        Shapes corresponding to --input_arrays, colon-
                        separated. For many models each shape takes the form
                        batch size, input array height, input array width,
                        input array depth. (default None)
  --output_file OUTPUT_FILE
                        Full filepath of img file path.
  --export_models       export models of debug/float/cmodel_float/fix

2、相关参数说明：

(1) 必选参数：

--model_file: 指定需进行转换的模型文件路径。

输入的模型为TensorFlow saved_model.builder生成的文件路径。
--input_config: input_config.ini文件路径。

该文件为input tensor的配置信息。
-i: 指定转换模型所需的图片文件路径。

使用须知

支持使用单张图片路径进行传参，也支持图片文件夹路径，或存储图片路径列表的文件。使用路径列表形式时可参考如下方式：
- 网络模型为单输入时：
  
  -i ~/SGS_IPU_SDK/image_test/2007000364.jpg
- 网络模型为多输入时：
  
  -i _{/SGS_IPU_SDK/image_test/2007000364.jpg,}/SGS_IPU_SDK/image_test/ILSVRC2012_test_00000002.bmp

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

详见Calibrator:图片前处理方法。
--output_file: 指定生成的img文件。

(2) 可选参数：

--export_models: 指定转换模型时保存各个阶段的文件，不使用该参数则只生成离线网络文件。
--output_file: 指定生成的img文件。
--input_shapes: 网络输入Tensor的shape。

格式为NHWC，dimention 之间以逗号( , )分隔，shape个数和inputs 个数对应，多个shape之间以冒号( : )分隔。若不指定则从saved_model_dir中获取。
--tag_set: 需要和save model时所指定的tag匹配。

如果不做设定，则默认为‘serve’。
--signature_key: 需要和save model时所指定的signature匹配。

如果不做设定，则默认为 ‘DEFAULT_SERVING_SIGNATURE_DEF_KEY’
--inplace_input_buf: RAWDATA_F32_NHWC 是否替换并覆盖原始输入buf.

使用须知

training_input_formats 和 input_formats 配置为 RAWDATA_F32_NHWC 且使用 --batch_mode的one_buf模式时才可以配置此参数。
可选True/False，默认为True。
True: 替换并覆盖原始输入buf。
False: 保留原始输入buf。

--q: 当使用torch_calibrator量化float模型时，需要制定此参数。

具体设置哪些量化选项详见Calibrator:torch_calibrator简介。
--quant_config: 当设置--q参数时，需要通过此参数传入quant_config.yaml量化参数文件。

量化参数文件quant_config.yaml格式详见Calibrator:torch_calibrator简介。

3、工具使用示例：

python3 SGS_converter.py tensorflow_savemodel \
--saved_model_dir ~/test/tensorflow_model/save_model \
--input_config input_config.ini \
-i file.list
-n preprocess.py
--output_file save_model.img

8.2.6 keras 框架指令¶

1、information：

python3 SGS_converter.py keras -h
usage: SGS_converter.py keras [-h]
    --model_file MODEL_FILE
    --input_config INPUT_CONFIG
    -i IMAGE_FILE
    -n PREPROCESS
    [--input_shapes INPUT_SHAPES]
    [--output_file OUTPUT_FILE]
    [--export_models]

optional arguments:
  -h, --help            show this help message and exit
  --model_file MODEL_FILE
                        SavedModel directory to convert
  -n PREPROCESS, --preprocess PREPROCESS
                        Name of model to select image preprocess method
  --input_config INPUT_CONFIG
                        Input config path.
  -i IMAGE_FILE, --image IMAGE_FILE
                        Image / Directory containing images path / Image_list
                        for multi_input model.
  --input_shapes INPUT_SHAPES
                        Shapes corresponding to --input_arrays, colon-
                        separated. For many models each shape takes the form
                        batch size, input array height, input array width,
                        input array depth. (default None)
  --output_file OUTPUT_FILE
                        Full filepath of img file path.
  --export_models       export models of debug/float/cmodel_float/fix

2、相关参数说明：

(1) 必选参数：

--model_file: 指定需进行转换的模型文件路径。

输入的模型为keras h5格式文件路径。
--input_config: input_config.ini文件路径。

该文件为input tensor的配置信息。
-i: 指定转换模型所需的图片文件路径。

使用须知

支持使用单张图片路径进行传参，也支持图片文件夹路径，或存储图片路径列表的文件。使用路径列表形式时可参考如下方式：
- 网络模型为单输入时：
  
  -i ~/SGS_IPU_SDK/image_test/2007000364.jpg
- 网络模型为多输入时：
  
  -i _{/SGS_IPU_SDK/image_test/2007000364.jpg,}/SGS_IPU_SDK/image_test/ILSVRC2012_test_00000002.bmp

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

详见Calibrator:图片前处理方法。
--output_file: 指定生成的img文件。

(2) 可选参数：

--export_models: 指定转换模型时保存各个阶段的文件，不使用该参数则只生成离线网络文件。
--output_file: 指定生成的img文件。
--custom_objects: Dict mapping names (strings) to custom classes or functions to be considered during model deserialization (default None).
--inplace_input_buf: RAWDATA_F32_NHWC 是否替换并覆盖原始输入buf.

使用须知

training_input_formats 和 input_formats 配置为 RAWDATA_F32_NHWC 且使用 --batch_mode的one_buf模式时才可以配置此参数。
可选True/False，默认为True。
True: 替换并覆盖原始输入buf。
False: 保留原始输入buf。

--q: 当使用torch_calibrator量化float模型时，需要制定此参数。

具体设置哪些量化选项详见Calibrator:torch_calibrator简介。
--quant_config: 当设置--q参数时，需要通过此参数传入quant_config.yaml量化参数文件。

量化参数文件quant_config.yaml格式详见Calibrator:torch_calibrator简介。

3、工具使用示例：

python3 SGS_converter.py keras \
--model_file resnet50.h5 \
--input_config input_config.ini \
-i file.list
-n resnet50.py
--output_file resnet50.img

8.3. 转换带有特殊设定的模型¶

使用Convert、Calibrator、Compiler工具生成SGS各阶段网络时，可以通过配置转换指令参数的方式指定模型的转换模式。如果需要使用一键转换工具实现上述工具的同等功能，可以通过

(1)在input_config.ini中配置指定参数（对input_config.ini配置信息的详细说明已在 Convert Tool:input_config配置信息设置中给出）
(2)在转换指令中配置指定参数

两种方式实现，实现各功能所对应的方法如下所示：

(1) 功能：指定同时运行的进程数

该功能对应Calibrator中的可选参数--num_process所实现的功能；

一键转换模型时，通过在input_config.ini的[INPUT_CONFIG]中配置num_process指定进程数实现：

[INPUT_CONFIG]
;Amount of processes run at same time.
num_process=10;

使用须知

如果无进程数要求，则无需在input_config.ini中配置该参数，并将使用默认值10进行模型转换。

(2) 功能：选择量化等级

该功能对应Calibrator中的可选参数--quant_level所实现的功能；

一键转换模型时，通过在input_config.ini的[INPUT_CONFIG]中配置--quant_level指定量化等级实现：

[INPUT_CONFIG]
;choices=['L1', 'L2', 'L3', 'L4', 'L5'],
;Indicate Quantilization level. The higher the level, the slower the speed and the higher the accuracy.
quant_level=L5;

使用须知

如果无量化要求，则无需在input_config.ini中配置该参数，将使用默认值L5进行模型转换。

(3) 功能：选择量化工具

该功能对应Calibrator中的torch_calibrator工具所实现的功能；如需选择量化工具，请使用分阶段转换模型的方式进行模型转换。

(4) 功能：选择Batch数

该功能对应Compiler中的可选参数-b, --batch和--batch_mode所实现的功能；

一键转换模型时，通过在input_config.ini的[INPUT_CONFIG]中配置batch指定Batch数,配置batchmode指定多batch模式实现：

[INPUT_CONFIG]
;Expected max batch size in normal batch mode,or specific batches, comma-separated for multi-batches
batch=1;
;choices=['n_buf', 'one_buf']
batchmode=one_buf;

使用须知

如果无需求，则无需在input_config.ini中配置相关参数，将使用默认值(batch=1,batchmode=one_buf)进行模型转换。

(5) 功能：选择模型的类别

该功能对应Compiler中的可选参数-c, --category所实现的功能；

一键转换模型时无需对该参数进行配置。

(6) 功能：RAWDATA_F32_NHWC 是否替换并覆盖原始输入buf.

该功能对应Compiler中的可选参数--inplace_input_buf所实现的功能；

一键转换模型时，通过在转换命令中配置参数--inplace_input_buf实现.