nudt_dsp
/
netrans
0
0
Fork 3
Code Issues Pull Requests Packages Projects Releases Wiki Activity

del cache

This commit is contained in:
xujiao 2026-04-23 12:58:35 +08:00
parent 2245509b46
commit 175b1850bc
22 changed files with 0 additions and 6105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/Vivante.Programming.ACUITY.Toolkit.User.Guide-v6.33.x-B-20240625.pdf
View File

Binary file not shown.

123
docs/acuity_quantization_types.md
View File

@ -1,123 +0,0 @@
# Acuity 数据类型与量化算法参考
本文档汇总了 Acuity 量化框架支持的数据类型和量化算法。
---
## 📊 数据类型（Quantizer Types）
### 1. 标准量化类型（激活和权重使用相同类型）
| 类型 | 量化器 | 数据类型 | 说明 |
|------|--------|----------|------|
| `asymu8` | asymmetric_affine | uint8 | 非对称无符号8位（最常用） |
| `asymi8` | asymmetric_affine | int8 | 非对称有符号8位 |
| `symi8` | symmetric_affine | int8 | 对称有符号8位 |
| `pcqi8` | perchannel_symmetric_affine | int8 | 逐通道对称8位 |
| `symi16` | symmetric_affine | int16 | 对称有符号16位 |
| `dfpi16` | dynamic_fixed_point | int16 | 动态定点16位 |
| `fp16` | float16 | float16 | 半精度浮点 |
| `qbfp16` | qbfloat16 | qbfloat16 | 量化BFloat16 |
| `asymi4` | asymmetric_affine | int4 | 非对称4位 |
| `symi4` | symmetric_affine | int4 | 对称4位 |
| `pcqi4` | perchannel_symmetric_affine | int4 | 逐通道对称4位 |
| `asymu4` | asymmetric_affine | uint4 | 非对称无符号4位 |
| `e5m2pcqf8` | perchannel_float8 | e5m2 | 逐通道Float8 (E5M2) |
| `e4m3pcqf8` | perchannel_float8 | e4m3 | 逐通道Float8 (E4M3) |
| `e5m2fp8` | float8 | e5m2 | Float8 (E5M2) |
| `e4m3fp8` | float8 | e4m3 | Float8 (E4M3) |
### 2. 混合量化类型（激活和权重使用不同类型）
| 类型 | 激活 | 权重 | 说明 |
|------|------|------|------|
| `Ai8Wpcqi4` | symi8 | pcqi4 | 激活8位，权重逐通道4位 |
| `Ai16Wi8` | symi16 | symi8 | 激活16位，权重8位 |
| `Ai16Wi4` | symi16 | symi4 | 激活16位，权重4位 |
| `Ai16Wpcqi8` | symi16 | pcqi8 | 激活16位，权重逐通道8位 |
| `Ai16Wpcqi4` | symi16 | pcqi4 | 激活16位，权重逐通道4位 |
| `Afp16Wi4` | float16 | symi4 | 激活FP16，权重4位 |
| `Afp16Wpgqi4` | float16 | pgqi4 | 激活FP16，权重逐组4位 |
| `Adfpi16Wpcqi8` | dfpi16 | pcqi8 | 激活DFP16，权重逐通道8位 |
| `Adfpi16Wpcqi4` | dfpi16 | pcqi4 | 激活DFP16，权重逐通道4位 |
---
## 🔧 量化算法
```python
algorithms = ["normal", "kl_divergence", "moving_average", "auto"]
```
| 索引 | 算法 | 说明 |
|------|------|------|
| 0 | `normal` | 标准量化（默认） |
| 1 | `kl_divergence` | KL散度算法（KL） |
| 2 | `moving_average` | 移动平均 |
| 3 | `auto` | 自动选择 |
**特殊说明**：
- Float8 类型（`e5m2pcqf8`, `e4m3pcqf8`, `e5m2fp8`, `e4m3fp8`）强制使用 `normal` 算法
- 可通过 `algorithm` 参数指定（0-3）
- 可通过 `iterations` 参数指定迭代次数
---
## ⚙️ 高级参数
| 参数 | 类型 | 说明 |
|------|------|------|
| `entropy` | bool | 计算每层张量的熵 |
| `mle` | bool | 最小化逐层误差（Minimize Layer Error） |
---
## 💡 使用示例
### Python API
```python
from netrans import Netrans
model = Netrans()
model.load('./yolov5s', mean=[0,0,0], scale=255)
# 标准量化 - 默认 normal 算法
model.quantize('asymu8')
# KL 散度算法
model.quantize('asymu8', algorithm=1)
# KL 散度 + 3次迭代 + 熵计算 + 最小化层误差
model.quantize('asymu8', algorithm=1, iterations=3, entropy=True, mle=True)
# 混合量化
model.quantize_hybrid('asymu8', cust_qnt_layers='layers.txt')
# FP16 量化（支持前后处理）
model.export('fp16', platform='pnna', preprocess=True, postprocess=True)
```
### CLI
```bash
# 标准量化
netrans quantize ./yolov5s asymu8
# 指定算法和迭代次数
netrans quantize ./yolov5s asymu8 --algorithm 1 --iterations 3
# 启用熵计算和最小化层误差
netrans quantize ./yolov5s asymu8 --entropy --mle
# 混合量化
netrans quantize_hybrid ./yolov5s asymu8 --cust_qnt_layers layers.txt
```
---
## 📁 相关文件
- `src/netrans/quantize_types.py` - 数据类型定义
- `src/netrans/quantize.py` - 量化实现
- `src/netrans/quantize_hybrid.py` - 混合量化实现

165
docs/acuity_readme.md
View File

@ -1,165 +0,0 @@
Requirement: Acuity 6.22.0 and above, whl package was installed
User guide of the python script as below:
Please copy all python scripts to a same floder that is at the same level as the floder containing the model berore using scripts.
The model floder uses the same name as the model, such as:
```
lenet/
├── channel_mean_value.txt
├── dataset.txt
├── hw_config.txt
├── input_image
│   ├── 0.jpg
│   ├── 1.jpg
│   ├── 2.jpg
│   ├── 3.jpg
│   ├── 4.jpg
│   ├── 5.jpg
│   ├── 6.jpg
│   ├── 7.jpg
│   ├── 8.jpg
│   └── 9.jpg
├── lenet.caffemodel
└── lenet.prototxt
```
## Introduction for each script
### test_demo.py
Include entire acuity flow
The arguments sre as follows:
model: Model directory, type: str,
--quantized: Quantization type, type: str, default: 'asymu8'
--algorithm: Quantization algotithm, The corresponding relationship between numbers and algorithms is as follows:[0: normal, 1:kl_divergence, 2:moving_average, 3:auto],
type: int, default: 1, choices=[0, 1, 2, 3]
--iterations: Running iterations, type: int, default: 1
--batch_size: Batch size, type: int, default: 0
--entropy: Compute tensor entropy, action: store_true
--mle: Minimize per layer error, action: store_true
--save: Save the intermediate file, action: store_true
eg:
python3 test_demo.py lenet/ --save
### importer.py:
Import the model.
The arguments sre as follows:
model: Model directory. type: str
### quantize_types.py
The quantize type supported by scripts.
[asymi4, symi4, pcqsymi4, asymu4, asymi8, symi8, pcqsymi8, asymu8, e5m2pcqf8, symi16, dfpi16, fp16, qbfp16,
Afp16Wi4, Ai8Wpcqi4, Ai16Wi8,Ai16Wi4, Ai16Wpcqi8, Ai16Wpcqi4, Adfpi16Wpcqi4, Au16Wi8, Au16Wpcqi8, Afp16Wpcqi8,
Afp16Wpcqi4]
### quantize.py:
Quantize the model.
The arguments sre as follows:
model: Model directory, type: str
quantized: Quantization type, type: str
--algorithm: Quantization algotithm, The corresponding relationship between numbers and algorithms is as follows:[0: normal, 1:kl_divergence, 2:moving_average, 3:auto],
type: int, default: 1, choices=[0, 1, 2, 3]
--iterations: Running iterations, type: int, default: 1
--entropy: Compute tensor entropy, action: store_true
--mle: Minimize per layer error, action: store_true
### quantize_hybrid.py:
model: Model directory, type: str
quantized: Hybrid quantization type, type: str
choices=['asymi8', 'symi8', 'pcqi8', 'asymu8', 'Ai16Wi8'])
--algorithm: Quantization algotithm, The corresponding relationship between numbers and algorithms is as follows:[0: normal, 1:kl_divergence, 2:moving_average, 3:auto],
type: int, default: 1, choices=[0, 1, 2, 3]
--iterations: Running iterations, type: int, default: 1
--entropy: Calculate the entropy of each layer, action: "store_true"
--hybrid_qtype: The choices of hybrid quantization type. choices=['dfpi16', 'float32'], default="dfpi16"
--cust_qnt_layers: The file that contains the layer names that you want to quantized to dfpi16, type: str,
The file content supports two formats:
├── one is that enter the input names and output names of the subgraph. such as
--inputs \'Conv_Conv_178_217,Conv_Conv_178_219#Input_1\' --outputs \'output1,output0#output2\'
--inputs is the input names of subgraph in json. The input names of the same subgraph are separated with commas.
Input names between different subgraph are separated with hashtags.
--outputs is the output names of subgraph in json.The output names of the same subgraph are separated with commas.
Output names between different subgraph are separated with hashtags.
├── Other is that enter the layer name in json of each layer that you want to quantized to dfpi16. Put only one layer name per row.
### inference.py:
model: Model directory, type: str
quantized: Quantization type, type: str.
--iterations: Running iterations, type: int, default: 1
--use_hybrid: If you use hybrid quantize,please set this argument.
### export.py:
model: Model directory, type: str
quantized: Quantization type, type: str.
--iterations: Running iterations, type: int, default: 1
--use_hybrid: If you use hybrid quantize,please set this argument.
### export_nbg.py:
model: Model directory, type: str
quantized: Quantization type, type: str
optimize: The optimization method for the export. Specify a configuration file path or a configuration name for this argument
--use_hybrid: If you use hybrid quantize,please set this argument.
Note: VIV_SDK_PATH environment variable is used for Vivante SDK path. It is automatically configured during installation.
### dump.py:
model: Model directory, type: str
quantized: Quantization type, type: str.
--use_hybrid: If you use hybrid quantize,please set this argument.
### measure.py:
model: Model directory, type: str
quantized: Quantization type, type: str.
--use_hybrid: If you use hybrid quantize,please set this argument.
note: profile.py for experiental use only.
### profile.py:
model: Model directory
quantized: Quantization type
choices=['float32', 'asymi4', 'symi4', 'pcqsymi4', 'asymu4', 'asymi8', 'symi8',
pcqi8', 'asymu8', 'symi16', 'dfpi16', 'fp16', 'qbfp16', 'Ai16Wi8', 'Ai16Wpcqi8', Ai16Wpcqi4', 'Ai8Wpcqi4']
hw_config: A txt file located in model directory that describes the hardware configuration. Its contents are as follows:
"VSIMULATOR_CONFIG: VIP9000NANODI_PID0X10000020"
"NN_EXT_DDR_READ_BW_LIMIT: 16"
"NN_EXT_DDR_WRITE_BW_LIMIT: 16"
"NN_EXT_VIP_SRAM_SIZE: 262144"
Note: VIV_SDK_PATH environment variable is used for Vivante SDK path. It is automatically configured during installation.
### summary.py:
model: Model directory, type: str
quantized: Quantization type, type: str.
--iterations: Iteration number, type: int, default: 1
eg: import: python3 importer.py lenet/
normal quantization: python3 quantize.py lenet/ asymu8
hybrid Quantization: python3 quantize_hybrid.py lenet/ asymu8 --cust_qnt_layers cust_qnt_layers.txt
inference: python3 inference.py lenet/ asymu8
If you use the .quantize file generated by quantize_hybrid.py, the inference command should be python3 inference.py lenet/ asymu8 --use_hybrid
export: python3 export.py lenet/ asymu8
If you use the .quantize file generated by quantize_hybrid.py, the export command should be python3 export.py lenet/ asymu8 --use_hybrid
export_nbg: python3 export_nbg.py lenet/ asymu8 VIP9000NANODI_PID0X10000020
If you use the .quantize file generated by quantize_hybrid.py, the export_nbg command should be python3 export_nbg.py lenet/ asymu8 VIP9000NANODI_PID0X10000020 --use_hybrid
dump: python3 dump.py lenet/ asymu8
If you use the .quantize file generated by quantize_hybrid.py, the dump command should be python3 dump.py lenet/ asymu8 --use_hybrid
measure: python3 measure.py lenet/ asymu8
If you use the .quantize file generated by quantize_hybrid.py, the measure command should be python3 measure.py lenet/ asymu8 --use_hybrid
profile: python3 profile.py lenet/ asymu8 hw_config.txt
The general process of summary.py is as follows:
1. Run the importer.py script to generate the .json and .data files of the model.
2. Run the inference.py script with float32 type to generate the output tensors of the model, which will be used as golden data.
3. Run the quantize.py script with tha quantization format you want to quantize the model.
4. Run the summary.py script to quantize the model layer by layer and compare the quantized output with the golden data for each layer.
For example:
1. Generating .json and .data file: python3 importer.py lenet/
2. Generating golden data: python3 inference.py lenet/ float32
3. Quantizing the model: python3 quantize.py lenet/ asymu8
4. Quantizing each layer anf evaluating per-layer precision: python3 summary.py lenet/ asymu8 --iterations 1

471
docs/backup/cookbook.md
View File

@ -1,471 +0,0 @@
# Netrans Cookbook - 实用指南
本文档提供 Netrans 的实用操作指南、常见问题和故障排查。
---
## 目录
1. [快速参考](#快速参考)
2. [基础操作](#基础操作)
3. [场景示例](#场景示例)
4. [调试技巧](#调试技巧)
5. [故障排查](#故障排查)
6. [最佳实践](#最佳实践)
7. [附录](#附录)
---
## 快速参考
### 命令速查表
| 操作 | CLI 命令 | Python API |
|------|----------|------------|
| 加载模型 | `netrans load ./model --mean 0 0 0 --scale 255` | `model.load('./model', mean=[0,0,0], scale=255)` |
| 量化 | `netrans quantize ./model asymu8` | `model.quantize('asymu8')` |
| 混合量化 | `netrans quantize_hybrid ./model asymu8 --cust-qnt-layers layers.txt` | `model.quantize_hybrid('asymu8', cust_qnt_layers='layers.txt')` |
| 导出 | `netrans export ./model asymu8 --platform pnna` | `model.export('asymu8', platform='pnna')` |
| 多核导出 | `netrans export ./model asymu8 --platform pnna2 --core-num 4core` | `model.export('asymu8', platform='pnna2', core_num='4core')` |
| Dump | `netrans dump ./model asymu8` | `model.dump('asymu8')` |
| 推理 | `netrans inference ./model asymu8` | `model.inference('asymu8')` |
### 量化类型速查
```
┌─────────────┬─────────────┬─────────────┬────────────────────────────┐
│ 类型 │ 激活量化 │ 权重量化 │ 适用场景 │
├─────────────┼─────────────┼─────────────┼────────────────────────────┤
│ asymu8 │ uint8 │ uint8 │ 通用推荐，精度速度平衡 │
│ symi8 │ int8 │ int8 │ 对称数据分布 │
│ symi16 │ int16 │ int16 │ 高精度要求 │
│ dfpi16 │ int16 │ int16 │ 混合量化中的高精度层 │
│ AI16WI8 │ int16 │ int8 │ 高精度激活，紧凑权重 │
│ AI16WI4 │ int16 │ int4 │ 极高精度，超紧凑 │
│ fp16 │ float16 │ float16 │ 浮点量化，支持前后处理 │
└─────────────┴─────────────┴─────────────┴────────────────────────────┘
```
### 预处理参数速查
| 模型类型 | mean | scale | 说明 |
|----------|------|-------|------|
| YOLOv5/v8 | `[0, 0, 0]` | `255` | 归一化到 [0,1] |
| ResNet/ImageNet | `[123.675, 116.28, 103.53]` | `[58.395, 57.12, 57.375]` | ImageNet 统计值 |
| MobileNet | `[127.5, 127.5, 127.5]` | `127.5` | 归一化到 [-1,1] |
| 自定义 | 根据训练配置 | 根据训练配置 | 与训练时预处理一致 |
---
## 基础操作
### 完整转换流程
```bash
# 1. 加载模型
netrans load ./model --mean 0 0 0 --scale 255
# 2. 量化
netrans quantize ./model asymu8 --algorithm 1 --iterations 1
# 3. 导出（自动集成前后处理）
netrans export ./model asymu8 --platform pnna
```
### Python API 完整流程
```python
from netrans import Netrans
model = Netrans()
model.load('./model', mean=[0, 0, 0], scale=255)
model.quantize('asymu8')
model.export('asymu8', platform='pnna', preprocess=True, postprocess=True)
```
---
## 场景示例
### 场景1：YOLOv5s 快速转换
```python
#!/usr/bin/env python3
"""YOLOv5s 模型转换 - 快速版"""
from netrans import Netrans
model = Netrans()
model.load('./yolov5s', mean=[0, 0, 0], scale=255)
model.quantize('asymu8', algorithm=1)
model.export('asymu8', platform='pnna', preprocess=True, postprocess=True)
print("✅ 转换完成: wksp/yolov5s_asymu8_nbg_unify/network_binary.nb")
```
### 场景2：ResNet50 ImageNet 模型
```python
#!/usr/bin/env python3
"""ResNet50 ImageNet 模型转换"""
from netrans import Netrans
model = Netrans()
# ImageNet 预处理参数
model.load(
'./resnet50',
mean=[123.675, 116.28, 103.53], # RGB mean
scale=[58.395, 57.12, 57.375] # RGB std
)
model.quantize('asymu8', algorithm=1, iterations=5)
model.export('asymu8', platform='pnna')
```
### 场景3：YOLO 检测模型混合量化
```python
#!/usr/bin/env python3
"""YOLO 模型混合量化 - 检测头高精度"""
from netrans import Netrans
import os
model_dir = './yolov5s'
model = Netrans()
model.load(model_dir, mean=[0, 0, 0], scale=255)
# 创建混合量化配置（检测头使用高精度）
config_file = os.path.join(model_dir, 'cust_qnt_layers.txt')
with open(config_file, 'w') as f:
f.write('Conv_245\n') # 检测头1
f.write('Conv_269\n') # 检测头2
f.write('Conv_293\n') # 检测头3
# 执行混合量化
model.quantize_hybrid('asymu8', cust_qnt_layers=config_file)
model.export('asymu8', platform='pnna', use_hybrid=True)
```
### 场景4：PNNA2 多核导出
```python
#!/usr/bin/env python3
"""PNNA2 平台 4 核导出"""
from netrans import Netrans
model = Netrans()
model.load('./model', mean=[0, 0, 0], scale=255)
model.quantize('asymu8')
# 仅 pnna2 平台支持多核
model.export('asymu8', platform='pnna2', core_num='4core')
print("✅ 4核 NBG 导出完成")
```
### 场景5：批量转换多个模型
```bash
#!/bin/bash
# 批量转换脚本
MODELS=("yolov5s" "yolov5m" "yolov5l")
MEAN=(0 0 0)
SCALE=255
for model in "${MODELS[@]}"; do
echo "=== 转换 $model ==="
netrans load ./$model --mean ${MEAN[@]} --scale $SCALE
netrans quantize ./$model asymu8 --algorithm 1
netrans export ./$model asymu8 --platform pnna
echo "✅ $model 完成"
done
```
### 场景6：精度验证流程
```python
#!/usr/bin/env python3
"""精度验证 - 对比浮点和量化模型"""
from netrans import Netrans
import numpy as np
import os
def compare_outputs(float_dir, quant_dir):
"""对比两个目录的张量输出"""
float_files = sorted([f for f in os.listdir(float_dir) if f.endswith('.tensor')])
quant_files = sorted([f for f in os.listdir(quant_dir) if f.endswith('.tensor')])
print(f"{'Layer':<30} {'Max Diff':<15} {'Mean Diff':<15}")
print("-" * 60)
for ff, qf in zip(float_files, quant_files):
fdata = np.fromfile(os.path.join(float_dir, ff), dtype=np.float32)
qdata = np.fromfile(os.path.join(quant_dir, qf), dtype=np.float32)
max_diff = np.max(np.abs(fdata - qdata))
mean_diff = np.mean(np.abs(fdata - qdata))
layer_name = ff.replace('.tensor', '')[:28]
print(f"{layer_name:<30} {max_diff:<15.6f} {mean_diff:<15.6f}")
# 执行验证
model = Netrans()
model.load('./model', mean=[0, 0, 0], scale=255)
# 浮点推理
model.inference('float32', iterations=1)
# 量化并推理
model.quantize('asymu8')
model.inference('asymu8', iterations=1)
# 对比输出
compare_outputs(
'wksp/model_float32/golden',
'wksp/model_asymu8/golden'
)
```
---
## 调试技巧
### Dump 张量数据
```python
# Dump 浮点模型作为基准
model = Netrans()
model.load('./model', mean=[0, 0, 0], scale=255)
model.dump('float32') # 输出: dump/model_float32/
# 量化后对比
model.quantize('asymu8')
model.dump('asymu8') # 输出: dump/model_asymu8/
# 对比两层输出差异，定位精度损失层
```
### 检查 NBG 导出结果
```bash
# 检查 NBG 文件大小
ls -lh wksp/*_nbg_unify/network_binary.nb
# asymu8 量化的 NBG 应该比 float32 小约 75%
# 如果大小相近，说明量化未生效
# 查看 NBG 元数据
cat wksp/*_nbg_unify/nbg_meta.json | jq .
```
### 检查预处理配置
```bash
# 1. 检查 channel_mean_value.txt
cat channel_mean_value.txt
# 格式: "mean1 mean2 mean3 scale" 或 "mean1 mean2 mean3 scale1 scale2 scale3"
# 2. 检查 _inputmeta.yml
cat *_inputmeta.yml | grep -A 15 "preprocess:"
# 3. 检查是否启用了预处理节点
grep "add_preproc_node" *_inputmeta.yml
```
---
## 故障排查
### 错误代码速查
| 错误信息 | 可能原因 | 解决方案 |
|----------|----------|----------|
| `ImportError: CXXABI_1.3.15 not found` | libstdc++ 版本冲突 | 先导入 netrans，再导入 tensorflow |
| `xxx.quantize file does not exist` | 未执行量化或类型不匹配 | 执行 `netrans quantize` 并确保类型一致 |
| `Warning: @{lid}:<suffix> not found` | hybrid 层名不匹配 | 使用 `netrans dump` 查看实际层名 |
| `NBG 文件大小异常` | 量化未生效 | 确保 `quantize()` 后调用 `export()` |
| `预处理参数不生效` | 配置未正确加载 | 检查 `channel_mean_value.txt` 格式 |
### 问题1: libstdc++ 版本冲突
**症状**: `ImportError: ... version 'CXXABI_1.3.15' not found`
**解决**: 确保导入顺序正确
```python
# ✅ 正确
from netrans import Netrans
import tensorflow as tf
# ❌ 错误
import tensorflow as tf
from netrans import Netrans # 可能失败
```
### 问题2: 量化文件找不到
**症状**: `xxx.quantize file does not exist`
**原因**: 未执行 `netrans quantize` 或量化类型不匹配
**解决**:
```bash
# 确认量化步骤已执行
netrans quantize ./model asymu8
# 确保后续命令使用相同的量化类型
netrans export ./model asymu8 # 类型必须一致
```
### 问题3: NBG 文件大小异常
**症状**: 量化后的 NBG 文件大小与浮点模型相近
**原因**:
- Python API 使用时未更新网络对象
- 导出时重新加载了浮点模型
**解决**:
```python
# ✅ 正确流程
model.quantize('asymu8') # 量化
model.export('asymu8') # 导出（使用量化后的网络对象）
# ❌ 错误：不要重新创建 Netrans 实例
model1 = Netrans()
model1.load('./model')
model1.quantize('asymu8')
model2 = Netrans() # 新实例！
model2.load('./model') # 加载的是浮点模型
model2.export('asymu8') # 导出的是浮点 NBG
```
### 问题4: 预处理参数不生效
**症状**: 模型输出与预期不符
**排查步骤**:
```bash
# 1. 检查 channel_mean_value.txt 格式
cat channel_mean_value.txt
# 应该是: "mean1 mean2 mean3 scale"
# 2. 检查 _inputmeta.yml
cat *_inputmeta.yml | grep -A 10 "preprocess:"
# 3. 确认 add_pre_post 执行成功
grep "add_preproc_node" *_inputmeta.yml # 应该显示 true
```
### 问题5: Hybrid 量化层找不到
**症状**: `Warning: @{lid}:<suffix> not found`
**原因**: 配置文件中的层名与模型中的层名不匹配
**解决**:
```bash
# 使用 dump 查看实际层名
netrans dump ./model asymu8
# 确保配置文件中使用的是 lid（如 Conv_245）
# 不是层名称（如 "Conv_245_relu"）
```
---
## 最佳实践
### 1. 推荐转换流程
```bash
# 标准三步法
netrans load ./model --mean 0 0 0 --scale 255
netrans quantize ./model asymu8 --algorithm 1 --iterations 1
netrans export ./model asymu8 --platform pnna
```
### 2. 精度优先流程
```bash
# 高精度要求时使用
netrans load ./model --mean 0 0 0 --scale 255
netrans quantize ./model asymu8 --algorithm 3 --iterations 5 # auto 算法
netrans export ./model asymu8 --platform pnna
```
### 3. 速度优先流程
```bash
# 快速转换，牺牲部分精度
netrans load ./model --mean 0 0 0 --scale 255
netrans quantize ./model asymu8 --algorithm 0 --iterations 1 # normal 算法
netrans export ./model asymu8 --platform pnna
```
### 4. 磁盘空间管理
```bash
# Dump 会占用大量空间，及时清理
rm -rf dump/
# 清理旧的 golden 数据
rm -rf wksp/*/golden/
# 只保留最终的 NBG 文件
ls wksp/*_nbg_unify/network_binary.nb
```
### 5. 版本控制建议
```bash
# 不要提交生成的文件
echo "*.data" >> .gitignore
echo "*.quantize" >> .gitignore
echo "wksp/" >> .gitignore
echo "dump/" >> .gitignore
```
---
## 附录
### A. 量化算法详解
| 算法 | 值 | 特点 | 适用场景 |
|------|-----|------|----------|
| normal | 0 | 直接统计 min/max | 快速测试 |
| KL散度 | 1 | 最小化 KL 散度 | **推荐默认** |
| moving_average | 2 | 移动平均 | 动态范围大的数据 |
| auto | 3 | 自动选择每层最优 | 最高精度，最慢 |
### B. 多核配置详解
```
┌──────────┬─────────────────────┬──────────────────────────┐
│ 核数 │ VIV_MGPU_AFFINITY │ VIV_OVX_MULTI_DEVICES │
├──────────┼─────────────────────┼──────────────────────────┤
│ 1核 │ 1:0 │ 0:1 │
│ 2核 │ 1:2 │ 0:2-2 │
│ 3核 │ 1:3 │ 0:3-1 │
│ 4核 │ 1:4 │ 0:4-1 │
└──────────┴─────────────────────┴──────────────────────────┘
```
**注意**: 多核配置仅 `pnna2` 平台支持，`pnna` 平台为单核架构。
### C. 文件命名规范
| 文件 | 说明 |
|------|------|
| `{model}.json` | 网络结构描述 |
| `{model}.data` | 权重数据（二进制） |
| `{model}_inputmeta.yml` | 输入预处理配置 |
| `{model}_postprocess_file.yml` | 输出后处理配置 |
| `{model}_{qtype}.quantize` | 量化参数 |
| `{model}_{qtype}_hy.quantize` | 混合量化参数（hybrid 模式） |
### D. 相关文档
- [快速入门](quick-start.md)
- [API 参考](netrans_api.md)
- [CLI 参考](netrans_cli.md)
- [版本发布记录](release.md)

433
docs/backup/netrans_api.md
View File

@ -1,433 +0,0 @@
# Netrans Python API 参考手册
**版本**: v6.33.3 (Python 3.10 + Acuity 6.33)
## 概述
Netrans提供简洁而功能完整的Python API，用于将神经网络模型转换为PNNA芯片可运行的NBG格式。支持多种深度学习框架（TensorFlow、PyTorch、ONNX、Caffe、Darknet）和量化策略。
## 快速开始
```python
from netrans import Netrans
# 推荐的完整工作流程：加载 → 量化 → 导出(集成前后处理)
model = Netrans()
model.load('./yolov5s', mean=[0,0,0], scale=0.00392) # 加载模型
model.quantize('asymu8') # 量化
model.export('asymu8', preprocess=True, postprocess=True) # 导出并集成前后处理
```
## 核心类
### Netrans类
神经网络转换工具的主类，提供完整的模型处理流水线。
#### 初始化
```python
Netrans()
```
创建Netrans实例，自动验证运行环境和依赖项。
**示例：**
```python
from netrans import Netrans
# 创建实例
model = Netrans()
```
---
#### load()
加载并准备模型，支持多种框架格式和预处理参数配置。
```python
load(model_path, *, mean=None, scale=None)
```
**参数：**
- `model_path` (str): 模型目录路径，必须包含有效的模型文件
- `mean` (float | list[float], 可选): 通道均值。支持格式：
- **列表**：长度必须与模型输入通道数一致，按通道顺序对应
- **单值**：仅适用于单通道模型（如灰度图像）
- `scale` (float | list[float], 可选): 通道缩放系数。支持格式：
- **单值**：自动广播到所有通道
- **列表**：长度必须与`mean`参数一致，或单值广播
**技术规范：**
- 通道数由模型输入shape决定，常见CV模型为3通道（RGB）
- `mean`列表长度必须等于模型输入通道数；`scale`支持单值广播
- `mean`和`scale`长度关系：`len(mean) == len(scale)` 或 `len(scale) == 1`
- 数值类型支持`int`和`float`，内部统一转换为`float32`
**正确用法：**
```python
# 三通道RGB模型（如YOLOv5、ResNet50等）
model.load('./yolov5s', mean=[128.0, 128.0, 128.0], scale=255.0) # scale广播
model.load('./resnet50', mean=[123.675, 116.28, 103.53], scale=[58.395, 57.12, 57.375])
# 单通道灰度模型
model.load('./lenet_gray', mean=[127.5], scale=255.0) # mean用列表，即使单通道
# 或
model.load('./lenet_gray', mean=127.5, scale=255.0) # 单值仅适用于单通道
```
**错误用法：**
```python
# 三通道模型不能用单值mean
model.load('./yolov5s', mean=128, scale=1) # ❌ 错误：三通道模型mean必须用列表
# 长度不一致
model.load('./model', mean=[128, 128], scale=[1, 1, 1]) # ❌ mean和scale长度不匹配
```
**验证方法：**
检查模型输入元数据文件`<model>_inputmeta.yml`中的`shape`字段：
```yaml
shape: [1, 3, 640, 640] # [batch, channels, height, width]
```
`channels`值即为输入通道数，`mean`和`scale`列表长度必须与此值一致。
**异常：**
- `FileNotFoundError`: 模型目录不存在
- `ValueError`: 未找到模型文件或参数格式错误
- `TypeError`: mean/scale格式无效
---
#### quantize()
对加载的模型进行量化处理，支持多种量化算法和配置。
```python
quantize(quantized, *, algorithm=1, iterations=1, entropy=False, mle=False)
```
**参数：**
- `quantized` (str): 目标量化类型，支持：
- `'asymu8'`: 非对称8位无符号量化（最常用）
- `'symi8'`: 对称8位有符号量化
- `'symi16'`: 对称16位有符号量化
- `algorithm` (int, 可选): 量化算法选择，默认1：
- `0`: 普通量化
- `1`: KL散度量化（推荐，精度较高）
- `2`: 移动平均量化
- `3`: 自动选择量化
- `iterations` (int, 可选): 量化迭代次数，默认1。增加迭代可提高精度但耗时更长
- `entropy` (bool, 可选): 是否计算张量熵，默认False。用于量化分析
- `mle` (bool, 可选): 是否最小化层间误差，默认False
**算法选择建议：**
- 大多数模型：`algorithm=1` (KL散度，平衡精度和速度)
- 对精度要求极高：`algorithm=3` (自动选择，可能更耗时)
- 快速测试：`algorithm=0` (最快，精度可能略低)
**示例：**
```python
# 基础量化
model.quantize('asymu8')
# 高精度量化
model.quantize('asymu8', algorithm=1, iterations=5)
# 量化分析模式
model.quantize('asymu8', entropy=True, mle=True)
```
**注意：**
- 从 v2.0 开始，`preprocess` 和 `postprocess` 参数已移至 `export()` 方法
- 建议在 `export()` 时设置 `preprocess=True` 和 `postprocess=True`
**异常：**
- `QuantizationError`: 量化过程失败
- `ValueError`: 量化类型不支持
---
#### quantize_hybrid()
对指定层应用混合精度量化，允许同一模型中使用不同量化策略。
```python
quantize_hybrid(quantized, *, algorithm=1, iterations=1,
hybrid_qtype='dfpi16', cust_qnt_layers=None)
```
**参数：**
- `quantized` (str): 基础量化类型
- `algorithm` (int, 可选): 量化算法，同`quantize()`
- `iterations` (int, 可选): 迭代次数，默认1
- `hybrid_qtype` (str, 可选): 混合层量化类型，默认'dfpi16'
- `cust_qnt_layers` (str, 可选): 自定义量化层配置文件路径
**配置文件格式（cust_qnt_layers.txt）：**
```
# Layer列表格式
Conv_1
Conv_2
Conv_3
```
**示例：**
```python
# 基础混合量化
model.quantize_hybrid('asymu8', cust_qnt_layers='layers.txt')
# 完整混合量化流程
model.quantize_hybrid('asymu8', cust_qnt_layers='layers.txt')
model.add_pre_post('asymu8', use_hybrid=True) # 混合量化后需要单独添加
model.export('asymu8', use_hybrid=True)
```
**异常：**
- `QuantizationError`: 混合量化失败
---
#### add_pre_post()
将预处理和后处理操作集成到网络图中，优化推理性能。
```python
add_pre_post(quantized, *, preprocess=True, postprocess=True, use_hybrid=False)
```
**参数：**
- `quantized` (str): 量化类型
- `preprocess` (bool, 可选): 是否集成预处理（mean/scale），默认True
- `postprocess` (bool, 可选): 是否集成后处理（反量化），默认True
- `use_hybrid` (bool, 可选): 是否使用混合量化文件，默认False
**注意事项：**
- FP16量化类型下此操作无效
- 功能等价于 `quantize(..., pre=True, post=True)`，提供分步控制能力
- 主要用于混合量化流程和调试分析
**示例：**
```python
# 混合量化后添加前后处理
model.add_pre_post('asymu8', use_hybrid=True)
# 单独控制预处理
model.add_pre_post('asymu8', preprocess=True, postprocess=False)
```
---
#### export()
将量化后的模型导出为PNNA芯片可加载的NBG格式。
```python
export(quantized='float32', *, model_path=None, platform='pnna', use_hybrid=False,
preprocess=True, postprocess=True, core_num=None)
```
**参数：**
- `quantized` (str, 可选): 量化类型，默认'float32'。应与量化步骤一致
- `model_path` (str, 可选): 模型目录路径，如与已加载模型不同则重新加载
- `platform` (str, 可选): 目标芯片平台，默认'pnna'：
- `'pnna'`: VIP8000NANOQI_PLUS_PID0XB1（默认平台）
- `'pnna2'`: VIP9400O_PID0X1000004F
- `use_hybrid` (bool, 可选): 是否使用混合量化文件，默认False
- `preprocess` (bool, 可选): 是否集成预处理到网络图，默认True
- `postprocess` (bool, 可选): 是否集成后处理（反量化）到网络图，默认True
- `core_num` (str, 可选): 多核配置，可选值：
- `"1core"` 或 `"1"`: 单核模式
- `"2core"` 或 `"2"`: 双核模式
- `"3core"` 或 `"3"`: 三核模式
- `"4core"` 或 `"4"`: 四核模式
**平台选择：**
- 不确定时保持默认`'pnna'`
- 特定芯片型号需要对应平台，咨询硬件团队确认
**平台与多核支持：**
| 平台 | 芯片型号 | 多核支持 | 说明 |
|------|----------|----------|------|
| `'pnna'` | VIP8000NANOQI_PLUS_PID0XB1 | ❌ 不支持 | 单核架构，不需要 viv-sdk |
| `'pnna2'` | VIP9400O_PID0X1000004F | ✅ 支持 1-4 核 | 多核架构，需要 viv-sdk 生成多核 NBG |
**注意：** 多核配置 (`core_num`) 仅在 `pnna2` 平台有效，`pnna` 平台不支持多核模式。
**前后处理集成：**
- `preprocess=True`: 将 mean/scale 预处理操作集成到网络图
- `postprocess=True`: 将反量化操作集成到网络图
- 推荐在生产环境中启用，减少运行时开销
- FP16 量化类型下此功能无效
**示例：**
```python
# 基础导出
model.export('asymu8')
# 带前后处理的导出（推荐）
model.export('asymu8', preprocess=True, postprocess=True)
# 指定平台
model.export('asymu8', platform='pnna')
model.export('asymu8', platform='pnna2')
# 混合量化导出
model.export('asymu8', use_hybrid=True)
# 多核导出
model.export('asymu8', platform='pnna2', core_num='4core') # 4核模式
model.export('asymu8', platform='pnna2', core_num='1') # 单核模式（简写）
# 连续导出不同配置
model.export('asymu8', platform='pnna2', core_num='1core') # 1核
model.export('asymu8', platform='pnna2', core_num='4core') # 4核（覆盖）
```
**多核配置说明：**
通过 `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 | 1:4 | 0:4-1 | 四核模式 |
**重要限制：**
- 多核配置 **仅 `pnna2` 平台支持**，`pnna` 平台不支持多核
- 使用多核导出时，必须确保 `VIV_SDK_PATH` 环境变量已正确设置
- `core_num` 设置仅影响当前进程，进程结束后自动恢复
**输出文件：**
- `wksp/<model>_<quantized>_nbg_unify/network_binary.nb`: 最终NBG文件
- `wksp/<model>_<quantized>_nbg_unify/nbg_meta.json`: NBG元数据
- `wksp/<model>_<quantized>_nbg_unify/main.c`: 示例C代码
**异常：**
- `ExportError`: 导出过程失败
- `ValueError`: 平台或量化类型不支持，或 `core_num` 值无效
---
#### dump()
导出网络各层张量数据，用于量化效果分析和精度调试。
```python
dump(quantized='float32', *, use_hybrid=False)
```
**参数：**
- `quantized` (str, 可选): 量化类型，默认'float32'
- `use_hybrid` (bool, 可选): 是否使用混合量化文件，默认False
**输出：**
- `dump/<model>_<quantized>/`: 张量数据目录
- `*.tensor`: 各层激活值文件，可用于对比分析
**示例：**
```python
# 基础导出
model.dump('asymu8')
# 混合量化导出
model.dump('asymu8', use_hybrid=True)
```
---
#### inference()
运行模型推理并保存输入输出张量，用于精度验证。
```python
inference(quantized='float32', *, iterations=1, use_hybrid=False)
```
**参数：**
- `quantized` (str, 可选): 量化类型，默认'float32'
- `iterations` (int, 可选): 推理迭代次数，默认1
- `use_hybrid` (bool, 可选): 是否使用混合量化文件，默认False
**输出：**
- `wksp/<model>_<quantized>/golden/`: 标准输入输出数据
- 可用于对比不同量化版本的精度差异
**示例：**
```python
# 单次推理
model.inference('asymu8')
# 多次推理（统计稳定性）
model.inference('asymu8', iterations=5)
# 混合量化推理
model.inference('asymu8', use_hybrid=True)
```
---
## 完整示例
更多完整示例请参考 [cookbook.md](cookbook.md)，包括：
- YOLOv5s 完整转换流程
- 混合量化示例
- 批量处理脚本
- 调试与验证流程
---
#### check_opset()
检查 ONNX 模型的 opset 版本是否符合 Netrans 要求。
```python
check_opset(model_path, verbose=False)
```
**参数：**
- `model_path` (str): ONNX 模型文件路径或包含 .onnx 文件的目录
- `verbose` (bool, 可选): 是否显示详细信息，默认 False
**返回：**
- `bool`: 是否符合要求（True=符合，False=不符合或检查失败）
**支持的 opset 版本：**
Netrans 支持 ONNX opset 版本范围：**7 - 17**
| Opset 版本 | ONNX 版本 | 支持状态 |
|---|---|---|
| 7-17 | 1.2-1.12 | ✅ 支持 |
| 18+ | 1.13+ | ❌ 不支持 |
**示例：**
```python
from netrans import Netrans
model = Netrans()
# 检查单个 ONNX 文件
is_valid = model.check_opset('./yolov5s.onnx')
print(f"模型可用: {is_valid}")
# 检查目录（自动查找 .onnx 文件）
is_valid = model.check_opset('./yolov5s/')
# 详细输出
is_valid = model.check_opset('./yolov5s.onnx', verbose=True)
```
**输出示例：**
```
============================================================
ONNX 模型 Opset 版本检查
============================================================
模型路径: ./yolov5s.onnx
Opset 版本: 11 (ONNX 1.6)
IR 版本: 6
Producer: pytorch 1.9
状态: ✅ opset 版本 11 符合要求
============================================================
```
**异常：**
- `NetransError`: 检查过程中发生错误（如 onnx 包未安装）
---
## 相关文档
- [netrans_cli.md](netrans_cli.md) - 命令行工具参考
- [cookbook.md](cookbook.md) - 使用指南
**技术支持：** 如遇API使用问题，请参考示例代码或联系技术支持团队。

374
docs/backup/netrans_cli.md
View File

@ -1,374 +0,0 @@
# Netrans CLI 参考手册
本手册提供 Netrans 命令行接口的完整规范，按子命令分节描述。
如需快速上手，请参考 [cookbook.md](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
将指定目录中的模型文件载入工作区，并可同时写入通道均值/缩放参数。
#### 用法
```bash
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 级别日志 |
#### 示例
```bash
# 三通道RGB模型（如YOLOv8s）
$ netrans load ./yolov8s --mean 0 0 0 --scale 255
# 单通道灰度模型
$ netrans load ./lenet_gray --mean 127.5 --scale 255
```
对模型载入并设定预处理参数。`--scale` 支持单值广播，`--mean` 长度必须与输入通道数一致。
#### 运行结果
- 生成 `<dir>/channel_mean_value.txt`（若用户指定均值或缩放）
- 生成 `<dir>/<model>.json` 内部网络描述，供后续子命令读取
#### 异常说明
若目录内存在多个候选模型文件，或扩展名不被识别，命令将终止并返回非零退出码，同时向标准错误输出具体原因。
### 3.2 netrans quantize
对载入后的网络执行静态量化，生成量化配置文件。
#### 用法
```bash
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 | — | 同前 |
#### 示例
```bash
$ netrans quantize . asymu8 --algorithm 1 --iterations 1
```
对当前目录模型执行非对称 8 位量化，采用 KL 算法一次迭代。
#### 运行结果
- 生成 `<dir>/<model>_<qtype>.quantize` 量化配置
- 若指定 --entropy，额外输出张量熵日志
#### 异常说明
若未先执行 load，或量化文件已存在且被覆盖保护，将报"无法创建量化配置"错误。
### 3.3 netrans quantize_hybrid
对指定层列表使用混合精度量化，其余层沿用基准量化类型。
#### 用法
```bash
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 | — | 同前 |
#### 示例
```bash
$ 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
将均值（预处理）与反量化（后处理）节点嵌入网络，生成统一计算图。
#### 用法
```bash
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 | — | 同前 |
#### 示例
```bash
$ 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 网络二进制文件。
#### 用法
```bash
netrans 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 | — | 同前 |
#### 示例
```bash
$ netrans export . asymu8 --platform pnna
```
导出适用于 pnna 的 .nb 文件。
```bash
$ 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
导出网络各层激活张量，用于精度比对与调试。
#### 用法
```bash
netrans dump <dir> <qtype> [--use-hybrid] [--verbose]
```
#### 参数列表
| 参数 | 必要性 | 类型 | 描述 |
|---|---|---|---|
| dir | 必选 | 路径 | 已量化模型目录 |
| qtype | 必选 | string | 量化类型 |
| 选项 | 必要性 | 类型 | 默认值 | 描述 |
|---|---|---|---|---|
| --use-hybrid | 可选 | flag | — | 使用 hybrid 量化文件 |
| --verbose, -v | 可选 | flag | — | 同前 |
#### 示例
```bash
$ netrans dump . asymu8
```
导出 asymu8 量化后各层张量。
#### 运行结果
- 生成 `dump/<model>_<qtype>[_hy]/*.tensor`（每层一个文件）
#### 异常说明
若量化文件缺失，或输出目录不可写，将报"Dump failed"。
### 3.7 netrans inference
执行一次前向推理，并将输入/输出张量保存至 golden 目录。
#### 用法
```bash
netrans inference <dir> <qtype> [--iterations <int>] [--use-hybrid] [--verbose]
```
#### 参数列表
| 参数 | 必要性 | 类型 | 描述 |
|---|---|---|---|
| dir | 必选 | 路径 | 已量化模型目录 |
| qtype | 必选 | string | 量化类型 |
| 选项 | 必要性 | 类型 | 默认值 | 描述 |
|---|---|---|---|---|
| --iterations | 可选 | int | 1 | 推理迭代次数 ≥1 |
| --use-hybrid | 可选 | flag | — | 使用 hybrid 量化文件 |
| --verbose, -v | 可选 | flag | — | 同前 |
#### 示例
```bash
$ 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 要求。
#### 用法
```bash
netrans check_opset <path> [--verbose]
```
#### 参数列表
| 参数 | 必要性 | 类型 | 描述 |
|---|---|---|---|
| path | 必选 | 路径 | ONNX 模型文件路径或包含 .onnx 文件的目录 |
| 选项 | 必要性 | 类型 | 默认值 | 描述 |
|---|---|---|---|---|
| --verbose, -v | 可选 | flag | — | 显示详细信息 |
#### 示例
```bash
# 检查单个 ONNX 文件
$ netrans check_opset ./yolov5s.onnx
# 检查目录（自动查找 .onnx 文件）
$ 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"
```
## 参见
- [netrans_api.md](netrans_api.md) —— Python API 参考
- [cookbook.md](cookbook.md) —— 场景脚本合集

646
docs/backup/release.md
View File

@ -1,646 +0,0 @@
# Netrans 版本发布记录
**当前版本**: 6.33.3
**最后更新**: 2026-02-27
---
## 目录
- [v6.33.3](#v6333-2026-02-27) - 多核配置支持 (1-4核)
- [v6.33.2](#v6332-2026-02-25) - 安装脚本优化 & 消除依赖冲突警告
- [v6.33.1](#v6331-2026-02-24) - 目录结构优化 & 安装流程改进
- [v6.33.0](#v6330-2026-02-09) - Python 3.10 & Acuity 6.33 迁移
- [v6.42.4](#v6424-2026-02-09) - Acuity 拆分 & 离线打包
- [v6.42.3+](#v6423-2025-12---2026-01) - Export API 优化
- [v6.42.3](#v6423-2025-12-05) - Hybrid 量化 & Dump 功能
- [v6.42.2](#v6422-2025-12-05) - Platform 参数替换 Optimize
- [历史版本](#历史版本)
---
## v6.33.3 (2026-02-27)
### 新增功能：多核配置支持 (1-4核)
**变更日期**: 2026-02-27
**影响范围**: `export()` 方法、CLI、文档
#### 功能说明
支持在导出 NBG 模型时配置 VIP 多核运行模式（1-4核）。
**多核配置映射**:
| core_num | VIV_MGPU_AFFINITY | VIV_OVX_MULTI_DEVICES | 说明 |
|----------|-------------------|----------------------|------|
| `1core` / `1` | `1:0` | `0:1` | 单核模式 |
| `2core` / `2` | `1:2` | `0:2-2` | 双核模式 |
| `3core` / `3` | `1:3` | `0:3-1` | 三核模式 |
| `4core` / `4` | `1:4` | `0:4-1` | 四核模式 |
**配置说明**:
- `VIV_MGPU_AFFINITY`: GPU 亲和性配置
- `1:n` - 启用独立模式，n 表示核心数
- `0` - 多核模式（4核）
- `VIV_OVX_MULTI_DEVICES`: 多设备配置，格式 `0:n-m` 表示设备0包含两组内核
#### Python API
```python
# 4核导出
model.export('asymu8', core_num='4core')
# 简写形式
model.export('asymu8', core_num='4')
# 指定平台
model.export('asymu8', platform='pnna2', core_num='4core')
```
#### CLI
```bash
# 4核导出
netrans export model asymu8 --core-num 4core
# 简写形式
netrans export model asymu8 --core-num 4
# 指定平台
netrans export model asymu8 --platform pnna2 --core-num 4core
```
#### 更新文件
- `src/netrans/netrans.py`: 添加 `_MULTICORE_CONFIGS` 和 `_set_multicore_env()`
- `script/netrans`: 添加 `--core-num` 参数
- `test/uint_test/test_multicore.py`: 多核配置单元测试
- `docs/netrans_cli.md`: CLI 文档更新
- `docs/netrans_api.md`: API 文档更新
- `AGENTS.md`: 项目设计文档更新
### 文档更新：CLI/API 文档同步与链接修复
**变更日期**: 2026-03-13
**影响范围**: 文档文件
#### 变更内容
1. **CLI 版本号修正**: 修正 `script/netrans` 中的版本号（从错误的 `6.42.3` 改为正确的 `6.33.3`）
2. **API 文档更新** (`docs/netrans_api.md`):
- 移除已废弃的 `viv_sdk` 参数（已改用 `VIV_SDK_PATH` 环境变量）
- 添加 `model_path` 参数说明
- 更新 4 核配置表（`1:4` / `0:4-1`）
- 修复文档链接引用
3. **CLI 文档更新** (`docs/netrans_cli.md`):
- 从 quantize 命令移除 `--preprocess`/`--postprocess` 参数（已移至 export 命令）
- 向 export 命令添加 `--preprocess`/`--postprocess`/`--core-num` 参数说明
- 移除 `--viv-sdk` 参数说明
4. **README 增强** (`README.md`):
- 添加文档描述和链接说明
- 添加 CI 自动同步说明
5. **文档链接修复** (`docs/release.md`):
- 修复文档文件名引用（`cli-reference.md` → `netrans_cli.md`）
#### 更新文件
- `script/netrans`: 版本号修正
- `docs/netrans_api.md`: API 文档同步
- `docs/netrans_cli.md`: CLI 文档同步
- `README.md`: 文档链接增强
- `docs/release.md`: 链接修复
#### 注意事项
- 多核配置通过环境变量实现，仅影响当前进程
- `core_num=None`（默认）时不修改环境变量，使用当前环境配置
- 无效的配置值会抛出 `ValueError`
### 功能优化：Export 默认启用前后处理
**变更日期**: 2026-02-27
**影响范围**: `export()` 方法、CLI
#### 变更内容
`export()` 方法的 `preprocess` 和 `postprocess` 参数默认值从 `False` 改为 `True`。
| 参数 | 旧默认值 | 新默认值 | 说明 |
|------|---------|---------|------|
| `preprocess` | `False` | `True` | 将均值节点并入网络 |
| `postprocess` | `False` | `True` | 将反量化节点并入网络 |
#### Python API
```python
# 默认启用前后处理
model.export('asymu8')
# 显式禁用前后处理
model.export('asymu8', preprocess=False, postprocess=False)
```
#### CLI
```bash
# 默认启用前后处理
netrans export model asymu8
# 显式传 False 禁用
netrans export model asymu8 --preprocess False --postprocess False
```
#### 更新文件
- `src/netrans/netrans.py`: 修改 `preprocess` 和 `postprocess` 默认值为 `True`
- `script/netrans`: CLI 参数支持布尔值类型
- `docs/cli-reference.md`: 更新 CLI 文档
- `docs/netrans_api.md`: 更新 API 文档
---
## v6.33.2 (2026-02-25)
### 变更：安装脚本优化 - 消除依赖冲突警告
**变更日期**: 2026-02-25
**影响范围**: `setup.sh` 安装脚本
#### 问题
安装时出现依赖冲突警告：
```
acuity 6.33.19 requires torch==1.5.1, but you have torch 2.2.2 which is incompatible.
```
#### 解决方案
调整 `setup.sh` 安装顺序：
1. **先安装 Python 依赖**（包括 torch 2.2.2）
2. **再用 `--no-deps` 安装 acuity**（跳过其依赖检查）
**修改的文件**:
- `setup.sh`: 交换步骤1和步骤2的顺序，确保依赖先安装
#### 安装顺序对比
| 顺序 | 变更前 | 变更后 |
|------|--------|--------|
| 步骤1 | 安装 acuity (`--no-deps`) | 安装 Python 依赖 |
| 步骤2 | 安装 Python 依赖 | 安装 acuity (`--no-deps`) |
---
## v6.33.1 (2026-02-24)
### 变更：目录结构优化 & 安装流程改进
**变更日期**: 2026-02-24
**影响范围**: 目录结构、安装脚本、文档
#### 1. 目录结构优化
| 变更 | 原位置 | 新位置 |
|------|--------|--------|
| packing 目录 | `packaging/` | `devtools/packing/` |
**更新内容**:
- 将 `packaging/` 目录移动到 `devtools/packing/`
- 更新所有相关脚本和文档中的路径引用
- 更新 `Makefile` 中的 `package` 和 `sync` 命令
#### 2. Python 3.10 环境迁移
| 项目 | 变更前 | 变更后 |
|------|--------|--------|
| Python | 3.8 | **3.10** |
| acuity whl | cp38 | **cp310** |
**文件变更**:
- `.python-version`: `3.8` → `3.10`
- `setup.py`: `python_requires=">=3.8"` → `python_requires=">=3.10"`
- `setup.sh`: 安装 `acuity-6.33.19-cp310-cp310-*.whl`
- `requirements_py3.8.txt` → `requirements.txt`
#### 3. acuity 安装优化
**问题**: acuity 安装时会覆盖已安装的 torch 版本
**解决方案**:
- 使用 `--no-deps` 参数安装 acuity
- torch 已在 requirements.txt 中单独安装
**修改的文件**:
- `setup.sh`: `pip install "$ACUITY_WHL" --no-deps`
- `devtools/packing/install.sh`: 更新 `install_package` 函数支持额外参数
- 所有相关文档更新安装说明
#### 4. 版本号统一
统一所有版本号为 **6.33.0**:
- `setup.py`: 6.33.0
- `devtools/packing/setup.py`: 6.42.4 → 6.33.0
- `src/netrans/__init__.py`: 6.42.3 → 6.33.0
---
## v6.33.0 (2026-02-09)
### 重大变更：Python 3.10 & Acuity 6.33 迁移
**变更日期**: 2026-02-09
**影响范围**: Python 版本、Acuity 版本、模型加载逻辑
#### 1. Python 版本升级
| 项目 | 变更前 | 变更后 |
|------|--------|--------|
| Python | 3.8 | **3.10** |
| Acuity | 6.42.x | **6.33.x** |
**文件变更**:
- `setup.py`: `python_requires=">=3.8"` → `python_requires=">=3.10"`
- `requirements_py3.8.txt` → `requirements.txt`
- `vendor/acuity-6.33.19-cp38-...` → `vendor/acuity-6.33.19-cp310-...`
#### 2. 模型加载逻辑重构
**问题**: `export()` 等操作会重新调用 `importer()` 导致 `add_pre_post` 配置丢失。
**解决方案**:
- 新增 `load_generated()` 方法：专门用于加载已生成的文件（.json, .data, .quantize）
- `load()` 方法：仅用于从原始模型格式导入（.cfg, .weights, .pb 等）
- CLI 各命令使用正确的加载方式
**API 变更**:
| 方法 | 用途 | 加载来源 |
|------|------|----------|
| `load()` | 首次导入原始模型 | .cfg, .weights, .pb, .onnx 等 |
| `load_generated()` | 加载已生成模型 | .json, .data, .quantize, _inputmeta.yml |
#### 3. CLI 命令加载方式更新
| 命令 | 加载方式 | 说明 |
|------|----------|------|
| `netrans load` | `load()` | 从原始模型导入 |
| `netrans quantize` | `load_generated()` | 加载已生成的 .json, .data |
| `netrans export` | `load_generated()` | 加载已生成的文件（包含 inputmeta） |
| `netrans dump` | `load_generated()` | 加载已生成的文件 |
| `netrans inference` | `load_generated()` | 加载已生成的文件 |
| `netrans add_pre_post` | 直接操作文件 | 修改 _inputmeta.yml |
#### 4. Export Pre/Post 参数位置调整
| 版本 | `quantize()` | `export()` |
|------|--------------|------------|
| 旧版 | 支持 `--preprocess/--postprocess` | 不支持 |
| 新版 | 移除该参数 | 支持 `--preprocess/--postprocess` |
**正确 Workflow**:
```bash
# 1. 从原始模型导入（生成 .json, .data, _inputmeta.yml）
netrans load yolov4_tiny --mean 128 128 128 --scale 1 1 1
# 2. 量化（加载已生成的文件）
netrans quantize yolov4_tiny asymu8
# 3. 添加前后处理（修改 _inputmeta.yml 和 _postprocess_file.yml）
netrans add_pre_post yolov4_tiny asymu8 --preprocess --postprocess
# 4. 导出时集成前后处理（加载已生成的文件，包含修改后的配置）
netrans export yolov4_tiny asymu8 --platform pnna --preprocess --postprocess
```
#### 5. 迁移指南
**从 v6.42.x 迁移到 v6.33.0**:
1. **Python 环境**: 升级到 Python 3.10
```bash
conda create -n netrans python=3.10
```
2. **Acuity 安装**: 安装 cp310 版本（使用 `--no-deps` 避免覆盖 torch）
```bash
pip install vendor/acuity-6.33.19-cp310-cp310-manylinux2010_x86_64.whl --no-deps
```
3. **代码更新**: 更新 `requirements.txt`
```bash
pip install -r requirements.txt
```
4. **Workflow 更新**: 确保使用正确的加载顺序
- 先用 `netrans load` 导入原始模型
- 后续操作使用 `netrans quantize/export/dump`（自动使用 load_generated）
---
## v6.42.4 (2026-02-09)
### 重大变更
#### 1. Acuity 拆分
将 acuity 解码库从 netrans 包中拆分，作为独立依赖：
- **变更前**: acuitylib 打包在 netrans whl 中
- **变更后**: acuity 通过独立 whl 安装
- **安装方式**: `pip install acuity-6.42.10-*.whl --no-deps`
**影响**:
- 减小 netrans 包体积
- 允许独立更新 acuity
- 安装时需要额外安装 acuity
#### 2. 离线打包支持
新增 `devtools/packing/` 目录，支持离线环境安装：
```bash
# 开发环境（联网）
cd devtools/packing/
python3 download_dependencies.py # 下载依赖
bash build.sh # 构建离线包（输出到 dist/release/）
# 用户环境（离线）
tar -xzf netrans_offline_v*.tar.gz
cd netrans_offline/
bash install.sh
```
**特性**:
- 自动处理 TensorFlow 2.17.0 与 ml-dtypes 版本冲突
- 一键构建离线安装包
- 支持完全离线的环境部署
### 目录结构优化
```
netrans/
├── src/netrans/ # 源码（移除 acuitylib）
├── devtools/packing/ # 离线打包配置（新增）
├── devtools/ # 开发工具（新增）
│ ├── debug/ # 调试脚本
│ ├── verify/ # 验证脚本
│ └── dev/ # 开发辅助
│
├── vendor/ # 第三方依赖（新增）
│ └── acuity-*.whl # Acuity 核心库
└── tests/unit/ # 单元测试（新增）
```
### 依赖更新
```
# 新增
ml-dtypes==0.4.1 # TensorFlow 2.17.0 兼容
# acuity 变为外部依赖
acuity>=6.42.0 # 独立安装
```
---
## v6.42.3+ (2025-12 - 2026-01)
### API 优化：Export Pre/Post 参数迁移
**变更日期**: 2026-02-04
**影响范围**: `quantize()` 和 `export()` 方法
#### 变更内容
| 方法 | 变更前 | 变更后 |
|------|--------|--------|
| `quantize()` | `preprocess=True, postprocess=True` | 移除 pre/post 参数 |
| `export()` | 无 pre/post 参数 | 新增 `preprocess=False, postprocess=False` |
#### 迁移示例
**旧代码 (v1.x)**:
```python
model.quantize('asymu8', preprocess=True, postprocess=True)
model.export('asymu8')
```
**新代码 (v2.0)**:
```python
model.quantize('asymu8') # 仅量化
model.export('asymu8', preprocess=True, postprocess=True) # 导出时集成
```
#### 修复问题
解决 `export()` 重新加载模型导致 `add_pre_post` 配置被重置的问题。
---
## v6.42.3 (2025-12-05)
### 新增功能
#### 1. Hybrid 量化 (`quantize_hybrid`)
对模型的不同层使用不同的量化策略，实现混合精度。
**支持组合**:
- 基础量化: `asymu8`, `symi8`, `pcqi8`
- Hybrid 类型: `dfpi16`, `float32`
**使用方式**:
```python
# Python API
model.quantize_hybrid(
quantized='asymu8',
hybrid_qtype='dfpi16',
cust_qnt_layers='layers.txt'
)
model.export('asymu8', use_hybrid=True)
# CLI
netrans quantize_hybrid model asymu8 --cust-qnt-layers layers.txt
netrans export model asymu8 --use-hybrid
```
**适用场景**:
- 目标检测：Backbone (asymu8) + Head (dfpi16)
- 分割模型：主体 (symi8) + 上采样 (float32)
- Transformer：全连接 (asymu8) + 注意力 (dfpi16)
#### 2. Dump 功能 (`dump`)
导出网络各层的输入输出张量数据，用于调试分析。
**使用方式**:
```python
# Python API
model.dump('asymu8') # 普通量化
model.dump('asymu8', use_hybrid=True) # Hybrid 量化
# CLI
netrans dump model asymu8
netrans dump model asymu8 --use-hybrid
```
**输出**:
```
dump/
└── model_name_quantized/
├── layer1_input_0.tensor
├── layer1_output_0.tensor
└── ...
```
---
## v6.42.2 (2025-12-05)
### 平台参数优化
将 `export` 功能的 `optimize` 参数改为更友好的 `platform` 参数。
#### 变更对比
| 旧方式 | 新方式 |
|--------|--------|
| `optimize='VIP8000NANOQI_PLUS_PID0XB1'` | `platform='pnna'` |
| `optimize='VIP9400O_PID0X1000004F'` | `platform='pnna2'` |
#### 平台映射
| platform | 芯片 | optimize 值 |
|---------|------|------------|
| `pnna` | VIP8000 | VIP8000NANOQI_PLUS_PID0XB1 |
| `pnna2` | VIP9400 | VIP9400O_PID0X1000004F |
#### 迁移示例
**Python API**:
```python
# 旧
model.export('asymu8', optimize='VIP8000NANOQI_PLUS_PID0XB1')
# 新
model.export('asymu8', platform='pnna') # 更简洁
```
**CLI**:
```bash
# 旧
netrans export model asymu8 --optimize VIP8000NANOQI_PLUS_PID0XB1
# 新
netrans export model asymu8 --platform pnna
```
⚠️ **破坏性变更**: 需要更新所有使用 `optimize` 的代码。
---
## 功能更新详情
### Add_pre_post 功能增强
#### 支持 Hybrid 量化 (v6.42.3)
新增 `--use-hybrid` 参数，支持处理 Hybrid 量化模型：
```bash
# 普通量化
netrans add_pre_post model asymu8 --preprocess --postprocess
# Hybrid 量化
netrans add_pre_post model asymu8 --preprocess --postprocess --use-hybrid
```
#### 显式控制 Pre/Post (v6.42.3+)
支持显式控制 pre 和 post 处理：
```python
# 只启用前处理
model.add_pre_post('asymu8', pre=True, post=False, use_hybrid=True)
# 只启用后处理
model.add_pre_post('asymu8', pre=False, post=True, use_hybrid=True)
```
---
## 命令行工具更新
### 当前支持的子命令
```bash
netrans load # 加载模型
netrans quantize # 模型量化
netrans quantize_hybrid # Hybrid 量化（v6.42.3+）
netrans add_pre_post # 添加前后处理
netrans export # 导出模型
netrans dump # Dump 张量数据（v6.42.3+）
netrans inference # 执行推理
netrans measure # 统计计算量
```
### 新增入口点
安装后提供以下命令：
```bash
netrans-dump
netrans-export-nbg
netrans-inference
netrans-importer
netrans-measure
netrans-quantize
netrans-quantize-hybrid
netrans-add-prepost
```
---
## 历史版本
### v6.42.1 及更早
- 基础模型导入、量化、导出功能
- 支持 TensorFlow、PyTorch、ONNX、Caffe、Darknet
- 命令行工具和 Python API
---
## 迁移指南汇总
### 从 v6.42.2 迁移到 v6.42.3+
1. **Platform 参数**: `optimize` → `platform`
2. **Hybrid 量化**: 新增工作流，使用 `quantize_hybrid`
3. **Dump 功能**: 新增调试功能
### 从 v6.42.3 迁移到 v6.42.4
1. **Acuity 安装**: 需要单独安装 acuity whl
2. **依赖更新**: 添加 `ml-dtypes==0.4.1`
### 从 v6.42.3+ 迁移到 v6.33.0
1. **环境降级**: Python 3.10 → 3.8, Acuity 6.42 → 6.33
2. **加载逻辑**: 区分 `load()` 和 `load_generated()`
3. **Pre/Post 迁移**: 从 `quantize()` 移到 `export()`
---
## 相关文档
- [quick-start.md](quick-start.md) - 快速入门
- [netrans_cli.md](netrans_cli.md) - CLI 参考
- [netrans_api.md](netrans_api.md) - Python API 参考
- [DUMP_USAGE.md](DUMP_USAGE.md) - Dump 功能详解
- [INFERENCE_USAGE.md](INFERENCE_USAGE.md) - 推理功能详解
---
**当前版本**: v6.33.3 (Python 3.10 + Acuity 6.33)
**维护团队**: Netrans 开发组
**问题反馈**: 请联系项目维护团队

74
docs/ci-setup.md
View File

@ -1,74 +0,0 @@
# CI 文档同步配置说明
## 概述
本项目配置了 GitLink DevOps (建木) CI 流程，在每次 push 到 `master` 分支时，自动将文档同步到 [nudtdocs 仓库](https://gitlink.org.cn/nudt_dsp/nudt_dsp_doc/tree/master/source/pnna/model_compilation)。
## 触发条件
文档同步会在以下情况下触发：
- Push 到 `master` 分支
## 配置步骤
### 1. 配置 DevOps 流水线
1. 登录 [GitLink](https://gitlink.org.cn)
2. 进入 netrans 仓库 → **DevOps** → **流水线**
3. 创建新的流水线，选择 **导入 YAML**
4. 上传 `.devops/sync-docs-to-nudtdocs.yml` 文件
### 2. 配置密钥
在 DevOps 平台的 **密钥管理** 中，确保以下密钥已配置：
- `gitlink.account` - GitLink 账号
- `gitlink.password` - GitLink 密码/令牌
### 3. 验证配置
配置完成后，可以通过以下方式验证：
1. 修改 `README.md` 或 `docs/` 目录下的任意文件
2. 提交并 push 到 `master` 分支
3. 查看 DevOps 流水线执行状态
4. 检查 [nudtdocs 仓库](https://gitlink.org.cn/nudt_dsp/nudt_dsp_doc/tree/master/source/pnna/model_compilation) 是否已同步更新
## 同步行为
- **文件映射**:
主文档：
| 源文件 | 目标文件 | 说明 |
|--------|----------|------|
| `README.md` | `introduction.md` | Netrans 简介 |
| `docs/netrans_cli.md` | `netrans_cli.md` | CLI 参考手册 |
| `docs/netrans_api.md` | `netrans_py.md` | Python API 参考手册 |
示例文档：
| 源文件 | 目标文件 | 说明 |
|--------|----------|------|
| `examples/caffe/README.md` | `examples/caffe_model.md` | Caffe 示例 |
| `examples/darknet/README.md` | `examples/darknet_model.md` | Darknet 示例 |
| `examples/onnx/README.md` | `examples/onnx_model.md` | ONNX 示例 |
| `examples/tensorflow/README.md` | `examples/tensorflow_model.md` | TensorFlow 示例 |
| `examples/pytorch/README.md` | `examples/pytorch_model.md` | PyTorch 示例 |
- **提交信息**: 同步提交信息为 `docs: sync from netrans`
## 故障排查
### 流水线执行失败
1. 查看 DevOps 平台流水线执行日志
2. 检查 `gitlink.account` 和 `gitlink.password` 密钥是否正确配置
3. 确认账号有权限访问 `nudt_dsp/nudt_dsp_doc` 仓库
### 文档未同步
1. 确认修改的文件在映射列表中
2. 检查 push 的分支是否为 `master`
3. 查看流水线触发记录，确认被正确触发
## 手动触发同步
如需手动触发同步，可以在 DevOps 平台手动运行该流水线。

13
docs/design/README.md
View File

@ -1,13 +0,0 @@
# Netrans 设计文档
本目录包含 Netrans 的技术设计方案和架构决策记录。
## 文档列表
| 文档 | 说明 |
|------|------|
| [multicore-and-platform-config.md](multicore-and-platform-config.md) | 多核配置与平台差异化配置设计 |
## 归档文档
历史设计文档已归档到 `devtools/dev/archive/` 目录。

303
docs/design/multicore-and-platform-config.md
View File

@ -1,303 +0,0 @@
# Netrans 多核配置集成方案（简化版）
## 1. 方案概述
根据 `acuity6.33多核配置.txt` 中的配置，VIP（Verisilicon Image Processor）支持 1-4 核配置。
**重要前提**：多核功能仅 **pnna2 平台** 支持，pnna 平台为单核架构，不支持多核配置。
| 平台 | 芯片型号 | 多核支持 | viv-sdk 依赖 |
|------|----------|----------|--------------|
| pnna | VIP8000NANOQI_PLUS_PID0XB1 | ❌ 不支持 | 不需要 |
| pnna2 | VIP9400O_PID0X1000004F | ✅ 支持 1-4 核 | 必须使用 |
**设计原则**：
- `nn.export_ovxlib()` 不支持多核参数，通过 `os.environ` 设置环境变量实现
- Netrans 的 `export()` 方法接收 `core_num` 参数
- **简化设计**：`os.environ` 只影响当前进程，无需保存/恢复，直接设置即可
- **viv-sdk 关联**：viv-sdk 用于生成多核 NBG，仅在 pnna2 平台导出时通过 `VIV_SDK_PATH` 环境变量自动调用
## 2. 多核配置定义
| 核心数 | VIV_MGPU_AFFINITY | VIV_OVX_MULTI_DEVICES | 说明 |
|--------|-------------------|----------------------|------|
| 1核 | 1:0 | 0:1 | 单核模式，使用 VIP_0 |
| 2核 | 1:2 | 0:2-2 | 双核模式，2个内核 |
| 3核 | 1:3 | 0:3-1 | 三核模式，组1有3个内核，组2有1个内核 |
| 4核 | 0 | (unset) | 四核模式，使用默认配置 |
## 3. 实现方案
### 3.1 修改 `netrans.py`
在 `netrans.py` 中添加多核配置字典和辅助函数：
```python
# 多核配置映射表
_MULTICORE_CONFIGS = {
"1": ("1:0", "0:1"),
"1core": ("1:0", "0:1"),
"2": ("1:2", "0:2-2"),
"2core": ("1:2", "0:2-2"),
"3": ("1:3", "0:3-1"),
"3core": ("1:3", "0:3-1"),
"4": ("0", None),
"4core": ("0", None),
}
def _set_multicore_env(core_num: Optional[str]) -> None:
"""
设置多核环境变量（仅当前进程有效）
Args:
core_num: 核心数配置，如 "1core", "2core", "3core", "4core" 或简写 "1", "2", "3", "4"
为 None 时不做任何修改
"""
if core_num is None:
return
if core_num not in _MULTICORE_CONFIGS:
valid = ", ".join(sorted(set(_MULTICORE_CONFIGS.keys())))
raise ValueError(f"Unknown core mode: {core_num}. Valid: {valid}")
affinity, multi_devices = _MULTICORE_CONFIGS[core_num]
os.environ["VIV_MGPU_AFFINITY"] = affinity
if multi_devices is not None:
os.environ["VIV_OVX_MULTI_DEVICES"] = multi_devices
else:
os.environ.pop("VIV_OVX_MULTI_DEVICES", None)
```
修改 `export()` 方法，添加 `core_num` 参数：
```python
@_ensure_meta
@chdir
def export(self, quantized: str = "float32", *, model_path: Optional[str] = None,
platform: str = "pnna", use_hybrid: bool = False,
preprocess: bool = False, postprocess: bool = False,
core_num: Optional[str] = None) -> None:
"""
Export the quantized model to chip-specific format.
Args:
quantized: Quantization type (e.g., 'asymu8', 'symi8', 'float32')
model_path: Optional path to save the exported model
platform: Target platform ('pnna' or 'pnna2')
use_hybrid: Whether to use hybrid quantization
preprocess: Whether to add preprocessing nodes to the graph
postprocess: Whether to add postprocessing nodes to the graph
core_num: Multi-core configuration, options: "1core", "2core", "3core", "4core"
or shorthand: "1", "2", "3", "4"
Default is None (use current environment configuration)
Example:
>>> model.export('asymu8', platform='pnna', core_num='4core')
"""
# ... 原有代码 ...
# 设置多核环境变量
_set_multicore_env(core_num)
# 执行导出
export_nbg_without_reload(...)
```
### 3.2 修改 CLI 脚本 `script/netrans`
在 `export` 子命令中添加 `--core-num` 参数：
```python
# 在 export_parser 部分添加
export_parser.add_argument(
'--core-num',
type=str,
choices=['1core', '2core', '3core', '4core', '1', '2', '3', '4'],
default=None,
help='Multi-core configuration: 1core, 2core, 3core, 4core (default: use current environment)'
)
# 修改 handle_export 函数，传递 core_num 参数
def handle_export(args):
"""Handle export command"""
# ... 原有代码 ...
model.export(
args.quant_type,
platform=args.platform,
use_hybrid=args.use_hybrid,
preprocess=args.preprocess,
postprocess=args.postprocess,
core_num=args.core_num # 传递多核配置
)
```
## 4. 使用示例
### 4.1 Python API 使用
```python
from netrans import Netrans
# 加载模型
model = Netrans()
model.load('./model', mean=128, scale=1)
# 量化
model.quantize('asymu8')
# 导出 - 使用4核配置
model.export('asymu8', platform='pnna', core_num='4core')
# 或使用简写
model.export('asymu8', platform='pnna', core_num='4')
# 连续导出不同配置
model.export('asymu8', core_num='1core') # 1核
model.export('asymu8', core_num='4core') # 4核（覆盖）
```
### 4.2 CLI 使用
```bash
# 使用4核导出
netrans export ./model asymu8 --platform pnna --core-num 4core
# 或使用简写
netrans export ./model asymu8 --platform pnna --core-num 4
# 查看帮助
netrans export -h
```
## 5. 关键设计点
### 5.1 进程级隔离
`os.environ` 只影响**当前进程**，进程结束后自动恢复，无需手动保存/恢复：
```python
# 在当前进程设置
os.environ["VIV_MGPU_AFFINITY"] = "0"
# 进程结束后，环境变量自动恢复为系统默认值
```
### 5.2 连续调用支持
用户连续 export 不同配置时，每次调用传参数即可，后设置的值会覆盖前者：
```python
model.export('asymu8', core_num='1core') # 设置 VIV_MGPU_AFFINITY=1:0
model.export('asymu8', core_num='4core') # 覆盖为 VIV_MGPU_AFFINITY=0
```
### 5.3 错误处理
非法的 `core_num` 值会立即抛出 `ValueError`：
```python
model.export('asymu8', core_num='8core') # ValueError: Unknown core mode: 8core
```
## 6. 文件变更清单
| 文件 | 变更类型 | 说明 |
|------|----------|------|
| `src/netrans/netrans.py` | 修改 | 添加多核配置字典、`_set_multicore_env` 函数、`export()` 添加 `core_num` 参数 |
| `script/netrans` | 修改 | CLI 添加 `--core-num` 参数 |
## 7. 注意事项
1. **环境变量作用域**: 只影响当前 Python 进程，不影响系统环境或其他进程
2. **4核特殊处理**: 4核模式需要 `unset VIV_OVX_MULTI_DEVICES`，代码中使用 `None` 表示
3. **默认行为**: `core_num=None` 时不修改环境变量，使用当前环境配置
4. **错误提示**: 非法值会给出清晰的可用选项列表
## 8. 版本历史
| 版本 | 日期 | 变更 |
|------|------|------|
| v2 | 2026-02-27 | 简化设计，移除上下文管理器，直接设置环境变量 |
| v1 | - | 原始方案，使用上下文管理器保存/恢复环境变量 |
# 平台差异化 VIV_SDK_PATH 配置变更说明
## 变更概述
本次更新实现了针对不同目标平台（`pnna` vs `pnna2`）的差异化 VIV_SDK_PATH 配置逻辑。根据平台类型动态决定是否使用 Vivante SDK。
## 变更详情
### 1. 核心逻辑修改
**文件：** `src/netrans/export_nbg.py`
在 `export_nbg()` 和 `export_nbg_without_reload()` 函数中增加了平台判断逻辑：
```python
# pnna 平台不使用 viv_sdk，pnna2 平台从环境变量获取 VIV_SDK_PATH
_PNNA2_OPTIMIZE = "VIP9400O_PID0X1000004F"
viv_sdk = os.environ.get('VIV_SDK_PATH') if optimize == _PNNA2_OPTIMIZE else None
```
### 2. 平台行为对照表
| 平台 | optimize 值 | 多核支持 | 是否使用 VIV_SDK_PATH | 说明 |
|------|-------------|----------|----------------------|------|
| `pnna` | `VIP8000NANOQI_PLUS_PID0XB1` | ❌ 不支持 | ❌ 否（viv_sdk=None） | 单核架构，不依赖 Vivante SDK |
| `pnna2` | `VIP9400O_PID0X1000004F` | ✅ 支持 1-4 核 | ✅ 是（读取环境变量） | 多核架构，从 `VIV_SDK_PATH` 获取 SDK 路径生成多核 NBG |
### 3. 用户接口不变
用户仍通过 `platform` 参数选择目标平台：
```python
# pnna 平台（默认）- 不使用 Vivante SDK
model.export('asymu8', platform='pnna')
# pnna2 平台 - 使用 Vivante SDK
model.export('asymu8', platform='pnna2')
```
内部会自动将 `platform` 映射为对应的 `optimize` 值，并据此决定 `viv_sdk` 参数。
## 影响范围
### 正向影响
1. **降低依赖耦合**：`pnna` 平台不再强制依赖 Vivante SDK
2. **提升兼容性**：简化了 `pnna` 平台的部署流程
3. **透明切换**：用户无需关心底层实现细节，只需选择平台即可
### 注意事项
1. **多核支持限制**：只有 `pnna2` 平台支持多核配置，`pnna` 平台始终为单核模式
2. **viv-sdk 依赖**：`pnna2` 平台导出多核 NBG 时必须正确配置 `VIV_SDK_PATH` 环境变量
3. 环境变量配置方式不变（通过 `setup.sh` 自动完成）
4. 错误处理机制保持原有逻辑，由 acuitylib 内部处理 `viv_sdk=None` 的情况
## 测试建议
建议分别测试两种平台配置：
```bash
# 测试 pnna 平台（不使用 Vivante SDK）
netrans export ./model asymu8 --platform pnna
# 测试 pnna2 平台（使用 Vivante SDK）
netrans export ./model asymu8 --platform pnna2
```
## 相关文档更新
- `docs/netrans_api.md`：更新了 `export()` 方法的参数说明和平台差异化行为表格
- `docs/API_REFERENCE.md`：同步更新了平台行为说明
- `README.md`：调整了 Python API 示例代码
## 版本信息
- **版本号**：v6.33.3
- **变更类型**：功能增强
- **兼容性**：向前兼容，无破坏性变更

242
docs/pmf/CONTEXT.md
View File

@ -1,242 +0,0 @@
# Netrans 项目背景与关键声明
> 本文档用于新 session 和上下文压缩后的信息恢复，记录项目关键背景和概念澄清。
---
## 一、Netrans 定位声明
### 1.1 Netrans 不是什么
**Netrans 不是 Acuity 的替代品**。Netrans 不会重新实现模型解析、量化算法、NBG 生成等核心功能。
### 1.2 Netrans 是什么
**Netrans 是 Acuity 和用户之间的中间层**。
```
用户/算法工程师
↓
Netrans（中间层）
↓
Acuitylib（VeriSilicon）
↓
PNNA 芯片
```
### 1.3 中间层的价值
| 价值 | 说明 |
|------|------|
| **易用性** | 封装 Acuity 复杂 API，提供简洁的 CLI 和 Python API |
| **标准化** | 统一工作流程，建立公司模型交付规范 |
| **隔离性** | 用户代码不直接依赖 Acuity，降低供应商绑定风险 |
| **可替换性** | 如果后续更换供应商，对用户来说是无感的 |
### 1.4 供应商切换场景
假设未来从 VeriSilicon 切换到其他供应商（如 NVIDIA、ARM）：
```
切换前：
用户代码 → Netrans API → Acuitylib → PNNA
切换后：
用户代码 → Netrans API → 新供应商SDK → 新芯片
↑
用户代码无需修改
```
**关键点**：Netrans 的接口设计是供应商无关的，底层实现可以替换。
---
## 二、技术难点澄清
### 2.1 Netrans 的技术难点不是 Acuity 本身的功能
Acuity 已经提供了模型导入、量化、导出等核心功能。Netrans 的技术难点在于：
| 难点 | 说明 | 为什么 Acuity 不解决 |
|------|------|---------------------|
| **状态同步** | 量化后网络对象的生命周期管理 | Acuity API 设计问题，需要上层封装解决 |
| **配置驱动** | YAML 配置文件管理工作流 | Acuity 没有这个设计理念 |
| **前后处理集成** | 预处理/后处理节点嵌入网络图 | Acuity 提供能力，但需要上层封装简化使用 |
| **多核配置自动化** | 环境变量自动管理 | Acuity 需要用户手动配置 |
| **双模式接口** | CLI + Python API 统一设计 | Acuity 只有 Python API |
### 2.2 核心技术难点详解
#### 难点1：量化后网络对象状态同步
**问题**：
```python
# Acuity API 行为
net = load_model("model.onnx") # net 是浮点网络
quantized_net = nn.quantize(net, ...) # 返回新的量化网络对象
# 问题：原 net 对象不变，quantized_net 是新对象
# 如果用户继续使用 net，量化结果会丢失
```
**Netrans 解决方案**：
```python
# Netrans API 设计
class Netrans:
def __init__(self):
self._meta = None # ModelMeta 包含网络对象
def quantize(self, ...):
quantized_net = quantize(self._meta.net, ...)
# 关键：更新 self._meta，确保后续操作使用量化后的网络
self._meta = ModelMeta(net=quantized_net, ...)
```
**为什么这是技术难点**：
- Acuity API 设计如此，不会修改原对象
- 需要上层封装管理对象生命周期
- 命令行工具每次是新进程，不存在此问题
- Python API 连续调用时必须正确处理
#### 难点2：配置驱动的工作流
**问题**：
- Acuity 每次操作需要传入大量参数
- 参数散落在代码中，难以复现和版本管理
- 团队协作时配置不统一
**Netrans 解决方案**：
```yaml
# _inputmeta.yml - 预处理配置
ports:
- lid: images_270
preprocess:
mean: [0, 0, 0]
scale: [0.00392, 0.00392, 0.00392]
# 配置文件可以：
# 1. 版本管理（Git）
# 2. 团队共享
# 3. 复现问题
```
#### 难点3：前后处理集成
**问题**：
- Acuity 支持前后处理节点嵌入，但配置复杂
- 用户需要理解 YAML 配置格式
- 导出时需要重新加载配置才能生效
**Netrans 解决方案**：
```python
# 一行命令完成前后处理集成
netrans add_pre_post ./model asymu8 --preprocess --postprocess
# 自动修改 _inputmeta.yml 和 _postprocess_file.yml
# 自动处理配置同步问题
```
---
## 三、概念澄清
### 3.1 WB 成熟度
**"WB 成熟度"是两个概念的混合**：
| 概念 | 全称 | 含义 |
|------|------|------|
| **WBS** | Work Breakdown Structure | 工作包结构，项目工作分解 |
| **TRL** | Technology Readiness Level | 技术成熟度，评估技术发展阶段 |
**TRL 五级简化版**：
| 级别 | 定义 | Netrans 对应 |
|------|------|--------------|
| TRL 1 | 基本原理观察 | AI 编译器原理研究 |
| TRL 2 | 技术概念形成 | 架构设计 |
| TRL 3 | 概念验证 | 核心功能原型 |
| TRL 4 | 实验室验证 | 单元测试通过 |
| TRL 5 | 相关环境验证 | 集成测试通过 |
**文档中的"WB成熟度维度"评估表**：
- 实际上是对工具链产品化程度的评估
- 更接近 TRL 的应用
- 建议改名为"工具链成熟度评估"或"产品化程度评估"
### 3.2 工作包分解（WBS）
WBS 是项目管理标准工具，用于：
- 分解项目工作
- 估算工作量
- 分配责任
- 跟踪进度
Netrans 项目的 WBS 结构参见立项文档附录。
---
## 四、项目关键决策记录
### 4.1 为什么选择封装 Acuity 而非自研
| 方案 | 优点 | 缺点 |
|------|------|------|
| **自研编译器** | 完全自主可控 | 开发周期长（2-3年）、技术风险高 |
| **封装 Acuity** | 快速交付、降低风险 | 依赖供应商 |
| **混合方案** | 平衡自主性和效率 | 复杂度高 |
**决策**：选择封装 Acuity，理由：
1. PNNA 芯片官方支持 Acuity
2. 快速交付，满足业务需求
3. 通过中间层设计降低供应商绑定风险
### 4.2 为什么同时提供 CLI 和 Python API
| 接口 | 目标用户 | 使用场景 |
|------|----------|----------|
| **CLI** | 部署工程师、测试工程师 | 批量转换、脚本集成、CI/CD |
| **Python API** | 算法工程师 | 训练流水线集成、快速验证 |
**决策**：同时提供两种接口，满足不同用户需求。
---
## 五、常见误解澄清
### 5.1 "Netrans 是 Acuity 的包装"
**澄清**：Netrans 不仅是包装，更是：
- 状态管理：解决 Acuity API 的状态同步问题
- 流程标准化：建立公司统一的模型交付规范
- 供应商隔离：降低供应商绑定风险
### 5.2 "Netrans 的技术难点是 Acuity 的功能"
**澄清**：Netrans 的技术难点是 Acuity 没有解决的问题：
- Acuity 提供底层能力
- Netrans 解决上层工程问题（状态管理、配置驱动、接口设计）
### 5.3 "WB 成熟度是行业标准"
**澄清**：WB 成熟度是两个概念的混合：
- WBS（工作包结构）是 PMI 标准
- TRL（技术成熟度）是 NASA/DoD 标准
- "WB成熟度"是两者的结合，需要分开理解
---
## 六、文档索引
| 文档 | 路径 | 用途 |
|------|------|------|
| 设计文档 | `AGENTS.md` | AI Agent 工作指南，包含架构设计和开发规范 |
| CLI 参考 | `docs/netrans_cli.md` | 命令行工具使用手册 |
| API 参考 | `docs/netrans_api.md` | Python API 使用手册 |
| 使用指南 | `docs/cookbook.md` | 典型场景使用指南 |
| 发布记录 | `docs/release.md` | 版本历史和变更记录 |
| 立项文档 | `docs/pmf/` | 产品需求规格书 |
---
*本文档用于上下文恢复，如有更新请同步修改。*

255
docs/pmf/PROJECT_CONTEXT.md
View File

@ -1,255 +0,0 @@
# Netrans 项目背景与核心声明
> 本文档用于应对 AI Agent 会话上下文丢失，确保项目理解的一致性
> 创建日期：2026-03-23
> 版本：v1.0
---
## 一、项目定位声明（核心！）
### 1.1 Netrans 是什么
**Netrans 不是替代 Acuitylib，而是 Acuitylib 和用户的中间层。**
```
用户/算法工程师
↓
Netrans（CLI / Python API）← 本项目
↓
Acuitylib（VeriSilicon 提供的神经网络编译库）← 第三方依赖
↓
PNNA 芯片驱动 / NBG 文件
↓
PNNA NPU 硬件
```
### 1.2 为什么要做 Netrans
| 问题 | Acuitylib 现状 | Netrans 解决 |
|------|---------------|-------------|
| 易用性 | API 复杂，学习成本高 | CLI 一键转换 + Python API |
| 标准化 | 各项目流程不一 | 统一 YAML + CLI 规范 |
| 可调试性 | 缺少中间结果查看 | dump/inference/measure 工具链 |
| 可维护性 | 依赖外部，不可控 | 自主代码，模块化架构 |
| 供应商绑定 | 直接调用 Acuity，切换成本高 | 中间层隔离，切换对用户无感 |
### 1.3 供应商无关性设计（关键！）
**设计目标**：如果未来更换底层编译器供应商（如从 VeriSilicon 换成其他），
对用户来说应该是**无感知的**。
实现方式：
- Netrans 提供统一的抽象接口
- 底层 Acuitylib 的调用被封装在内部模块
- 用户只与 Netrans 的 CLI/API 交互，不直接接触 Acuitylib
---
## 二、技术成熟度模型（WB 成熟度）
### 2.1 概念说明
**"WB 成熟度"是内部术语**，是以下两个概念的混合：
| 概念 | 全称 | 说明 |
|------|------|------|
| WBS | Work Breakdown Structure | 工作分解结构，项目管理的任务拆分 |
| TRL | Technology Readiness Level | 技术成熟度等级，NASA 提出的 1-9 级评估框架 |
**WB 成熟度 = 简化的 TRL（1-5 级）**，用于评估工具链/平台的工程化完善程度。
### 2.2 五级成熟度定义
| 等级 | 名称 | 定义 | 工具链典型特征 |
|------|------|------|----------------|
| L1 | 概念级 | 技术概念已形成 | 论文/原型，无实际代码 |
| L2 | 组件级 | 核心组件实验室验证 | 有代码，无法端到端运行 |
| L3 | 系统级 | 完整系统模拟环境验证 | 可运行，需专家操作，无文档 |
| L4 | 产品级 | 系统真实环境验证，可交付 | 有文档和基础工具，体验一般 |
| L5 | 成熟级 | 系统成熟，易用性好 | 完整工具链，标准化流程，生态完善 |
### 2.3 评估维度
从以下 6 个维度评估成熟度：
1. **工具链完整性**：从模型到芯片的端到端能力
2. **标准化程度**：流程统一、配置规范、交付标准
3. **易用性**：学习成本低、操作简便、文档完备
4. **可调试性**：问题定位方便、调试工具齐全
5. **可维护性**：代码质量高、架构清晰、测试覆盖
6. **可扩展性**：新需求支持能力强、模块化设计
### 2.4 Netrans 的成熟度目标
| 维度 | Acuitylib 现状 | Netrans 目标 | 提升措施 |
|------|---------------|-------------|----------|
| 工具链完整性 | L3-L4 | L5 | 端到端标准化流程 |
| 标准化程度 | L3 | L5 | 统一 YAML + CLI 规范 |
| 易用性 | L3 | L5 | CLI + Python API 双模式 |
| 可调试性 | L3 | L5 | dump/inference/measure 工具链 |
| 可维护性 | L3 | L4 | 自主代码，模块化架构 |
| 可扩展性 | L3 | L4 | 配置驱动，模块化扩展 |
**综合目标：从 L3（系统级）提升到 L4+（产品级向成熟级过渡）**
---
## 三、技术难点声明（重要！）
### 3.1 Netrans 的技术难点**不是** Acuitylib 本身就有的功能
Acuitylib 已经提供的功能（Netrans 只是封装）：
- 模型解析（Caffe/TensorFlow/ONNX 等格式）
- 量化算法（KL 散度、移动平均等）
- NBG 文件生成
- 算子优化和图融合
### 3.2 Netrans 真正的技术难点
| 难点 | 说明 | 对应模块 |
|------|------|----------|
| **网络对象生命周期管理** | `nn.quantize()` 返回新对象，需同步更新引用，否则导出的是浮点模型 | `netrans.py` |
| **配置与网络对象同步** | `add_pre_post()` 只改 YAML，导出前需重新加载到 net 对象 | `export_nbg.py` |
| **多核环境变量管理** | 多核配置通过环境变量实现，需确保不影响其他进程 | `netrans.py` |
| **libstdc++ 版本冲突** | acuitylib 需要 CXXABI_1.3.15，tensorflow 加载系统库 | `config.py` |
| **供应商抽象层设计** | 接口设计需考虑未来切换供应商的可能性 | 整体架构 |
### 3.3 典型踩坑记录
#### 坑 1：量化后网络对象未更新（已修复）
```python
# 错误做法（修复前）
def quantize(self, ...):
quantize(self._meta.net, ...) # 没有接收返回值！
# self._meta.net 仍是浮点网络
# 正确做法（修复后）
def quantize(self, ...):
quantized_net = quantize(self._meta.net, ...)
self._meta = ModelMeta(..., net=quantized_net) # 更新为量化后的网络
```
**原因**：`nn.quantize()` 返回新的网络对象，原对象不变。
#### 坑 2：add_pre_post 配置被覆盖（已修复）
```python
# 问题流程
add_pre_post() # 修改 YAML 配置
export() # 重新加载模型，配置被重置
# 修复方案
export_nbg_without_reload() # 直接使用内存中的网络对象，不重新加载
```
**原因**：`export_nbg()` 重新加载模型导致配置重置。
---
## 四、WBS 工作分解结构
### 4.1 顶层结构
```
Netrans 模型转换工具链开发项目 (100)
│
├── 1. 项目管理 (110)
├── 2. 需求与设计 (120)
├── 3. 核心框架开发 (130)
├── 4. 模型导入模块 (140)
├── 5. 量化模块 (150)
├── 6. 前后处理集成 (160)
├── 7. NBG 导出模块 (170)
├── 8. 调试分析工具 (180)
├── 9. 接口层开发 (190)
├── 10. 测试验证 (200)
├── 11. 文档与交付 (210)
└── 12. 产品化与维护 (220)
```
### 4.2 与代码模块的对应关系
| WBS 编号 | 工作包名称 | 对应代码模块 | 状态 |
|---------|-----------|-------------|------|
| 130 | 核心框架 | `netrans.py`, `config.py`, `exceptions.py`, `decorators.py`, `utils.py` | 已完成 |
| 140 | 模型导入 | `importer.py`, `model_loader.py` | 已完成 |
| 150 | 量化模块 | `quantize.py`, `quantize_hybrid.py`, `quantize_types.py` | 已完成 |
| 160 | 前后处理集成 | `add_prepost_to_graph.py` | 已完成 |
| 170 | NBG 导出 | `export_nbg.py` | 已完成 |
| 180 | 调试分析工具 | `dump.py`, `inference.py`, `measure.py`, `check_opset.py` | 已完成 |
| 190 | 接口层 | `script/netrans` | 已完成 |
| 200 | 测试验证 | `test/` 目录 | 已完成 |
| 210 | 文档与交付 | `docs/` 目录 | 已完成 |
### 4.3 工作量估算
| WBS 编号 | 工作包 | 估算工时(人天) |
|---------|--------|----------------|
| 1.x | 项目管理 | 20 |
| 2.1 | 模型导入模块 | 30 |
| 2.2 | 模型量化模块 | 25 |
| 2.3 | 前后处理模块 | 15 |
| 2.4 | 模型导出模块 | 20 |
| 2.5 | 调试分析模块 | 15 |
| 3.1 | 命令行接口 | 15 |
| 3.2 | Python API | 20 |
| 4.x | 测试与质量保证 | 40 |
| 5.x | 文档编制 | 25 |
| 6.x | 部署与发布 | 10 |
| **合计** | | **235 人天**（约 5 人月） |
---
## 五、关键术语表
| 术语 | 定义 |
|------|------|
| **PNNA** | Programmable Neural Network Accelerator，可编程神经网络加速器（公司自研 NPU） |
| **NBG** | Network Binary Graph，网络二进制图，PNNA 芯片可执行的模型格式 |
| **Acuitylib** | VeriSilicon 提供的神经网络编译库，Netrans 的核心依赖 |
| **Netrans** | 本项目，Acuitylib 的上层封装，提供 CLI 和 Python API |
| **WB 成熟度** | 内部术语，简化的 TRL（1-5 级），评估工具链工程化程度 |
| **WBS** | Work Breakdown Structure，工作分解结构 |
| **量化** | 将浮点模型转换为定点模型，减少模型大小和计算量 |
| **Hybrid 量化** | 混合精度量化，对不同层使用不同精度 |
| **前后处理集成** | 将 mean/scale 预处理和反量化后处理嵌入网络图 |
---
## 六、快速参考：回答常见问题
### Q1: Netrans 和 Acuitylib 是什么关系？
**标准回答**：Netrans 是 Acuitylib 的上层封装和中间层，不是替代关系。
用户通过 Netrans 的 CLI/API 间接使用 Acuitylib 的功能。
### Q2: 为什么要做 Netrans，直接用 Acuitylib 不行吗？
**标准回答**：Acuitylib "能用但不好用"，直接使用的学习成本高、流程不统一、
缺少调试工具。Netrans 提升工具链成熟度（从 L3 到 L4+），降低算法部署门槛。
### Q3: Netrans 的技术难点是什么？
**标准回答**：难点**不是** Acuitylib 已有的功能（如量化算法、NBG 生成），
而是：
1. 网络对象生命周期管理（状态同步）
2. 配置与网络对象同步
3. 多核环境变量管理
4. libstdc++ 版本冲突
5. 供应商抽象层设计（未来可切换）
### Q4: 如果以后不用 Acuitylib 了，Netrans 怎么办？
**标准回答**：Netrans 的设计目标就是供应商无关性。如果更换供应商，
只需修改 Netrans 内部实现，用户接口保持不变，对用户无感知。
### Q5: "WB 成熟度"是什么？
**标准回答**：内部术语，是 WBS（工作分解结构）和 TRL（技术成熟度等级）
的混合概念。采用简化的 1-5 级评估体系，评估工具链的工程化完善程度。
---
*本文档应在每次新的 AI Agent 会话开始时阅读，确保项目理解的一致性。*

185
docs/pmf/产品需求规格书-Netrans软件-WB成熟度与WBS草稿.md
View File

@ -1,185 +0,0 @@
# Netrans软件 产品需求规格书 - WB成熟度与WBS草稿
> 本文档为立项文档的草稿，包含WB成熟度分析和WBS工作分解结构
---
## 一、WB（Workbench）成熟度分析
### 1.1 WB成熟度定义
WB成熟度衡量的是AI编译器工具链的产品化、工程化完善程度，包括：
- **工具链完整性**：从模型到芯片的端到端能力
- **标准化程度**：流程统一、配置规范、交付标准
- **易用性**：学习成本低、操作简便、文档完备
- **可调试性**：问题定位方便、调试工具齐全
- **可维护性**：代码质量高、架构清晰、测试覆盖
- **可扩展性**：新需求支持能力强、模块化设计
### 1.2 Netrans的WB成熟度定位
Netrans基于Acuitylib构建，目标是提升PNNA芯片AI工具链的WB成熟度：
| WB成熟度维度 | 现状（直接使用Acuity） | 目标（使用Netrans） |
|-------------|----------------------|-------------------|
| 工具链完整性 | 底层能力具备，但缺少上层整合 | 端到端标准化流程 |
| 标准化程度 | 各项目流程不一，配置散落 | 统一YAML+CLI规范 |
| 易用性 | API复杂，学习成本高 | CLI一键转换+Python API |
| 可调试性 | 缺少中间结果查看工具 | dump/inference/measure工具链 |
| 可维护性 | 依赖外部，不可控 | 自主代码，模块化架构 |
| 可扩展性 | 黑盒，难以定制 | 配置驱动，模块化扩展 |
### 1.3 WB成熟度提升的关键价值
1. **降低门槛**：算法工程师无需了解Acuity细节即可完成模型转换
2. **统一标准**：建立公司模型交付规范，项目交接成本降低
3. **效率提升**：标准化流程减少重复工作，转换时间缩短
4. **质量保障**：完整调试工具链确保转换精度和性能
5. **生态闭环**：Netrans + PAPI + Driver形成自主可控工具链
---
## 二、WBS工作分解结构
```
Netrans 模型转换工具链开发项目 (100)
│
├── 1. 项目管理 (110)
│ ├── 111. 项目计划与跟踪
│ ├── 112. 需求管理
│ ├── 113. 配置管理
│ └── 114. 质量保证
│
├── 2. 需求与设计 (120)
│ ├── 121. 需求分析（WB成熟度需求提炼）
│ ├── 122. 架构设计（核心类/模块划分）
│ ├── 123. 接口设计（CLI/API规范）
│ └── 124. 技术方案评审
│
├── 3. 核心框架开发 (130) 【WB成熟度：架构基础】
│ ├── 131. Netrans核心类实现
│ ├── 132. 配置管理系统
│ ├── 133. 异常处理体系
│ ├── 134. 装饰器与工具函数
│ └── 135. 模型元数据管理
│
├── 4. 模型导入模块 (140) 【WB成熟度：多框架支持】
│ ├── 141. Caffe导入器
│ ├── 142. TensorFlow导入器
│ ├── 143. ONNX导入器
│ ├── 144. PyTorch导入器
│ ├── 145. TFLite导入器
│ ├── 146. Darknet导入器
│ └── 147. Keras导入器
│
├── 5. 量化模块 (150) 【WB成熟度：核心能力】
│ ├── 151. 基础量化引擎
│ ├── 152. 多类型量化支持（asymu8/symi8/symi16/fp16）
│ ├── 153. 量化算法实现（KL/MA/auto）
│ ├── 154. 混合精度量化
│ └── 155. 激活权重量化分离
│
├── 6. 前后处理集成 (160) 【WB成熟度：端到端优化】
│ ├── 161. 预处理嵌入（mean/scale）
│ └── 162. 后处理嵌入（反量化）
│
├── 7. NBG导出模块 (170) 【WB成熟度：芯片适配】
│ ├── 171. PNNA平台导出（单核）
│ ├── 172. PNNA2平台导出（多核1-4）
│ └── 173. 多核配置管理
│
├── 8. 调试分析工具 (180) 【WB成熟度：可调试性】
│ ├── 181. 张量导出工具（dump）
│ ├── 182. 推理验证工具（inference）
│ ├── 183. 性能测量工具（measure）
│ └── 184. Opset检查工具
│
├── 9. 接口层开发 (190) 【WB成熟度：易用性】
│ ├── 191. Python API实现
│ ├── 192. CLI工具实现
│ └── 193. 命令行解析与帮助系统
│
├── 10. 测试验证 (200) 【WB成熟度：可靠性】
│ ├── 201. 单元测试
│ ├── 202. 集成测试
│ ├── 203. 性能测试
│ ├── 204. 示例工程（ResNet/YOLO等）
│ └── 205. 回归测试套件
│
├── 11. 文档与交付 (210) 【WB成熟度：可交付性】
│ ├── 211. API参考手册
│ ├── 212. CLI使用手册
│ ├── 213. 开发指南（Cookbook）
│ ├── 214. 设计文档（AGENTS.md）
│ ├── 215. 示例代码与教程
│ └── 216. 发布说明
│
└── 12. 产品化与维护 (220) 【WB成熟度：可持续性】
├── 221. 安装包制作
├── 222. CI/CD流程
├── 223. 版本管理
└── 224. 问题跟踪与修复
```
---
## 三、WBS与代码模块对应关系
| WBS编号 | 工作包名称 | 对应代码模块 | 状态 |
|---------|-----------|-------------|------|
| 130 | 核心框架 | `netrans.py`, `config.py`, `exceptions.py`, `decorators.py`, `utils.py` | 已完成 |
| 140 | 模型导入 | `importer.py`, `model_loader.py` | 已完成 |
| 150 | 量化模块 | `quantize.py`, `quantize_hybrid.py`, `quantize_types.py` | 已完成 |
| 160 | 前后处理集成 | `add_prepost_to_graph.py` | 已完成 |
| 170 | NBG导出 | `export_nbg.py` | 已完成 |
| 180 | 调试分析工具 | `dump.py`, `inference.py`, `measure.py`, `check_opset.py` | 已完成 |
| 190 | 接口层 | `cli.py`, `script/netrans` | 已完成 |
| 200 | 测试验证 | `test/`目录 | 已完成 |
| 210 | 文档与交付 | `docs/`目录 | 已完成 |
---
## 四、立项文档关键表述建议
### 4.1 项目概述
> 本项目旨在提升 PNNA 芯片 AI 工具链的 **WB（Workbench）成熟度**，基于 Acuitylib 构建标准化、易用的模型转换中间层 **Netrans**。解决当前 Acuity "能用但不好用"的问题，建立公司统一的模型交付标准，降低算法部署门槛。
### 4.2 研究内容（对应WBS）
1. **标准化流程封装技术**（WBS 130-160）：将分散的Acuity操作固化为标准流水线
2. **多框架统一接入技术**（WBS 140）：7+框架模型一键导入
3. **量化策略优化技术**（WBS 150）：混合精度、分层量化等高级特性
4. **芯片感知导出技术**（WBS 170）：单核/多核自适应配置
5. **调试工具链技术**（WBS 180）：全链路可视化调试能力
6. **双模式接口设计**（WBS 190）：CLI满足部署工程师，Python API满足算法工程师
### 4.3 关键技术
1. **Acuity封装与状态同步**：解决量化后网络对象生命周期管理
2. **配置即代码**：YAML驱动的工作流，可复现、可版本管理
3. **前后处理图融合**：减少运行时开销的端到端优化
4. **多核配置自动化**：环境变量自动管理，用户无感知
### 4.4 创新点
1. **WB工具链闭环**：Netrans + PAPI + Driver 形成完整自主工具链
2. **双模式接口**：CLI批处理 + Python API流水线集成
3. **配置驱动设计**：一次配置，多次复用，团队协作标准化
---
## 五、风险与控制措施（基于WBS）
| 风险类别 | 风险描述 | 影响WBS | 控制措施 |
|---------|---------|---------|---------|
| 技术风险 | Acuitylib版本升级导致接口变更 | 140-170 | 封装层隔离，版本适配 |
| 技术风险 | 新框架模型解析失败 | 140 | 建立支持/不支持清单，优先覆盖主流模型 |
| 进度风险 | 多框架支持开发延期 | 140 | 分阶段交付，优先TF/ONNX/PyTorch |
| 质量风险 | 量化精度损失超标 | 150 | 建立精度评估流程，典型模型对比验证 |
| 资源风险 | 核心开发人员不足 | 110-130 | 文档完备，代码审查，知识共享 |
---
*草稿生成时间：2026-03-20*
*待完善：详细工期估算、资源分配、里程碑定义*

612
docs/pmf/产品需求规格书-Netrans软件-v2.md
View File

@ -1,612 +0,0 @@
# Netrans软件 产品需求规格书
> 版本：v2.0
> 日期：2026-03-23
---
## 1 项目概述
本项目旨在开发一套 **Acuity 与用户之间的中间层软件**，提供命令行工具 **netrans** 和 Python API **netrans_py**，支持将 TensorFlow、PyTorch、ONNX 等多种深度学习框架的模型转换为 PNNA NPU 可执行的 NBG（Network Binary Graph）格式。
### 1.1 项目定位
Netrans 定位为 **Acuity 与用户之间的中间层**，而非 Acuity 的替代品：
```
┌─────────────────────────────────────────────────────────────┐
│ 用户/算法工程师 │
│ ↓ │
│ Netrans（中间层） │
│ ↙ ↘ │
│ CLI 工具 Python API │
│ ↓ │
│ Acuitylib（VeriSilicon） │
│ ↓ │
│ PNNA 芯片 │
└─────────────────────────────────────────────────────────────┘
```
**中间层的核心价值**：
| 价值维度 | 说明 |
|----------|------|
| **易用性** | 封装 Acuity 复杂 API，提供简洁的 CLI 和 Python API |
| **标准化** | 统一工作流程，建立公司模型交付规范 |
| **隔离性** | 用户代码不直接依赖 Acuity，降低供应商绑定风险 |
| **可替换性** | 如果后续更换供应商，用户代码无需修改 |
**供应商切换场景**：
```
切换前：
用户代码 → Netrans API → Acuitylib → PNNA
切换后：
用户代码 → Netrans API → 新供应商SDK → 新芯片
↑
用户代码无需修改
```
### 1.2 术语及定义
| 术语 | 定义 |
|------|------|
| PNNA | Programmable Neural Network Accelerator，可编程神经网络加速器 |
| NBG | Network Binary Graph，网络二进制图，PNNA 芯片可执行的模型格式 |
| NPU | Neural Processing Unit，神经网络处理单元 |
| Acuitylib | VeriSilicon 提供的神经网络编译库，Netrans 的底层依赖 |
| 中间层 | 位于底层 SDK 和用户之间的软件层，提供简化的接口和标准化的工作流 |
| 供应商隔离 | 用户代码不直接依赖底层 SDK，降低供应商绑定风险的设计原则 |
| 量化 | 将浮点模型转换为定点模型的过程，减少模型大小和计算量 |
| Hybrid 量化 | 混合精度量化，对不同层使用不同精度 |
---
## 2 引用文件
无。
---
## 3 研究内容
本项目主要研究 **中间层软件的设计与实现技术**，解决直接使用 Acuitylib 时存在的工程问题。
### 3.1 模型转换流程的状态管理
**问题背景**：Acuitylib 的 `nn.quantize()` 返回新的网络对象，原对象保持不变。Netrans 的 Python API 需要支持链式调用（`model.load().quantize().export()`），如果未正确更新引用，导出的是浮点网络而非量化网络，导致 NBG 文件大小异常。
**研究内容**：设计可靠的状态同步方案，确保 Python API 链式调用时各阶段使用的是正确的模型状态。
### 3.2 前后处理配置的简化
**问题背景**：Acuitylib 的前后处理集成需要用户手动：1）从 .quantize 文件提取输入层量化参数；2）修改 `_inputmeta.yml` 添加 `preproc_node_params`；3）修改 `_postprocess_file.yml` 添加 `postproc_params`。涉及多个文件、多个参数，格式要求严格，操作复杂易错。
**研究内容**：设计一键化配置机制，自动完成参数提取和文件修改，用户无需了解配置文件细节。
### 3.3 复杂配置的简化封装
**问题背景**：Acuitylib 对不同框架有不同的导入函数和参数要求；多核配置需要设置复杂的环境变量；量化参数配置繁琐。
**研究内容**：设计多层次的简化封装：多核环境变量自动管理、多框架导入统一接口、量化参数简化配置、平台差异透明处理。
### 3.4 离线版工具链部署
**问题背景**：内网用户无法访问 PyPI 安装依赖，acuitylib 等依赖有特定版本要求，离线部署容易出错。
**研究内容**：设计完整的离线部署机制，包含依赖打包、自动安装脚本和部署文档。
### 3.5 供应商隔离的接口设计
**问题背景**：用户代码直接依赖 Acuitylib，存在供应商绑定风险。如果未来更换供应商，用户代码需要大量修改。
**研究内容**：设计供应商无关的中间层接口，确保用户代码与底层 SDK 解耦，为未来供应商切换预留空间。
---
## 4 技术要求
### 4.1 硬件要求
无特殊硬件要求。开发环境为通用 x86_64 Linux 服务器。
### 4.2 软件要求
#### 4.2.1 开发环境
- 操作系统：Linux（推荐 Ubuntu 20.04+）
- Python 版本：Python 3.10
- 核心依赖：numpy、protobuf、tensorflow、torch、onnx、acuitylib（>=6.33.0）
#### 4.2.2 功能要求
**模型导入功能**
系统应支持从多种深度学习框架导入模型：
- TensorFlow（.pb 格式，需配合 inputs_outputs.txt 指定输入输出）
- TensorFlow Lite（.tflite 格式）
- PyTorch（.pt 格式，通过 ONNX 后端转换）
- ONNX（.onnx 格式，支持 opset 7-17）
- Caffe（.prototxt + .caffemodel 格式）
- Darknet（.cfg + .weights 格式，支持 YOLO 系列）
- Keras（.h5 格式）
导入过程应完成模型解析、权重提取、中间表示生成，并输出网络结构描述文件（.json）和权重数据文件（.data）。
**模型量化功能**
系统应支持多种量化策略：
- 非对称 8 位量化（asymu8）：适用于通用场景，精度与性能平衡
- 对称 8 位量化（symi8）：适用于对称数据分布的模型
- 对称 16 位量化（symi16）：适用于高精度需求场景
- 混合精度量化（hybrid）：对敏感层使用高精度，其他层使用低精度
- 激活权重量化分离（AI16WI8/AI16WI4）：激活和权重使用不同精度
量化过程应支持多种校准算法：普通量化（normal）、KL 散度量化（kl_divergence）、移动平均量化（moving_average）、自动选择（auto）。
**前后处理集成功能**
系统应支持将预处理和后处理节点嵌入网络图：
- 预处理集成：将 mean/scale 归一化操作嵌入网络输入节点
- 后处理集成：将反量化操作嵌入网络输出节点
集成后生成的 NBG 文件可直接接受原始数据输入（如 uint8 图像），无需应用层额外处理。
**模型导出功能**
系统应支持将优化和量化后的模型导出为 PNNA 芯片可执行的 NBG 格式：
- 支持单核和多核配置（1-4 核 VIP 模式）
- 支持多平台优化（pnna: VIP8000 系列，pnna2: VIP9400 系列）
- 导出过程应生成 NBG 二进制文件、元数据文件和示例 C 代码
**调试分析功能**
系统应提供调试和分析工具：
- 张量导出（dump）：导出每层输入输出张量，用于精度对比
- 推理验证（inference）：执行前向推理，保存输入输出作为 golden 数据
- 性能测量（measure）：统计模型计算量（FLOPs）和内存占用
- Opset 检查（check_opset）：检查 ONNX 模型的 opset 版本兼容性
#### 4.2.3 接口要求
**命令行接口（netrans）**
系统应提供完整的命令行工具：
- `netrans load`：模型导入
- `netrans quantize`：模型量化
- `netrans quantize_hybrid`：混合精度量化
- `netrans add_pre_post`：前后处理集成
- `netrans export`：NBG 导出
- `netrans dump`：张量导出
- `netrans inference`：推理验证
- `netrans measure`：性能测量
- `netrans check_opset`：Opset 检查
**Python API（netrans_py）**
系统应提供 Python API，支持集成到训练流水线：
- `Netrans` 类：主类，封装完整的模型处理流水线
- `load()`、`quantize()`、`quantize_hybrid()`、`add_pre_post()`、`export()`、`dump()`、`inference()` 等方法
### 4.3 结构要求
无。
### 4.4 主要性能及可靠性指标要求
| 指标类别 | 指标项 | 要求 | 验证方法 |
|----------|--------|------|----------|
| 转换效率 | 大模型转换时间 | ResNet50 量化导出 < 5 分钟 | 标准开发环境实测 |
| 优化效果 | 模型压缩率 | asymu8 量化后模型大小减少 > 70% | 对比 .onnx 与 .nb 文件大小 |
| 量化精度 | 分类精度损失 | ResNet50 Top-1 精度损失 < 1% | ImageNet 验证集测试 |
| 量化精度 | 检测精度损失 | YOLOv5s mAP 下降 < 1% | COCO 验证集测试 |
| 资源占用 | 内存使用 | 转换过程峰值内存 < 模型大小 × 3 | 内存监控 |
| 易用性 | 学习成本 | 新用户 30 分钟内完成首次转换 | 用户测试 |
### 4.5 认证测试要求
无。
### 4.6 环境要求
无特殊环境要求。
### 4.7 非功能要求
**性能方面**
- 命令行工具冷启动时间 < 1 秒
- 支持大模型（>100MB）的高效转换
- 量化过程充分利用多核 CPU 并行计算
**安全性方面**
- 转换过程不修改原始模型文件
- 临时文件自动清理，敏感数据不残留
- 错误信息不暴露内部实现细节
**可用性方面**
- 错误信息明确指示问题原因和解决建议
- CLI 支持 `--verbose` 输出详细调试信息
- 提供完整的用户文档和示例代码
**可靠性方面**
- 转换过程异常中断时不损坏原始模型文件
- 关键操作前自动备份配置文件
- 支持断点续传（量化后的模型可重复导出）
**兼容性方面**
- 支持 TensorFlow >= 2.x、PyTorch >= 1.8、ONNX >= 1.10
- 支持 ONNX opset 7-17
- Python API 支持类型注解
**可维护性方面**
- 代码遵循 Python PEP 8 规范
- 关键函数有完整的 docstring
- 测试覆盖率 > 80%
**可替换性方面**
- 架构设计考虑底层库的可替换性
- 供应商相关代码集中封装，与核心逻辑解耦
- 接口设计遵循通用原则，降低迁移成本
- 如果更换底层 SDK，用户代码无需修改
### 4.8 关键器件及外协要求
无。
### 4.9 产品其它技术需求
**依赖说明**
本软件核心依赖 acuitylib（VeriSilicon 提供的神经网络编译库），需确保版本 >= 6.33.0。acuitylib 需要特定版本的 libstdc++（CXXABI_1.3.15），需通过 conda 环境管理。
**导入顺序要求**
由于 libstdc++ 版本冲突，用户代码必须先导入 netrans，再导入 tensorflow。
**平台支持**
本软件运行在 x86_64 Linux 开发环境，生成的 NBG 文件运行在 PNNA 芯片（ARM/DSP 平台）。
---
## 5 关键技术/工艺及创新点
### 5.1 关键技术
1. **模型转换状态同步机制**
**问题描述**：Acuitylib 的 `nn.quantize()` 返回新的网络对象，原对象保持不变。Netrans 的 Python API 需要支持链式调用（`model.load().quantize().export()`），如果未正确更新引用，导出的是浮点网络而非量化网络，导致 NBG 文件大小异常。
**解决方案**：设计 ModelMeta 不可变数据类，量化操作后创建新的实例。`quantize()` 方法内部更新 `self._meta` 引用，对用户无感知。
**验证方法**：链式调用与命令行分步执行生成的 NBG 文件大小一致，量化后比浮点小约 75%。
2. **前后处理配置的简化**
**问题描述**：Acuitylib 的前后处理集成需要用户手动：1）从 .quantize 文件提取输入层量化参数；2）修改 `_inputmeta.yml` 添加 `preproc_node_params`；3）修改 `_postprocess_file.yml` 添加 `postproc_params`。涉及多个文件、多个参数，格式要求严格，操作复杂易错。
**解决方案**：`add_pre_post()` 函数自动完成上述操作：读取量化参数、生成正确的 YAML 结构、写入对应位置。用户只需调用一个函数，无需了解配置文件细节。
**验证方法**：调用 `add_pre_post()` 后，检查 `_inputmeta.yml` 和 `_postprocess_file.yml` 中配置正确；导出后的 NBG 可直接接收 uint8 输入。
3. **多核环境配置简化**
**问题描述**：PNNA2 多核配置需要设置 `VIV_MGPU_AFFINITY` 和 `VIV_OVX_MULTI_DEVICES` 环境变量，格式复杂（如 `1:4` 和 `0:4-1`），且是进程级全局设置，容易影响其他操作。
**解决方案**：设计 `_set_multicore_env()` 函数，根据 `core_num` 参数（如 `'4core'`）自动计算并设置环境变量，导出后恢复。用户只需传递简单参数，无需了解环境变量细节。
**验证方法**：设置 4 核配置后导出，检查 NBG 多核元数据正确；同进程其他导出操作不受影响的单核配置。
4. **模型导入接口统一**
**问题描述**：Acuitylib 对不同框架（TensorFlow、PyTorch、ONNX 等）有不同的导入函数和参数要求，用户需要了解各框架的细节差异。
**解决方案**：设计统一的 `load()` 接口，自动识别模型格式并调用对应的 Acuitylib 导入函数。通过文件扩展名和内容检测，自动选择正确的导入器。
**验证方法**：同一 `load()` 接口可正确导入 7 种框架的模型，无需用户指定框架类型。
5. **供应商隔离的接口设计**
**问题描述**：用户代码直接依赖 Acuitylib，存在供应商绑定风险。如果未来更换供应商（如从 VeriSilicon 切换到 NVIDIA、ARM），用户代码需要大量修改。
**解决方案**：设计供应商无关的中间层接口，用户代码通过 Netrans API 调用，不直接依赖 Acuitylib。底层实现封装在独立模块，可替换而不影响用户代码。
**验证方法**：用户代码中不出现 Acuitylib 相关的 import 语句；接口设计参考行业标准（ONNX Runtime、TensorRT）。
### 5.2 关键工艺
无。
### 5.3 创新点
1. **供应商隔离的中间层设计**
Netrans 作为 Acuity 与用户之间的中间层，用户代码不直接依赖 Acuity。如果后续更换供应商，用户代码无需修改，只需替换 Netrans 底层实现。这为公司 AI 编译器工具链提供了供应商无关的演进路径。
2. **模型转换状态同步机制**
针对 Acuitylib 对象生命周期不一致的问题，设计 ModelMeta 封装和状态同步方案，实现 Python API 链式调用与底层库行为的正确衔接。
3. **复杂配置的简化封装体系**
针对 Acuitylib 配置复杂的问题，设计多层次的简化封装：多核环境自动管理、多框架统一导入接口、量化策略简化配置等，显著降低用户使用门槛。
4. **离线版工具链部署方案**
针对内网用户无法访问 PyPI 的问题，设计完整的离线安装机制，包含依赖打包、自动安装脚本和部署文档。
---
## 6 任务安排及分工建议
本项目软件开发和项目管理工作主要由软件部组织完成，关键项目里程碑由科研管理部组织实施。
---
## 7 项目组成员建议
### 7.1 项目经理
项目经理：XXX
### 7.2 项目人员及分工
| 序号 | 姓名 | 职称 | 部门及职位 | 分工建议 | 备注 |
|------|------|------|------------|----------|------|
| 1 | 隋强 | | 长城银河 | 项目经理 | |
| 2 | 许骄 | | 长城银河 | 软件开发 | |
| 3 | 欧高亮 | | 长城银河 | 产品定义及开发 | |
| 4 | 关洪涛 | | 长城银河 | 软件测试 | |
| 5 | 周倩 | 工程师 | 长城银河 | 项目管理 | |
---
## 8 进度安排
本项目周期为：2025年07月 - 2025年12月（6个月）
| 阶段 | 时间 | 主要工作 | 里程碑 | 交付物 |
|------|------|---------|--------|--------|
| 需求与设计 | 7月 | 需求分析、架构设计 | 完成需求评审 | 需求规格书 |
| 核心开发 | 8-9月 | 核心框架、导入、量化、导出 | 完成核心功能 | Alpha版本 |
| 接口与工具 | 10月 | CLI、Python API、调试工具 | 完成接口开发 | Beta版本 |
| 测试验证 | 11月 | 单元测试、集成测试、性能测试 | 完成测试 | 测试报告 |
| 文档与发布 | 12月 | 文档完善、打包发布 | 正式发布 | v1.0版本 |
---
## 9 成果要求
### 9.1 技术文件类成果
- 软件源码：netrans_cli、netrans_py
- CLI 参考手册
- Python API 参考手册
- 使用指南（Cookbook）
- 设计文档（AGENTS.md）
- 版本发布记录
### 9.2 实物类成果
无。
### 9.3 知识产权类成果
软件著作权：1 项
---
## 10 经费预算
本项目预算：5 万元。
| 类别 | 金额（万元） | 说明 |
|------|-------------|------|
| 人力成本 | 4 | 开发人员工资及福利 |
| 设备/软件 | 0.5 | 开发环境、测试设备 |
| 外协/咨询 | 0.3 | 技术支持、培训 |
| 其他 | 0.2 | 差旅、资料等 |
| **合计** | **5** | |
---
## 11 存在风险及控制措施
### 11.1 技术风险及控制措施
**性能优化风险**。优化算法效果可能不及预期。
控制措施：建立完善的测试体系，覆盖主流模型（ResNet、YOLO 等），定期与芯片团队对齐优化策略。
**模型精度风险**。转换过程中可能出现精度损失。
控制措施：建立量化精度评估流程，提供 dump 和 inference 工具帮助定位精度问题。
**框架兼容性风险**。深度学习框架版本更新快，可能导致兼容性问题。
控制措施：明确支持的框架版本范围，对不兼容情况提供明确的错误提示。
### 11.2 进度风险及控制措施
**工作量压力风险**。目前软件团队可支持该项目的开发人员有限（1人），工作量估算为 235 人天（约 5 人月），项目周期 6 个月，资源配置紧张。
控制措施：
1. 优先交付核心功能，非核心功能可延后
2. 保留完整的开发过程文档，确保其他开发人员能快速接手
3. 建立代码审查机制，确保至少 2 人熟悉核心代码
### 11.3 供应链风险及控制措施
**核心依赖风险**。本项目底层依赖 acuitylib（VeriSilicon 提供），存在供应商技术支持、版本更新、商业授权等风险。
控制措施：
1. **中间层隔离设计**：用户代码通过 Netrans API 调用，不直接依赖 Acuity，降低供应商绑定风险
2. **接口抽象**：Netrans 接口设计为供应商无关的，底层实现可替换
3. **多供应商预案**：预留其他供应商 SDK 的适配接口，如未来支持 NVIDIA TensorRT、ARM NN 等
4. **技术支持渠道**：与 VeriSilicon 建立稳定的技术支持渠道，及时获取版本更新和问题修复
### 11.4 资源配置风险及控制措施
目前软件团队可支持该项目的开发人员有限，存在人员流失导致项目停滞的风险。
控制措施：
1. 招聘有经验的工程师，及时补充团队核心成员
2. 在团队内发展复合技术人员
3. 保留完整的开发过程文档，确保其他开发人员能快速接手
4. 建立代码审查机制，确保至少 2 人熟悉核心代码
---
## 12 产品其它需求描述
无。
---
## 附录A：工具链成熟度评估
### A.1 成熟度等级定义
本评估模型参考 **TRL（Technology Readiness Level，技术成熟度）** 的简化版本，用于评估工具链的工程化完善程度：
| 等级 | 名称 | 典型特征 |
|------|------|----------|
| L1 | 概念级 | 技术概念已形成，基本原理可行 |
| L2 | 组件级 | 核心组件在实验室环境验证 |
| L3 | 系统级 | 完整系统在模拟环境验证，可运行但需专家操作 |
| L4 | 产品级 | 系统在真实环境验证，可交付，有文档和基础工具 |
| L5 | 成熟级 | 系统成熟，易用性好，有完整工具链和标准化流程 |
> **注**：WBS（Work Breakdown Structure，工作包结构）用于项目工作分解，参见附录 B。本节评估的是工具链成熟度，与 WBS 是两个独立概念。
### A.2 评估维度与现状分析
从六个维度评估 AI 编译器工具链的成熟度：
| 维度 | 说明 | Acuitylib现状 | Netrans目标 |
|------|------|---------------|-------------|
| 工具链完整性 | 从模型到芯片的端到端能力 | L3-L4 | L5 |
| 标准化程度 | 流程统一、配置规范 | L3 | L5 |
| 易用性 | 学习成本、操作简便性 | L3 | L5 |
| 可调试性 | 问题定位、调试工具 | L3 | L5 |
| 可维护性 | 代码质量、架构清晰 | L3 | L4 |
| 可扩展性 | 新需求支持、模块化 | L3 | L4 |
### A.3 成熟度提升的关键措施
| 维度 | 提升措施 | 对应WBS工作包 |
|------|---------|--------------|
| 工具链完整性 | 端到端标准化流程 | 130,140,150,160,170 |
| 标准化程度 | 统一YAML+CLI规范 | 121,132,210 |
| 易用性 | CLI+Python API双模式 | 123,190,213 |
| 可调试性 | dump/inference/measure工具链 | 180 |
| 可维护性 | 自主代码，模块化架构 | 122,133,214 |
| 可扩展性 | 配置驱动，分层架构 | 122,132 |
---
## 附录B：WBS工作分解结构
### B.1 WBS 结构图
```
Netrans 模型转换工具链开发项目 (100)
│
├── 1. 项目管理 (110)
│ ├── 111. 项目计划与跟踪
│ ├── 112. 需求管理
│ ├── 113. 配置管理
│ └── 114. 质量保证
│
├── 2. 需求与设计 (120)
│ ├── 121. 需求分析
│ ├── 122. 架构设计
│ ├── 123. 接口设计
│ └── 124. 技术方案评审
│
├── 3. 核心框架开发 (130)
│ ├── 131. Netrans核心类实现
│ ├── 132. 配置管理系统
│ ├── 133. 异常处理体系
│ ├── 134. 装饰器与工具函数
│ └── 135. 模型元数据管理
│
├── 4. 模型导入模块 (140)
│ ├── 141. Caffe导入器
│ ├── 142. TensorFlow导入器
│ ├── 143. ONNX导入器
│ ├── 144. PyTorch导入器
│ ├── 145. TFLite导入器
│ ├── 146. Darknet导入器
│ └── 147. Keras导入器
│
├── 5. 量化模块 (150)
│ ├── 151. 基础量化引擎
│ ├── 152. 多类型量化支持
│ ├── 153. 量化算法实现
│ ├── 154. 混合精度量化
│ └── 155. 激活权重量化分离
│
├── 6. 前后处理集成 (160)
│ ├── 161. 预处理嵌入
│ └── 162. 后处理嵌入
│
├── 7. NBG导出模块 (170)
│ ├── 171. PNNA平台导出
│ ├── 172. PNNA2平台导出
│ └── 173. 多核配置管理
│
├── 8. 调试分析工具 (180)
│ ├── 181. 张量导出工具
│ ├── 182. 推理验证工具
│ ├── 183. 性能测量工具
│ └── 184. Opset检查工具
│
├── 9. 接口层开发 (190)
│ ├── 191. Python API实现
│ ├── 192. CLI工具实现
│ └── 193. 命令行解析与帮助系统
│
├── 10. 测试验证 (200)
│ ├── 201. 单元测试
│ ├── 202. 集成测试
│ ├── 203. 性能测试
│ ├── 204. 示例工程
│ └── 205. 回归测试套件
│
├── 11. 文档与交付 (210)
│ ├── 211. API参考手册
│ ├── 212. CLI使用手册
│ ├── 213. 开发指南
│ ├── 214. 设计文档
│ ├── 215. 示例代码与教程
│ └── 216. 发布说明
│
└── 12. 产品化与维护 (220)
├── 221. 安装包制作
├── 222. CI/CD流程
├── 223. 版本管理
└── 224. 问题跟踪与修复
```
### B.2 工作量估算
| WBS编号 | 工作包 | 估算工时(人天) |
|---------|--------|----------------|
| 1.x | 项目管理 | 20 |
| 2.1 | 模型导入模块 | 30 |
| 2.2 | 模型量化模块 | 25 |
| 2.3 | 前后处理模块 | 15 |
| 2.4 | 模型导出模块 | 20 |
| 2.5 | 调试分析模块 | 15 |
| 3.1 | 命令行接口 | 15 |
| 3.2 | Python API | 20 |
| 4.x | 测试与质量保证 | 40 |
| 5.x | 文档编制 | 25 |
| 6.x | 部署与发布 | 10 |
| **合计** | | **235人天**（约5人月） |
---
*文档结束*

561
docs/pmf/产品需求规格书-Netrans软件-v3.md
View File

@ -1,561 +0,0 @@
# Netrans软件 产品需求规格书
> 版本：v3.0
> 日期：2026-03-23
---
## 1 项目概述
本项目旨在开发一套面向 PNNA 芯片的 AI 模型转换工具链，提供命令行工具 **netrans** 和 Python API **netrans_py**，支持将 TensorFlow、PyTorch、ONNX 等多种深度学习框架的模型转换为 PNNA NPU 可执行的 NBG（Network Binary Graph）格式。
本软件基于 Acuitylib 构建，通过上层封装和流程整合，解决直接使用底层库时的易用性、标准化和可调试性问题，形成完整的产品级工具链。
### 1.1 术语及定义
| 术语 | 定义 |
|------|------|
| PNNA | Programmable Neural Network Accelerator，可编程神经网络加速器 |
| NBG | Network Binary Graph，网络二进制图，PNNA 芯片可执行的模型格式 |
| NPU | Neural Processing Unit，神经网络处理单元 |
| Acuitylib | VeriSilicon 提供的神经网络编译库 |
| 量化 | 将浮点模型转换为定点模型的过程，减少模型大小和计算量 |
| Hybrid 量化 | 混合精度量化，对不同层使用不同精度 |
---
## 2 引用文件
无。
---
## 3 研究内容
### 3.1 模型转换流程的状态管理
研究模型转换多阶段流水线中的状态传递机制。Acuitylib 的量化操作返回新的网络对象而非修改原对象，需要设计可靠的状态同步方案，确保 Python API 链式调用时各阶段使用的是正确的模型状态。
### 3.2 前后处理配置的简化
研究 Acuitylib 前后处理配置的简化方法。Acuity 需要手动从量化文件提取参数、修改多个 YAML 文件的特定位置，操作复杂易错。需要设计一键化配置机制，自动完成参数提取和文件修改。
### 3.3 复杂配置的简化封装
研究 Acuitylib 复杂配置的简化方法。包括：多核环境变量的自动管理、多框架导入的统一接口、量化参数的简化配置、平台差异的透明处理等，降低用户使用门槛。
### 3.4 离线版工具链部署
研究内网环境下的工具链部署方案。外网用户可通过 pip 安装依赖，内网用户需要离线安装包和本地化依赖管理，需要设计完整的离线部署机制。
### 3.5 供应商解耦的接口设计
研究用户代码与底层 SDK 的解耦方法。通过设计统一的接口层，使用户代码不直接依赖特定供应商的库，为未来可能的供应商切换预留空间，降低供应商绑定风险。
---
## 4 技术要求
### 4.1 硬件要求
无特殊硬件要求。开发环境为通用 x86_64 Linux 服务器。
### 4.2 软件要求
#### 4.2.1 开发环境
- 操作系统：Linux（推荐 Ubuntu 20.04+）
- Python 版本：Python 3.10
- 核心依赖：numpy、protobuf、tensorflow、torch、onnx、acuitylib（>=6.33.0）
#### 4.2.2 功能要求
**模型导入功能**
系统应支持从多种深度学习框架导入模型：
- TensorFlow（.pb 格式，需配合 inputs_outputs.txt 指定输入输出）
- TensorFlow Lite（.tflite 格式）
- PyTorch（.pt 格式，通过 ONNX 后端转换）
- ONNX（.onnx 格式，支持 opset 7-17）
- Caffe（.prototxt + .caffemodel 格式）
- Darknet（.cfg + .weights 格式，支持 YOLO 系列）
- Keras（.h5 格式）
导入过程应完成模型解析、权重提取、中间表示生成，并输出网络结构描述文件（.json）和权重数据文件（.data）。
**模型量化功能**
系统应支持多种量化策略：
- 非对称 8 位量化（asymu8）：适用于通用场景，精度与性能平衡
- 对称 8 位量化（symi8）：适用于对称数据分布的模型
- 对称 16 位量化（symi16）：适用于高精度需求场景
- 混合精度量化（hybrid）：对敏感层使用高精度，其他层使用低精度
- 激活权重量化分离（AI16WI8/AI16WI4）：激活和权重使用不同精度
量化过程应支持多种校准算法：普通量化（normal）、KL 散度量化（kl_divergence）、移动平均量化（moving_average）、自动选择（auto）。
**前后处理集成功能**
系统应支持将预处理和后处理节点嵌入网络图：
- 预处理集成：将 mean/scale 归一化操作嵌入网络输入节点
- 后处理集成：将反量化操作嵌入网络输出节点
集成后生成的 NBG 文件可直接接受原始数据输入（如 uint8 图像），无需应用层额外处理。
**模型导出功能**
系统应支持将优化和量化后的模型导出为 PNNA 芯片可执行的 NBG 格式：
- 支持单核和多核配置（1-4 核 VIP 模式）
- 支持多平台优化（pnna: VIP8000 系列，pnna2: VIP9400 系列）
- 导出过程应生成 NBG 二进制文件、元数据文件和示例 C 代码
**调试分析功能**
系统应提供调试和分析工具：
- 张量导出（dump）：导出每层输入输出张量，用于精度对比
- 推理验证（inference）：执行前向推理，保存输入输出作为 golden 数据
- 性能测量（measure）：统计模型计算量（FLOPs）和内存占用
- Opset 检查（check_opset）：检查 ONNX 模型的 opset 版本兼容性
#### 4.2.3 接口要求
**命令行接口（netrans）**
系统应提供完整的命令行工具：
- `netrans load`：模型导入
- `netrans quantize`：模型量化
- `netrans quantize_hybrid`：混合精度量化
- `netrans add_pre_post`：前后处理集成
- `netrans export`：NBG 导出
- `netrans dump`：张量导出
- `netrans inference`：推理验证
- `netrans measure`：性能测量
- `netrans check_opset`：Opset 检查
**Python API（netrans_py）**
系统应提供 Python API，支持集成到训练流水线：
- `Netrans` 类：主类，封装完整的模型处理流水线
- `load()`、`quantize()`、`quantize_hybrid()`、`add_pre_post()`、`export()`、`dump()`、`inference()` 等方法
### 4.3 结构要求
无。
### 4.4 主要性能及可靠性指标要求
| 指标类别 | 指标项 | 要求 | 验证方法 |
|----------|--------|------|----------|
| 转换效率 | 大模型转换时间 | ResNet50 量化导出 < 5 分钟 | 标准开发环境实测 |
| 优化效果 | 模型压缩率 | asymu8 量化后模型大小减少 > 70% | 对比 .onnx 与 .nb 文件大小 |
| 量化精度 | 分类精度损失 | ResNet50 Top-1 精度损失 < 1% | ImageNet 验证集测试 |
| 量化精度 | 检测精度损失 | YOLOv5s mAP 下降 < 1% | COCO 验证集测试 |
| 资源占用 | 内存使用 | 转换过程峰值内存 < 模型大小 × 3 | 内存监控 |
| 易用性 | 学习成本 | 新用户 30 分钟内完成首次转换 | 用户测试 |
### 4.5 认证测试要求
无。
### 4.6 环境要求
无特殊环境要求。
### 4.7 非功能要求
**性能方面**
- 命令行工具冷启动时间 < 1 秒
- 支持大模型（>100MB）的高效转换
- 量化过程充分利用多核 CPU 并行计算
**安全性方面**
- 转换过程不修改原始模型文件
- 临时文件自动清理，敏感数据不残留
- 错误信息不暴露内部实现细节
**可用性方面**
- 错误信息明确指示问题原因和解决建议
- CLI 支持 `--verbose` 输出详细调试信息
- 提供完整的用户文档和示例代码
**可靠性方面**
- 转换过程异常中断时不损坏原始模型文件
- 关键操作前自动备份配置文件
- 支持断点续传（量化后的模型可重复导出）
**兼容性方面**
- 支持 TensorFlow >= 2.x、PyTorch >= 1.8、ONNX >= 1.10
- 支持 ONNX opset 7-17
- Python API 支持类型注解
**可维护性方面**
- 代码遵循 Python PEP 8 规范
- 关键函数有完整的 docstring
- 测试覆盖率 > 80%
**可移植性方面**
- 架构设计考虑底层库的兼容性
- 供应商相关代码集中封装，与核心逻辑解耦
- 接口设计遵循通用原则，降低迁移成本
### 4.8 关键器件及外协要求
无。
### 4.9 产品其它技术需求
**依赖说明**
本软件核心依赖 acuitylib（VeriSilicon 提供的神经网络编译库），需确保版本 >= 6.33.0。acuitylib 需要特定版本的 libstdc++（CXXABI_1.3.15），需通过 conda 环境管理。
**导入顺序要求**
由于 libstdc++ 版本冲突，用户代码必须先导入 netrans，再导入 tensorflow。
**平台支持**
本软件运行在 x86_64 Linux 开发环境，生成的 NBG 文件运行在 PNNA 芯片（ARM/DSP 平台）。
---
## 5 关键技术/工艺及创新点
### 5.1 关键技术
1. **模型转换状态同步机制**
**问题描述**：Acuitylib 的 `nn.quantize()` 返回新的网络对象，原对象保持不变。Netrans 的 Python API 需要支持链式调用（`model.load().quantize().export()`），如果未正确更新引用，导出的是浮点网络而非量化网络，导致 NBG 文件大小异常。
**解决方案**：设计 ModelMeta 不可变数据类，量化操作后创建新的实例。`quantize()` 方法内部更新 `self._meta` 引用，对用户无感知。
**验证方法**：链式调用与命令行分步执行生成的 NBG 文件大小一致，量化后比浮点小约 75%。
2. **前后处理配置的简化**
**问题描述**：Acuitylib 的前后处理集成需要用户手动：1）从 .quantize 文件提取输入层量化参数；2）修改 `_inputmeta.yml` 添加 `preproc_node_params`；3）修改 `_postprocess_file.yml` 添加 `postproc_params`。涉及多个文件、多个参数，格式要求严格，操作复杂易错。
**解决方案**：`add_pre_post()` 函数自动完成上述操作：读取量化参数、生成正确的 YAML 结构、写入对应位置。用户只需调用一个函数，无需了解配置文件细节。
**验证方法**：调用 `add_pre_post()` 后，检查 `_inputmeta.yml` 和 `_postprocess_file.yml` 中配置正确；导出后的 NBG 可直接接收 uint8 输入。
3. **多核环境配置简化**
**问题描述**：PNNA2 多核配置需要设置 `VIV_MGPU_AFFINITY` 和 `VIV_OVX_MULTI_DEVICES` 环境变量，格式复杂（如 `1:4` 和 `0:4-1`），且是进程级全局设置，容易影响其他操作。
**解决方案**：设计 `_set_multicore_env()` 函数，根据 `core_num` 参数（如 `'4core'`）自动计算并设置环境变量，导出后恢复。用户只需传递简单参数，无需了解环境变量细节。
**验证方法**：设置 4 核配置后导出，检查 NBG 多核元数据正确；同进程其他导出操作不受影响的单核配置。
4. **模型导入接口统一**
**问题描述**：Acuitylib 对不同框架（TensorFlow、PyTorch、ONNX 等）有不同的导入函数和参数要求，用户需要了解各框架的细节差异。
**解决方案**：设计统一的 `load()` 接口，自动识别模型格式并调用对应的 Acuitylib 导入函数。通过文件扩展名和内容检测，自动选择正确的导入器。
**验证方法**：同一 `load()` 接口可正确导入 7 种框架的模型，无需用户指定框架类型。
5. **供应商解耦的接口设计**
**问题描述**：用户代码直接依赖 Acuitylib，存在供应商绑定风险。如果未来更换供应商，用户代码需要大量修改。
**解决方案**：设计统一的接口层，用户代码通过 Netrans API 调用，不直接依赖 Acuitylib。底层实现封装在独立模块，可替换而不影响用户代码。
**验证方法**：用户代码中不出现 Acuitylib 相关的 import 语句；接口设计参考行业标准（ONNX Runtime、TensorRT）。
### 5.2 关键工艺
无。
### 5.3 创新点
1. **模型转换状态同步机制**
针对 Acuitylib 对象生命周期不一致的问题，设计 ModelMeta 封装和状态同步方案，实现 Python API 链式调用与底层库行为的正确衔接。
2. **前后处理配置的简化**
针对 Acuitylib 前后处理配置复杂的问题，设计自动化的参数提取和配置文件修改方案，将多步骤手动操作简化为一键调用。
3. **复杂配置的简化封装体系**
针对 Acuitylib 配置复杂的问题，设计多层次的简化封装：多核环境自动管理、多框架统一导入接口、量化策略简化配置等，显著降低用户使用门槛。
4. **离线版工具链部署方案**
针对内网用户无法访问 PyPI 的问题，设计完整的离线安装机制，包含依赖打包、自动安装脚本和部署文档。
5. **供应商解耦的接口设计**
通过统一的接口层设计，使用户代码与底层 SDK 解耦，降低供应商绑定风险，为未来可能的供应商切换预留空间。
---
## 6 任务安排及分工建议
本项目软件开发和项目管理工作主要由软件部组织完成，关键项目里程碑由科研管理部组织实施。
---
## 7 项目组成员建议
### 7.1 项目经理
项目经理：XXX
### 7.2 项目人员及分工
| 序号 | 姓名 | 职称 | 部门及职位 | 分工建议 | 备注 |
|------|------|------|------------|----------|------|
| 1 | 隋强 | | 长城银河 | 项目经理 | |
| 2 | 许骄 | | 长城银河 | 软件开发 | |
| 3 | 欧高亮 | | 长城银河 | 产品定义及开发 | |
| 4 | 关洪涛 | | 长城银河 | 软件测试 | |
| 5 | 周倩 | 工程师 | 长城银河 | 项目管理 | |
---
## 8 进度安排
本项目周期为：2025年07月 - 2025年12月（6个月）
| 阶段 | 时间 | 主要工作 | 里程碑 | 交付物 |
|------|------|---------|--------|--------|
| 需求与设计 | 7月 | 需求分析、架构设计 | 完成需求评审 | 需求规格书 |
| 核心开发 | 8-9月 | 核心框架、导入、量化、导出 | 完成核心功能 | Alpha版本 |
| 接口与工具 | 10月 | CLI、Python API、调试工具 | 完成接口开发 | Beta版本 |
| 测试验证 | 11月 | 单元测试、集成测试、性能测试 | 完成测试 | 测试报告 |
| 文档与发布 | 12月 | 文档完善、打包发布 | 正式发布 | v1.0版本 |
---
## 9 成果要求
### 9.1 技术文件类成果
- 软件源码：netrans_cli、netrans_py
- CLI 参考手册
- Python API 参考手册
- 使用指南（Cookbook）
- 设计文档（AGENTS.md）
- 版本发布记录
### 9.2 实物类成果
无。
### 9.3 知识产权类成果
软件著作权：1 项
---
## 10 经费预算
本项目预算：5 万元。
| 类别 | 金额（万元） | 说明 |
|------|-------------|------|
| 人力成本 | 4 | 开发人员工资及福利 |
| 设备/软件 | 0.5 | 开发环境、测试设备 |
| 外协/咨询 | 0.3 | 技术支持、培训 |
| 其他 | 0.2 | 差旅、资料等 |
| **合计** | **5** | |
---
## 11 存在风险及控制措施
### 11.1 技术风险及控制措施
**性能优化风险**。优化算法效果可能不及预期。
控制措施：建立完善的测试体系，覆盖主流模型（ResNet、YOLO 等），定期与芯片团队对齐优化策略。
**模型精度风险**。转换过程中可能出现精度损失。
控制措施：建立量化精度评估流程，提供 dump 和 inference 工具帮助定位精度问题。
**框架兼容性风险**。深度学习框架版本更新快，可能导致兼容性问题。
控制措施：明确支持的框架版本范围，对不兼容情况提供明确的错误提示。
### 11.2 进度风险及控制措施
**工作量压力风险**。目前软件团队可支持该项目的开发人员有限（1人），工作量估算为 235 人天（约 5 人月），项目周期 6 个月，资源配置紧张。
控制措施：
1. 优先交付核心功能，非核心功能可延后
2. 保留完整的开发过程文档，确保其他开发人员能快速接手
3. 建立代码审查机制，确保至少 2 人熟悉核心代码
### 11.3 供应链风险及控制措施
**核心依赖风险**。本项目底层依赖 acuitylib（VeriSilicon 提供），存在供应商技术支持、版本更新、商业授权等风险。
控制措施：
1. 与 VeriSilicon 建立稳定的技术支持渠道，及时获取版本更新和问题修复
2. 通过统一的接口层设计，使用户代码与底层 SDK 解耦，降低供应商绑定风险
3. 调研备选方案，评估迁移成本
### 11.4 资源配置风险及控制措施
目前软件团队可支持该项目的开发人员有限，存在人员流失导致项目停滞的风险。
控制措施：
1. 招聘有经验的工程师，及时补充团队核心成员
2. 在团队内发展复合技术人员
3. 保留完整的开发过程文档，确保其他开发人员能快速接手
4. 建立代码审查机制，确保至少 2 人熟悉核心代码
---
## 12 产品其它需求描述
无。
---
## 附录A：工具链成熟度评估
### A.1 成熟度等级定义
本评估模型参考技术成熟度（TRL）的简化版本，用于评估工具链的工程化完善程度：
| 等级 | 名称 | 典型特征 |
|------|------|----------|
| L1 | 概念级 | 技术概念已形成，基本原理可行 |
| L2 | 组件级 | 核心组件在实验室环境验证 |
| L3 | 系统级 | 完整系统在模拟环境验证，可运行但需专家操作 |
| L4 | 产品级 | 系统在真实环境验证，可交付，有文档和基础工具 |
| L5 | 成熟级 | 系统成熟，易用性好，有完整工具链和标准化流程 |
### A.2 评估维度与现状分析
从六个维度评估 AI 编译器工具链的成熟度：
| 维度 | 说明 | Acuitylib现状 | Netrans目标 |
|------|------|---------------|-------------|
| 工具链完整性 | 从模型到芯片的端到端能力 | L3-L4 | L5 |
| 标准化程度 | 流程统一、配置规范 | L3 | L5 |
| 易用性 | 学习成本、操作简便性 | L3 | L5 |
| 可调试性 | 问题定位、调试工具 | L3 | L5 |
| 可维护性 | 代码质量、架构清晰 | L3 | L4 |
| 可扩展性 | 新需求支持、模块化 | L3 | L4 |
### A.3 成熟度提升的关键措施
| 维度 | 提升措施 | 对应WBS工作包 |
|------|---------|--------------|
| 工具链完整性 | 端到端标准化流程 | 130,140,150,160,170 |
| 标准化程度 | 统一YAML+CLI规范 | 121,132,210 |
| 易用性 | CLI+Python API双模式 | 123,190,213 |
| 可调试性 | dump/inference/measure工具链 | 180 |
| 可维护性 | 自主代码，模块化架构 | 122,133,214 |
| 可扩展性 | 配置驱动，分层架构 | 122,132 |
---
## 附录B：WBS工作分解结构
### B.1 WBS 结构图
```
Netrans 模型转换工具链开发项目 (100)
│
├── 1. 项目管理 (110)
│ ├── 111. 项目计划与跟踪
│ ├── 112. 需求管理
│ ├── 113. 配置管理
│ └── 114. 质量保证
│
├── 2. 需求与设计 (120)
│ ├── 121. 需求分析
│ ├── 122. 架构设计
│ ├── 123. 接口设计
│ └── 124. 技术方案评审
│
├── 3. 核心框架开发 (130)
│ ├── 131. Netrans核心类实现
│ ├── 132. 配置管理系统
│ ├── 133. 异常处理体系
│ ├── 134. 装饰器与工具函数
│ └── 135. 模型元数据管理
│
├── 4. 模型导入模块 (140)
│ ├── 141. Caffe导入器
│ ├── 142. TensorFlow导入器
│ ├── 143. ONNX导入器
│ ├── 144. PyTorch导入器
│ ├── 145. TFLite导入器
│ ├── 146. Darknet导入器
│ └── 147. Keras导入器
│
├── 5. 量化模块 (150)
│ ├── 151. 基础量化引擎
│ ├── 152. 多类型量化支持
│ ├── 153. 量化算法实现
│ ├── 154. 混合精度量化
│ └── 155. 激活权重量化分离
│
├── 6. 前后处理集成 (160)
│ ├── 161. 预处理嵌入
│ └── 162. 后处理嵌入
│
├── 7. NBG导出模块 (170)
│ ├── 171. PNNA平台导出
│ ├── 172. PNNA2平台导出
│ └── 173. 多核配置管理
│
├── 8. 调试分析工具 (180)
│ ├── 181. 张量导出工具
│ ├── 182. 推理验证工具
│ ├── 183. 性能测量工具
│ └── 184. Opset检查工具
│
├── 9. 接口层开发 (190)
│ ├── 191. Python API实现
│ ├── 192. CLI工具实现
│ └── 193. 命令行解析与帮助系统
│
├── 10. 测试验证 (200)
│ ├── 201. 单元测试
│ ├── 202. 集成测试
│ ├── 203. 性能测试
│ ├── 204. 示例工程
│ └── 205. 回归测试套件
│
├── 11. 文档与交付 (210)
│ ├── 211. API参考手册
│ ├── 212. CLI使用手册
│ ├── 213. 开发指南
│ ├── 214. 设计文档
│ ├── 215. 示例代码与教程
│ └── 216. 发布说明
│
└── 12. 产品化与维护 (220)
├── 221. 安装包制作
├── 222. CI/CD流程
├── 223. 版本管理
└── 224. 问题跟踪与修复
```
### B.2 工作量估算
| WBS编号 | 工作包 | 估算工时(人天) |
|---------|--------|----------------|
| 1.x | 项目管理 | 20 |
| 2.1 | 模型导入模块 | 30 |
| 2.2 | 模型量化模块 | 25 |
| 2.3 | 前后处理模块 | 15 |
| 2.4 | 模型导出模块 | 20 |
| 2.5 | 调试分析模块 | 15 |
| 3.1 | 命令行接口 | 15 |
| 3.2 | Python API | 20 |
| 4.x | 测试与质量保证 | 40 |
| 5.x | 文档编制 | 25 |
| 6.x | 部署与发布 | 10 |
| **合计** | | **235人天**（约5人月） |
---
*文档结束*

584
docs/pmf/产品需求规格书-Netrans软件-v4.md
View File

@ -1,584 +0,0 @@
# Netrans软件 产品需求规格书
> 版本：v4.0
> 日期：2026-03-23
---
## 1 项目概述
本项目旨在开发一套面向 PNNA 芯片的 AI 模型转换工具链，提供命令行工具 netrans 和 Python API netrans_py，支持将 TensorFlow、PyTorch、ONNX 等多种深度学习框架的模型转换为 PNNA NPU 可执行的 NBG（Network Binary Graph）格式。
本软件基于 Acuitylib 构建，通过上层封装和流程整合，解决直接使用底层库时的易用性、标准化和可调试性问题，形成完整的产品级工具链。
### 1.1 术语及定义
| 术语 | 定义 |
|------|------|
| PNNA | Programmable Neural Network Accelerator，可编程神经网络加速器 |
| NBG | Network Binary Graph，网络二进制图，PNNA 芯片可执行的模型格式 |
| NPU | Neural Processing Unit，神经网络处理单元 |
| Acuitylib | VeriSilicon 提供的神经网络编译库 |
| 量化 | 将浮点模型转换为定点模型的过程，减少模型大小和计算量 |
| Hybrid 量化 | 混合精度量化，对不同层使用不同精度 |
| WB 成熟度 | Workbench 成熟度，评估工具链工程化完善程度的 1-5 级模型 |
---
## 2 引用文件
无。
---
## 3 研究内容
### 3.1 业务逻辑的封装与简化
研究 Acuitylib 复杂业务逻辑的封装方法。包括：输入输出文件名的自动推导、工作目录的自动管理、临时文件的自动清理、错误信息的友好转换等基础封装，使用户无需了解底层细节即可调用 Acuitylib 功能。
### 3.2 模型转换流程的状态管理
研究模型转换多阶段流水线中的状态传递机制。Acuitylib 的量化操作返回新的网络对象而非修改原对象，需要设计可靠的状态同步方案，确保 Python API 链式调用和 CLI 分步调用时各阶段使用的是正确的模型状态。
### 3.3 复杂配置的简化封装
研究 Acuitylib 复杂配置的简化方法。包括：多框架导入的统一接口、多核环境变量的自动管理、Vivante SDK 路径的自动配置、平台差异的透明处理等，将环境变量和 SDK 管理等底层配置转化为简单参数。
### 3.4 导出配置的简化封装
研究 Acuitylib 导出配置的简化方法。Acuity 需要通过环境变量配置平台（pnna/pnna2）和 Vivante SDK 路径，且多核配置复杂。需要设计参数化的导出接口，自动管理环境配置和 SDK 调用，避免污染用户环境。
### 3.5 前后处理配置的简化
研究 Acuitylib 前后处理配置的简化方法。Acuity 需要手动从量化文件提取参数、修改多个 YAML 文件的特定位置，操作复杂易错。需要设计一键化配置机制，自动完成参数提取和文件修改。
### 3.6 离线版工具链部署
研究内网环境下的工具链部署方案。外网用户可通过 pip 安装依赖，内网用户需要离线安装包和本地化依赖管理，需要设计完整的离线部署机制。
---
## 4 技术要求
### 4.1 硬件要求
无特殊硬件要求。开发环境为通用 x86_64 Linux 服务器。
### 4.2 软件要求
#### 4.2.1 开发环境
- 操作系统：Linux（推荐 Ubuntu 20.04+）
- Python 版本：Python 3.10
- 核心依赖：numpy、protobuf、tensorflow、torch、onnx、acuitylib（>=6.33.0）
#### 4.2.2 功能要求
模型导入功能
系统应支持从多种深度学习框架导入模型：
- TensorFlow（.pb 格式，需配合 inputs_outputs.txt 指定输入输出）
- TensorFlow Lite（.tflite 格式）
- PyTorch（.pt 格式，通过 ONNX 后端转换）
- ONNX（.onnx 格式，支持 opset 7-17）
- Caffe（.prototxt + .caffemodel 格式）
- Darknet（.cfg + .weights 格式，支持 YOLO 系列）
- Keras（.h5 格式）
导入过程应完成模型解析、权重提取、中间表示生成，并输出网络结构描述文件（.json）和权重数据文件（.data）。
模型量化功能
系统应支持多种量化策略：
- 非对称 8 位量化（asymu8）：适用于通用场景，精度与性能平衡
- 对称 8 位量化（symi8）：适用于对称数据分布的模型
- 对称 16 位量化（symi16）：适用于高精度需求场景
- 混合精度量化（hybrid）：对敏感层使用高精度，其他层使用低精度
- 激活权重量化分离（AI16WI8/AI16WI4）：激活和权重使用不同精度
量化过程应支持多种校准算法：普通量化（normal）、KL 散度量化（kl_divergence）、移动平均量化（moving_average）、自动选择（auto）。
前后处理集成功能
系统应支持将预处理和后处理节点嵌入网络图：
- 预处理集成：将 mean/scale 归一化操作嵌入网络输入节点
- 后处理集成：将反量化操作嵌入网络输出节点
集成后生成的 NBG 文件可直接接受原始数据输入（如 uint8 图像），无需应用层额外处理。
模型导出功能
系统应支持将优化和量化后的模型导出为 PNNA 芯片可执行的 NBG 格式：
- 支持单核和多核配置（1-4 核 VIP 模式）
- 支持多平台优化（pnna: VIP8000 系列，pnna2: VIP9400 系列）
- 导出过程应生成 NBG 二进制文件、元数据文件和示例 C 代码
调试分析功能
系统应提供调试和分析工具：
- 张量导出（dump）：导出每层输入输出张量，用于精度对比
- 推理验证（inference）：执行前向推理，保存输入输出作为 golden 数据
- 性能测量（measure）：统计模型计算量（FLOPs）和内存占用
- ONNX Opset 兼容性检查（check_opset）：检查 ONNX 模型的 opset 版本是否在支持范围内（7-17），提前发现兼容性问题，避免导入失败
#### 4.2.3 接口要求
命令行接口（netrans）
系统应提供完整的命令行工具：
- `netrans load`：模型导入
- `netrans quantize`：模型量化
- `netrans quantize_hybrid`：混合精度量化
- `netrans add_pre_post`：前后处理集成
- `netrans export`：NBG 导出
- `netrans dump`：张量导出
- `netrans inference`：推理验证
- `netrans measure`：性能测量
- `netrans check_opset`：ONNX Opset 兼容性检查
Python API（netrans_py）
系统应提供 Python API，支持集成到训练流水线：
- `Netrans` 类：主类，封装完整的模型处理流水线
- `load()`、`quantize()`、`quantize_hybrid()`、`add_pre_post()`、`export()`、`dump()`、`inference()` 等方法
### 4.3 结构要求
无。
### 4.4 主要可靠性及易用性指标要求
| 指标类别 | 指标项 | 要求 | 验证方法 |
|----------|--------|------|----------|
| 易用性 | 学习成本 | 新用户参照快速入门指南，30 分钟内完成首次模型转换 | 用户测试 |
| 易用性 | 操作简洁性 | 完成完整转换流程仅需 3-4 个 API 调用或 1 条 CLI 命令 | 代码审查 |
| 易用性 | 错误提示 | 错误信息明确指出问题原因和解决建议 | 错误注入测试 |
| 可靠性 | 状态一致性 | Python API 链式调用与 CLI 分步执行生成的 NBG 文件一致 | 自动化测试 |
| 可靠性 | 配置生效性 | add_pre_post 后导出的 NBG 可直接接收 uint8 原始输入 | 功能测试 |
| 鲁棒性 | 异常处理 | 无效输入或异常操作时给出明确错误信息，不崩溃 | 边界测试 |
| 鲁棒性 | 参数校验 | 必填参数缺失或格式错误时提前报错，不进入 Acuity 运算 | 单元测试 |
### 4.5 认证测试要求
无。
### 4.6 环境要求
无特殊环境要求。
### 4.7 非功能要求
易用性方面
- 提供快速入门指南，新用户 30 分钟内完成首次转换
- 错误信息明确指示问题原因和解决建议
- CLI 支持 `--verbose` 输出详细调试信息
- 提供完整的用户文档和示例代码
可靠性方面
- 转换过程异常中断时不损坏原始模型文件
- 关键操作前自动备份配置文件
- 支持断点续传（量化后的模型可重复导出）
- Python API 链式调用与 CLI 分步执行结果一致
鲁棒性方面
- 对输入参数进行严格校验，无效输入提前报错
- 错误处理完善，异常情况不崩溃
- 保护用户免受底层库复杂性困扰
兼容性方面
- 支持 TensorFlow >= 2.x、PyTorch >= 1.8、ONNX >= 1.10
- 支持 ONNX opset 7-17
- Python API 支持类型注解
可维护性方面
- 代码遵循 Python PEP 8 规范
- 关键函数有完整的 docstring
- 测试覆盖率 > 80%
可移植性方面
- 架构设计考虑底层库的兼容性
- 核心逻辑与供应商相关代码解耦
- 接口设计遵循通用原则，降低迁移成本
### 4.8 关键器件及外协要求
无。
### 4.9 产品其它技术需求
无。
---
## 5 关键技术/工艺及创新点
### 5.1 关键技术
1. 模型转换状态同步机制
问题描述：Acuitylib 的 `nn.quantize()` 返回新的网络对象，原对象保持不变。Python API 需要支持链式调用（`model.load().quantize().export()`），如果未正确更新引用，导出的是浮点网络而非量化网络。CLI 分步执行（`netrans quantize` 后 `netrans export`）也存在同样问题，需要确保状态正确传递。
解决方案：Python API 设计 ModelMeta 不可变数据类，量化操作后创建新的实例，`quantize()` 方法内部更新 `self._meta` 引用。CLI 通过磁盘文件（.quantize）保存状态，导出时加载量化后的模型而非原始模型。
验证方法：Python API 链式调用与 CLI 分步执行生成的 NBG 文件大小一致，量化后比浮点小约 75%。
2. 前后处理配置的简化
问题描述：Acuitylib 的前后处理集成需要用户手动：1）从 .quantize 文件提取输入层量化参数；2）修改 `_inputmeta.yml` 添加 `preproc_node_params`；3）修改 `_postprocess_file.yml` 添加 `postproc_params`。涉及多个文件、多个参数，格式要求严格，操作复杂易错。
解决方案：`add_pre_post()` 函数自动完成上述操作：读取量化参数、生成正确的 YAML 结构、写入对应位置。用户只需调用一个函数，无需了解配置文件细节。
验证方法：调用 `add_pre_post()` 后，检查 `_inputmeta.yml` 和 `_postprocess_file.yml` 中配置正确；导出后的 NBG 可直接接收 uint8 输入。
3. 多核环境配置简化
问题描述：PNNA2 多核配置需要设置 `VIV_MGPU_AFFINITY` 和 `VIV_OVX_MULTI_DEVICES` 环境变量，格式复杂（如 `1:4` 和 `0:4-1`），且是进程级全局设置，容易影响其他操作。
解决方案：设计 `_set_multicore_env()` 函数，根据 `core_num` 参数（如 `'4core'`）自动计算并设置环境变量，导出后恢复。用户只需传递简单参数，无需了解环境变量细节。
验证方法：设置 4 核配置后导出，检查 NBG 多核元数据正确；同进程其他导出操作不受影响的单核配置。
4. 模型导入接口统一
问题描述：Acuitylib 对不同框架（TensorFlow、PyTorch、ONNX 等）有不同的导入函数和参数要求，用户需要了解各框架的细节差异。
解决方案：设计统一的 `load()` 接口，自动识别模型格式并调用对应的 Acuitylib 导入函数。通过文件扩展名和内容检测，自动选择正确的导入器。
验证方法：同一 `load()` 接口可正确导入 7 种框架的模型，无需用户指定框架类型。
5. 导出配置的简化封装
问题描述：Acuitylib 的导出需要通过环境变量配置平台（`optimize` 参数对应 pnna/pnna2），且 pnna2 多核导出需要 Vivante SDK。用户需要手动设置环境变量和 `VIV_SDK_PATH`，容易出错且污染全局环境。
解决方案：`export()` 通过 `platform` 参数（`'pnna'` 或 `'pnna2'`）自动选择平台配置；根据 `platform` 和 `core_num` 自动判断是否需要 Vivante SDK；安装时自动配置 `VIV_SDK_PATH` 到环境变量；导出时临时设置环境变量，避免污染用户环境。
验证方法：用户只需指定 `platform='pnna2'` 和 `core_num='4core'`，无需手动设置环境变量；pnna 单核导出不依赖 Vivante SDK；导出后用户环境变量保持不变。
6. Vivante SDK 环境配置简化
问题描述：PNNA2 平台导出多核 NBG 需要 Vivante SDK，用户需要手动设置 `VIV_SDK_PATH` 环境变量，且需要了解何时需要 SDK（仅 pnna2 多核需要，pnna 单核不需要）。
解决方案：安装时自动检测并配置 `VIV_SDK_PATH` 到 `~/.bashrc`；`export()` 根据 `platform` 和 `core_num` 参数自动判断是否需要 SDK，无需用户关心。
验证方法：安装后 `VIV_SDK_PATH` 自动设置；导出时 pnna 平台不依赖 SDK，pnna2 多核自动使用 SDK。
7. 业务逻辑封装
问题描述：Acuitylib 需要用户管理多个文件名、工作目录、临时文件等细节。如输入输出文件名需手动指定，工作目录切换容易出错，临时文件需要手动清理。
解决方案：`@chdir` 装饰器自动管理模型目录；文件名从模型路径自动推导；临时文件使用上下文管理器自动清理；错误信息转换为友好提示。
验证方法：用户只需提供模型目录路径，无需指定具体文件名；异常时当前目录正确恢复；临时文件自动清理。
8. 依赖库版本冲突解决
问题描述：acuitylib 需要 libstdc++ CXXABI_1.3.15（conda 环境），tensorflow 会加载系统 libstdc++ CXXABI_1.3.13。如果先导入 tensorflow，acuitylib 将无法加载，导致导入失败。
解决方案：在 `config.py` 中强制控制导入顺序，确保先加载 acuitylib 再加载 tensorflow。通过设置 `CUDA_VISIBLE_DEVICES=""` 禁用 GPU，避免 tensorflow 初始化时加载冲突库。
验证方法：`import tensorflow; from netrans import Netrans` 失败；`from netrans import Netrans; import tensorflow` 成功。
### 5.2 关键工艺
无。
### 5.3 创新点
1. 模型转换状态同步机制
针对 Acuitylib 对象生命周期不一致的问题，设计 ModelMeta 封装和状态同步方案，实现 Python API 链式调用与底层库行为的正确衔接。
2. 前后处理配置的简化
针对 Acuitylib 前后处理配置复杂的问题，设计自动化的参数提取和配置文件修改方案，将多步骤手动操作简化为一键调用。
3. 复杂配置的简化封装体系
针对 Acuitylib 配置复杂的问题，设计多层次的简化封装：多核环境自动管理、Vivante SDK 自动配置、多框架统一导入接口、量化策略简化配置等，显著降低用户使用门槛。
4. 业务逻辑封装与简化
针对 Acuitylib 业务逻辑复杂的问题，设计文件名自动推导、工作目录自动管理、临时文件自动清理、错误信息友好转换等机制，使用户无需了解底层细节。
5. 离线版工具链部署方案
针对内网用户无法访问 PyPI 的问题，设计完整的离线安装机制，包含依赖打包、自动安装脚本和部署文档。
6. 导出配置的简化封装
针对 Acuitylib 导出配置复杂的问题，设计参数化的导出接口，自动管理平台环境变量和 Vivante SDK 调用，避免污染用户环境。
7. 依赖库版本冲突解决
针对 acuitylib 与 tensorflow 的 libstdc++ 版本冲突问题，设计强制导入顺序控制机制，解决了 CXXABI 版本不兼容导致的加载失败问题。
---
## 6 任务安排及分工建议
本项目软件开发和项目管理工作主要由软件部组织完成，关键项目里程碑由科研管理部组织实施。
---
## 7 项目组成员建议
### 7.1 项目经理
项目经理：XXX
### 7.2 项目人员及分工
| 序号 | 姓名 | 职称 | 部门及职位 | 分工建议 | 备注 |
|------|------|------|------------|----------|------|
| 1 | 隋强 | | 长城银河 | 项目经理 | |
| 2 | 许骄 | | 长城银河 | 软件开发 | |
| 3 | 欧高亮 | | 长城银河 | 产品定义及开发 | |
| 4 | 关洪涛 | | 长城银河 | 软件测试 | |
| 5 | 周倩 | 工程师 | 长城银河 | 项目管理 | |
---
## 8 进度安排
本项目周期为：2025年07月 - 2025年12月（6个月）
| 阶段 | 时间 | 主要工作 | 里程碑 | 交付物 |
|------|------|---------|--------|--------|
| 需求与设计 | 7月 | 需求分析、架构设计 | 完成需求评审 | 需求规格书 |
| 核心开发 | 8-9月 | 核心框架、导入、量化、导出 | 完成核心功能 | Alpha版本 |
| 接口与工具 | 10月 | CLI、Python API、调试工具 | 完成接口开发 | Beta版本 |
| 测试验证 | 11月 | 单元测试、集成测试、性能测试 | 完成测试 | 测试报告 |
| 文档与发布 | 12月 | 文档完善、打包发布 | 正式发布 | v1.0版本 |
---
## 9 成果要求
### 9.1 技术文件类成果
- 软件源码：netrans_cli、netrans_py
- CLI 参考手册
- Python API 参考手册
- 使用指南（Cookbook）
- 设计文档（AGENTS.md）
- 版本发布记录
### 9.2 实物类成果
无。
### 9.3 知识产权类成果
软件著作权：1 项
---
## 10 经费预算
本项目预算：5 万元。
| 类别 | 金额（万元） | 说明 |
|------|-------------|------|
| 人力成本 | 4 | 开发人员工资及福利 |
| 设备/软件 | 0.5 | 开发环境、测试设备 |
| 外协/咨询 | 0.3 | 技术支持、培训 |
| 其他 | 0.2 | 差旅、资料等 |
| 合计 | 5 | |
---
## 11 存在风险及控制措施
### 11.1 技术风险及控制措施
性能优化风险。优化算法效果可能不及预期。
控制措施：建立完善的测试体系，覆盖主流模型（ResNet、YOLO 等），定期与芯片团队对齐优化策略。
模型精度风险。转换过程中可能出现精度损失。
控制措施：建立量化精度评估流程，提供 dump 和 inference 工具帮助定位精度问题。
框架兼容性风险。深度学习框架版本更新快，可能导致兼容性问题。
控制措施：明确支持的框架版本范围，对不兼容情况提供明确的错误提示。
### 11.2 进度风险及控制措施
工作量压力风险。目前软件团队可支持该项目的开发人员有限（1人），工作量估算为 235 人天（约 5 人月），项目周期 6 个月，资源配置紧张。
控制措施：
1. 优先交付核心功能，非核心功能可延后
2. 保留完整的开发过程文档，确保其他开发人员能快速接手
3. 建立代码审查机制，确保至少 2 人熟悉核心代码
### 11.3 供应链风险及控制措施
核心依赖风险。本项目底层依赖 acuitylib（VeriSilicon 提供），存在供应商技术支持、版本更新、商业授权等风险。
控制措施：
1. 与 VeriSilicon 建立稳定的技术支持渠道，及时获取版本更新和问题修复
2. 通过统一的接口层设计，使用户代码与底层 SDK 解耦，降低供应商绑定风险
3. 调研备选方案，评估迁移成本
### 11.4 资源配置风险及控制措施
目前软件团队可支持该项目的开发人员有限，存在人员流失导致项目停滞的风险。
控制措施：
1. 招聘有经验的工程师，及时补充团队核心成员
2. 在团队内发展复合技术人员
3. 保留完整的开发过程文档，确保其他开发人员能快速接手
4. 建立代码审查机制，确保至少 2 人熟悉核心代码
---
## 12 产品其它需求描述
无。
---
## 附录A：工具链成熟度评估
### A.1 成熟度等级定义
本评估模型参考技术成熟度（TRL）的简化版本，用于评估工具链的工程化完善程度：
| 等级 | 名称 | 典型特征 |
|------|------|----------|
| L1 | 概念级 | 技术概念已形成，基本原理可行 |
| L2 | 组件级 | 核心组件在实验室环境验证 |
| L3 | 系统级 | 完整系统在模拟环境验证，可运行但需专家操作 |
| L4 | 产品级 | 系统在真实环境验证，可交付，有文档和基础工具 |
| L5 | 成熟级 | 系统成熟，易用性好，有完整工具链和标准化流程 |
### A.2 评估维度与现状分析
从六个维度评估 AI 编译器工具链的成熟度：
| 维度 | 说明 | Acuitylib现状 | Netrans目标 |
|------|------|---------------|-------------|
| 工具链完整性 | 从模型到芯片的端到端能力 | L3-L4 | L5 |
| 标准化程度 | 流程统一、配置规范 | L3 | L5 |
| 易用性 | 学习成本、操作简便性 | L3 | L5 |
| 可调试性 | 问题定位、调试工具 | L3 | L5 |
| 可维护性 | 代码质量、架构清晰 | L3 | L4 |
| 可扩展性 | 新需求支持、模块化 | L3 | L4 |
### A.3 成熟度提升的关键措施
| 维度 | 提升措施 | 对应WBS工作包 |
|------|---------|--------------|
| 工具链完整性 | 端到端标准化流程 | 130,140,150,160,170 |
| 标准化程度 | 统一YAML+CLI规范 | 121,132,210 |
| 易用性 | CLI+Python API双模式 | 123,190,213 |
| 可调试性 | dump/inference/measure工具链 | 180 |
| 可维护性 | 自主代码，模块化架构 | 122,133,214 |
| 可扩展性 | 配置驱动，分层架构 | 122,132 |
---
## 附录B：WBS工作分解结构
### B.1 WBS 结构图
```
Netrans 模型转换工具链开发项目 (100)
│
├── 1. 项目管理 (110)
│ ├── 111. 项目计划与跟踪
│ ├── 112. 需求管理
│ ├── 113. 配置管理
│ └── 114. 质量保证
│
├── 2. 需求与设计 (120)
│ ├── 121. 需求分析
│ ├── 122. 架构设计
│ ├── 123. 接口设计
│ └── 124. 技术方案评审
│
├── 3. 核心框架开发 (130)
│ ├── 131. Netrans核心类实现
│ ├── 132. 配置管理系统
│ ├── 133. 异常处理体系
│ ├── 134. 装饰器与工具函数
│ └── 135. 模型元数据管理
│
├── 4. 模型导入模块 (140)
│ ├── 141. 模型格式自动识别
│ ├── 142. 统一导入接口封装
│ ├── 143. 多框架导入适配
│ └── 144. 导入状态管理
│
├── 5. 量化模块 (150)
│ ├── 151. 量化接口封装
│ ├── 152. 量化参数简化配置
│ ├── 153. 混合精度量化支持
│ └── 154. 量化状态管理
│
├── 6. 前后处理集成 (160)
│ ├── 161. 预处理配置自动化
│ ├── 162. 后处理配置自动化
│ └── 163. 配置参数提取与生成
│
├── 7. NBG导出模块 (170)
│ ├── 171. 导出接口封装
│ ├── 172. 多核环境自动配置
│ └── 173. 导出状态管理
│
├── 8. 调试分析工具 (180)
│ ├── 181. 张量导出接口封装
│ ├── 182. 推理验证接口封装
│ ├── 183. 性能测量接口封装
│ └── 184. ONNX Opset 兼容性检查
│
├── 9. 接口层开发 (190)
│ ├── 191. Python API实现
│ ├── 192. CLI工具实现
│ └── 193. 命令行解析与帮助系统
│
├── 10. 测试验证 (200)
│ ├── 201. 单元测试
│ ├── 202. 集成测试
│ ├── 203. 性能测试
│ ├── 204. 示例工程
│ └── 205. 回归测试套件
│
├── 11. 文档与交付 (210)
│ ├── 211. API参考手册
│ ├── 212. CLI使用手册
│ ├── 213. 开发指南
│ ├── 214. 设计文档
│ ├── 215. 示例代码与教程
│ └── 216. 发布说明
│
└── 12. 产品化与维护 (220)
├── 221. 安装包制作
├── 222. CI/CD流程
├── 223. 版本管理
└── 224. 问题跟踪与修复
```
### B.2 工作量估算
| WBS编号 | 工作包 | 估算工时(人天) |
|---------|--------|----------------|
| 1.x | 项目管理 | 20 |
| 2.x | 需求与设计 | 15 |
| 3.x | 核心框架开发 | 25 |
| 4.x | 模型导入模块 | 20 |
| 5.x | 量化模块 | 20 |
| 6.x | 前后处理集成 | 15 |
| 7.x | NBG导出模块 | 15 |
| 8.x | 调试分析工具 | 15 |
| 9.x | 接口层开发 | 25 |
| 10.x | 测试验证 | 35 |
| 11.x | 文档与交付 | 25 |
| 12.x | 产品化与维护 | 15 |
| 合计 | | 235人天（约5人月） |
---
*文档结束*

511
docs/pmf/产品需求规格书-Netrans软件-优化版.md
View File

@ -1,511 +0,0 @@
# Netrans软件 产品需求规格书（优化版）
> 本文档基于 WB 成熟度模型优化，参考 PNNA_Driver 和检测流程信息化系统的规范写法
---
## 目录
1. 项目概述
2. 引用文件
3. 研究内容
4. 技术要求
5. 关键技术/工艺及创新点
6. 任务安排及分工建议
7. 项目组成员建议
8. 进度安排
9. 成果要求
10. 经费预算
11. 存在风险及控制措施
12. 产品其它需求描述
附录A：WBS工作分解结构
---
## 1 项目概述
本项目为软件部自研软件项目，旨在开发一套针对自研 PNNA 芯片的 AI 编译器工具链，提供命令行工具 **netrans_cli** 和 Python API **netrans_py**，用于将深度学习模型转换成在 PNNA NPU 上运行的 NBG（Network Binary Graph）格式文件。本软件是 PNNA 芯片生态的核心组成部分，直接提升芯片的易用性和开发者友好度，降低用户应用层适配成本。
### 1.1 术语及定义
| 术语 | 定义 |
|------|------|
| PNNA | Programmable Neural Network Accelerator，可编程神经网络加速器 |
| NBG | Network Binary Graph，网络二进制图，PNNA 芯片可执行的模型格式 |
| NPU | Neural Processing Unit，神经网络处理单元 |
| IR | Intermediate Representation，中间表示 |
| 量化 | 将浮点模型转换为定点模型的过程，减少模型大小和计算量 |
| Hybrid | 混合精度量化，对不同层使用不同精度 |
---
## 2 引用文件
无。
---
## 3 研究内容
本项目主要研究内容包括：
1. **跨框架模型解析技术**：研究 TensorFlow、PyTorch、ONNX、Caffe、Darknet、TFLite、Keras 等多种深度学习框架的模型格式解析方法，实现统一的中间表示（IR）转换。
2. **面向专用芯片的模型优化算法**：研究计算图优化、算子融合、常量折叠等优化技术，提升模型在 PNNA 芯片上的运行效率。
3. **神经网络量化技术**：研究非对称量化（asymu8）、对称量化（symi8/symi16）、混合精度量化等算法，平衡模型精度与推理性能。
4. **芯片专用二进制生成技术**：研究将优化后的模型转换为 PNNA 芯片可执行的 NBG 格式，支持单核和多核配置。
5. **前后处理集成技术**：研究将预处理（mean/scale 归一化）和后处理（反量化）嵌入网络图的方法，减少运行时开销。
---
## 4 技术要求
### 4.1 硬件要求
无特殊硬件要求。开发环境为通用 x86_64 Linux 服务器。
### 4.2 软件要求
#### 4.2.1 开发环境
- 操作系统：Linux（推荐 Ubuntu 20.04+）
- Python 版本：Python 3.10
- 核心依赖：numpy、protobuf、tensorflow、torch、onnx、acuitylib（>=6.33.0）
#### 4.2.2 功能要求
**模型导入功能**。系统应支持从多种深度学习框架导入模型，包括但不限于：
- TensorFlow（.pb 格式，需配合 inputs_outputs.txt 指定输入输出）
- TensorFlow Lite（.tflite 格式）
- PyTorch（.pt 格式，通过 ONNX 后端转换）
- ONNX（.onnx 格式，支持 opset 7-17）
- Caffe（.prototxt + .caffemodel 格式）
- Darknet（.cfg + .weights 格式，支持 YOLO 系列）
- Keras（.h5 格式）
导入过程应完成模型解析、权重提取、中间表示生成，并输出网络结构描述文件（.json）和权重数据文件（.data）。
**模型量化功能**。系统应支持多种量化策略，满足不同精度和性能需求：
- 非对称 8 位量化（asymu8）：适用于通用场景，精度与性能平衡
- 对称 8 位量化（symi8）：适用于对称数据分布的模型
- 对称 16 位量化（symi16）：适用于高精度需求场景
- 混合精度量化（hybrid）：对敏感层使用高精度，其他层使用低精度
- 激活权重量化分离（AI16WI8/AI16WI4）：激活和权重使用不同精度
量化过程应支持多种校准算法：普通量化（normal）、KL 散度量化（kl_divergence）、移动平均量化（moving_average）、自动选择（auto）。系统应生成量化配置文件（.quantize），记录每层的量化参数。
**前后处理集成功能**。系统应支持将预处理和后处理节点嵌入网络图：
- 预处理集成：将 mean/scale 归一化操作嵌入网络输入节点，支持通道级均值和缩放配置
- 后处理集成：将反量化操作嵌入网络输出节点，支持强制 float32 输出
集成后生成的 NBG 文件可直接接受原始数据输入（如 uint8 图像），无需应用层额外处理。
**模型导出功能**。系统应支持将优化和量化后的模型导出为 PNNA 芯片可执行的 NBG 格式：
- 支持单核和多核配置（1-4 核 VIP 模式）
- 支持多平台优化（pnna: VIP8000 系列，pnna2: VIP9400 系列）
- 导出过程应生成 NBG 二进制文件、元数据文件和示例 C 代码
**调试分析功能**。系统应提供调试和分析工具：
- 张量导出（dump）：导出每层输入输出张量，用于精度对比和问题定位
- 推理验证（inference）：执行前向推理，保存输入输出作为 golden 数据
- 性能测量（measure）：统计模型计算量（FLOPs）和内存占用
- Opset 检查（check_opset）：检查 ONNX 模型的 opset 版本兼容性
#### 4.2.3 接口要求
**命令行接口（netrans_cli）**。系统应提供完整的命令行工具，支持批处理和脚本集成：
- `netrans load`：模型导入
- `netrans quantize`：模型量化
- `netrans quantize_hybrid`：混合精度量化
- `netrans add_pre_post`：前后处理集成
- `netrans export`：NBG 导出
- `netrans dump`：张量导出
- `netrans inference`：推理验证
- `netrans measure`：性能测量
- `netrans check_opset`：Opset 检查
每个子命令应支持 `--verbose` 选项输出详细日志，支持 `--help` 选项显示帮助信息。
**Python API（netrans_py）**。系统应提供 Python API，支持集成到训练流水线：
- `Netrans` 类：主类，封装完整的模型处理流水线
- `load()` 方法：模型导入
- `quantize()` 方法：模型量化
- `quantize_hybrid()` 方法：混合精度量化
- `add_pre_post()` 方法：前后处理集成
- `export()` 方法：NBG 导出
- `dump()` 方法：张量导出
- `inference()` 方法：推理验证
API 设计应遵循 Python 风格指南，支持类型注解，提供完整的 docstring 文档。
### 4.3 结构要求
无。
### 4.4 主要性能及可靠性指标要求
| 指标类别 | 指标项 | 要求 |
|----------|--------|------|
| 转换效率 | 大模型转换时间 | ResNet50 量化导出 < 5 分钟 |
| 优化效果 | 模型压缩率 | asymu8 量化后模型大小减少 > 70% |
| 量化精度 | 精度损失 | 典型 CV 模型精度损失 < 1% |
| 资源占用 | 内存使用 | 转换过程峰值内存 < 模型大小 × 3 |
| 易用性 | 学习成本 | 新用户 30 分钟内完成首次转换 |
### 4.5 认证测试要求
无。
### 4.6 环境要求
无特殊环境要求。
### 4.7 非功能要求
**性能方面**。系统应支持大模型（>100MB）的高效转换，量化过程应充分利用多核 CPU 并行计算。命令行工具启动时间应 < 1 秒。
**易用性方面**。系统应提供清晰的用户文档和示例代码，错误信息应明确指出问题原因和解决建议。CLI 应支持 `--verbose` 选项输出详细调试信息。
**可扩展性方面**。系统应采用模块化设计，各功能模块独立，便于添加新的模型格式支持和量化算法。量化类型应通过配置文件定义，便于扩展。
**兼容性方面**。系统应兼容主流深度学习框架版本：
- TensorFlow >= 2.x
- PyTorch >= 1.8
- ONNX >= 1.10
- ONNX opset 7-17
**可靠性方面**。系统应对输入参数进行严格校验，无效输入应返回明确的错误信息而非崩溃。转换过程应保留原始模型文件，不进行原地修改。
**可维护性方面**。代码应遵循 Python PEP 8 规范，关键函数应有完整的 docstring。项目应提供单元测试和集成测试，测试覆盖率 > 80%。
### 4.8 关键器件及外协要求
无。
### 4.9 产品其它技术需求
**依赖说明**。本软件核心依赖 acuitylib（VeriSilicon 提供的神经网络编译库），需确保 acuitylib 版本 >= 6.33.0。acuitylib 需要特定版本的 libstdc++（CXXABI_1.3.15），与系统默认版本可能存在冲突，需通过 conda 环境管理。
**导入顺序要求**。由于 libstdc++ 版本冲突，用户代码必须先导入 netrans，再导入 tensorflow，否则会导致 acuitylib 加载失败。
**平台支持**。本软件为模型转换工具，运行在 x86_64 Linux 开发环境，生成的 NBG 文件运行在 PNNA 芯片（ARM/DSP 平台）。
---
## 5 关键技术/工艺及创新点
### 5.1 关键技术
1. **跨框架统一中间表示**：设计统一的 IR 格式，实现多种深度学习框架模型到 IR 的无损转换，支持动态 shape 推断和算子语义对齐。
2. **KL 散度量化算法**：采用 KL 散度最小化策略确定量化参数，相比简单的 min-max 量化，显著减少量化精度损失。
3. **混合精度量化策略**：针对检测模型等敏感场景，自动识别精度敏感层，对检测头使用高精度量化，主干网络使用低精度量化，平衡精度与性能。
4. **前后处理图融合**：将预处理和后处理操作嵌入计算图，生成端到端的 NBG 文件，减少运行时数据拷贝和计算开销。
### 5.2 关键工艺
无。
### 5.3 创新点
1. **Python API 与 CLI 双接口设计**：同时提供命令行工具和 Python API，满足批处理场景和流水线集成场景的不同需求。
2. **多核配置支持**：支持 1-4 核 VIP 多核运行模式配置，通过环境变量自动管理多核亲和性，简化用户配置流程。
3. **量化后网络对象管理**：解决量化后网络对象状态同步问题，确保 Python API 连续调用时量化结果正确传递到导出阶段。
---
## 6 任务安排及分工建议
本项目软件开发和项目管理工作主要由软件部组织完成，关键项目里程碑由科研管理部组织实施。
---
## 7 项目组成员建议
### 7.1 项目经理
项目经理：XXX
### 7.2 项目人员及分工
如表 1 所示。
**表 1 项目人员及分工**
| 序号 | 姓名 | 职称 | 部门及职位 | 分工建议 | 备注 |
|------|------|------|------------|----------|------|
| 1 | 隋强 | | 长城银河 | 项目经理 | |
| 2 | 许骄 | | 长城银河 | 软件开发 | |
| 3 | 欧高亮 | | 长城银河 | 产品定义及开发 | |
| 4 | 关洪涛 | | 长城银河 | 软件测试 | |
| 5 | 周倩 | 工程师 | 长城银河 | 项目管理 | |
---
## 8 进度安排
本项目周期为：2025年07月xx日 - 202X年xx月xx日
---
## 9 成果要求
### 9.1 技术文件类成果
按公司软件项目齐套性要求输出的软件开发全套过程文档及源码。
软件源码包括：
- **netrans_cli**：命令行转换工具
- **netrans_py**：Python API 接口库
技术文档包括：
- CLI 参考手册（netrans_cli.md）
- Python API 参考手册（netrans_api.md）
- 使用指南（cookbook.md）
- 设计文档（AGENTS.md）
- 版本发布记录（release.md）
### 9.2 实物类成果
无。
### 9.3 知识产权类成果
软件著作权：1 项
---
## 10 经费预算
本项目预算：5 万元。
---
## 11 存在风险及控制措施
### 11.1 技术风险及控制措施
本项目技术复杂，难度高。开发过程中可能面临的技术风险主要有：
**性能优化风险**。优化算法效果可能不及预期，芯片特性利用不充分。
控制措施：建立完善的测试体系，覆盖主流模型（ResNet、YOLO、Swin Transformer 等），通过边界测试和错误操作测试软件边界。定期与芯片团队对齐优化策略。
**模型精度风险**。转换过程中可能出现精度损失，数值计算不一致。
控制措施：建立量化精度评估流程，对典型模型进行量化前后精度对比。提供 dump 和 inference 工具帮助用户定位精度问题。
**框架兼容性风险**。深度学习框架版本更新快，可能导致兼容性问题。
控制措施：明确支持的框架版本范围，建立版本兼容性测试矩阵。对不兼容情况提供明确的错误提示和解决建议。
### 11.2 进度风险及控制措施
无。
### 11.3 供应链风险及控制措施
**核心依赖风险**。本项目核心依赖 acuitylib（VeriSilicon 提供的第三方库），存在供应商技术支持和版本更新依赖。
控制措施：与供应商建立稳定的技术支持渠道，及时获取版本更新和问题修复。在项目文档中明确 acuitylib 版本要求，避免版本不匹配问题。
### 11.4 资源配置风险及控制措施
目前软件团队可支持该项目的开发人员仅 1 人，存在人员流失导致项目停滞甚至失败的风险。
控制措施：
1. 招聘有经验的工程师，及时补充团队核心成员
2. 在团队内发展复合技术人员，以应对人员突然流失的风险
3. 管理上应保留完整的开发过程文档，确保其他开发人员能在短时间内接手项目
4. 建立代码审查机制，确保至少 2 人熟悉核心代码
---
## 12 产品其它需求描述
无。
---
## 附录A：WBS工作分解结构
### A.1 WBS 结构图
```
Netrans软件开发项目
│
├── 1. 项目管理
│ ├── 1.1 项目规划
│ │ ├── 1.1.1 需求分析
│ │ ├── 1.1.2 技术方案设计
│ │ └── 1.1.3 项目计划编制
│ ├── 1.2 项目监控
│ │ ├── 1.2.1 进度跟踪
│ │ ├── 1.2.2 风险管理
│ │ └── 1.2.3 变更控制
│ └── 1.3 项目收尾
│ ├── 1.3.1 验收评审
│ └── 1.3.2 项目总结
│
├── 2. 核心功能开发
│ ├── 2.1 模型导入模块
│ │ ├── 2.1.1 ONNX格式解析
│ │ ├── 2.1.2 TensorFlow格式解析
│ │ ├── 2.1.3 PyTorch格式解析
│ │ ├── 2.1.4 Caffe格式解析
│ │ ├── 2.1.5 Darknet格式解析
│ │ ├── 2.1.6 TFLite格式解析
│ │ └── 2.1.7 中间表示生成
│ │
│ ├── 2.2 模型量化模块
│ │ ├── 2.2.1 非对称量化(asymu8)
│ │ ├── 2.2.2 对称量化(symi8/symi16)
│ │ ├── 2.2.3 混合精度量化(hybrid)
│ │ ├── 2.2.4 KL散度校准算法
│ │ ├── 2.2.5 移动平均校准算法
│ │ └── 2.2.6 量化参数优化
│ │
│ ├── 2.3 前后处理模块
│ │ ├── 2.3.1 预处理节点集成
│ │ ├── 2.3.2 后处理节点集成
│ │ ├── 2.3.3 YAML配置解析
│ │ └── 2.3.4 图节点融合
│ │
│ ├── 2.4 模型导出模块
│ │ ├── 2.4.1 NBG格式生成
│ │ ├── 2.4.2 多核配置支持
│ │ ├── 2.4.3 平台优化配置
│ │ └── 2.4.4 元数据生成
│ │
│ └── 2.5 调试分析模块
│ ├── 2.5.1 张量导出(dump)
│ ├── 2.5.2 推理验证(inference)
│ ├── 2.5.3 性能测量(measure)
│ └── 2.5.4 Opset检查
│
├── 3. 接口开发
│ ├── 3.1 命令行接口(CLI)
│ │ ├── 3.1.1 load子命令
│ │ ├── 3.1.2 quantize子命令
│ │ ├── 3.1.3 quantize_hybrid子命令
│ │ ├── 3.1.4 add_pre_post子命令
│ │ ├── 3.1.5 export子命令
│ │ ├── 3.1.6 dump子命令
│ │ ├── 3.1.7 inference子命令
│ │ ├── 3.1.8 measure子命令
│ │ └── 3.1.9 check_opset子命令
│ │
│ └── 3.2 Python API
│ ├── 3.2.1 Netrans核心类
│ ├── 3.2.2 模型元数据管理
│ ├── 3.2.3 异常处理体系
│ └── 3.2.4 类型注解支持
│
├── 4. 测试与质量保证
│ ├── 4.1 单元测试
│ │ ├── 4.1.1 导入模块测试
│ │ ├── 4.1.2 量化模块测试
│ │ ├── 4.1.3 导出模块测试
│ │ └── 4.1.4 API接口测试
│ │
│ ├── 4.2 集成测试
│ │ ├── 4.2.1 端到端转换测试
│ │ ├── 4.2.2 多框架兼容性测试
│ │ └── 4.2.3 量化精度验证
│ │
│ ├── 4.3 性能测试
│ │ ├── 4.3.1 转换效率测试
│ │ ├── 4.3.2 内存占用测试
│ │ └── 4.3.3 大模型压力测试
│ │
│ └── 4.4 用户验收测试
│ ├── 4.4.1 典型模型验证
│ └── 4.4.2 用户场景测试
│
├── 5. 文档编制
│ ├── 5.1 技术文档
│ │ ├── 5.1.1 设计文档(AGENTS.md)
│ │ ├── 5.1.2 API参考手册
│ │ └── 5.1.3 CLI参考手册
│ │
│ ├── 5.2 用户文档
│ │ ├── 5.2.1 快速入门指南
│ │ ├── 5.2.2 使用手册(cookbook.md)
│ │ └── 5.2.3 示例代码
│ │
│ └── 5.3 过程文档
│ ├── 5.3.1 版本发布记录
│ └── 5.3.2 测试报告
│
└── 6. 部署与发布
├── 6.1 环境配置
│ ├── 6.1.1 依赖管理
│ ├── 6.1.2 安装脚本
│ └── 6.1.3 环境验证
│
├── 6.2 打包发布
│ ├── 6.2.1 Python包打包
│ └── 6.2.2 版本管理
│
└── 6.3 持续集成
├── 6.3.1 CI流程配置
└── 6.3.2 自动化测试
```
### A.2 WBS 词典
| WBS编号 | 工作包名称 | 工作内容描述 | 交付物 | 负责人 |
|---------|------------|--------------|--------|--------|
| 1.1 | 项目规划 | 需求分析、技术方案设计、计划编制 | 需求规格书、技术方案、项目计划 | 项目经理 |
| 1.2 | 项目监控 | 进度跟踪、风险管理、变更控制 | 周报、风险清单、变更记录 | 项目经理 |
| 2.1 | 模型导入模块 | 多框架模型解析与IR转换 | importer.py、model_loader.py | 开发工程师 |
| 2.2 | 模型量化模块 | 量化算法实现与参数优化 | quantize.py、quantize_hybrid.py | 开发工程师 |
| 2.3 | 前后处理模块 | 预处理/后处理节点集成 | add_prepost_to_graph.py | 开发工程师 |
| 2.4 | 模型导出模块 | NBG格式生成与多核配置 | export_nbg.py | 开发工程师 |
| 2.5 | 调试分析模块 | 张量导出、推理验证、性能测量 | dump.py、inference.py、measure.py | 开发工程师 |
| 3.1 | 命令行接口 | CLI子命令实现 | script/netrans | 开发工程师 |
| 3.2 | Python API | Netrans类与辅助模块 | netrans.py、exceptions.py | 开发工程师 |
| 4.1 | 单元测试 | 各模块单元测试 | test/目录下测试文件 | 测试工程师 |
| 4.2 | 集成测试 | 端到端转换流程测试 | 集成测试报告 | 测试工程师 |
| 5.1 | 技术文档 | 设计文档、API/CLI手册 | docs/目录下文档 | 开发工程师 |
| 5.2 | 用户文档 | 快速入门、使用手册、示例 | cookbook.md、examples/ | 开发工程师 |
| 6.1 | 环境配置 | 依赖管理、安装脚本 | setup.py、setup.sh | 开发工程师 |
### A.3 工作量估算
| WBS编号 | 工作包 | 估算工时(人天) | 备注 |
|---------|--------|----------------|------|
| 1.x | 项目管理 | 20 | 全周期 |
| 2.1 | 模型导入模块 | 30 | 7种格式支持 |
| 2.2 | 模型量化模块 | 25 | 4种量化类型 |
| 2.3 | 前后处理模块 | 15 | YAML配置+图融合 |
| 2.4 | 模型导出模块 | 20 | NBG+多核配置 |
| 2.5 | 调试分析模块 | 15 | 4个调试工具 |
| 3.1 | 命令行接口 | 15 | 9个子命令 |
| 3.2 | Python API | 20 | 核心类+异常体系 |
| 4.x | 测试与质量保证 | 40 | 单元+集成+性能 |
| 5.x | 文档编制 | 25 | 技术+用户+过程 |
| 6.x | 部署与发布 | 10 | 打包+CI |
| **合计** | | **235人天** | 约5人月 |
---
## 附录B：与原版文档对比
| 章节 | 原版 | 优化版 | 改进说明 |
|------|------|--------|----------|
| 项目概述 | 简单描述 | 增加术语定义 | 明确专业术语 |
| 软件要求 | 3条笼统描述 | 5个功能模块详细描述 | 参考 PNNA_Driver 写法 |
| 非功能要求 | 写"无" | 6个维度详细描述 | 参考"检测流程信息化系统"写法 |
| 关键技术 | 写"无" | 4项关键技术 | 基于项目实际内容提取 |
| 创新点 | 写"无" | 3项创新点 | 基于项目特色总结 |
| 产品其它技术需求 | 写"无" | 依赖说明、导入顺序、平台支持 | 补充关键技术约束 |
| 风险控制 | 2条 | 4条 | 增加框架兼容性风险和供应链风险 |
| WBS结构 | 无 | 新增附录A | 工作分解结构、WBS词典、工作量估算 |

BIN
docs/pmf/产品需求规格书-Netrans软件.docx
View File

Binary file not shown.

553
docs/pmf/产品需求规格书-Netrans软件.md
View File

@ -1,553 +0,0 @@
# Netrans软件 产品需求规格书
> 版本：v1.0
> 日期：2026-03-23
---
## 1 项目概述
本项目旨在开发一套面向 PNNA 芯片的 AI 模型转换工具链，提供命令行工具 **netrans** 和 Python API **netrans_py**，支持将 TensorFlow、PyTorch、ONNX 等多种深度学习框架的模型转换为 PNNA NPU 可执行的 NBG（Network Binary Graph）格式。
本软件基于 Acuitylib 构建，通过上层封装和流程整合，解决直接使用底层库时的易用性、标准化和可调试性问题，形成完整的产品级工具链。
### 1.1 术语及定义
| 术语 | 定义 |
|------|------|
| PNNA | Programmable Neural Network Accelerator，可编程神经网络加速器 |
| NBG | Network Binary Graph，网络二进制图，PNNA 芯片可执行的模型格式 |
| NPU | Neural Processing Unit，神经网络处理单元 |
| Acuitylib | VeriSilicon 提供的神经网络编译库 |
| 量化 | 将浮点模型转换为定点模型的过程，减少模型大小和计算量 |
| Hybrid 量化 | 混合精度量化，对不同层使用不同精度 |
| WB 成熟度 | Workbench 成熟度，评估工具链工程化完善程度的 1-5 级模型 |
---
## 2 引用文件
无。
---
## 3 研究内容
### 3.1 模型转换流程的状态管理
研究模型转换多阶段流水线中的状态传递机制。Acuitylib 的量化操作返回新的网络对象而非修改原对象，需要设计可靠的状态同步方案，确保 Python API 链式调用时各阶段使用的是正确的模型状态。
### 3.2 前后处理配置的简化
研究 Acuitylib 前后处理配置的简化方法。Acuity 需要手动从量化文件提取参数、修改多个 YAML 文件的特定位置，操作复杂易错。需要设计一键化配置机制，自动完成参数提取和文件修改。
### 3.3 复杂配置的简化封装
研究 Acuitylib 复杂配置的简化方法。包括：多核环境变量的自动管理、多框架导入的统一接口、量化参数的简化配置、平台差异的透明处理等，降低用户使用门槛。
### 3.4 离线版工具链部署
研究内网环境下的工具链部署方案。外网用户可通过 pip 安装依赖，内网用户需要离线安装包和本地化依赖管理，需要设计完整的离线部署机制。
---
## 4 技术要求
### 4.1 硬件要求
无特殊硬件要求。开发环境为通用 x86_64 Linux 服务器。
### 4.2 软件要求
#### 4.2.1 开发环境
- 操作系统：Linux（推荐 Ubuntu 20.04+）
- Python 版本：Python 3.10
- 核心依赖：numpy、protobuf、tensorflow、torch、onnx、acuitylib（>=6.33.0）
#### 4.2.2 功能要求
**模型导入功能**
系统应支持从多种深度学习框架导入模型：
- TensorFlow（.pb 格式，需配合 inputs_outputs.txt 指定输入输出）
- TensorFlow Lite（.tflite 格式）
- PyTorch（.pt 格式，通过 ONNX 后端转换）
- ONNX（.onnx 格式，支持 opset 7-17）
- Caffe（.prototxt + .caffemodel 格式）
- Darknet（.cfg + .weights 格式，支持 YOLO 系列）
- Keras（.h5 格式）
导入过程应完成模型解析、权重提取、中间表示生成，并输出网络结构描述文件（.json）和权重数据文件（.data）。
**模型量化功能**
系统应支持多种量化策略：
- 非对称 8 位量化（asymu8）：适用于通用场景，精度与性能平衡
- 对称 8 位量化（symi8）：适用于对称数据分布的模型
- 对称 16 位量化（symi16）：适用于高精度需求场景
- 混合精度量化（hybrid）：对敏感层使用高精度，其他层使用低精度
- 激活权重量化分离（AI16WI8/AI16WI4）：激活和权重使用不同精度
量化过程应支持多种校准算法：普通量化（normal）、KL 散度量化（kl_divergence）、移动平均量化（moving_average）、自动选择（auto）。
**前后处理集成功能**
系统应支持将预处理和后处理节点嵌入网络图：
- 预处理集成：将 mean/scale 归一化操作嵌入网络输入节点
- 后处理集成：将反量化操作嵌入网络输出节点
集成后生成的 NBG 文件可直接接受原始数据输入（如 uint8 图像），无需应用层额外处理。
**模型导出功能**
系统应支持将优化和量化后的模型导出为 PNNA 芯片可执行的 NBG 格式：
- 支持单核和多核配置（1-4 核 VIP 模式）
- 支持多平台优化（pnna: VIP8000 系列，pnna2: VIP9400 系列）
- 导出过程应生成 NBG 二进制文件、元数据文件和示例 C 代码
**调试分析功能**
系统应提供调试和分析工具：
- 张量导出（dump）：导出每层输入输出张量，用于精度对比
- 推理验证（inference）：执行前向推理，保存输入输出作为 golden 数据
- 性能测量（measure）：统计模型计算量（FLOPs）和内存占用
- Opset 检查（check_opset）：检查 ONNX 模型的 opset 版本兼容性
#### 4.2.3 接口要求
**命令行接口（netrans）**
系统应提供完整的命令行工具：
- `netrans load`：模型导入
- `netrans quantize`：模型量化
- `netrans quantize_hybrid`：混合精度量化
- `netrans add_pre_post`：前后处理集成
- `netrans export`：NBG 导出
- `netrans dump`：张量导出
- `netrans inference`：推理验证
- `netrans measure`：性能测量
- `netrans check_opset`：Opset 检查
**Python API（netrans_py）**
系统应提供 Python API，支持集成到训练流水线：
- `Netrans` 类：主类，封装完整的模型处理流水线
- `load()`、`quantize()`、`quantize_hybrid()`、`add_pre_post()`、`export()`、`dump()`、`inference()` 等方法
### 4.3 结构要求
无。
### 4.4 主要性能及可靠性指标要求
| 指标类别 | 指标项 | 要求 |
|----------|--------|------|
| 转换效率 | 大模型转换时间 | ResNet50 量化导出 < 5 分钟 |
| 优化效果 | 模型压缩率 | asymu8 量化后模型大小减少 > 70% |
| 量化精度 | 精度损失 | 典型 CV 模型精度损失 < 1% |
| 资源占用 | 内存使用 | 转换过程峰值内存 < 模型大小 × 3 |
| 易用性 | 学习成本 | 新用户 30 分钟内完成首次转换 |
### 4.5 认证测试要求
无。
### 4.6 环境要求
无特殊环境要求。
### 4.7 非功能要求
**性能方面**
- 命令行工具冷启动时间 < 1 秒
- 支持大模型（>100MB）的高效转换
- 量化过程充分利用多核 CPU 并行计算
**安全性方面**
- 转换过程不修改原始模型文件
- 临时文件自动清理，敏感数据不残留
- 错误信息不暴露内部实现细节
**可用性方面**
- 错误信息明确指示问题原因和解决建议
- CLI 支持 `--verbose` 输出详细调试信息
- 提供完整的用户文档和示例代码
**可靠性方面**
- 转换过程异常中断时不损坏原始模型文件
- 关键操作前自动备份配置文件
- 支持断点续传（量化后的模型可重复导出）
**兼容性方面**
- 支持 TensorFlow >= 2.x、PyTorch >= 1.8、ONNX >= 1.10
- 支持 ONNX opset 7-17
- Python API 支持类型注解
**可维护性方面**
- 代码遵循 Python PEP 8 规范
- 关键函数有完整的 docstring
- 测试覆盖率 > 80%
**可移植性方面**
- 架构设计考虑底层库的兼容性
- 供应商相关代码集中封装，与核心逻辑解耦
- 接口设计遵循通用原则，降低迁移成本
### 4.8 关键器件及外协要求
无。
### 4.9 产品其它技术需求
**依赖说明**
本软件核心依赖 acuitylib（VeriSilicon 提供的神经网络编译库），需确保版本 >= 6.33.0。acuitylib 需要特定版本的 libstdc++（CXXABI_1.3.15），需通过 conda 环境管理。
**导入顺序要求**
由于 libstdc++ 版本冲突，用户代码必须先导入 netrans，再导入 tensorflow。
**平台支持**
本软件运行在 x86_64 Linux 开发环境，生成的 NBG 文件运行在 PNNA 芯片（ARM/DSP 平台）。
---
## 5 关键技术/工艺及创新点
### 5.1 关键技术
1. **模型转换状态同步机制**
**问题描述**：Acuitylib 的 `nn.quantize()` 返回新的网络对象，原对象保持不变。Netrans 的 Python API 需要支持链式调用（`model.load().quantize().export()`），如果未正确更新引用，导出的是浮点网络而非量化网络，导致 NBG 文件大小异常。
**解决方案**：设计 ModelMeta 不可变数据类，量化操作后创建新的实例。`quantize()` 方法内部更新 `self._meta` 引用，对用户无感知。
**验证方法**：链式调用与命令行分步执行生成的 NBG 文件大小一致，量化后比浮点小约 75%。
2. **前后处理配置的简化**
**问题描述**：Acuitylib 的前后处理集成需要用户手动：1）从 .quantize 文件提取输入层量化参数；2）修改 `_inputmeta.yml` 添加 `preproc_node_params`；3）修改 `_postprocess_file.yml` 添加 `postproc_params`。涉及多个文件、多个参数，格式要求严格，操作复杂易错。
**解决方案**：`add_pre_post()` 函数自动完成上述操作：读取量化参数、生成正确的 YAML 结构、写入对应位置。用户只需调用一个函数，无需了解配置文件细节。
**验证方法**：调用 `add_pre_post()` 后，检查 `_inputmeta.yml` 和 `_postprocess_file.yml` 中配置正确；导出后的 NBG 可直接接收 uint8 输入。
3. **多核环境配置简化**
**问题描述**：PNNA2 多核配置需要设置 `VIV_MGPU_AFFINITY` 和 `VIV_OVX_MULTI_DEVICES` 环境变量，格式复杂（如 `1:4` 和 `0:4-1`），且是进程级全局设置，容易影响其他操作。
**解决方案**：设计 `_set_multicore_env()` 函数，根据 `core_num` 参数（如 `'4core'`）自动计算并设置环境变量，导出后恢复。用户只需传递简单参数，无需了解环境变量细节。
**验证方法**：设置 4 核配置后导出，检查 NBG 多核元数据正确；同进程其他导出操作不受影响的单核配置。
4. **模型导入接口统一**
**问题描述**：Acuitylib 对不同框架（TensorFlow、PyTorch、ONNX 等）有不同的导入函数和参数要求，用户需要了解各框架的细节差异。
**解决方案**：设计统一的 `load()` 接口，自动识别模型格式并调用对应的 Acuitylib 导入函数。通过文件扩展名和内容检测，自动选择正确的导入器。
**验证方法**：同一 `load()` 接口可正确导入 7 种框架的模型，无需用户指定框架类型。
5. **量化配置简化**
**问题描述**：Acuitylib 的量化需要设置多个参数（quantizer、qtype、algorithm 等），且不同量化类型（asymu8、symi8、hybrid）有不同的调用方式。
**解决方案**：设计统一的 `quantize()` 接口，通过 `quantized` 参数（如 `'asymu8'`）自动选择量化策略。封装量化类型的差异，提供一致的调用方式。
**验证方法**：用户只需指定量化类型字符串，无需了解底层量化器的差异。
6. **离线版工具链部署**
**问题描述**：内网用户无法访问 PyPI 安装依赖，需要离线安装方案。acuitylib 等依赖有特定版本要求，离线部署容易出错。
**解决方案**：制作离线安装包，包含所有依赖 wheel 文件；提供 `setup.sh` 自动检测环境并安装；文档说明内网部署步骤。
**验证方法**：在无外网环境测试安装，验证所有功能正常；检查依赖版本正确。
### 5.2 关键工艺
无。
### 5.3 创新点
1. **模型转换状态同步机制**
针对 Acuitylib 对象生命周期不一致的问题，设计 ModelMeta 封装和状态同步方案，实现 Python API 链式调用与底层库行为的正确衔接。
2. **前后处理配置的简化**
针对 Acuitylib 前后处理配置复杂的问题，设计自动化的参数提取和配置文件修改方案，将多步骤手动操作简化为一键调用。
3. **复杂配置的简化封装体系**
针对 Acuitylib 配置复杂的问题，设计多层次的简化封装：多核环境自动管理、多框架统一导入接口、量化策略简化配置等，显著降低用户使用门槛。
4. **离线版工具链部署方案**
针对内网用户无法访问 PyPI 的问题，设计完整的离线安装机制，包含依赖打包、自动安装脚本和部署文档。
5. **工具链成熟度评估模型**
提出 WB（Workbench）成熟度模型，从六个维度建立 1-5 级评估体系，为 AI 编译器工具链的产品化提供量化改进路径。
---
## 6 任务安排及分工建议
本项目软件开发和项目管理工作主要由软件部组织完成，关键项目里程碑由科研管理部组织实施。
---
## 7 项目组成员建议
### 7.1 项目经理
项目经理：XXX
### 7.2 项目人员及分工
| 序号 | 姓名 | 职称 | 部门及职位 | 分工建议 | 备注 |
|------|------|------|------------|----------|------|
| 1 | 隋强 | | 长城银河 | 项目经理 | |
| 2 | 许骄 | | 长城银河 | 软件开发 | |
| 3 | 欧高亮 | | 长城银河 | 产品定义及开发 | |
| 4 | 关洪涛 | | 长城银河 | 软件测试 | |
| 5 | 周倩 | 工程师 | 长城银河 | 项目管理 | |
---
## 8 进度安排
本项目周期为：2025年07月 - 2025年12月（6个月）
| 阶段 | 时间 | 主要工作 | 里程碑 | 交付物 |
|------|------|---------|--------|--------|
| 需求与设计 | 7月 | 需求分析、架构设计 | 完成需求评审 | 需求规格书 |
| 核心开发 | 8-9月 | 核心框架、导入、量化、导出 | 完成核心功能 | Alpha版本 |
| 接口与工具 | 10月 | CLI、Python API、调试工具 | 完成接口开发 | Beta版本 |
| 测试验证 | 11月 | 单元测试、集成测试、性能测试 | 完成测试 | 测试报告 |
| 文档与发布 | 12月 | 文档完善、打包发布 | 正式发布 | v1.0版本 |
---
## 9 成果要求
### 9.1 技术文件类成果
- 软件源码：netrans_cli、netrans_py
- CLI 参考手册
- Python API 参考手册
- 使用指南（Cookbook）
- 设计文档（AGENTS.md）
- 版本发布记录
### 9.2 实物类成果
无。
### 9.3 知识产权类成果
软件著作权：1 项
---
## 10 经费预算
本项目预算：5 万元。
| 类别 | 金额（万元） | 说明 |
|------|-------------|------|
| 人力成本 | 4 | 开发人员工资及福利 |
| 设备/软件 | 0.5 | 开发环境、测试设备 |
| 外协/咨询 | 0.3 | 技术支持、培训 |
| 其他 | 0.2 | 差旅、资料等 |
| **合计** | **5** | |
---
## 11 存在风险及控制措施
### 11.1 技术风险及控制措施
**性能优化风险**。优化算法效果可能不及预期。
控制措施：建立完善的测试体系，覆盖主流模型（ResNet、YOLO 等），定期与芯片团队对齐优化策略。
**模型精度风险**。转换过程中可能出现精度损失。
控制措施：建立量化精度评估流程，提供 dump 和 inference 工具帮助定位精度问题。
**框架兼容性风险**。深度学习框架版本更新快，可能导致兼容性问题。
控制措施：明确支持的框架版本范围，对不兼容情况提供明确的错误提示。
### 11.2 进度风险及控制措施
无。
### 11.3 供应链风险及控制措施
**核心依赖风险**。本项目核心依赖 acuitylib，存在供应商技术支持和版本更新依赖。
控制措施：与供应商建立稳定的技术支持渠道；通过架构设计降低对单一供应商的依赖；调研备选方案，评估迁移成本。
### 11.4 资源配置风险及控制措施
目前软件团队可支持该项目的开发人员有限，存在人员流失导致项目停滞的风险。
控制措施：
1. 招聘有经验的工程师，及时补充团队核心成员
2. 在团队内发展复合技术人员
3. 保留完整的开发过程文档，确保其他开发人员能快速接手
4. 建立代码审查机制，确保至少 2 人熟悉核心代码
---
## 12 产品其它需求描述
无。
---
## 附录A：WB成熟度分析
### A.1 成熟度等级定义
WB（Workbench）成熟度采用简化的 1-5 级模型，评估工具链的工程化完善程度：
| 等级 | 名称 | 典型特征 |
|------|------|----------|
| L1 | 概念级 | 技术概念已形成，基本原理可行 |
| L2 | 组件级 | 核心组件在实验室环境验证 |
| L3 | 系统级 | 完整系统在模拟环境验证，可运行但需专家操作 |
| L4 | 产品级 | 系统在真实环境验证，可交付，有文档和基础工具 |
| L5 | 成熟级 | 系统成熟，易用性好，有完整工具链和标准化流程 |
### A.2 评估维度与现状分析
从六个维度评估 AI 编译器工具链的成熟度：
| 维度 | 说明 | Acuitylib现状 | Netrans目标 |
|------|------|---------------|-------------|
| 工具链完整性 | 从模型到芯片的端到端能力 | L3-L4 | L5 |
| 标准化程度 | 流程统一、配置规范 | L3 | L5 |
| 易用性 | 学习成本、操作简便性 | L3 | L5 |
| 可调试性 | 问题定位、调试工具 | L3 | L5 |
| 可维护性 | 代码质量、架构清晰 | L3 | L4 |
| 可扩展性 | 新需求支持、模块化 | L3 | L4 |
### A.3 成熟度提升的关键措施
| 维度 | 提升措施 | 对应WBS工作包 |
|------|---------|--------------|
| 工具链完整性 | 端到端标准化流程 | 130,140,150,160,170 |
| 标准化程度 | 统一YAML+CLI规范 | 121,132,210 |
| 易用性 | CLI+Python API双模式 | 123,190,213 |
| 可调试性 | dump/inference/measure工具链 | 180 |
| 可维护性 | 自主代码，模块化架构 | 122,133,214 |
| 可扩展性 | 配置驱动，分层架构 | 122,132 |
### A.4 WBS工作分解结构
```
Netrans 模型转换工具链开发项目 (100)
│
├── 1. 项目管理 (110)
│ ├── 111. 项目计划与跟踪
│ ├── 112. 需求管理
│ ├── 113. 配置管理
│ └── 114. 质量保证
│
├── 2. 需求与设计 (120)
│ ├── 121. 需求分析
│ ├── 122. 架构设计
│ ├── 123. 接口设计
│ └── 124. 技术方案评审
│
├── 3. 核心框架开发 (130)
│ ├── 131. Netrans核心类实现
│ ├── 132. 配置管理系统
│ ├── 133. 异常处理体系
│ ├── 134. 装饰器与工具函数
│ └── 135. 模型元数据管理
│
├── 4. 模型导入模块 (140)
│ ├── 141. Caffe导入器
│ ├── 142. TensorFlow导入器
│ ├── 143. ONNX导入器
│ ├── 144. PyTorch导入器
│ ├── 145. TFLite导入器
│ ├── 146. Darknet导入器
│ └── 147. Keras导入器
│
├── 5. 量化模块 (150)
│ ├── 151. 基础量化引擎
│ ├── 152. 多类型量化支持
│ ├── 153. 量化算法实现
│ ├── 154. 混合精度量化
│ └── 155. 激活权重量化分离
│
├── 6. 前后处理集成 (160)
│ ├── 161. 预处理嵌入
│ └── 162. 后处理嵌入
│
├── 7. NBG导出模块 (170)
│ ├── 171. PNNA平台导出
│ ├── 172. PNNA2平台导出
│ └── 173. 多核配置管理
│
├── 8. 调试分析工具 (180)
│ ├── 181. 张量导出工具
│ ├── 182. 推理验证工具
│ ├── 183. 性能测量工具
│ └── 184. Opset检查工具
│
├── 9. 接口层开发 (190)
│ ├── 191. Python API实现
│ ├── 192. CLI工具实现
│ └── 193. 命令行解析与帮助系统
│
├── 10. 测试验证 (200)
│ ├── 201. 单元测试
│ ├── 202. 集成测试
│ ├── 203. 性能测试
│ ├── 204. 示例工程
│ └── 205. 回归测试套件
│
├── 11. 文档与交付 (210)
│ ├── 211. API参考手册
│ ├── 212. CLI使用手册
│ ├── 213. 开发指南
│ ├── 214. 设计文档
│ ├── 215. 示例代码与教程
│ └── 216. 发布说明
│
└── 12. 产品化与维护 (220)
├── 221. 安装包制作
├── 222. CI/CD流程
├── 223. 版本管理
└── 224. 问题跟踪与修复
```
### A.5 工作量估算
| WBS编号 | 工作包 | 估算工时(人天) |
|---------|--------|----------------|
| 1.x | 项目管理 | 20 |
| 2.1 | 模型导入模块 | 30 |
| 2.2 | 模型量化模块 | 25 |
| 2.3 | 前后处理模块 | 15 |
| 2.4 | 模型导出模块 | 20 |
| 2.5 | 调试分析模块 | 15 |
| 3.1 | 命令行接口 | 15 |
| 3.2 | Python API | 20 |
| 4.x | 测试与质量保证 | 40 |
| 5.x | 文档编制 | 25 |
| 6.x | 部署与发布 | 10 |
| **合计** | | **235人天**（约5人月） |
---
*文档结束*

BIN
docs/pmf/产品需求规格书-PNNA_Driver.docx
View File

Binary file not shown.

BIN
docs/pmf/产品需求规格书-检测流程信息化系统.docx
View File

Binary file not shown.

0
docs/temp.md
View File