Netrans Python API 参考

本手册提供 Netrans Python API 的完整规范，按方法分节描述。
如需快速上手，请先阅读快速入门指南。

概述

Netrans 提供简洁而功能完整的 Python API，用于将神经网络模型转换为 PNNA 芯片可运行的 NBG 格式。支持多种深度学习框架（TensorFlow、PyTorch、ONNX、Caffe、Darknet）和量化策略。

核心类

Netrans类

神经网络转换工具的主类，提供完整的模型处理流水线。

快速开始

from netrans import Netrans

# 推荐的完整工作流程：加载 → 量化(集成前后处理) → 导出
model = Netrans()                    
model.load('./yolov5s', mean=[0,0,0], scale=0.00392)  # 加载模型  
model.quantize('asymu8', pre=True, post=True)        # 量化并集成前后处理
model.export('asymu8')                               # 导出为芯片格式

方法总览

方法	一句话描述
load	将模型载入工作区并写入预处理参数
quantize	对网络执行静态量化
quantize_hybrid	对指定层使用混合精度量化
add_pre_post	将前后处理节点嵌入网络
export	生成 PNNA 芯片可加载的 .nb 文件
dump	导出各层激活张量用于调试
inference	执行一次前向推理并保存输入输出

方法详细规范

Netrans.init

描述：实例化 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	模型目录路径（可选），如果传入且与当前已加载目录不一致，则重新加载模型

支持的量化类型有： 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 文件。

Netrans.quantize_hybrid 混合量化

描述：对指定层应用混合精度量化，允许同一模型中使用不同量化策略。

代码示例：

# 基础混合量化
yolo_netrans.quantize_hybrid('asymu8', cust_qnt_layers='layers.txt')

# 完整混合量化流程
yolo_netrans.quantize_hybrid('asymu8', cust_qnt_layers='layers.txt')
yolo_netrans.add_pre_post('asymu8', use_hybrid=True)
yolo_netrans.export('asymu8', use_hybrid=True)

参数

参数名	类型	说明
quantized	str	基础量化类型
model_path	str	模型目录路径（可选），如果传入且与当前已加载目录不一致，则重新加载模型
algorithm	int	量化算法，默认为 1
iterations	int	迭代次数，默认为 1
entropy	bool	是否计算张量熵，默认为 False
hybrid_qtype	str	混合层量化类型，默认为 'dfpi16'
cust_qnt_layers	str	自定义量化层配置文件路径

配置文件格式（layers.txt）：

# 层名列表（每行一个）
Conv_0
Conv_2
Conv_4

输出返回：无。

注意：混合量化后需要单独执行 add_pre_post 和 export，并设置 use_hybrid=True。

Netrans.dump 张量导出

描述：导出网络各层张量数据，用于量化效果分析和精度调试。

代码示例：

# 基础导出
yolo_netrans.dump('asymu8')

# 混合量化导出
yolo_netrans.dump('asymu8', use_hybrid=True)

参数

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

输出：

dump/<model>_<quantized>/: 张量数据目录
*.tensor: 各层激活值文件，可用于对比分析

输出返回：无。

Netrans.inference 模型推理

描述：运行模型推理并保存输入输出张量，用于精度验证。

代码示例：

# 单次推理
yolo_netrans.inference('asymu8')

# 多次推理（统计稳定性）
yolo_netrans.inference('asymu8', iterations=5)

# 混合量化推理
yolo_netrans.inference('asymu8', use_hybrid=True)

参数

参数名	类型	说明
quantized	str	量化类型，默认为 "float32"
model_path	str	模型目录路径（可选），如果传入且与当前已加载目录不一致，则重新加载模型
iterations	int	推理迭代次数，默认为 1
use_hybrid	bool	是否使用混合量化文件，默认为 False

输出：

wksp/<model>_<quantized>/golden/: 标准输入输出数据
可用于对比不同量化版本的精度差异

输出返回：无。

使用示例

基础转换流程

from netrans import Netrans

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

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

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

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

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

混合量化流程

from netrans import Netrans
import os

# 初始化 Netrans
netrans = Netrans()

# 导入模型
netrans.load('./yolov5s', mean=[0, 0, 0], scale=0.00392)

# 创建混合量化配置文件
with open('layers.txt', 'w') as f:
    f.write('Conv_245\n')  # 检测头1
    f.write('Conv_269\n')  # 检测头2
    f.write('Conv_293\n')  # 检测头3

# 执行混合量化
netrans.quantize_hybrid('asymu8', cust_qnt_layers='layers.txt')

# 添加前后处理（混合量化需要单独执行）
netrans.add_pre_post('asymu8', use_hybrid=True)

# 导出模型
netrans.export('asymu8', use_hybrid=True)

调试和分析流程

from netrans import Netrans

# 初始化 Netrans
netrans = Netrans()

# 导入模型
netrans.load('./model', mean=[128, 128, 128], scale=1)

# 量化
netrans.quantize('asymu8')

# 导出各层张量用于调试
netrans.dump('asymu8')

# 执行推理验证
netrans.inference('asymu8', iterations=3)

# 导出最终模型
netrans.export('asymu8')

作者：@xj xujiao@hngwg.com