364 lines
9.3 KiB
Markdown
364 lines
9.3 KiB
Markdown
# Netrans CLI 参考手册
|
||
|
||
本手册提供 Netrans 命令行接口的完整规范。
|
||
|
||
## 命令总览
|
||
|
||
```
|
||
netrans load → quantize → export
|
||
```
|
||
|
||
| 子命令 | 用途 |
|
||
|--------|------|
|
||
| load | 加载模型并配置预处理参数 |
|
||
| quantize | 对模型进行量化 |
|
||
| quantize_hybrid | 混合精度量化 |
|
||
| add_pre_post | 嵌入前后处理节点 |
|
||
| export | 导出 NBG 文件 |
|
||
| dump | 导出各层张量用于调试 |
|
||
| inference | 执行推理并保存输入输出 |
|
||
| measure | 统计模型计算量（FLOPs）和参数量 |
|
||
| check_opset | 检查 ONNX 模型 opset 版本 |
|
||
|
||
---
|
||
|
||
## 快速参考
|
||
|
||
### 命令速查
|
||
|
||
| 命令 | 示例 |
|
||
|------|------|
|
||
| load | `netrans load ./model --mean 0 0 0 --std 255` |
|
||
| quantize | `netrans quantize ./model asymu8 --algorithm 1` |
|
||
| export | `netrans export ./model asymu8 --platform pnna` |
|
||
| dump | `netrans dump ./model asymu8` |
|
||
| inference | `netrans inference ./model asymu8 --iterations 1` |
|
||
| measure | `netrans measure ./model asymu8` |
|
||
|
||
### 参数速查
|
||
|
||
#### 量化类型
|
||
- `asymu8`: 非对称8位（默认）
|
||
- `symi8`: 对称8位
|
||
- `symi16`: 对称16位
|
||
- `fp16`: 半精度浮点
|
||
|
||
**注意事项**：
|
||
- **FP16**: v6.33.4+ 支持嵌入前后处理节点
|
||
- **symi16**: 不支持预处理嵌入，需设置 `--preprocess False` 或改用 `dfpi16`
|
||
|
||
#### 量化算法
|
||
- `0` / `normal`: 普通量化
|
||
- `1` / `KL`: KL散度（默认）
|
||
- `2` / `moving_average`: 移动平均
|
||
- `3` / `auto`: 自动选择
|
||
|
||
#### 平台
|
||
- `pnna`: 单核架构
|
||
- `pnna2`: 多核架构（支持 1-4 核）
|
||
|
||
#### 多核配置（仅 pnna2）
|
||
- `1core` / `1`: 单核
|
||
- `2core` / `2`: 双核
|
||
- `3core` / `3`: 三核
|
||
- `4core` / `4`: 四核
|
||
|
||
---
|
||
|
||
## 命令详解
|
||
|
||
### netrans load
|
||
|
||
加载模型并配置预处理参数。
|
||
|
||
**用法：**
|
||
```bash
|
||
netrans load <dir> [--mean <values>] [--std <values>] [--verbose]
|
||
```
|
||
|
||
**参数：**
|
||
- `dir` (必选): 模型目录路径
|
||
- `--mean` (可选): 通道均值，如 `"0 0 0"`
|
||
- `--std` (可选): 通道标准差（归一化除数），如 `255`
|
||
- `--verbose, -v` (可选): 输出 DEBUG 日志
|
||
|
||
**示例：**
|
||
```bash
|
||
# 三通道模型
|
||
netrans load ./yolov5s --mean "0 0 0" --std "255"
|
||
|
||
# 单通道模型
|
||
netrans load ./lenet_gray --mean "127.5" --std "255"
|
||
```
|
||
|
||
**模型文件查找优先级：**
|
||
|
||
目录中可能存在多种文件时，按以下固定优先级识别（`get_modelfile_name`）：
|
||
|
||
1. `.json` / `.data` — 已生成的模型产物（优先级最高）
|
||
2. `.onnx` > `.pb` (TF) > `.prototxt` (Caffe) > `.tflite` > `.pt` (PyTorch) > `.h5` (Keras) > `.cfg` (Darknet)
|
||
|
||
文件名含 `quantize` 的文件会被忽略。v6.33.5 起改为确定性优先级，不再依赖文件系统排序。
|
||
|
||
**输出：**
|
||
- `channel_mean_value.txt`: 预处理参数文件
|
||
- `<model>.json`: 网络结构描述
|
||
- `<model>.data`: 权重数据
|
||
|
||
---
|
||
|
||
### netrans quantize
|
||
|
||
对模型进行量化。
|
||
|
||
**用法：**
|
||
```bash
|
||
netrans quantize <dir> <qtype> [--algorithm <int>] [--iterations <int>]
|
||
[--entropy] [--mle] [--verbose]
|
||
```
|
||
|
||
**参数：**
|
||
- `dir` (必选): 已加载模型的目录
|
||
- `qtype` (必选): 量化类型，如 `asymu8`
|
||
- `--algorithm` (可选): 量化算法，0/1/2/3，默认 1
|
||
- `--iterations` (可选): 迭代次数，默认 1
|
||
- `--entropy` (可选): 计算张量熵（分析用）
|
||
- `--mle` (可选): 最小化层间误差（分析用）
|
||
- `--verbose, -v` (可选): 输出 DEBUG 日志
|
||
|
||
**示例：**
|
||
```bash
|
||
# 基础量化
|
||
netrans quantize ./model asymu8
|
||
|
||
# 高精度量化
|
||
netrans quantize ./model asymu8 --algorithm 1 --iterations 5
|
||
|
||
# 量化分析
|
||
netrans quantize ./model asymu8 --entropy --mle
|
||
|
||
```
|
||
|
||
**输出：**
|
||
- `<model>_<qtype>.quantize`: 量化参数文件
|
||
|
||
---
|
||
|
||
### netrans quantize_hybrid
|
||
|
||
混合精度量化。
|
||
|
||
**用法：**
|
||
```bash
|
||
netrans quantize_hybrid <dir> <qtype> --cust-qnt-layers <file>
|
||
[--hybrid-qtype <type>] [--algorithm <int>]
|
||
[--iterations <int>] [--verbose]
|
||
```
|
||
|
||
**参数：**
|
||
- `dir` (必选): 已加载模型的目录
|
||
- `qtype` (必选): 基础量化类型
|
||
- `--cust-qnt-layers` (必选): 层配置文件路径
|
||
- `--hybrid-qtype` (可选): 混合层量化类型，默认 `dfpi16`
|
||
- `--algorithm` (可选): 量化算法，默认 1
|
||
- `--iterations` (可选): 迭代次数，默认 1
|
||
- `--verbose, -v` (可选): 输出 DEBUG 日志
|
||
|
||
**示例：**
|
||
```bash
|
||
netrans quantize_hybrid ./model asymu8 --cust-qnt-layers layers.txt
|
||
```
|
||
|
||
---
|
||
|
||
### netrans add_pre_post
|
||
|
||
嵌入前后处理节点。
|
||
|
||
**用法：**
|
||
```bash
|
||
netrans add_pre_post <dir> <qtype> [--preprocess] [--postprocess]
|
||
[--use-hybrid] [--verbose]
|
||
```
|
||
|
||
**参数：**
|
||
- `dir` (必选): 已量化模型目录
|
||
- `qtype` (必选): 量化类型
|
||
- `--preprocess` (可选): 嵌入预处理节点（默认启用）。传入即启用，与 API `preprocess=True` 一致
|
||
- `--postprocess` (可选): 嵌入后处理节点（默认启用）。传入即启用，与 API `postprocess=True` 一致
|
||
- `--use-hybrid` (可选): 使用混合量化文件
|
||
- `--verbose, -v` (可选): 输出 DEBUG 日志
|
||
|
||
**示例：**
|
||
```bash
|
||
# 默认同时嵌入前后处理节点（无需传参）
|
||
netrans add_pre_post ./model asymu8
|
||
```
|
||
|
||
---
|
||
|
||
### netrans export
|
||
|
||
导出 NBG 文件。
|
||
|
||
**用法：**
|
||
```bash
|
||
netrans export <dir> <qtype> [--platform <plat>] [--use-hybrid]
|
||
[--preprocess <bool>] [--postprocess <bool>]
|
||
[--core-num <n>] [--set-name <name>] [--verbose]
|
||
```
|
||
|
||
**参数：**
|
||
- `dir` (必选): 已量化模型目录
|
||
- `qtype` (必选): 量化类型
|
||
- `--platform` (可选): 平台，`pnna` 或 `pnna2`，默认 `pnna`
|
||
- `--use-hybrid` (可选): 使用混合量化文件
|
||
- `--preprocess` (可选): 嵌入预处理，默认 `true`
|
||
- `--postprocess` (可选): 嵌入后处理，默认 `true`
|
||
- `--core-num` (可选): 多核配置，`1core`/`2core`/`4core`（仅 pnna2）
|
||
- `--set-name` (可选): 自定义 NB 文件名，导出后将 `network_binary.nb` 复制为 `{name}.nb`
|
||
- `--verbose, -v` (可选): 输出 DEBUG 日志
|
||
|
||
**示例：**
|
||
```bash
|
||
# 基础导出
|
||
netrans export ./model asymu8 --platform pnna
|
||
|
||
# 多核导出（仅 pnna2）
|
||
netrans export ./model asymu8 --platform pnna2 --core-num 4core
|
||
|
||
# 自定义 NB 文件名
|
||
netrans export ./model asymu8 --platform pnna --set-name my_model
|
||
```
|
||
|
||
**输出：**
|
||
- `wksp/<model>_<qtype>_nbg_unify/network_binary.nb`: NBG 文件
|
||
- `wksp/<model>_<qtype>_nbg_unify/nbg_meta.json`: 元数据
|
||
|
||
---
|
||
|
||
### netrans dump
|
||
|
||
导出各层张量用于调试。
|
||
|
||
**用法：**
|
||
```bash
|
||
netrans dump <dir> <qtype> [--use-hybrid] [--save-bin] [--verbose]
|
||
```
|
||
|
||
**参数：**
|
||
- `dir` (必选): 已量化模型目录
|
||
- `qtype` (必选): 量化类型
|
||
- `--use-hybrid` (可选): 使用混合量化文件
|
||
- `--save-bin` (可选): 额外保存二进制 `.tensor.bin` 文件，方便 C 语言端读取
|
||
- `--verbose, -v` (可选): 输出 DEBUG 日志
|
||
|
||
**示例：**
|
||
```bash
|
||
netrans dump ./model asymu8
|
||
netrans dump ./model asymu8 --save-bin
|
||
```
|
||
|
||
**输出：** `dump/<model>_<qtype>/` 目录
|
||
|
||
---
|
||
|
||
### netrans inference
|
||
|
||
执行推理并保存输入输出。
|
||
|
||
**用法：**
|
||
```bash
|
||
netrans inference <dir> <qtype> [--iterations <int>] [--use-hybrid]
|
||
[--save-bin] [--verbose]
|
||
```
|
||
|
||
**参数：**
|
||
- `dir` (必选): 已量化模型目录
|
||
- `qtype` (必选): 量化类型
|
||
- `--iterations` (可选): 迭代次数，默认 1
|
||
- `--use-hybrid` (可选): 使用混合量化文件
|
||
- `--save-bin` (可选): 额外保存二进制 `.tensor.bin` 文件，方便 C 语言端读取
|
||
- `--verbose, -v` (可选): 输出 DEBUG 日志
|
||
|
||
**示例：**
|
||
```bash
|
||
netrans inference ./model asymu8 --iterations 1
|
||
```
|
||
|
||
**输出：** `wksp/<model>_<qtype>/golden/` 目录
|
||
|
||
---
|
||
|
||
### netrans measure
|
||
|
||
计算网络计算量（FLOPs、MACs 等）。
|
||
|
||
**用法：**
|
||
```bash
|
||
netrans measure <dir> [qtype] [--use-hybrid] [--verbose]
|
||
```
|
||
|
||
**参数：**
|
||
- `dir` (必选): 已执行 `netrans load` 的模型目录
|
||
- `qtype` (可选): 量化类型，默认 `float32`；统计量化模型时必须与已有 `.quantize` 文件的类型一致
|
||
- `--use-hybrid` (可选): 使用 `<model>_<qtype>_hy.quantize` 和对应的 Hybrid 模型文件
|
||
- `--verbose, -v` (可选): 输出 DEBUG 日志
|
||
|
||
**前置产物：**
|
||
|
||
- 所有模式均需要 `<model>.json`、`<model>.data` 和 `<model>_inputmeta.yml`
|
||
- 非 `float32` 模式还需要先执行 `netrans quantize <dir> <qtype>`
|
||
- Hybrid 模式需要先执行 `netrans quantize_hybrid`，并传入 `--use-hybrid`
|
||
|
||
**示例：**
|
||
```bash
|
||
# qtype 省略时统计 float32 网络
|
||
netrans measure ./model
|
||
|
||
netrans measure ./model asymu8
|
||
netrans measure ./model asymu8 --use-hybrid
|
||
|
||
# 安装后也可使用等价入口
|
||
netrans-measure ./model asymu8
|
||
```
|
||
|
||
**输出：** 模型目录下的 `wksp/<model>_<qtype>/`；Hybrid 模式输出到 `wksp/<model>_<qtype>_hy/`。统计文件的具体名称和字段以实际生成结果为准。
|
||
|
||
完整可运行流程见 [measure 示例](../examples/measure/README.md)。
|
||
|
||
---
|
||
|
||
### netrans check_opset
|
||
|
||
检查 ONNX 模型 opset 版本。
|
||
|
||
**用法：**
|
||
```bash
|
||
netrans check_opset <path> [--verbose]
|
||
```
|
||
|
||
**参数：**
|
||
- `path` (必选): ONNX 文件路径或目录
|
||
- `--verbose, -v` (可选): 显示详细信息
|
||
|
||
**示例：**
|
||
```bash
|
||
netrans check_opset ./model.onnx
|
||
netrans check_opset ./model_dir/
|
||
```
|
||
|
||
**支持的 opset 版本：** 7 - 17
|
||
|
||
**退出码：**
|
||
- 0: 符合要求
|
||
- 1: 不符合或检查失败
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- [cookbook.md](cookbook.md) - 实用指南、速查表、场景示例、故障排查
|
||
- [netrans_api.md](netrans_api.md) - Python API 参考
|
||
- [release.md](release.md) - 版本发布记录
|