Netrans Python API 参考手册
版本: v6.33.3 (Python 3.10 + Acuity 6.33)
概述
Netrans提供简洁而功能完整的Python API，用于将神经网络模型转换为PNNA芯片可运行的NBG格式。支持多种深度学习框架（TensorFlow、PyTorch、ONNX、Caffe、Darknet）和量化策略。
快速开始
from netrans import Netrans
# 推荐的完整工作流程：加载 → 量化 → 导出(集成前后处理)
model = Netrans()
model.load('./yolov5s', mean=[0,0,0], scale=0.00392) # 加载模型
model.quantize('asymu8') # 量化
model.export('asymu8', preprocess=True, postprocess=True) # 导出并集成前后处理
核心类
Netrans类
神经网络转换工具的主类，提供完整的模型处理流水线。
初始化
Netrans()
创建Netrans实例，自动验证运行环境和依赖项。
示例：
from netrans import Netrans
# 创建实例
model = Netrans()
load()
加载并准备模型，支持多种框架格式和预处理参数配置。
load(model_path, *, mean=None, scale=None)
参数：
model_path(str): 模型目录路径，必须包含有效的模型文件mean(float | list[float], 可选): 通道均值。支持格式：列表：长度必须与模型输入通道数一致，按通道顺序对应
单值：仅适用于单通道模型（如灰度图像）
scale(float | list[float], 可选): 通道缩放系数。支持格式：单值：自动广播到所有通道
列表：长度必须与
mean参数一致，或单值广播
技术规范：
通道数由模型输入shape决定，常见CV模型为3通道（RGB）
mean列表长度必须等于模型输入通道数；scale支持单值广播mean和scale长度关系：len(mean) == len(scale)或len(scale) == 1数值类型支持
int和float，内部统一转换为float32
正确用法：
# 三通道RGB模型（如YOLOv5、ResNet50等）
model.load('./yolov5s', mean=[128.0, 128.0, 128.0], scale=255.0) # scale广播
model.load('./resnet50', mean=[123.675, 116.28, 103.53], scale=[58.395, 57.12, 57.375])
# 单通道灰度模型
model.load('./lenet_gray', mean=[127.5], scale=255.0) # mean用列表，即使单通道
# 或
model.load('./lenet_gray', mean=127.5, scale=255.0) # 单值仅适用于单通道
错误用法：
# 三通道模型不能用单值mean
model.load('./yolov5s', mean=128, scale=1) # ❌ 错误：三通道模型mean必须用列表
# 长度不一致
model.load('./model', mean=[128, 128], scale=[1, 1, 1]) # ❌ mean和scale长度不匹配
验证方法：
检查模型输入元数据文件<model>_inputmeta.yml中的shape字段：
1shape: [1, 3, 640, 640] # [batch, channels, height, width]
channels值即为输入通道数，mean和scale列表长度必须与此值一致。
异常：
FileNotFoundError: 模型目录不存在ValueError: 未找到模型文件或参数格式错误TypeError: mean/scale格式无效
quantize()
对加载的模型进行量化处理，支持多种量化算法和配置。
quantize(quantized, *, algorithm=1, iterations=1, entropy=False, mle=False)
参数：
quantized(str): 目标量化类型，支持：'asymu8': 非对称8位无符号量化（最常用）'symi8': 对称8位有符号量化'symi16': 对称16位有符号量化
algorithm(int, 可选): 量化算法选择，默认1：0: 普通量化1: KL散度量化（推荐，精度较高）2: 移动平均量化3: 自动选择量化
iterations(int, 可选): 量化迭代次数，默认1。增加迭代可提高精度但耗时更长entropy(bool, 可选): 是否计算张量熵，默认False。用于量化分析mle(bool, 可选): 是否最小化层间误差，默认False
算法选择建议：
大多数模型：
algorithm=1(KL散度，平衡精度和速度)对精度要求极高：
algorithm=3(自动选择，可能更耗时)快速测试：
algorithm=0(最快，精度可能略低)
示例：
# 基础量化
model.quantize('asymu8')
# 高精度量化
model.quantize('asymu8', algorithm=1, iterations=5)
# 量化分析模式
model.quantize('asymu8', entropy=True, mle=True)
注意：
从 v2.0 开始，
preprocess和postprocess参数已移至export()方法建议在
export()时设置preprocess=True和postprocess=True
异常：
QuantizationError: 量化过程失败ValueError: 量化类型不支持
quantize_hybrid()
对指定层应用混合精度量化，允许同一模型中使用不同量化策略。
quantize_hybrid(quantized, *, algorithm=1, iterations=1,
hybrid_qtype='dfpi16', cust_qnt_layers=None)
参数：
quantized(str): 基础量化类型algorithm(int, 可选): 量化算法，同quantize()iterations(int, 可选): 迭代次数，默认1hybrid_qtype(str, 可选): 混合层量化类型，默认'dfpi16'cust_qnt_layers(str, 可选): 自定义量化层配置文件路径
配置文件格式（cust_qnt_layers.txt）：
# Layer列表格式
Conv_1
Conv_2
Conv_3
示例：
# 基础混合量化
model.quantize_hybrid('asymu8', cust_qnt_layers='layers.txt')
# 完整混合量化流程
model.quantize_hybrid('asymu8', cust_qnt_layers='layers.txt')
model.add_pre_post('asymu8', use_hybrid=True) # 混合量化后需要单独添加
model.export('asymu8', use_hybrid=True)
异常：
QuantizationError: 混合量化失败
add_pre_post()
将预处理和后处理操作集成到网络图中，优化推理性能。
add_pre_post(quantized, *, preprocess=True, postprocess=True, use_hybrid=False)
参数：
quantized(str): 量化类型preprocess(bool, 可选): 是否集成预处理（mean/scale），默认Truepostprocess(bool, 可选): 是否集成后处理（反量化），默认Trueuse_hybrid(bool, 可选): 是否使用混合量化文件，默认False
注意事项：
FP16量化类型下此操作无效
功能等价于
quantize(..., pre=True, post=True)，提供分步控制能力主要用于混合量化流程和调试分析
示例：
# 混合量化后添加前后处理
model.add_pre_post('asymu8', use_hybrid=True)
# 单独控制预处理
model.add_pre_post('asymu8', preprocess=True, postprocess=False)
export()
将量化后的模型导出为PNNA芯片可加载的NBG格式。
export(quantized='float32', *, model_path=None, platform='pnna', use_hybrid=False,
preprocess=True, postprocess=True, core_num=None)
参数：
quantized(str, 可选): 量化类型，默认'float32'。应与量化步骤一致model_path(str, 可选): 模型目录路径，如与已加载模型不同则重新加载platform(str, 可选): 目标芯片平台，默认'pnna'：'pnna': VIP8000NANOQI_PLUS_PID0XB1（默认平台）'pnna2': VIP9400O_PID0X1000004F
use_hybrid(bool, 可选): 是否使用混合量化文件，默认Falsepreprocess(bool, 可选): 是否集成预处理到网络图，默认Truepostprocess(bool, 可选): 是否集成后处理（反量化）到网络图，默认Truecore_num(str, 可选): 多核配置，可选值："1core"或"1": 单核模式"2core"或"2": 双核模式"3core"或"3": 三核模式"4core"或"4": 四核模式
平台选择：
不确定时保持默认
'pnna'特定芯片型号需要对应平台，咨询硬件团队确认
平台与多核支持：
平台 |
芯片型号 |
多核支持 |
说明 |
|---|---|---|---|
|
VIP8000NANOQI_PLUS_PID0XB1 |
❌ 不支持 |
单核架构，不需要 viv-sdk |
|
VIP9400O_PID0X1000004F |
✅ 支持 1-4 核 |
多核架构，需要 viv-sdk 生成多核 NBG |
注意： 多核配置 (core_num) 仅在 pnna2 平台有效，pnna 平台不支持多核模式。
前后处理集成：
preprocess=True: 将 mean/scale 预处理操作集成到网络图postprocess=True: 将反量化操作集成到网络图推荐在生产环境中启用，减少运行时开销
FP16 量化类型下此功能无效
示例：
# 基础导出
model.export('asymu8')
# 带前后处理的导出（推荐）
model.export('asymu8', preprocess=True, postprocess=True)
# 指定平台
model.export('asymu8', platform='pnna')
model.export('asymu8', platform='pnna2')
# 混合量化导出
model.export('asymu8', use_hybrid=True)
# 多核导出
model.export('asymu8', platform='pnna2', core_num='4core') # 4核模式
model.export('asymu8', platform='pnna2', core_num='1') # 单核模式（简写）
# 连续导出不同配置
model.export('asymu8', platform='pnna2', core_num='1core') # 1核
model.export('asymu8', platform='pnna2', core_num='4core') # 4核（覆盖）
多核配置说明：
通过 core_num 参数可控制 VIP 多核运行模式：
配置值 |
VIV_MGPU_AFFINITY |
VIV_OVX_MULTI_DEVICES |
说明 |
|---|---|---|---|
1core 或 1 |
1:0 |
0:1 |
单核模式，使用 VIP_0 |
2core 或 2 |
1:2 |
0:2-2 |
双核模式 |
3core 或 3 |
1:3 |
0:3-1 |
三核模式 |
4core 或 4 |
1:4 |
0:4-1 |
四核模式 |
重要限制：
多核配置 仅
pnna2平台支持，pnna平台不支持多核使用多核导出时，必须确保
VIV_SDK_PATH环境变量已正确设置core_num设置仅影响当前进程，进程结束后自动恢复
输出文件：
wksp/<model>_<quantized>_nbg_unify/network_binary.nb: 最终NBG文件wksp/<model>_<quantized>_nbg_unify/nbg_meta.json: NBG元数据wksp/<model>_<quantized>_nbg_unify/main.c: 示例C代码
异常：
ExportError: 导出过程失败ValueError: 平台或量化类型不支持，或core_num值无效
dump()
导出网络各层张量数据，用于量化效果分析和精度调试。
dump(quantized='float32', *, use_hybrid=False)
参数：
quantized(str, 可选): 量化类型，默认'float32'use_hybrid(bool, 可选): 是否使用混合量化文件，默认False
输出：
dump/<model>_<quantized>/: 张量数据目录*.tensor: 各层激活值文件，可用于对比分析
示例：
# 基础导出
model.dump('asymu8')
# 混合量化导出
model.dump('asymu8', use_hybrid=True)
inference()
运行模型推理并保存输入输出张量，用于精度验证。
inference(quantized='float32', *, iterations=1, use_hybrid=False)
参数：
quantized(str, 可选): 量化类型，默认'float32'iterations(int, 可选): 推理迭代次数，默认1use_hybrid(bool, 可选): 是否使用混合量化文件，默认False
输出：
wksp/<model>_<quantized>/golden/: 标准输入输出数据可用于对比不同量化版本的精度差异
示例：
# 单次推理
model.inference('asymu8')
# 多次推理（统计稳定性）
model.inference('asymu8', iterations=5)
# 混合量化推理
model.inference('asymu8', use_hybrid=True)
完整示例
更多完整示例请参考 cookbook.md，包括：
YOLOv5s 完整转换流程
混合量化示例
批量处理脚本
调试与验证流程
check_opset()
检查 ONNX 模型的 opset 版本是否符合 Netrans 要求。
check_opset(model_path, verbose=False)
参数：
model_path(str): ONNX 模型文件路径或包含 .onnx 文件的目录verbose(bool, 可选): 是否显示详细信息，默认 False
返回：
bool: 是否符合要求（True=符合，False=不符合或检查失败）
支持的 opset 版本： Netrans 支持 ONNX opset 版本范围：7 - 17
Opset 版本 |
ONNX 版本 |
支持状态 |
|---|---|---|
7-17 |
1.2-1.12 |
✅ 支持 |
18+ |
1.13+ |
❌ 不支持 |
示例：
from netrans import Netrans
model = Netrans()
# 检查单个 ONNX 文件
is_valid = model.check_opset('./yolov5s.onnx')
print(f"模型可用: {is_valid}")
# 检查目录（自动查找 .onnx 文件）
is_valid = model.check_opset('./yolov5s/')
# 详细输出
is_valid = model.check_opset('./yolov5s.onnx', verbose=True)
输出示例：
============================================================
ONNX 模型 Opset 版本检查
============================================================
模型路径: ./yolov5s.onnx
Opset 版本: 11 (ONNX 1.6)
IR 版本: 6
Producer: pytorch 1.9
状态: ✅ opset 版本 11 符合要求
============================================================
异常：
NetransError: 检查过程中发生错误（如 onnx 包未安装）
相关文档
netrans_cli.md - 命令行工具参考
cookbook.md - 使用指南
技术支持： 如遇API使用问题，请参考示例代码或联系技术支持团队。