netrans/docs/netrans_py.md

Netrans_py 使用

Netrans_py 是针对 PNNA 芯片的模型处理工具的 Python 调用接口，用于将模型权重转换成在 PNNA 芯片上运行的 nbg（network binary graph）格式（.nb 为后缀），nbg 文件可用于后续模型部署和推理工程的交叉编译。

使用 Netrans_py 完成模型转换的步骤如下：

1. 初始化 Netrans
2. 导入模型并配置预处理参数
3. 量化模型
4. 前后处理加入推理计算图
5. 导出模型

系统依赖

• CPU ： Intel® Core™ i5-6500 CPU @ 3.2 GHz x4 支持 the Intel® Advanced Vector Extensions.
• RAM ： 至少8GB
• 硬盘 ： 160GB
• 操作系统 ： Ubuntu 20.04 LTS 64-bit with Python 3.10，不推荐使用其他版本

安装 Netrans_py

建议使用 mamba 作为环境隔离管理工具，避免安装 Netrans 导致污染系统环境。安装并激活 mamba 步骤如下：

# 下载 mamba 安装脚本
 wget "https://mirrors.tuna.tsinghua.edu.cn/github-release/conda-forge/miniforge/LatestRelease//Miniforge3-$(uname)-$(uname -m).sh"
 # 创建 mamba 的安装目录
 mkdir -p ~/app 
 # 安装 mamba 到 ~/app/ 
 bash Miniforge3-Linux-x86_64.sh -b -p ${HOME}/app/miniforge3
 # 添加 mamba 的初始化脚本到环境配置文件
 echo "source " ${HOME}/app/miniforge3/etc/profile.d/mamba.sh"" >> ${HOME}/.bashrc
 # 重新加载 ~/.bashrc 文件，使 mamba 初始化生效
 source ${HOME}/.bashrc
 # 创建一个名为 netrans 的虚拟环境，并安装 Python 3.8
 mamba create -n netrans python=3.8 -y
 # 激活 netrans 虚拟环境
 mamba activate netrans

下载 Netrans

cd ~/app
git clone https://gitlink.org.cn/nudt_dsp/netrans.git

Netrans_cli 是基于 Netrans_api 封装的命令行工具，执行 setup.sh 可安装 Netrans_cli。

cd ~/app/netrans 
# 激活 netrans 环境
mamba activate netrans
# 安装 Netrans 及 依赖
pip install bin/netrans-6.42.3-cp310-none-manylinux2010_x86_64.whl
pip install -r requirements_py3.10.txt

模型准备

不同框架下训练的模型需要准备不同的数据，所有的数据都需要与模型放在同一个文件夹下。具体参照 example 中不同框架的示例说明。 如 ONNX 格式保存的 yolov8s 模型，目录结构如下：

yolov4_tiny/
├── channel_mean_value.txt # 定义预处理中 mean & scale 的配置参数
├── dataset.txt # 定义量化数据的文件
├── input_image
│   ├── 0.jpg
│   ├── 1.jpg
│   ├── 2.jpg
│   ├── 3.jpg
│   ├── 4.jpg
│   ├── 5.jpg
│   ├── 6.jpg
│   ├── 7.jpg
│   ├── 8.jpg
│   └── 9.jpg
├── yolov4_tiny.cfg # 模型结构 
└── yolov4_tiny.weights # 模型权重

Netrans 类

创建 Netrans

描述：实例化 Netrans 类。

代码示例：

from netrans import Netrans
yolo_netrans = Netrans()

参数

参数名	类型	说明
无	无	无

输出返回：无。

Netrans.load 模型导入

描述：导入模型并配置预处理参数，将模型转换成 PNNA 支持的格式。

代码示例：

model_path = '../examples/darknet/yolov4_tiny'
# 导入 model_path 下的模型，并配置参 mean 为 129，scale 为 1
yolo_netrans.load(model_path, mean=[128, 128, 128], scale=[1, 1, 1])
# 导入 model_path 下的模型，并配置参 mean 为 129，scale 为 1
yolo_netrans.load(model_path, mean=[128, 128, 128], scale=[1])

参数

参数名	类型	说明
model_path	str	模型目录路径
mean	None，list, tuple	通道均值，可以是单个数字或数字列表/元组，列表/元组长度和输入的通道数保持一致。默认为 None
scale	None，list, tuple	通道缩放比例，可以是单个数字或数字列表/元组，列表/元组长度和输入的通道数保持一致。默认为 None

输出返回：无。

注意：在工程目录下生成 PNNA 支持的模型格式，以.json结尾的模型文件和 .data结尾的权重文件。

Netrans.quantize 模型量化

描述：对模型进行量化。

代码示例：

yolo_netrans.quantize('asymu8')

参数

参数名	类型	说明
quantized	str	量化类型
model_path	str	模型目录路径（可选），如果传入且与当前已加载目录不一致，则重新加载模型

| pre | bool | 是否将前处理做进推理网络计算图，默认为 False | | post | bool | 是否将后处理做进推理网络计算图，默认为 False |

支持的量化类型有： symi8: 对称量化算法，使用 int8 类型 asymu8: 非对称量化算法，使用 uint8 类型 symi16: 对称量化算法，使用 int16 类型

输出返回：无。

Netrans.add_pre_post 前后处理加入推理计算图

描述：配置将前后处理做进推理网络计算图。

代码示例：

yolo_netrans.add_pre_post('asymu8')

参数

参数名	类型	说明
quantized	str	量化类型
model_path	str	模型目录路径（可选），如果传入且与当前已加载目录不一致，则重新加载模型
pre	bool	是否将前处理做进推理网络计算图，默认为 True
post	bool	是否将后处理做进推理网络计算图，默认为 True

支持的量化类型有： symi8: 对称量化算法，使用 int8 类型 asymu8: 非对称量化算法，使用 uint8 类型 symi16: 对称量化算法，使用 int16 类型 输出返回：无。

Netrans.export 模型导出

描述：将量化后的模型导出为 nbg 文件。

代码示例：

yolo_netrans.export('asymu8')

参数

参数名	类型	说明
quantized	str	量化类型，默认为 "float32"
model_path	str	模型目录路径（可选），如果传入且与当前已加载目录不一致，则重新加载模型

支持的量化类型有： symi8: 对称量化算法，使用 int8 类型 asymu8: 非对称量化算法，使用 uint8 类型 symi16: 对称量化算法，使用 int16 类型

输出返回：无。

注意：请在目录 “wksp/*/” 下检查是否生成 nbg 文件。

使用示例

from netrans import Netrans

# 初始化 Netrans
model_path = '../examples/darknet/yolov4_tiny'
net = Netrans()

# 导入模型并配置预处理参数
net.load(model_path, mean=[128, 128, 128], scale=[1, 1, 1])

# 模型量化
net.quantize('asymu8')

# 配置前后处理加入推理计算图
net.add_pre_post('asymu8')

# 模型导出
net.export('asymu8')

作者：{{xujiao}}