netrans/docs/cli-reference.md

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

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

用法

netrans 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 级别日志

示例

$ netrans load ./yolov8s --mean 0 0 0 --scale 1 1 1

对 YOLOv8s 模型载入并设定三通道均值为 0、缩放为 1。

运行结果

• 生成 <dir>/channel_mean_value.txt（若用户指定均值或缩放）
• 生成 <dir>/<model>.json 内部网络描述，供后续子命令读取

异常说明

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

3.2 netrans quantize

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

用法

netrans 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 | — | 输出 DEBUG 日志 |

示例

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

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

运行结果

• 生成 <dir>/<model>_<qtype>.quantize 量化配置
• 若指定 --entropy，额外输出张量熵日志

异常说明

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

3.3 netrans quantize_hybrid

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

用法

netrans 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

示例

$ 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

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

用法

netrans 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	—	同前

示例

$ 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 网络二进制文件。

用法

netrans export <dir> <qtype> --platform <plat> [--viv-sdk <path>] [--use-hybrid] [--preprocess] [--postprocess] [--verbose]

参数列表

参数	必要性	类型	描述
dir	必选	路径	已完成量化及 add_pre_post 的目录
qtype	必选	string	量化类型
--platform	必选	string	芯片平台 {pnna, pnna2}

选项	必要性	类型	默认值	描述
--viv-sdk	可选	path	—	Vivante SDK 根目录（可选）
--use-hybrid	可选	flag	—	使用 hybrid 量化文件
--preprocess	可选	bool	True	将均值节点并入网络 (默认 True，可传 False 禁用)
--postprocess	可选	bool	True	将反量化节点并入网络 (默认 True，可传 False 禁用)
--core-num	可选	string	—	多核配置: 1core, 2core, 3core, 4core 或简写 1, 2, 3, 4
--verbose, -v	可选	flag	—	同前

示例

$ netrans export . asymu8 --platform pnna

导出适用于 VIP8000NANOQI_PLUS_PID0XB1 的 .nb 文件，默认将前后处理并入网络。

$ netrans export . asymu8 --platform pnna --core-num 4core

使用4核配置导出模型。

$ netrans export . asymu8 --platform pnna --preprocess False --postprocess False

导出模型，不将前后处理并入网络（显式传 False 禁用）。

运行结果

• 生成 wksp/<model>_<qtype>[_hy]_nbg_unify/network_binary.nb
• 生成 network_binary.desc（文本描述，调试用）

多核配置说明

通过 --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	0	(unset)	四核模式，使用默认配置

异常说明

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

3.6 netrans dump

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

用法

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

参数列表

参数	必要性	类型	描述
dir	必选	路径	已量化模型目录
qtype	必选	string	量化类型

选项	必要性	类型	默认值	描述
--use-hybrid	可选	flag	—	使用 hybrid 量化文件
--verbose, -v	可选	flag	—	同前

示例

$ netrans dump . asymu8

导出 asymu8 量化后各层张量。

运行结果

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

异常说明

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

3.7 netrans inference

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

用法

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

参数列表

参数	必要性	类型	描述
dir	必选	路径	已量化模型目录
qtype	必选	string	量化类型

选项	必要性	类型	默认值	描述
--iterations	可选	int	1	推理迭代次数 ≥1
--use-hybrid	可选	flag	—	使用 hybrid 量化文件
--verbose, -v	可选	flag	—	同前

示例

$ netrans inference . asymu8 --iterations 1

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

运行结果

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

异常说明

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

异常说明

若网络描述文件缺失，将报“Measure failed”。

附录

A. 平台代号对照

代号	芯片型号	备注
pnna	VIP8000NANOQI_PLUS_PID0XB1	默认目标
pnna2	VIP9400O_PID0X1000004F	需 SDK ≥ 6.4.0

B. 量化类型简表

符号	全称	说明
asymu8	asymmetric uint8	非对称 8 位无符号，默认推荐
symi8	symmetric int8	对称 8 位有符号
symi16	symmetric int16	对称 16 位，精度优先
float32	—	不量化，直接导出 FP32

C. layers.txt 文件格式

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

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

参见

• quick-start.md —— 三分钟跑通流程
• api-reference.md —— Python 接口规范
• cookbook.md —— 场景脚本合集