diff --git a/docs/Vivante.Programming.ACUITY.Toolkit.User.Guide-v6.33.x-B-20240625.pdf b/docs/Vivante.Programming.ACUITY.Toolkit.User.Guide-v6.33.x-B-20240625.pdf deleted file mode 100644 index 95ee6c5..0000000 Binary files a/docs/Vivante.Programming.ACUITY.Toolkit.User.Guide-v6.33.x-B-20240625.pdf and /dev/null differ diff --git a/docs/acuity_quantization_types.md b/docs/acuity_quantization_types.md deleted file mode 100644 index d4c74a2..0000000 --- a/docs/acuity_quantization_types.md +++ /dev/null @@ -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` - 混合量化实现 diff --git a/docs/acuity_readme.md b/docs/acuity_readme.md deleted file mode 100755 index 104e93a..0000000 --- a/docs/acuity_readme.md +++ /dev/null @@ -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 diff --git a/docs/backup/cookbook.md b/docs/backup/cookbook.md deleted file mode 100644 index 6139a03..0000000 --- a/docs/backup/cookbook.md +++ /dev/null @@ -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}: 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}: 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) diff --git a/docs/backup/netrans_api.md b/docs/backup/netrans_api.md deleted file mode 100644 index 02357e9..0000000 --- a/docs/backup/netrans_api.md +++ /dev/null @@ -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长度不匹配 -``` - -**验证方法：** -检查模型输入元数据文件`_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/__nbg_unify/network_binary.nb`: 最终NBG文件 -- `wksp/__nbg_unify/nbg_meta.json`: NBG元数据 -- `wksp/__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/_/`: 张量数据目录 -- `*.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/_/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使用问题，请参考示例代码或联系技术支持团队。 \ No newline at end of file diff --git a/docs/backup/netrans_cli.md b/docs/backup/netrans_cli.md deleted file mode 100644 index eb958ea..0000000 --- a/docs/backup/netrans_cli.md +++ /dev/null @@ -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 [--mean [,[,]]] [--scale [,[,]]] [--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` 长度必须与输入通道数一致。 - -#### 运行结果 -- 生成 `/channel_mean_value.txt`（若用户指定均值或缩放） -- 生成 `/.json` 内部网络描述，供后续子命令读取 - -#### 异常说明 -若目录内存在多个候选模型文件，或扩展名不被识别，命令将终止并返回非零退出码，同时向标准错误输出具体原因。 - -### 3.2 netrans quantize -对载入后的网络执行静态量化，生成量化配置文件。 - -#### 用法 -```bash -netrans quantize [--algorithm ] [--iterations ] [--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 算法一次迭代。 - -#### 运行结果 -- 生成 `/_.quantize` 量化配置 -- 若指定 --entropy，额外输出张量熵日志 - -#### 异常说明 -若未先执行 load，或量化文件已存在且被覆盖保护，将报"无法创建量化配置"错误。 - -### 3.3 netrans quantize_hybrid -对指定层列表使用混合精度量化，其余层沿用基准量化类型。 - -#### 用法 -```bash -netrans quantize_hybrid --cust-qnt-layers [--hybrid-qtype ] [--algorithm ] [--iterations ] [--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 量化。 - -#### 运行结果 -- 生成 `/__hy.quantize` 混合量化配置 -- 生成 `/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 [--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 -``` -将前后处理节点嵌入当前量化网络。 - -#### 运行结果 -- 更新 `/_.json`（节点增加） -- 若 --use-hybrid，则读取 hybrid 量化文件 - -#### 异常说明 -若未先执行量化，或量化文件与 --use-hybrid 不匹配，将报"Quantize file not found"。 - -### 3.5 netrans export -生成 PNNA 芯片可加载的 .nb 网络二进制文件。 - -#### 用法 -```bash -netrans export --platform [--use-hybrid] [--preprocess ] [--postprocess ] [--core-num ] [--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/_[_hy]_nbg_unify/network_binary.nb` -- 生成 `network_binary.desc`（文本描述，调试用） - -#### 异常说明 -若平台代号错误，或 NBG 编译器返回非零，将报"Export failed"并附详细日志。 - -### 3.6 netrans dump -导出网络各层激活张量，用于精度比对与调试。 - -#### 用法 -```bash -netrans dump [--use-hybrid] [--verbose] -``` - -#### 参数列表 -| 参数 | 必要性 | 类型 | 描述 | -|---|---|---|---| -| dir | 必选 | 路径 | 已量化模型目录 | -| qtype | 必选 | string | 量化类型 | - -| 选项 | 必要性 | 类型 | 默认值 | 描述 | -|---|---|---|---|---| -| --use-hybrid | 可选 | flag | — | 使用 hybrid 量化文件 | -| --verbose, -v | 可选 | flag | — | 同前 | - -#### 示例 -```bash -$ netrans dump . asymu8 -``` -导出 asymu8 量化后各层张量。 - -#### 运行结果 -- 生成 `dump/_[_hy]/*.tensor`（每层一个文件） - -#### 异常说明 -若量化文件缺失，或输出目录不可写，将报"Dump failed"。 - -### 3.7 netrans inference -执行一次前向推理，并将输入/输出张量保存至 golden 目录。 - -#### 用法 -```bash -netrans inference [--iterations ] [--use-hybrid] [--verbose] -``` - -#### 参数列表 -| 参数 | 必要性 | 类型 | 描述 | -|---|---|---|---| -| dir | 必选 | 路径 | 已量化模型目录 | -| qtype | 必选 | string | 量化类型 | - -| 选项 | 必要性 | 类型 | 默认值 | 描述 | -|---|---|---|---|---| -| --iterations | 可选 | int | 1 | 推理迭代次数 ≥1 | -| --use-hybrid | 可选 | flag | — | 使用 hybrid 量化文件 | -| --verbose, -v | 可选 | flag | — | 同前 | - -#### 示例 -```bash -$ netrans inference . asymu8 --iterations 1 -``` -执行一次推理并保存输入输出。 - -#### 运行结果 -- 生成 `wksp/_[_hy]/golden/input_*.tensor` -- 生成 `wksp/_[_hy]/golden/output_*.tensor` - -#### 异常说明 -若输入数据缺失或张量形状不匹配，将报"Inference failed"并附出错层名。 - -### 3.8 netrans check_opset -检查 ONNX 模型的 opset 版本是否符合 Netrans 要求。 - -#### 用法 -```bash -netrans check_opset [--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) —— 场景脚本合集 diff --git a/docs/backup/release.md b/docs/backup/release.md deleted file mode 100644 index 1c6898d..0000000 --- a/docs/backup/release.md +++ /dev/null @@ -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 开发组 -**问题反馈**: 请联系项目维护团队 diff --git a/docs/ci-setup.md b/docs/ci-setup.md deleted file mode 100644 index 87f96af..0000000 --- a/docs/ci-setup.md +++ /dev/null @@ -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 平台手动运行该流水线。 diff --git a/docs/design/README.md b/docs/design/README.md deleted file mode 100644 index e6db16c..0000000 --- a/docs/design/README.md +++ /dev/null @@ -1,13 +0,0 @@ -# Netrans 设计文档 - -本目录包含 Netrans 的技术设计方案和架构决策记录。 - -## 文档列表 - -| 文档 | 说明 | -|------|------| -| [multicore-and-platform-config.md](multicore-and-platform-config.md) | 多核配置与平台差异化配置设计 | - -## 归档文档 - -历史设计文档已归档到 `devtools/dev/archive/` 目录。 diff --git a/docs/design/multicore-and-platform-config.md b/docs/design/multicore-and-platform-config.md deleted file mode 100644 index 4e157be..0000000 --- a/docs/design/multicore-and-platform-config.md +++ /dev/null @@ -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 -- **变更类型**：功能增强 -- **兼容性**：向前兼容，无破坏性变更 \ No newline at end of file diff --git a/docs/pmf/CONTEXT.md b/docs/pmf/CONTEXT.md deleted file mode 100644 index e927ce7..0000000 --- a/docs/pmf/CONTEXT.md +++ /dev/null @@ -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/` | 产品需求规格书 | - ---- - -*本文档用于上下文恢复，如有更新请同步修改。* diff --git a/docs/pmf/PROJECT_CONTEXT.md b/docs/pmf/PROJECT_CONTEXT.md deleted file mode 100644 index a4b2d58..0000000 --- a/docs/pmf/PROJECT_CONTEXT.md +++ /dev/null @@ -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 会话开始时阅读，确保项目理解的一致性。* diff --git a/docs/pmf/产品需求规格书-Netrans软件-WB成熟度与WBS草稿.md b/docs/pmf/产品需求规格书-Netrans软件-WB成熟度与WBS草稿.md deleted file mode 100644 index 730ead2..0000000 --- a/docs/pmf/产品需求规格书-Netrans软件-WB成熟度与WBS草稿.md +++ /dev/null @@ -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* -*待完善：详细工期估算、资源分配、里程碑定义* diff --git a/docs/pmf/产品需求规格书-Netrans软件-v2.md b/docs/pmf/产品需求规格书-Netrans软件-v2.md deleted file mode 100644 index ae67f12..0000000 --- a/docs/pmf/产品需求规格书-Netrans软件-v2.md +++ /dev/null @@ -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人月） | - ---- - -*文档结束* diff --git a/docs/pmf/产品需求规格书-Netrans软件-v3.md b/docs/pmf/产品需求规格书-Netrans软件-v3.md deleted file mode 100644 index 5736df6..0000000 --- a/docs/pmf/产品需求规格书-Netrans软件-v3.md +++ /dev/null @@ -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人月） | - ---- - -*文档结束* diff --git a/docs/pmf/产品需求规格书-Netrans软件-v4.md b/docs/pmf/产品需求规格书-Netrans软件-v4.md deleted file mode 100644 index 22c6628..0000000 --- a/docs/pmf/产品需求规格书-Netrans软件-v4.md +++ /dev/null @@ -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人月） | - ---- - -*文档结束* diff --git a/docs/pmf/产品需求规格书-Netrans软件-优化版.md b/docs/pmf/产品需求规格书-Netrans软件-优化版.md deleted file mode 100644 index 26fe1a6..0000000 --- a/docs/pmf/产品需求规格书-Netrans软件-优化版.md +++ /dev/null @@ -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词典、工作量估算 | diff --git a/docs/pmf/产品需求规格书-Netrans软件.docx b/docs/pmf/产品需求规格书-Netrans软件.docx deleted file mode 100644 index 02ef5f5..0000000 Binary files a/docs/pmf/产品需求规格书-Netrans软件.docx and /dev/null differ diff --git a/docs/pmf/产品需求规格书-Netrans软件.md b/docs/pmf/产品需求规格书-Netrans软件.md deleted file mode 100644 index 7d5789f..0000000 --- a/docs/pmf/产品需求规格书-Netrans软件.md +++ /dev/null @@ -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人月） | - ---- - -*文档结束* diff --git a/docs/pmf/产品需求规格书-PNNA_Driver.docx b/docs/pmf/产品需求规格书-PNNA_Driver.docx deleted file mode 100644 index 592914c..0000000 Binary files a/docs/pmf/产品需求规格书-PNNA_Driver.docx and /dev/null differ diff --git a/docs/pmf/产品需求规格书-检测流程信息化系统.docx b/docs/pmf/产品需求规格书-检测流程信息化系统.docx deleted file mode 100644 index 0c7e899..0000000 Binary files a/docs/pmf/产品需求规格书-检测流程信息化系统.docx and /dev/null differ diff --git a/docs/temp.md b/docs/temp.md deleted file mode 100644 index e69de29..0000000