HiSpark AI

- 软件资料
  - AMCT模型压缩工具用户指南
    - 学习向导
    - 概述
    - 准备环境
    - 快速入门
    - AMCT（PyTorch）
    - AMCT（ONNX）
    - AMCT（TensorFlow）(不支持)
    - AMCT（Caffe）(不支持)
    - 命令行参数说明
    - 样例列表
    - FAQ
    - 附录
  - ATC离线模型编译工具用户指南
    - 学习向导
    - ATC简介
    - 准备环境
    - 快速入门
    - 初级功能
    - 高级功能
    - 参数说明
    - 专题
    - 参考
    - FAQ
  - HiSpark Studio AI for VS Code使用指南
    - 前言
    - HiSpark Studio AI简介
    - 数据准备与环境搭建
    - Hi3863操作指南
    - Hi3322操作指南
  - HiSpark.AI API开发指南
    - 前言
    - 简介
    - 接口调用流程介绍
    - HiSpark.AI API参考
    - 样例使用指导
    - FAQ
  - HiSpark.AI 快速入门指南
    - 前言
    - 简介
    - 开发板准备
    - 开发环境准备
    - 样例运行
    - 常见错误
  - HiSpark.AI 转换工具使用指南
    - 前言
    - Converter_lite工具使用环境搭建
    - 快速入门
    - 基础知识
    - 初级功能
    - 参数说明
    - 算子规格参考
    - 专题
  - Nano AI应用开发指导书
    - Nano AI应用界面
    - Nano 芯片支持数据类型和典型模型性能
    - Nano AI资料清单
    - Nano AI应用开发流程
    - FAQ
  - 应用开发指南
    - 简介
    - 准备环境
    - 编程接口与调用流程
    - 初始化与去初始化
    - 运行时资源管理
    - 模型管理
    - 更多特性
    - 应用编译&运行
    - 精度/性能优化
    - acl API参考
    - FAQ案例集
    - 附录
  - 开发环境安装指南
    - 简介
    - 获取软件包
    - 安装前准备
    - 安装
    - 常用操作
    - FAQ
    - 附录
    - Compiler的库文件存在路径
  - 术语和缩略语
    - 术语和缩略语
  - 模型评估脚本使用指南
    - 简介
    - 使用前准备
    - 使用步骤
  - 精度调试工具用户指南
    - 简介
    - 使用前准备
    - GPU vs NPU（TensorFlow离线推理）-IPV350不支持
    - GPU vs NPU（ONNX离线推理）-IPV350不支持
    - NPU vs NPU（离线推理）
    - 比对结果说明
    - 比对结果分析
    - 扩展功能
    - 附录
  - 驱动日志说明文档
    - 简介
    - 日志分类
    - 异常场景
    - 典型案例

### 该页内容

- 前言
- HiSpark Studio AI简介
  - 关于HiSpark Studio AI
  - 安装方案介绍
  - 窗口介绍
    - 整体窗口介绍
    - 侧边栏
    - 工作区
  - 关键概念
    - AMCT
    - ATC
- 数据准备与环境搭建
  - 数据准备
  - 环境搭建
- Hi3863操作指南
  - 工程创建
    - 约束说明
    - 界面介绍
      - 首页
      - 新建工程配置界面
  - 模型导入
    - 约束说明
    - 界面介绍
      - 整体界面
      - Linux导入配置界面（仅Linux端用户需要关注）
  - 模型量化
    - 约束说明
    - 量化前提
    - 界面介绍
      - 整体界面
      - 量化参数配置页面
      - 量化历史配置界面
      - 验证集精度分布直方图显示界面
  - 模型转换
    - 约束说明
    - 转换前提
    - 界面介绍
      - 整体界面
      - 转换参数配置页面
      - 转换历史配置界面
      - 内存占用分布条形图显示界面
  - 部署
    - 约束说明
    - 界面介绍
  - 模型调优
    - 约束说明
    - 调优前提
    - 界面介绍
      - 整体界面
      - 性能验证参数配置页面
      - 性能验证结果配置页面
      - 精度验证参数配置页面
      - 精度验证结果配置页面
      - 评估结果汇总页面
  - 应用开发
- Hi3322操作指南
  - 工程创建
    - 前提条件
    - 界面介绍
  - 模型导入
    - 约束说明
    - 前提条件
    - 界面介绍
  - 模型量化
    - 约束说明
    - 量化前提
    - 界面介绍
      - 整体界面
      - 量化参数配置界面
        - 训练后量化
        - 量化感知训练
      - 压缩历史显示界面
      - 验证集精度分布直方图显示界面
  - 模型转换
    - 整体界面
    - 模型转换参数配置界面
    - 转换历史显示界面
    - 转换结果显示界面
  - 部署
  - 模型调优
    - 约束说明
    - 调优前提
    - 界面介绍
      - 整体界面
      - 串口配置界面
      - 性能评估界面
      - 精度评估界面
      - 评估结果汇总界面
  - 应用开发

# 前言

概述

本文介绍 HiSpark Studio AI 插件工具，如何通过该工具进行模型量化、模型转换、模型评估，以及后续应用开发等功能。

读者对象

本文档主要适用于以下工程师：

- 技术支持工程师

- AI开发工程师

符号约定

在本文中可能出现下列标志，它们所代表的含义如下。

符号 | 说明
--- | ---
| 表示如不避免则将会导致死亡或严重伤害的具有高等级风险的危害。
| 表示如不避免则可能导致死亡或严重伤害的具有中等级风险的危害。
| 表示如不避免则可能导致轻微或中度伤害的具有低等级风险的危害。
| 用于传递设备或环境安全警示信息。如不避免则可能会导致设备损坏、数据丢失、设备性能降低或其它不可预知的结果。 “须知”不涉及人身伤害。
| 对正文中重点信息的补充说明。 “说明”不是安全警示信息，不涉及人身、设备及环境伤害信息。

修改记录

文档版本 | 发布日期 | 修改说明
--- | --- | ---
01 | 2026-03-27 | 第一次正式版本发布。

# HiSpark Studio AI简介

## 关于HiSpark Studio AI

HiSpark Studio AI是面向开发者提供的超轻量级AI应用开发平台，具备高集成、高专业、高易用等特征，聚焦嵌入式AI应用场景，提供模型压缩、模型转换、应用开发、端侧部署、性能调优的全流程开发平台。

- 高集成

  - 一站式开发平台，支持模型压缩/转换/推理/部署/调试等功能。

  - 统一的IDE界面和API接口，支持CPU/NPU等芯片AI应用开发和部署。

- 高专业

  - 高效的模型压缩，支持ONNX/TFLITE等AI模型。

  - 超轻量的模型部署，支持KB级RAM嵌入式设备。

- 高易用

  - 提供VS Code插件，方便安装和使用。

  - 支持性能/精度可视化分析，方便调试。

- 功能介绍

  HiSpark Studio AI功能架构如下图所示。具备核心功能有：

  - 导入ONNX/TFLITE等格式的AI模型，初始化开发环境。

  - 通过集成的NPU/CPU工具链可以进行模型压缩和转换。

  - 导入SDK并参考Sample进行用户AI应用开发。

  - 编译用户AI应用，烧录到嵌入式设备进行部署。

  - 根据串口日志检测性能精度是否达成目标。

  图 1 HiSpark Studio AI 功能架构

## 安装方案介绍

> 须知： 若之前已经安装过DevEco相关的插件，请手动禁用或者卸载所有与DevEco相关的插件，否则会与HiSpark Studio插件功能冲突。

1. 打开VS Code插件市场。

2. 搜索并安装HiSpark Studio AI。

   为保证功能正常运行，还需安装HiSpark Studio插件，需安装v26.4.1版本。

## 窗口介绍

### 整体窗口介绍

HiSpark Studio AI整体窗口如图1所示，主要包含两个部分：

1. 侧边栏：HiSpark Studio AI功能导航栏。

2. 工作区：HiSpark Studio AI工作区。

图 1 HiSpark Studio AI整体窗口

### 侧边栏

侧边栏为功能导航栏，展示了HiSpark Studio AI插件提供的五个主要功能，分别为：

1. Home（主页）：单击进入新建/导入工程，或在已打开工程的情况下进入HiSpark Studio AI模型选择主界面。

2. User Guide（用户指南）：单击在工作区打开用户指南，提供快速入门指南。

3. Connect to Server（连接服务器）：单击连接至服务器。

4. Command Line（命令行工具）：单击在命令行中运行HiSpark Studio AI的量化、转换等功能。

5. Download Toolchain（下载工具链）：单击下载运行HiSpark Studio AI插件所需要的工具链，并自动配置环境。

### 工作区

工作区为插件核心功能展示区域，详细交互逻辑请参见后续章节。

图 1 HiSpark Studio AI核心工作区示意图

## 关键概念

本文档中涉及如下概念，在此处做统一说明。

### AMCT

AMCT（Ascend Model Compression Toolkit，简称AMCT）是一个针对昇腾芯片的深度学习模型压缩工具包，提供量化、张量分解等多种模型压缩特性，压缩后的模型体积变小，部署到NPU IP加速器上后可使能低比特运算，提高计算效率，从而实现性能提升。有关AMCT具体操作请参考《AMCT模型压缩工具用户指南》。

### ATC

昇腾张量编译器（Ascend Tensor Compiler，简称ATC）是CANN异构计算架构体系下的模型转换工具，它可以将开源框架的网络模型转换为NPU IP加速器支持的离线模型。有关ATC具体操作请参考《ATC离线模型编译工具用户指南》。

# 数据准备与环境搭建

## 数据准备

模型的训练后量化校准、量化感知训练、量化精度评估以及上板精度评估等操作需要对应数据，请按照如下格式准备数据：

- 数据存储为npy格式，每个文件对应一个与网络输出张量匹配的样本。

- 若模型有多个输出，则不同的输出必须存储在不同的目录中。同一个样本不同的输出名称需要保持一致。

- 分类任务真值存储为csv格式。包含两列sample和label，其中sample表示样本的名称，和npy文件名保持一致。label表示标签值。csv文件示例见表1。

  表 1 分类真值标签csv表格示例

  sample | label
  --- | ---
  sample_00000_7.npy | 7
  sample_00001_2.npy | 2

## 环境搭建

环境配置请参考《HiSpark.AI 快速入门指南》。

# Hi3863操作指南

## 工程创建

### 约束说明

> 须知： 新建工程需要满足以下条件：

> 1. 用户使用WS63 SDK版本需要社区版本（WS63社区链接） 或海思发布的商用版本。商用客户优先使用商用版本。

> 2. SDK存放路径必须为英文路径。

### 界面介绍

#### 首页

单击HiSpark Studio AI插件中的“Home”按钮，进入首页如图1所示。

图 1 HiSpark Studio AI首页

若用户首次使用HiSpark Studio AI，单击“New Project”即可创建新项目。若用户需要项目迁移，也可以选择“Import Project”导入已有项目。

#### 新建工程配置界面

选择芯片为WS63，选择已准备好的SDK目录，工程项目目录选择SDK相同路径即可。

图 1 HiSpark Studio AI新建工程配置界面

新建工程导入页面的具体逻辑如下，参数详细配置如表1所示。

1. 选择芯片“SOC”为WS63，“Board”为WS63，“Project Type”为Common Project通用项目。

2. 填写“Project Name”为项目名称。

3. 配置“Project Path”以及“SDK”，一般情况下，配置为下载的SDK路径。

表 1 新建工程参数配置

参数 | 说明
--- | ---
SOC | AI部署工程SOC类型。
Board | AI部署工程所用具体单板型号。
Project Name | 项目名称。
Project Path | 工程配置相关文件存放路径。
SDK | SDK文件存放路径。
Finished | 完成新建文件。
Cancel | 取消新建文件。

> 须知：

> 1. 用户需要提前准备WS63 SDK解压到指定目录，一级目录包含application、tools等文件夹。

> 2. 通常情况下，用户将“SDK”和“Project Path”设置为相同路径即可。如果用户有将“.hiproj”等项目文件与SDK文件夹分开放置的需求，可以创建一个新的文件夹，专门用于放置项目文件，并单独配置到“Project Path”中。

## 模型导入

模型导入主要帮助用户将本地已经训练好的ONNX模型或者TFLITE模型加载到HiSpark Studio AI中，并且记录之前的导入记录。

### 约束说明

> 须知： 用户导入的模型有以下约束：

> 1. ONNX模型满足Opset版本小于等于18。

> 2. TFLITE推荐版本为Tensorflow 2.13。

> 3. ONNX以及TFLITE模型中的算子必须位于列表中，具体清单请参考《HiSpark. AI 转换工具 使用指南》。

> 4. 目前仅支持浮点ONNX以及TFLITE模型，量化后的模型暂时不支持。

### 界面介绍

#### 整体界面

图 1 模型导入整体页面

模型导入的界面如图1所示。主要包含以下部分：

1. 跳转标签（Select Model -> Quantize -> Convert -> Deploy -> Benchmark），当存在历史操作记录时，完成界面的切换。

2. 模型选择页面，用于选择部署目标模型。

3. 历史模型选择记录页面，显示所有的选择过模型的大小、修改时间，并提供回溯历史步骤以及删除功能。

模型导入步骤如下：

1. 进入模型选择页面，单击“Import Model”按钮，选择对应的Mnist ONNX模型，测试模型请参考Mnist-12.onnx。

2. 模型导入结束，进入量化页面。

#### Linux导入配置界面（仅Linux端用户需要关注）

1. 首次单击“Import Model”按钮，需要用户填写服务器相关配置，用于连接远端服务器（需要先按照快速入门指南环境准备章节配置环境）。

2. 单击“仅命令传输 & 待定文件下载连接”按钮。

图 1 Linux服务器连接选项页面

## 模型量化

### 约束说明

> 须知： 在进行模型压缩前，有以下约束：

> 1. 模型压缩仅针对ONNX以及TFLITE两种格式的模型。

> 2. 模型压缩仅支持未进行过量化的模型，已量化完成的ONNX以及TFLITE不支持。

> 3. 任何网络都会被处理为分类网络，带标签的量化精度准确率评估仅针对网络输入为[N, D]格式。

### 量化前提

用户需要准备模型量化的输入数据（Linux用户需要提前将数据放置到Docker环境所在的服务器上），可参考《快速入门指南》的“样例运行”章节准备。

### 界面介绍

#### 整体界面

图 1 模型量化示意图

模型压缩界面如图1所示，整体界面主要包含四个部分：

1. 跳转标签页面，能否跳转到该量化记录关联的前后步骤。

2. 量化参数配置界面。

3. 压缩历史显示界面，显示所有的量化网络余弦相似度、MSE、准确率等指标。

4. 样本精度分布直方图显示界面，显示验证集量化输出与浮点标杆相似度的直方图界面。

量化步骤如下：

1. 进入量化页面，配置量化参数，参数详情请参见“量化参数配置页面”。

   > 说明： 量化输入数据以及验证输入数据需要输入文件夹路径，文件夹内数据保持为npy格式。 多输入模型不同输入文件夹内每个npy文件名称代表样本名，样本名称需要保持一致。

2. 单击“Quantize”按钮，输出量化余弦相似度、准确率以及MSE等结果；单击“Next Without Quantization”按钮，直接跳过3和4进入转换步骤。

3. 在量化历史配置界面与验证集精度直方图分布界面，查看量化结果。

4. 单击“Next”进入下一步。

#### 量化参数配置页面

图 1 模型量化参数配置界面

参数解释如表1所示。

表 1 量化参数配置

参数 | 说明
--- | ---
Quantized Data Type | 数据量化的数据位数。目前仅支持8bit量化，权重或激活值会转换成int8类型来参与计算。
Quant Type | 数量量化类型。目前仅支持全量化。 FULL_QUANT：支持量化的算子权重以及中间层张量会被同时量化为低精度。
Calibration Inputs | 用户在该表格中输入量化的校准数据。表格中各列的含义如下所示： Input Node：网络输入节点的名称。 Path：校准数据的目录。目录中存放和模型输入匹配的npy文件数据。若模型有多个输入，同一个校准样本的多个输入npy文件文件名必须保持一致。 Shape（不可配置）：网络输入张量的形状。
Validation | 使能验证开关。当开关打开时，验证数据集输入界面展开，如图3所示。
Validation Inputs | 用户在该表格中输入量化评估网络的验证数据集。表格中各列的含义如下图3所示： Input Node：网络输入节点的名称。 Path：验证数据的目录。目录中存放和模型输入匹配的npy文件数据。若模型有多个输入，同一个验证样本的多个输入npy文件文件名必须保持一致。
Validation Labels | 使能开关打开后，输入含分类真值标签的csv表格文件。文件中的表格格式如表2所示。各列的含义如下所示： sample：验证样本的名称。 label：验证样本的标签值。
Quantize | 开始量化按钮。

图 2 跳过量化按钮

单击“Next Without Quantization”按钮，即可跳过量化步骤，直接转换成浮点模型。

图 3 验证数据输入页面

Validation Labels输入csv格式如表2所示。

表 2 label.csv文件内容

sample | label
--- | ---
sample_00000_7.npy | 7
sample_00001_2.npy | 2

> 说明： label.csv中为样本分类的真值标签。文件中的表格格式如表2所示。其中sample列表示样本的名称，label列表示样本对应的真值标签。

#### 量化历史配置界面

量化历史显示窗口如图1所示。

图 1 量化历史配置页面

该窗口以表格的方式显示历史量化的结果。表头解释如表1所示。

表 1 历史压缩结果表头说明

项目 | 说明
--- | ---
Trail ID | 网络量化结果的序号。
Model Name | 网络的名称，以及模型大小和修改时间。
Accuracy | 表示分类结果准确率，使用标签真值计算。
Cosine Similarity | 余弦相似度，使用量化评估网络的输出和原始浮点网络的输出计算。
MSE | 均方误差，使用量化评估网络的输出和原始浮点网络的输出计算。
RAM(KB) | 上板AI相关RAM内存估计。
FLASH(KB) | 上板AI相关FLASH内存估计。
Operation | 操作按钮： ：下载压缩结果。下载的压缩包中包含： {模型名称}.ms：量化后模型IR。 {模型名称}.cfg：量化配置。 quant_plot.json：量化评估结果文件。 ：删除当前记录。 ：跳转到模型转换页面，在模型转换页面对当前行对应的压缩网络进行模型转换。

#### 验证集精度分布直方图显示界面

验证集精度分布直方图显示窗口如图1所示，该窗口显示验证集的余弦相似度的分布图。横轴为余弦相似度，纵轴为验证集样本的百分比。

图 1 验证集精度分布直方图显示界面

## 模型转换

### 约束说明

> 须知： WS63模型转换需要满足以下条件：

> 1. 用户转换的模型格式、版本以及算子需要满足条件详见“约束说明”以及“约束说明”。

> 2. 用户需要确保Docker容器中MSLite工具链配套环境的完备性。（Windows侧用户保证toolchain文件中tools下存在“mindspore-xxx-lite-xxx.x.x-win-x64”文件夹；Linux侧用户保证Docker容器内“/usr/src/mindspore”存在对应的“mindspore-xxx-lite-xxx.x.x-linux-x64”文件夹）

### 转换前提

用户已成功完成量化或跳过量化，且量化所用的校准数据位置不改变。

### 界面介绍

#### 整体界面

图 1 模型转换整体界面

模型转换整体界面如图1所示，主要包含四个部分：

1. 跳转标签页面，能否跳转到该量化记录关联的前后步骤。

2. 转换参数配置界面。

3. 历史转换记录配置界面，显示所有的转换网络余弦相似度、MSE、准确率、RAM、FLASH等指标。

4. 转换结果RAM/FLASH对比界面，显示模型转换预估上板的各项RAM/FLASH估计。

转换步骤：

1. 进入转换页面，配置转换参数，参数详情详见“转换参数配置页面”。

2. 单击“Convert”按钮，输出转换RAM/FLASH等结果。

3. 单击“Next”进入下一步。

#### 转换参数配置页面

图 1 转换参数配置页面

参数解释如表1所示。

表 1 转换参数配置

参数 | 说明
--- | ---
Input Node（不可配置） | 输入变量名称。
Shape（不可配置） | 输入变量形状。
Data Type（不可配置） | 输入变量的数据类型。
Convert | 开始转换按钮。

#### 转换历史配置界面

图 1 历史转换结果配置界面

该窗口以表格的方式显示历史转换的结果。表头解释如表1所示。

表 1 历史转换结果表头说明

项目 | 说明
--- | ---
Trail ID | 网络转换结果的序号。
Model Name | 网络的名称，以及模型大小和修改时间。
Accuracy | 表示分类结果准确率，使用标签真值计算。
Cosine Similarity | 余弦相似度，使用量化评估网络的输出和原始浮点网络的输出计算。
MSE | 均方误差，使用量化评估网络的输出和原始浮点网络的输出计算。
RAM(KB) | 上板AI相关RAM内存估计。
FLASH(KB) | 上板AI相关FLASH内存估计。
Operation | 操作按钮： ：下载转换结果。下载的压缩包中包含： micro_gen文件夹：转换后的工程文件。 converter.cfg：转换配置。 convert_plot.json：转换评估结果文件。 ：删除当前记录。 ：跳转到部署页面，对模型进行进一步的部署与调优。

#### 内存占用分布条形图显示界面

图 1 AI上板各存储占用分布

AI上板存储占比如图1所示，蓝色显示为RAM占用，绿色显示为FLASH占用，各参数显示具体含义如表1所示。

表 1 内存占用分布条形图各项含义

项目 | 所属类型 | 说明
--- | --- | ---
workspace | RAM | 存储输入输出中间数据所需的工作空间RAM大小。
stack | RAM | AI推理栈空间所占用大小。
pack_weight | RAM | AI推理针对权重额外辅助空间占用大小。
other | RAM | 其他对输入输出张量元信息存储占用等大小（输入输出张量名称，张量shape等）。
code | FLASH | AI推理相关算子，Runtime代码段占用。
data | FLASH | AI推理过程中数据段占用。
weight | FLASH | AI推理参数FLASH存储代码段占用（非数据段）。

## 部署

### 约束说明

> 须知： WS63模型部署需要满足以下条件： 用户必须已成功完成模型转换。

### 界面介绍

图 1 模型部署页面

模型部署整体界面如图1所示，主要包含四个部分：

1. 跳转标签页面，能否跳转到该量化记录关联的前后步骤。

2. 模型选择页面，展示已选中的模型。

3. SDK编译以及烧录页面。

4. 转换产物下载页面。

转换步骤如下：

1. 单击界面上SDK Compile右侧的“Build”按钮，进行SDK的编译。

2. 选择对应的Port以及Baud Rate，单击界面上的“Burn”按钮，完成固件烧录。

3. 单击“Next”按钮，进行下一步性能 & 精度验证。

## 模型调优

### 约束说明

> 须知： WS63模型调优需要满足以下约束条件：

> 1. 用户需要保证SDK的完整性，确保AI组件（Adaptor 以及 AI_AT组件）包含在SDK中。

> 2. 用户需要准备一块WS63单板，并且使用USB串口线与本地PC连接。

### 调优前提

用户已完成模型转换步骤。

### 界面介绍

#### 整体界面

图 1 WS63模型调优整体页面

模型调优界面如图1所示，主要包含五个部分：

1. 跳转标签页面，能否跳转到该量化记录关联的前后步骤。

2. 性能验证参数配置页面，配置相关的串口连接相关选项。

3. 性能验证结果评估页面，显示AI上板推理时间、RAM内存消耗、FLASH内存消耗等信息。

4. 精度验证参数配置页面，配置相关的精度验证输入数据输入等信息。

5. 精度验证结果评估页面，显示上板精度评估余弦相似度分布直方图 & 准确率等信息。

模型调优步骤如下：

1. 进入模型调优页面，选择单板连接的串口以及波特率。

2. 单击“Performance Evaluation”按钮，输出上板推理时间、RAM内存消耗、FLASH内存消耗等信息。

3. 选择Windows本地相应的验证数据输入文件夹等精度验证相关的选项。

   > 说明： 上板精度验证输入数据以及验证输入数据需要输入文件夹路径，文件夹内上板精度验证数据保持为npy格式。

4. 单击“Accuracy Evaluation”按钮，输出相关的准确率、余弦相似度分布以及上板推理的时间、精度等信息。

#### 性能验证参数配置页面

图 1 性能验证选项配置

参数解释如表1所示。

表 1 转换参数配置

参数 | 说明
--- | ---
Port | 单板连接的串口号。
Baud Rate | 单板连接的波特率。

#### 性能验证结果配置页面

图 1 性能验证结果页面

具体每个参数含义如表1所示。

表 1 性能验证结果

参数 | 说明
--- | ---
INFERENCE TIME | 上板AI推理时间。
RAM | 上板性能验证的RAM内存消耗。
FLASH | 上板性能验证的FLASH内存消耗。
Performance Evaluation | 性能验证按钮。

#### 精度验证参数配置页面

图 1 上板精度验证配置页面

参数解释如表1所示。

表 1 转换参数配置

参数 | 说明
--- | ---
Input Node | 上板精度验证输入名称。
Path | 上板精度验证输入数据文件夹路径。
Validation Labels | 上板精度验证的labels标签。
Accuracy Validation | 精度验证按钮。

#### 精度验证结果配置页面

上板精度验证结果页面主要分为以下三部分：

- 准确率信息

- 逐项结果展示

- 余弦相似度分布直方图

各参数如表1所示。

表 1 上板精度验证结果说明

参数 | 所属部分 | 说明
--- | --- | ---
ACCURACY | 准确率信息 | 上板精度验证准确率
Sample Name | 逐项结果展示 | 样本名称
Output Name | 逐项结果展示 | 指标所对应的输出名称
Predict | 逐项结果展示 | 上板推理结果
Golden | 逐项结果展示 | 标杆推理结果
Accuracy | 逐项结果展示 | 样本所对应的准确率信息
Cosine Similarity | 逐项结果展示 | 余弦相似度
Probability Density Histogram | 余弦相似度分布直方图 | 余弦相似度分布图

图 1 上板精度验证准确率信息

图 2 上板精度验证逐项结果展示

图 3 上板精度验证余弦相似度分布直方图

#### 评估结果汇总页面

单击“Summary of Results”按钮之后弹出评估结果汇总界面，该界面汇总每次评估的结果。如图1所示。

图 1 评估结果汇总界面

评估结果汇总界面元素说明如表1所示。

表 1 评估结果界面元素说明

指标 | 指标所属部分 | 说明
--- | --- | ---
Trail ID | ---- | 评估结果序号。
Model Name | Benchmark | 网络的名称，以及模型大小和修改时间。
Accuracy | Benchmark | 模型上板精度评估的准确率。
Cosine Similarity | Benchmark | 模型上板精度评估的平均余弦相似度，计算公式如下，其中表示模型上板推理的输出，表示原始浮点网络在Windows的输出，表示验证集样本的数量。
Inference Time | Benchmark | 模型性能评估上板推理的时间。
RAM | Benchmark | 模型上板推理所占用的RAM开销。
Flash | Benchmark | 模型上板推理所占用的FLASH开销。
Accuracy | Quantize | 模型量化准确率。
Cosine Similarity | Quantize | 模型量化平均余弦相似度，计算公式如上
MSE | Quantize | 模型量化的均方误差，计算公式如下，其中表示模型上板推理的输出，表示原始浮点网络在Windows的输出，表示验证集样本的数量。

## 应用开发

在HiSpark Studio AI中完成模型量化、转换之后，将模型导出并使用HiSpark.AI API完成应用开发。具体步骤如下。

1. 在“Deploy”页面下载转换好的Micro工程文件。

   图 1 下载micro工程文件

2. 具体API的用法请参考文档《HiSpark.AI API开发指南》

# Hi3322操作指南

## 工程创建

### 前提条件

在工程创建前，请先获取Hi3322 SDK，并存放于本地Windows环境。

### 界面介绍

进入HiSpark Studio AI单击“New Project”按钮进入新建工程页面。工程创建整体界面如图1所示。

图 1 工程创建整体界面

工程创建的步骤如下所示：

1. 选择3322 SOC。

2. 输入工程创建配置参数。

3. 单击“Finished”按钮。

工程创建界面元素说明如表1所示。

表 1 工程创建元素说明

元素 | 说明
--- | ---
SOC | SOC，请选择3322。
Board | 单板型号。默认选择3322。
Project Type | 工程类型，请选择Common Project。
Project Name | 用户自定义的工程名称。
Project Path | 用户自定义的工程文件存放路径。
SDK | Hi3322 SDK存放路径。
Finished | 完成创建工程按钮。
Cancel | 取消创建工程按钮。

## 模型导入

### 约束说明

> 须知： 在进行模型导入前，请务必查看如下约束要求： Hi3322平台只支持导入ONNX以及pt、pth模型。ONNX模型支持训练后量化。pt、pth模型支持量化感知训练。

### 前提条件

- 完成Linux服务器环境配置或者WSL环境配置。

- 连接Linux服务器或者WSL环境，若未完成连接，在单击“Import Model”按钮时会弹出Linux服务器或者WSL连接窗口。

- 若使用Linux服务器，将待处理的网络模型上传至Linux服务器。

### 界面介绍

模型导入界面整体界面如图1所示。

图 1 模型导入界面

模型导入界面主要元素说明如表1。

表 1 模型导入主要元素说明

元素 | 说明
--- | ---
Import Model | 模型导入按钮。完成导入后自动进入模型压缩界面。
History Files | 模型导入历史列表。单击“Next”按钮进入对应历史模型的模型压缩界面。

## 模型量化

### 约束说明

> 须知： 在进行模型压缩前，请务必查看如下约束要求：

> - 支持原始框架类型为ONNX的模型训练后量化PTQ。

> - 支持原始框架类型为PyTorch（参数后缀pt或pth）的模型量化感知训练QAT。

> - 只支持单输出分类网络计算量化评估网络的准确率。

> - 量化感知训练只支持单输入单输出分类网络。

### 量化前提

- 若使用Linux服务器，将待量化的模型、数据上传到服务器。数据格式见“数据准备与环境搭建”。

- 若使用Linux服务器，并需要通过量化后仿真模型验证量化精度，请准备待量化数据；上传到服务器。数据格式见“数据准备与环境搭建”。

### 界面介绍

#### 整体界面

量化的整体界面如图 量化整体界面所示。

图 1 量化整体界面

模型量化整体界面如图1所示，主要包含三个部分：

1. 量化参数配置界面。

2. 压缩历史显示界面，显示所有压缩的网络及其精度指标。

3. 样本精度分布直方图显示界面，显示验证集的精度分布。

执行量化步骤如下：

1. 在量化参数界面配置量化参数。

2. 单击“Quantize”按钮。

3. 压缩历史显示界面查看压缩的结果。如果使能了量化精度验证，在该表格中显示量化精度验证评估结果。

4. 如果使能了量化精度验证，在样本精度分布直方图显示界面中查看验证集精度分布直方图。

5. 压缩历史显示界面中选择待转换的量化模型，单击“Next”按钮进入模型转换界面。

#### 量化参数配置界面

##### 训练后量化

训练后量化量化参数配置窗口如图 量化参数配置界面所示。

图 1 训练后量化参数配置界面

参数解释如表1所示。

表 1 训练后量化参数配置界面参数

参数 | 说明
--- | ---
Quantized Data Type | 模型量化类型。当配置为int8时，转换后模型占用空间相对较小，推理速度相对较快，精度损失相对更大。当配置为int16时，转换后模型占用空间相对较大，推理速度相对较慢，精度损失相对小。
Layerwise Config | 打开逐层量化配置窗口。逐层量化类型配置窗口如图2 逐层量化类型配置界面所示。表格中各列的含义如下所示： layer_name：层的名称。 layer_type：层的算子类型。 bit_num：用户在此列配置数据量化到的类型。
Calibration Inputs | 用户在该表格中输入量化的校准数据。表格中各列的含义如下所示： Input Node：网络输入节点的名称。 Path：校准数据的目录。校准数据为npy格式。 Shape：网络输入张量的形状。 DataType：网络输入张量的类型。
validation | 使能验证开关。当开关打开时，验证数据集输入界面展开，如图3 验证集输入界面所示。
Validation Inputs | 用户在该表格中输入量化评估网络的验证数据集。表格中各列的含义如下所示： Input Node：网络输入节点的名称。 Path：验证数据的目录。验证数据为npy格式。
Validation Labels | 使能开关打开后，输入含分类真值标签的csv表格文件。
Advanced | 高级模式使能开关。当开关打开时，高级模式界面展开，如图4所示。
Ascend Config | 高级模式量化配置文件输入控件。在该输入控件中输入昇腾量化配置cfg文件。昇腾量化配置文件编写格式参见文档《AMCT模型压缩工具用户指南》。单击可下载配置cfg文件模板。 在使能Ascend Config时，BitNum和Layerwise Config配置不生效。
Quantize | 开始量化按钮。

图 2 逐层量化类型配置界面

图 3 验证集输入界面

图 4 高级模式界面

##### 量化感知训练

量化感知训练参数配置窗口如图1所示。

图 1 量化感知训练参数配置界面

参数解释如表1所示。

表 1 量化感知训练参数配置界面参数

参数 | 说明
--- | ---
Network Struction | 网络结构输入路径。网络结构文件为一个python文件，里面含有网络结构的定义。在定义网络结构时，请满足如下约束： 网络结构类的名称固定为NNModel 当前只支持单输入和单输出网络，因此forward函数的输入输出类型为torch.Tensor 构造函数不包含除self外的其他入参，如果有其他入参请配置默认值 以下为LeNet5网络结构的参考实现：

    class NNModel(nn.Module):
        def __init__(self) -> None:
            """Initialize network layers and components."""
            super(NNModel, self).__init__()
        self.conv1 = nn.Conv2d(1, 8, kernel_size=(5, 5), padding=2)
        self.relu1 = nn.ReLU()
        self.maxpool1 = nn.MaxPool2d(kernel_size=(2, 2), stride=(2, 2), padding=(0, 0), dilation=1, ceil_mode=False)

        self.conv2 = nn.Conv2d(8, 16, kernel_size=(5, 5), padding=2)
        self.relu2 = nn.ReLU()
        self.maxpool2 = nn.MaxPool2d(kernel_size=(3, 3), stride=(3, 3), padding=(0, 0), dilation=1, ceil_mode=False)

        self.fc = torch.nn.Linear(256, 10, bias=True)

    def forward(self, img):
        """
        Forward pass of the network.

        Args:
            x (torch.Tensor): Input tensor with shape (batch_size, 1, 28, 28)

        Returns:
            torch.Tensor: Output logits with shape (batch_size, 10)
        """
        out = self.conv1(img)
        out = self.relu1(out)
        out = self.maxpool1(out)
        out = self.conv2(out)

        out = self.relu2(out)
        out = self.maxpool2(out)
        out = out.reshape(-1, 256)
        out = self.fc(out)
        return out</pre>
Input | Training Dataset：训练集输入数据目录。训练集输入数据为npy格式。 Validation Dataset: 验证集输入数据目录。目录中存放和模型输入匹配的npy文件数据。若模型有多个输入，同一个训练样本的多个输入npy文件文件名必须保持一致。
Label | Training Dataset: 训练集真值csv文件。 Validation Dataset: 验证集真值csv文件。
Epoch Num | 量化感知训练的Epoch数量。
Batch Size | 量化感知训练的Batch Size
Learning Rate | 量化感知训练时的学习率。
Layerwise Config | 打开逐层量化配置窗口。逐层量化类型配置窗口如图2所示。表格中各列的含义如下所示： layer_name：层的名称。 layer_type：层的算子类型。 bit_num：用户在此列配置数据量化到的类型。
Advanced Settings | 高级模式使能开关。当开关打开时，高级模式界面展开，如图3所示。
Ascend Config | 高级模式量化配置文件输入控件。在该输入控件中输入昇腾量化配置cfg文件。昇腾量化配置文件编写格式参见文档《AMCT模型压缩工具用户指南》。单击可下载配置cfg文件模板。 在使能Ascend Config时，Layerwise Config配置不生效。
Quantize | 开始量化按钮。

图 2 量化感知训练逐层量化类型配置界面

图 3 高级模式界面

#### 压缩历史显示界面

压缩历史显示窗口如图1所示。

图 1 压缩历史显示界面

该界面以表格的方式显示历史压缩的结果。表头解释如表1所示。

表 1 压缩历史

项目 | 说明
--- | ---
Trail ID | 网络压缩结果的序号。
Model Name | 网络的名称，以及修改时间。
Accuracy | 表示分类结果准确率，使用标签真值计算。计算公式如下，其中表示分类正确的样本数量，表示样本的总数量。
Cosine Similarity | 平均余弦相似度，计算公式如下，其中表示量化评估网络的输出，表示原始浮点网络的输出，表示验证集样本的数量。
MSE | 均方误差，计算公式如下，其中表示量化评估网络的输出，表示原始浮点网络的输出，表示验证集样本的数量。
Operation | 操作按钮： ：下载压缩结果。下载的压缩包中包含： {模型名称}_deploy_model.onnx：量化部署模型，即量化后的可在昇腾 AI 处理器部署的模型文件。 {模型名称}_fake_quant_model.onnx：量化仿真模型，即量化后的可在 ONNX执行框架ONNX Runtime进行精度仿真的模型文件。 {模型名称}_quant.json：融合信息文件。 precision_output.csv：验证集各个样本的精度信息。 ：删除当前记录。 ：跳转到模型转换页面，在模型转换页面对当前行对应的压缩网络进行模型转换。

#### 验证集精度分布直方图显示界面

验证集精度分布直方图显示界面如图 验证集精度分布直方图显示界面所示。该窗口显示验证集的余弦相似度的分布图，横轴为余弦相似度，纵轴为验证集样本的百分比。

图 1 验证集精度分布直方图显示界面

## 模型转换

### 整体界面

图 1 模型转换整体界面

用户在模型转换界面将模型转换成昇腾NPU执行的离线模型。模型转换整体界面如图1所示。主要包含三个部分：

1. 模型转换参数配置界面。

2. 转换历史显示界面，显示所有转换的网络及其相关信息。

3. 转换结果显示界面，显示转换后模型的大小。

模型转换步骤如下：

1. 在模型转换参数配置界面配置转换参数。

2. 单击“Convert”按钮。

3. 转换历史显示界面查看转换的结果。

4. 转换结果显示界面查看转换后模型的大小。

5. 转换历史显示界面选择待评估的模型，单击“Next”按钮进入部署界面。

### 模型转换参数配置界面

模型转换参数配置界面如图1所示。

图 1 模型转换参数配置界面

参数解释如表1所示。

表 1 模型转换参数配置界面参数

参数 | 说明
--- | ---
Input | 该标签显示为模型的输入节点名称。包含两个控件： 输入节点张量形状。 输入节点数据类型。转换后的网络接收该数据类型的数据。
Output Type | 输出节点数据类型。转换后的网络输出该数据类型的输出。
Advanced Options | 高级模式使能开关。当开关打开时，高级模式界面展开。
Additional Arguments | 扩展参数输入框。模型转换界面不支持配置，但是ATC工具支持的参数均可通过此选项进行扩展。在该输入框中用户根据实际情况输入ATC工具可用的参数。多个参数使用空格分隔。详细参数请参见《ATC离线模型编译工具用户指南》。
Convert | 开始转换按钮。

### 转换历史显示界面

转换历史显示界面如图1所示。

图 1 转换历史显示界面

该界面以表格的方式显示历史转换的结果。表头解释如表1所示

表 1 转换历史

项目 | 说明
--- | ---
Trail ID | 网络转换结果的序号。
Model Name | 网络的名称，以及修改时间。
Accuracy | 表示分类结果准确率，使用标签真值计算。计算公式如下，其中表示分类正确的样本数量，表示样本的总数量。
Cosine Similarity | 平均余弦相似度，计算公式如下，其中表示量化评估网络的输出，表示原始浮点网络的输出，表示验证集样本的数量。
MSE | 均方误差，计算公式如下，其中表示量化评估网络的输出，表示原始浮点网络的输出，表示验证集样本的数量。
Model Size(KB) | 转换后在昇腾AI处理器运行的离线模型文件大小。
Dbg Size(KB) | 图调试信息文件大小。
Operation | 操作按钮： ：下载模型转换结果。下载的压缩包中包含： convert.exeom：转换后在昇腾AI处理器运行的离线模型。 convert.dbg：图调试信息文件。 ：删除当前记录。 ：跳转到部署页面。

### 转换结果显示界面

转换结果显示界面如图1所示。该界面以柱状图的形式显示转换后模型以及图调试信息文件的大小。

图 1 转换结果显示界面

## 部署

部署界面如图1所示。

图 1 部署界面

该界面主要包含Model currently selected、Build and Burn、Download Results三个部分。Build and Burn中的主要控件如表1 Build and Burn主要控件说明所示。

表 1 Build and Burn主要控件说明

项目 | 说明
--- | ---
Burn Port | 镜像烧录串口号。
Baud Rate | 镜像烧录波特率。
Build SDK | 开始编译SDK。
Flash | 开始镜像烧录。
Next | 进入Benchmark界面。

表 2 Download Results主要控件说明

项目 | 说明
--- | ---
Download OM Model | 单击下载按钮下载模型量化、转换结果。

## 模型调优

### 约束说明

> 须知： 在进行模型调优前，请务必查看如下约束要求： 只支持单输出分类网络计算量化评估网络的准确率。

### 调优前提

- 准备精度验证数据，并保存于本地Windows环境。具体数据格式见“数据准备与环境搭建”。

- 准备并连接Hi3322单板。

### 界面介绍

#### 整体界面

图 1 模型调优整体界面

模型调优整体界面如图1所示，主要包含四个部分：

1. 串口配置界面。在该界面配置数据传输、烧录、命令串口和波特率。

2. 性能评估界面。

3. 精度评估界面。

4. 评估结果汇总按钮。

执行模型调优的步骤如下：

1. 配置数据传输、烧录、命令串口和波特率。

2. 可选。如需烧录镜像，单击“Flash”按钮，执行镜像烧录。

3. 可选。单击“Performance Validation”按钮，执行上板性能评估。查看性能评估结果。

4. 可选。配置精度验证数据集路径，单击“Accuracy Validation”按钮，执行上板精度评估。查看精度评估结果。

5. 单击“Summary of Results”按钮，在弹窗中查看历史评估结果。

#### 串口配置界面

用户在串口配置界面配置数据传输、命令发送串口和波特率。串口配置界面如图1所示。

图 1 串口配置界面

元素说明如表1所示。

表 1 串口配置界面元素说明

元素 | 说明
--- | ---
Data Port | 数据传输串口号。数据传输口用于将待评估的网络模型和验证数据传送到单板。
Data Port->Baudr Rate | 数据传输串口波特率。
Command Port | 命令发送串口号。命令发送串口用于向单板发送模型推理命令。
Command Port->Baud Rate | 命令发送串口波特率。

#### 性能评估界面

用户在性能评估界面触发上板性能评估，并查看性能评估结果。性能评估界面的如图1所示。

图 1 性能评估界面

性能评估界面元素说明如表1所示。

表 1 性能评估界面元素说明

元素 | 说明
--- | ---
Performance Evaluation | 开始上板精度评估按钮。
INFERENCE TIME | 上板推理时间。该时间只包括模型推理时间，不包括输入输出数据的拷贝。
MODEL SIZE | 模型文件大小。
DBG SIZE | 图调试信息文件大小。

#### 精度评估界面

用户在精度评估界面配置精度评估验证数据、触发上板精度验证以及查看精度验证结果。精度评估界面如图1所示。

图 1 精度评估界面

精度评估界面元素说明如表1所示。

表 1 精度评估界面元素说明

元素 | 说明
--- | ---
Input Node | Path：验证集输入数据目录。输入文件夹路径，文件夹中包含和模型输入数据匹配的npy文件。
Validation Labels | 包含两个元素： 下拉框： None：不输入分类真值标签文件。不进行准确率评估。 输出结点名称：从文件系统选择包含该节点分类真值标签的csv文件。并使用csv文件中包含的标签进行准确率计算。在选择该选项时，使能分类真值文件输入框。 分类真值文件输入框：输入包含分类真值的csv文件路径。
Accuracy Evaluation | 开始上板精度验证按钮。
ACCURACY | 表示分类结果准确率，使用标签真值计算。计算公式如下，其中表示分类正确的样本数量，表示样本的总数量。
Cosine Similarity | 平均余弦相似度，计算公式如下，其中表示量化评估网络的输出，表示原始浮点网络的输出，表示验证集样本的数量。
Evaluation Data | 各验证样本验证结果。表格中各项说明如表2所示。
Probability Density Histogram | 验证集的余弦相似度的分布图。横轴为余弦相似度，纵轴为验证集样本的百分比。

表 2 验证样本结果说明

元素 | 说明
--- | ---
Sample Name | 样本名称。
Output Name | 输出节点名称。
Predict | 模型上板推理的输出。
Golden | 原始浮点网络在Windows主机推理的输出。
Accuracy | 本样本的分类正确率。
Cosine Similarity | 余弦相似度，计算公式如下，其中表示模型上板推理的输出，表示原始浮点网络在Windows的输出。

#### 评估结果汇总界面

单击“Summary of Results”按钮之后弹出评估结果汇总界面，该界面汇总每次评估的结果。如图1所示。

图 1 评估结果汇总界面

评估结果汇总界面元素说明如表1所示。

表 1 评估结果界面元素说明

一级元素 | 二级元素 | 说明
--- | --- | ---
Trail ID |  | 评估结果序号。
Model Name |  | 网络的名称，以及修改时间。
Benchmark | Accuracy | 表示模型上板推理结果分类结果准确率，使用标签真值计算。计算公式如下，其中表示分类正确的样本数量，表示样本的总数量。
Cosine Similarity | 表示模型上板推理结果平均余弦相似度，计算公式如下，其中表示模型上板推理的输出，表示原始浮点网络在Windows的输出，表示验证集样本的数量。
Inference Time(MS) | 上板推理时间。
Model Size(KB) | 模型文件大小。
Dbg Size | 图调试信息文件大小。
Quantize | Cosine Similarity | 表示量化评估模型推理结果的平均余弦相似度，计算公式如下，其中表示模型上板推理的输出，表示原始浮点网络在Windows的输出，表示验证集样本的数量。
MSE | 表示量化评估模型推理结果的均方误差，计算公式如下，其中表示量化评估网络的输出，表示原始浮点网络的输出，表示验证集样本的数量。

## 应用开发

在HiSpark Studio AI中完成模型量化、转换之后，将模型导出并使用HiSpark.AI API完成应用开发。具体步骤如下：

1. 在Deploy页面下载转换好的exeom模型。

   图 1 下载exeom模型

2. 具体API的用法请参考文档《HiSpark.AI API开发指南》