Netrans CLI
本手册提供 Netrans 命令行接口的完整规范，按子命令分节描述。
如需快速上手，请先阅读 quick-start.md。
子命令总览
子命令 |
一句话描述 |
|---|---|
load |
将模型载入工作区并写入预处理参数 |
quantize |
对网络执行静态量化 |
quantize_hybrid |
对指定层使用混合精度量化 |
add_pre_post |
将前后处理节点嵌入网络 |
export |
生成 PNNA 芯片可加载的 .nb 文件 |
dump |
导出各层激活张量用于调试 |
inference |
执行一次前向推理并保存输入输出 |
measure |
统计模型计算量与内存占用 |
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 级别日志 |
示例
1netrans load ./yolov8s --mean 0 0 0 --scale 1 1 1
对 YOLOv8s 模型载入并设定归一化参数。
运行结果
生成
<dir>/channel_mean_value.txt（若用户指定均值或缩放）生成
<dir>/<model>.json内部网络描述，供后续子命令读取
异常说明
若目录内存在多个候选模型文件，或扩展名不被识别，命令将终止并返回非零退出码，同时向标准错误输出具体原因。
3.2 netrans quantize
对载入后的网络执行静态量化，生成量化配置文件。
用法
1netrans quantize <dir> <qtype> [--algorithm <int>] [--iterations <int>] [--entropy] [--mle] [--pre] [--post] [--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 |
— |
最小化逐层误差 |
--pre |
可选 |
flag |
— |
将均值节点并入网络 |
--post |
可选 |
flag |
— |
将反量化节点并入网络 |
--verbose, -v |
可选 |
flag |
— |
输出 DEBUG 日志 |
示例
1netrans quantize . asymu8 --algorithm 1 --iterations 1 --pre --post
对当前目录模型执行非对称 8 位量化，采用 KL 算法一次迭代，并将前后处理并入网络。
运行结果
生成
<dir>/<model>_<qtype>.quantize量化配置若指定 --entropy，额外输出张量熵日志
若指定 --pre/--post，同步更新
.json
异常说明
若未先执行 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 |
— |
同 quantize |
示例
1netrans 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 |
— |
同前 |
示例
1netrans add_pre_post . asymu8
将前后处理节点嵌入当前量化网络。
运行结果
更新
<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> [--viv-sdk <path>] [--use-hybrid] [--verbose]
参数列表
参数 |
必要性 |
类型 |
描述 |
|---|---|---|---|
dir |
必选 |
路径 |
已完成量化及 add_pre_post 的目录 |
qtype |
必选 |
string |
量化类型 |
--platform |
必选 |
string |
芯片平台 {pnna, pnna2} |
选项 |
必要性 |
类型 |
默认值 |
描述 |
|---|---|---|---|---|
--viv-sdk |
可选 |
path |
— |
Vivante SDK 根目录（可选） |
--use-hybrid |
可选 |
flag |
— |
使用 hybrid 量化文件 |
--verbose, -v |
可选 |
flag |
— |
同前 |
示例
1netrans export . asymu8 --platform pnna
导出适用于 pnna 的 .nb 文件。
运行结果
生成
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 |
— |
同前 |
示例
1netrans 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 |
— |
同前 |
示例
1netrans inference . asymu8 --iterations 1
执行一次推理并保存输入输出。
运行结果
生成
wksp/<model>_<qtype>[_hy]/golden/input_*.tensor生成
wksp/<model>_<qtype>[_hy]/golden/output_*.tensor
异常说明
若输入数据缺失或张量形状不匹配，将报"Inference failed"并附出错层名。
异常说明
若网络描述文件缺失，将报"Measure failed"。
附录
A. 量化类型简表
符号 |
全称 |
说明 |
|---|---|---|
asymu8 |
asymmetric uint8 |
非对称 8 位无符号， 默认推荐 |
symi8 |
symmetric int8 |
对称 8 位有符号 |
symi16 |
symmetric int16 |
对称 16 位，精度优先 |
float32 |
— |
不量化，直接导出 FP32 |
B. layers.txt 文件格式
1# 层名列表（每行一个）
2Conv_0
3Conv_2
4
5# 或子图描述
6--inputs "input0#input1" --outputs "output0,output1"
作者：@xj xujiao@hngwg.com