You're reading an pre-release version of this documentation.
For the latest stable release version, please have a look at master.

Netrans Python API 参考

版本: v6.33.6 (Python 3.10)

概述

Netrans 提供简洁的 Python API，用于将神经网络模型转换为 PNNA 芯片可运行的 NBG 格式。

核心流程

load() → quantize() → export()

方法总览

方法

用途

load()

加载模型并配置预处理参数

quantize()

对模型进行量化

quantize_hybrid()

混合精度量化

export()

导出 NBG 文件

add_pre_post()

嵌入前后处理节点

dump()

导出各层张量用于调试

inference()

执行推理并保存输入输出

measure()

统计模型计算量（FLOPs）和参数量

check_opset()

检查 ONNX 模型 opset 版本

快速示例

from netrans import Netrans

model = Netrans()
model.load('./yolov5s', mean=[0, 0, 0], std=255)
model.quantize('asymu8')
model.export('asymu8', platform='pnna')

Netrans 类

初始化

Netrans()

创建 Netrans 实例，自动验证运行环境和依赖项。

加载模型

load()

load(model_path, *, mean=None, std=None)

加载并准备模型，支持多种框架格式和预处理参数配置。

参数：

  • model_path (str): 模型目录路径，必须包含有效的模型文件

  • mean (float | list[float], 可选): 通道均值

    • v6.33.4 新增自动广播：单值或单元素列表自动广播到所有通道

    • 例如：mean=128 → [128, 128, 128]（三通道模型）

  • std (float | list[float], 可选): 通道标准差（归一化除数）

    • 自动广播：单值自动广播到所有通道

    • 例如：std=255 → [255, 255, 255]（三通道模型）

示例：

# 自动广播（推荐，v6.33.4+）
model.load('./yolov5s', mean=128, std=255)         # 单值自动广播
model.load('./yolov5s', mean=[128], std=[255])     # 单元素列表也广播

# 传统方式（仍然支持）
model.load('./yolov5s', mean=[0, 0, 0], std=255)   # std 单值广播
model.load('./yolov5s', mean=[0, 0, 0], std=[255, 255, 255])  # 全指定

# 不同通道数
model.load('./lenet_gray', mean=127.5, std=255)    # 单通道：[127.5], [255]
model.load('./yolov5s', mean=128, std=255)         # 三通道：[128, 128, 128]

注意：

  • 支持的模型格式：ONNX, TensorFlow, TFLite, PyTorch, Caffe, Darknet, Keras

  • 自动广播时会输出日志提示广播结果

  • 如果提供多值列表，长度必须匹配通道数

量化

quantize()

quantize(quantized, *, model_path=None, algorithm=1, iterations=1,
         entropy=False, mle=False, lid=None, in_out_quantized=None,
         quantize_file=None)

对加载的模型进行量化处理。

参数：

  • quantized (str): 目标量化类型

    • asymu8: 非对称8位无符号（默认推荐）

    • symi8: 对称8位有符号

    • symi16: 对称16位有符号

    • fp16: 半精度浮点

    • 更多类型详见 cookbook.md 速查表

  • model_path (str, 可选): 模型目录路径

  • algorithm (int, 可选): 量化算法，默认 1

    • 0: normal - 普通量化

    • 1: KL - KL散度（默认）

    • 2: moving_average - 移动平均

    • 3: auto - 自动选择

  • iterations (int, 可选): 量化迭代次数，默认 1

  • entropy (bool, 可选): 计算张量熵，用于量化分析，默认 False

  • mle (bool, 可选): 最小化层间误差，用于量化分析，默认 False

  • lid (str, 可选): 要应用自定义量化类型的层名，多个层以逗号分隔，如 'input_0' 或 'input_0,output_0'

  • in_out_quantized (str, 可选): 为 lid 指定的层单独设置量化类型，如 'dfpi16'、'symi16'。必须与 lid 同时使用

  • quantize_file (str, 保留参数): 当前 Python API 尚未接入 QAT 量化流程，请勿使用；QAT 支持以后续版本说明为准

示例：

# 基础量化
model.quantize('asymu8')

# 高精度量化
model.quantize('asymu8', algorithm=1, iterations=5)

# 量化分析模式
model.quantize('asymu8', entropy=True, mle=True)

# 自定义输入/输出层量化类型（set_ioq）
model.quantize('asymu8', lid='input_0', in_out_quantized='dfpi16')
model.quantize('asymu8', lid='input_0,output_0', in_out_quantized='symi16')

quantize_hybrid()

quantize_hybrid(quantized, *, model_path=None, algorithm=1, iterations=1,
                entropy=False, hybrid_qtype='dfpi16', cust_qnt_layers=None)

对指定层应用混合精度量化。

参数：

  • quantized (str): 基础量化类型

  • model_path (str, 可选): 模型目录路径

  • algorithm (int, 可选): 量化算法，同 quantize()

  • iterations (int, 可选): 迭代次数，默认 1

  • entropy (bool, 可选): 是否计算张量熵，默认 False

  • hybrid_qtype (str, 可选): 混合层量化类型，默认 'dfpi16'

  • cust_qnt_layers (str, 可选): 自定义量化层配置文件路径

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

Conv_245
Conv_269
Conv_293

示例：

model.quantize_hybrid('asymu8', cust_qnt_layers='layers.txt')

导出

export()

export(quantized='float32', *, model_path=None, platform='pnna', 
       use_hybrid=False, preprocess=True, postprocess=True, core_num=None,
       set_name=None)

将量化后的模型导出为 PNNA 芯片可加载的 NBG 格式。

参数：

  • quantized (str, 可选): 量化类型，默认 'float32'

  • model_path (str, 可选): 模型目录路径

  • platform (str, 可选): 目标芯片平台，默认 'pnna'

    • 'pnna': 单核架构（默认平台）

    • 'pnna2': 多核架构（支持 1-4 核）

  • use_hybrid (bool, 可选): 是否使用混合量化，默认 False

  • preprocess (bool, 可选): 是否集成预处理到网络图，默认 True

    • 注意: symi16 量化类型不支持将预处理嵌入推理节点，导出时会抛出 ValueError

  • postprocess (bool, 可选): 是否集成后处理到网络图，默认 True

  • core_num (str, 可选): 多核配置（仅 pnna2 支持）

    • "1core" / "1": 单核

    • "2core" / "2": 双核

    • "3core" / "3": 三核

    • "4core" / "4": 四核

  • set_name (str, 可选): 自定义 NB 文件名，导出后将 network_binary.nb 复制为 {set_name}.nb

示例：

# 基础导出
model.export('asymu8')

# 嵌入前后处理节点
model.export('asymu8', preprocess=True, postprocess=True)

# FP16 也支持嵌入前后处理节点
model.export('fp16', preprocess=True, postprocess=True)

# 多核导出（仅 pnna2）
model.export('asymu8', platform='pnna2', core_num='4core')

# symi16 需要关闭预处理
model.export('symi16', preprocess=False)

# 自定义 NB 文件名
model.export('asymu8', set_name='my_model')

输出文件：

  • wksp/<model>_<quantized>_nbg_unify/network_binary.nb: NBG 文件

  • wksp/<model>_<quantized>_nbg_unify/nbg_meta.json: 元数据

前后处理节点嵌入

add_pre_post()

add_pre_post(quantized, *, model_path=None, preprocess=True,
             postprocess=True, use_hybrid=False)

嵌入预处理和后处理节点。

参数：

  • quantized (str): 量化类型

  • model_path (str, 可选): 模型目录路径

  • preprocess (bool, 可选): 是否嵌入预处理节点，默认 True

  • postprocess (bool, 可选): 是否嵌入后处理节点，默认 True

  • use_hybrid (bool, 可选): 是否使用混合量化文件，默认 False

示例：

model.add_pre_post('asymu8', preprocess=True, postprocess=True)

调试分析

dump()

dump(quantized='float32', *, model_path=None, use_hybrid=False, save_bin=False)

导出网络各层张量数据，用于量化效果分析。

参数：

  • quantized (str, 可选): 量化类型，默认 'float32'

  • model_path (str, 可选): 模型目录路径

  • use_hybrid (bool, 可选): 是否使用混合量化，默认 False

  • save_bin (bool, 可选): 是否额外保存二进制 .tensor.bin 文件，方便 C 语言端读取，默认 False

输出： dump/<model>_<quantized>/ 目录下的张量文件

二进制格式说明： .tensor.bin 文件结构为 magic(u32) + dtype(u32) + ndim(u32) + reserved(u32) + shape[u32; ndim] + raw_data，C 端可直接 fread 读取。

示例：

model.dump('asymu8', save_bin=True)

inference()

inference(quantized='float32', *, model_path=None, iterations=1,
          use_hybrid=False, save_bin=False)

运行模型推理并保存输入输出张量。

参数：

  • quantized (str, 可选): 量化类型，默认 'float32'

  • model_path (str, 可选): 模型目录路径

  • iterations (int, 可选): 推理迭代次数，默认 1

  • use_hybrid (bool, 可选): 是否使用混合量化，默认 False

  • save_bin (bool, 可选): 是否额外保存二进制 .tensor.bin 文件，默认 False

输出： wksp/<model>_<quantized>/golden/ 目录

measure()

measure(quantized='float32', *, model_path=None, use_hybrid=False) -> str

计算网络计算量（FLOPs、MACs 等），用于性能评估。

调用前必须先通过 load() 加载网络。统计非 float32 网络时，需要先完成相同类型的量化；Hybrid 网络还需同时传入 use_hybrid=True。

参数：

  • quantized (str, 可选): 量化类型，默认 'float32'

  • model_path (str, 可选): 模型目录路径

  • use_hybrid (bool, 可选): 是否使用混合量化，默认 False

返回： 相对于模型目录的输出目录路径

输出： 普通模式写入模型目录下的 wksp/<model>_<quantized>/，Hybrid 模式写入 wksp/<model>_<quantized>_hy/。统计文件的具体名称和字段以实际生成结果为准。

示例：

# 计算量化后网络的计算量
model.measure('asymu8')

# Hybrid 量化模式（需先完成相同类型的 quantize_hybrid）
model.measure('asymu8', use_hybrid=True)

check_opset()

check_opset(model_path, verbose=False)

检查 ONNX 模型的 opset 版本是否符合要求。

参数：

  • model_path (str): ONNX 模型文件路径或目录

  • verbose (bool, 可选): 是否显示详细信息，默认 False

返回： bool，是否符合要求

支持的 opset 版本： 7 - 17

示例：

is_valid = model.check_opset('./model.onnx')

参数速查

量化类型

详见 cookbook.md - 量化类型

量化算法

值

算法

说明

0

normal

普通量化

1

KL

KL散度（推荐）

2

moving_average

移动平均

3

auto

自动选择

预处理参数

详见 cookbook.md - 预处理参数

完整示例

更多示例请参考 cookbook.md。

相关文档