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

Netrans CLI 参考手册

本手册提供 Netrans 命令行接口的完整规范，按子命令分节描述。
如需快速上手，请参考 cookbook.md 中的示例。

子命令总览

子命令

一句话描述

load

将模型载入工作区并写入预处理参数

quantize

对网络执行静态量化

quantize_hybrid

对指定层使用混合精度量化

add_pre_post

将前后处理节点嵌入网络

export

生成 PNNA 芯片可加载的 .nb 文件

dump

导出各层激活张量用于调试

inference

执行一次前向推理并保存输入输出

measure

统计模型计算量与内存占用

check_opset

检查 ONNX 模型 opset 版本

help

显示帮助文本

version

显示版本号

子命令详细规范

3.1 netrans load

将指定目录中的模型文件载入工作区，并可同时写入通道均值/缩放参数。

用法

1netrans load <dir> [--mean <f32>[,<f32>[,<f32>]]] [--scale <f32>[,<f32>[,<f32>]]] [--verbose]

参数列表

参数

必要性

类型

描述

dir

必选

文件系统路径

必须包含唯一模型主文件（*.onnx, *.prototxt, *.cfg 等）

选项

必要性

类型

默认值

描述

--mean

可选

float 或 float×3

0.0

通道均值；长度必须与模型输入通道数一致

--scale

可选

float 或 float×3

1.0

通道缩放；单值可广播，长度需与--mean匹配

--verbose, -v

可选

flag

—

输出 DEBUG 级别日志

示例

1# 三通道RGB模型（如YOLOv8s）
2$ netrans load ./yolov8s --mean 0 0 0 --scale 255
3
4# 单通道灰度模型
5$ netrans load ./lenet_gray --mean 127.5 --scale 255

对模型载入并设定预处理参数。--scale 支持单值广播，--mean 长度必须与输入通道数一致。

运行结果

  • 生成 <dir>/channel_mean_value.txt（若用户指定均值或缩放）

  • 生成 <dir>/<model>.json 内部网络描述，供后续子命令读取

异常说明

若目录内存在多个候选模型文件，或扩展名不被识别，命令将终止并返回非零退出码，同时向标准错误输出具体原因。

3.2 netrans quantize

对载入后的网络执行静态量化，生成量化配置文件。

用法

1netrans quantize <dir> <qtype> [--algorithm <int>] [--iterations <int>] [--entropy] [--mle] [--verbose]

参数列表

参数

必要性

类型

描述

dir

必选

路径

已载入模型的目录

qtype

必选

string

量化类型 {asymu8, symi8, symi16}

选项

必要性

类型

默认值

描述

--algorithm

可选

int

1

0=normal, 1=KL, 2=moving_avg, 3=auto

--iterations

可选

int

1

校准迭代次数 ≥1

--entropy

可选

flag

—

计算张量信息熵

--mle

可选

flag

—

最小化逐层误差

--verbose, -v

可选

flag

—

同前

示例

1$ netrans quantize . asymu8 --algorithm 1 --iterations 1

对当前目录模型执行非对称 8 位量化，采用 KL 算法一次迭代。

运行结果

  • 生成 <dir>/<model>_<qtype>.quantize 量化配置

  • 若指定 --entropy，额外输出张量熵日志

异常说明

若未先执行 load，或量化文件已存在且被覆盖保护，将报"无法创建量化配置"错误。

3.3 netrans quantize_hybrid

对指定层列表使用混合精度量化，其余层沿用基准量化类型。

用法

1netrans quantize_hybrid <dir> <qtype> --cust-qnt-layers <file> [--hybrid-qtype <htype>] [--algorithm <int>] [--iterations <int>] [--entropy] [--verbose]

参数列表

参数

必要性

类型

描述

dir

必选

路径

已载入模型的目录

qtype

必选

string

基准量化类型 {asymu8, symi8, symi16}

--cust-qnt-layers

必选

file

每行一个层名或子图描述文件

选项

必要性

类型

默认值

描述

--hybrid-qtype

可选

string

dfpi16

混合层量化类型 {dfpi16, float32}

--algorithm

可选

int

1

同 quantize

--iterations

可选

int

1

同 quantize

--entropy

可选

flag

—

同 quantize

--verbose, -v

可选

flag

—

同前

示例

1$ netrans quantize_hybrid . asymu8 --cust-qnt-layers layers.txt --hybrid-qtype dfpi16

对 layers.txt 所列层使用 dfpi16，其余层使用 asymu8 量化。

运行结果

  • 生成 <dir>/<model>_<qtype>_hy.quantize 混合量化配置

  • 生成 <dir>/hybrid_quant_params.json（层映射表）

异常说明

若 layers.txt 不存在或格式错误，将报"Custom quantization layers file not found"或"Parse error"。

3.4 netrans add_pre_post

将均值（预处理）与反量化（后处理）节点嵌入网络，生成统一计算图。

用法

1netrans add_pre_post <dir> <qtype> [--preprocess] [--postprocess] [--use-hybrid] [--verbose]

参数列表

参数

必要性

类型

描述

dir

必选

路径

已量化模型目录

qtype

必选

string

量化类型

选项

必要性

类型

默认值

描述

--preprocess

可选

flag

True

将均值节点并入网络

--postprocess

可选

flag

True

将反量化节点并入网络

--use-hybrid

可选

flag

—

读取 *_hy.quantize 文件

--verbose, -v

可选

flag

—

同前

示例

1$ netrans add_pre_post . asymu8 --preprocess --postprocess

将前后处理节点嵌入当前量化网络。

运行结果

  • 更新 <dir>/<model>_<qtype>.json（节点增加）

  • 若 --use-hybrid，则读取 hybrid 量化文件

异常说明

若未先执行量化，或量化文件与 --use-hybrid 不匹配，将报"Quantize file not found"。

3.5 netrans export

生成 PNNA 芯片可加载的 .nb 网络二进制文件。

用法

1netrans export <dir> <qtype> --platform <plat> [--use-hybrid] [--preprocess <bool>] [--postprocess <bool>] [--core-num <n>] [--verbose]

参数列表

参数

必要性

类型

描述

dir

必选

路径

已完成量化及 add_pre_post 的目录

qtype

必选

string

量化类型

--platform

必选

string

芯片平台 {pnna, pnna2}

选项

必要性

类型

默认值

描述

--use-hybrid

可选

flag

—

使用 hybrid 量化文件

--preprocess

可选

bool

True

将前处理做进推理网络计算图

--postprocess

可选

bool

True

将后处理做进推理网络计算图

--core-num

可选

string

None

多核配置: 1core, 2core, 3core, 4core 或简写 1, 2, 3, 4（仅 pnna2 平台支持）

--verbose, -v

可选

flag

—

同前

示例

1$ netrans export . asymu8 --platform pnna

导出适用于 pnna 的 .nb 文件。

1$ netrans export . asymu8 --platform pnna2 --core-num 4core

导出 4 核模式的 NBG 文件。

运行结果

  • 生成 wksp/<model>_<qtype>[_hy]_nbg_unify/network_binary.nb

  • 生成 network_binary.desc（文本描述，调试用）

异常说明

若平台代号错误，或 NBG 编译器返回非零，将报"Export failed"并附详细日志。

3.6 netrans dump

导出网络各层激活张量，用于精度比对与调试。

用法

1netrans dump <dir> <qtype> [--use-hybrid] [--verbose]

参数列表

参数

必要性

类型

描述

dir

必选

路径

已量化模型目录

qtype

必选

string

量化类型

选项

必要性

类型

默认值

描述

--use-hybrid

可选

flag

—

使用 hybrid 量化文件

--verbose, -v

可选

flag

—

同前

示例

1$ netrans dump . asymu8

导出 asymu8 量化后各层张量。

运行结果

  • 生成 dump/<model>_<qtype>[_hy]/*.tensor（每层一个文件）

异常说明

若量化文件缺失，或输出目录不可写，将报"Dump failed"。

3.7 netrans inference

执行一次前向推理，并将输入/输出张量保存至 golden 目录。

用法

1netrans inference <dir> <qtype> [--iterations <int>] [--use-hybrid] [--verbose]

参数列表

参数

必要性

类型

描述

dir

必选

路径

已量化模型目录

qtype

必选

string

量化类型

选项

必要性

类型

默认值

描述

--iterations

可选

int

1

推理迭代次数 ≥1

--use-hybrid

可选

flag

—

使用 hybrid 量化文件

--verbose, -v

可选

flag

—

同前

示例

1$ netrans inference . asymu8 --iterations 1

执行一次推理并保存输入输出。

运行结果

  • 生成 wksp/<model>_<qtype>[_hy]/golden/input_*.tensor

  • 生成 wksp/<model>_<qtype>[_hy]/golden/output_*.tensor

异常说明

若输入数据缺失或张量形状不匹配，将报"Inference failed"并附出错层名。

3.8 netrans check_opset

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

用法

1netrans check_opset <path> [--verbose]

参数列表

参数

必要性

类型

描述

path

必选

路径

ONNX 模型文件路径或包含 .onnx 文件的目录

选项

必要性

类型

默认值

描述

--verbose, -v

可选

flag

—

显示详细信息

示例

1# 检查单个 ONNX 文件
2$ netrans check_opset ./yolov5s.onnx
3
4# 检查目录（自动查找 .onnx 文件）
5$ netrans check_opset ./yolov5s/

输出示例

符合要求的模型：

============================================================
ONNX 模型 Opset 版本检查
============================================================
模型路径: ./yolov5s.onnx

Opset 版本: 11 (ONNX 1.6)
IR 版本: 6
Producer: pytorch 1.9

状态: ✅ opset 版本 11 符合要求
============================================================

不符合要求的模型（opset 过高）：

============================================================
ONNX 模型 Opset 版本检查
============================================================
模型路径: ./model_v19.onnx

Opset 版本: 19 (ONNX 1.14)
IR 版本: 9
Producer: pytorch 2.0

状态: ❌ opset 版本过高（19），Netrans 最高支持 opset 17
  当前模型使用 ONNX 1.14，建议转换为 ONNX 1.12（opset 17）

建议操作:
  1. 使用以下命令转换模型:
     python -c "import onnx; from onnx import version_converter; 
     onnx.save(version_converter.convert_version(onnx.load('./model_v19.onnx'), 17), './model_v19.onnx.converted.onnx')"
  2. 或者重新导出模型时指定 opset_version=17
     例如: torch.onnx.export(..., opset_version=17)
============================================================

退出码

退出码

含义

0

opset 版本符合要求

1

opset 版本不符合要求或检查失败

支持的 opset 版本

Netrans 支持 ONNX opset 版本范围：7 - 17

Opset 版本

ONNX 版本

支持状态

7-17

1.2-1.12

✅ 支持

18+

1.13+

❌ 不支持

附录

A. 平台代号对照

代号

芯片型号

多核支持

备注

pnna

VIP8000NANOQI_PLUS_PID0XB1

❌ 不支持

默认目标，单核架构

pnna2

VIP9400O_PID0X1000004F

✅ 支持 1-4 核

需 SDK ≥ 6.4.0，多核架构需 viv-sdk

B. 量化类型简表

符号

全称

说明

asymu8

asymmetric uint8

非对称 8 位无符号，默认推荐

symi8

symmetric int8

对称 8 位有符号

symi16

symmetric int16

对称 16 位，精度优先

C. layers.txt 文件格式

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

# 或子图描述
--inputs "input0#input1" --outputs "output0,output1"

参见