HiSpark Studio for VS Code指导资料

- HiSpark Studio AI for VS Code使用指南
  - 前言
  - HiSpark Studio AI简介
  - 数据准备与环境搭建
  - Hi3863操作指南
  - Hi3322操作指南
- HiSpark Studio for VS Code使用指南
  - 前言
  - 工具简介
  - 开发环境搭建
  - 工程管理
  - 工程配置
  - 编译运行
  - 软件包烧录
  - 栈分析和镜像分析
  - 工程调试
  - 远程开发工具
  - 串口控制台工具
  - Kconfig配置
  - GUI工程创建与使用
  - 高阶分析功能使用
  - 常见错误

### 该页内容

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

# 前言

概述

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

读者对象

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

- 技术支持工程师

- AI开发工程师

符号约定

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

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

修改记录

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

# 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

## 安装方案介绍

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

1. 打开VS Code插件市场。

2. 搜索并安装HiSpark Studio AI。

   为保证功能正常运行，还需安装HiSpark Studio插件。

## 窗口介绍

### 整体窗口介绍

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

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

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

图 1

### 侧边栏

侧边栏为功能导航栏，展示了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

## 关键概念

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

### AMCT

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

### ATC

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

# 数据准备与环境搭建

## 数据准备

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

- 数据存储为bin或npy格式，每个文件对应一个与网络输入张量匹配的样本。当前不同流程需要不同的格式，详细请参照“Hi3863操作指南”和“Hi3322操作指南”。

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

- 分类任务真值存储为csv格式。包含两列sample和label，其中sample表示样本的名称，和bin或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

新建工程导入页面的具体逻辑如下，参数详细配置如表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”设置为相同路径即可。如果用户有将“.proj”等项目文件与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. 跳转标签（Select Model -> Quantize -> Convert -> Deploy -> Profiling），当存在历史操作记录时，完成界面的切换。

2. 模型选择页面，用于选择Linux服务器上的部署目标模型。

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

模型导入步骤如下：

1. 进入模型选择页面，点击“New Model”按钮连接Linux服务器，输入密码，选择对应的Mnist Onnx模型，测试模型请参考 Mnist-5.onnx。

2. 连接远程服务器，输入Docker的IP、端口号、用户名、密码。

3. 导入成功后，将跳转到量化页面。

#### 导入配置界面

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

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

图 1

#### 导入配置成功界面

## 模型压缩

### 约束说明

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

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

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

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

### 压缩前提

用户需要准备模型压缩的输入数据，并将数据放置到Docker环境所在的服务器上，可参考快速入门指南的样例运行章节准备。

### 界面介绍

#### 整体界面

图 1 模型压缩示意图

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

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

2. 量化参数配置界面。

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

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

量化步骤如下：

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

   > 说明： 量化输入数据需要输入文件夹路径，文件夹内量化数据保持为bin格式；验证输入数据需要输入文件夹路径，文件夹内量化数据保持为npy格式。

2. 单击“Quantize”按钮，输出量化余弦相似度、准确率以及MSE等结果。

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

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

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

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

参数解释如表1所示。

表 1 量化参数配置

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

图 2 验证数据输入页面

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

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

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

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

## 模型转换

### 约束说明

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

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

> 2. 用户需要确保连接的Docker容器中 MSLite 工具链是已经准备好的。

### 转换前提

用户已成功完成量化，且量化所用的校准数据位置在Docker容器上不改变。

### 界面介绍

#### 整体界面

图 1 模型转换整体界面

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

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

2. 转换参数配置界面。

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

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

转换步骤：

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

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

3. 在历史转换记录配置界面 与 ，转换结果RAM/FLASH对比界面查看转换结果。

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

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

图 1 转换参数配置页面

参数解释如表1所示。

表 1 转换参数配置

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

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

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

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

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

项目 | 说明
--- | ---
Trail ID | 网络转换结果的序号。
Model Name | 网络的名称，以及模型大小和修改时间。
Balanced Accuracy | 表示分类结果准确率，使用标签真值计算。
Avg Sim | 平均余弦相似度，使用量化评估网络的输出和原始浮点网络的输出计算。
MSE | 均方误差，使用量化评估网络的输出和原始浮点网络的输出计算。
RAM(KB) | 上板AI相关RAM内存估计。
FLASH(KB) | 上板AI相关FLASH内存估计。
Operation | 操作按钮： ：下载压缩结果。下载的压缩包中包含： {模型名称}.ms：量化后模型IR。 {模型名称}.cfg：量化配置。 quant_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. 模型转换产物下载页面。

转换步骤如下：

1. 下载模型转换产物，用户后续应用开发部署，

2. 单击“Accuracy & Latency Profiling”按钮，进行下一步性能 & 精度验证。

## 模型调优

### 约束说明

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

> 1. 用户需要在环境变量中配置cmake路径、ninja路径、cmake_env路径。

> 2. 用户需要在.vscode本地配置config.json中的“mindspore”字段，为mindspore包本地解压路径。

> 3. 用户需要保证SDK的完成性。

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

### 调优前提

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

### 界面介绍

#### 整体界面

图 1 WS63模型调优整体页面

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

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

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

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

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

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

模型调优步骤如下：

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

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

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

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

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

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

图 1 性能验证选项配置

参数解释如表1所示。

表 1 转换参数配置

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

> 说明： 性能验证的过程中，会出现“Connecting...Reset the device...”以及 “send reset cmd”字样，并且界面有所停顿，需要及时手动按复位键。

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

图 1 性能验证结果页面

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

表 1 性能验证结果

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

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

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

参数解释如表1所示。

表 1 转换参数配置

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

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

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

- 准确率信息

- 逐项结果展示

- 余弦相似度分布直方图

各参数如表1所示。

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

参数 | 所属部分 | 说明
--- | --- | ---
Balanced Accuracy | 准确率信息 | 上板精度验证准确率
Sample | 逐项结果展示 | 样本名称
Predict | 逐项结果展示 | 上板推理结果
Golden | 逐项结果展示 | 标杆推理结果
Label | 逐项结果展示 | 标签
Similarity | 逐项结果展示 | 余弦相似度
Accuracy Validation | 余弦相似度分布直方图 | 余弦相似度分布图

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

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

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

## 应用开发

在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服务器环境配置。

- 连接Linux服务器，若未完成连接，在单击“New model”按钮时会弹出Linux服务器连接窗口。

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

### 界面介绍

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

图 1 模型导入界面

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

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

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

## 模型压缩

### 约束说明

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

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

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

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

### 压缩前提

- 将待量化的模型上传到服务器。

- 准备校准数据，上传到服务器。数据格式见“数据准备与环境搭建”。

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

### 界面介绍

#### 整体界面

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

图 1 量化整体界面

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

1. 量化参数配置界面。

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

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

执行量化步骤如下：

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

2. 单击“Quantize”按钮。

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

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

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

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

##### 训练后量化

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

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

参数解释如表1所示。

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

参数 | 说明
--- | ---
BitNum | 模型量化类型。当配置为int8时，转换后模型占用空间相对较小，推理速度相对较快，精度损失相对更大。当配置为int16时，转换后模型占用空间相对较大，推理速度相对较慢，精度损失相对小。
Layerwise Config | 打开逐层量化配置窗口。逐层量化类型配置窗口如图2 逐层量化类型配置界面所示。表格中各列的含义如下所示： layer_name：层的名称。 layer_type：层的算子类型。 bit_num：用户在此列配置数据量化到的类型。
Calibration Inputs | 用户在该表格中输入量化的校准数据。表格中各列的含义如下所示： Input Node：网络输入节点的名称。 Path：校准数据的目录。校准数据为bin格式。 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 量化感知训练参数配置界面

参数解释如表2所示。

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

参数 | 说明
--- | ---
Retrain Code | 点击Edit按钮打开量化感知训练代码编辑界面。 量化感知训练代码模板说明见表2。
Config File | 下拉框选择量化感知训练的配置文件。 Default：使用默认的配置文件进行量化感知训练。 Custom：使用用户自定义的配置文件进行量化感知训练。 量化感知训练配置文件具体请参考文档《AMCT模型压缩工具用户指南》。
Retrain Config | 单击“Edit”按钮打开用户自定义量化感知训练配置文件编辑界面。 量化感知训练配置文件具体请参考文档《AMCT模型压缩工具用户指南》。
Retrain Inputs | 训练集输入数据目录。训练集输入数据为bin格式。
Retrain Outputs | 训练集真值csv文件。
Validation Inputs | 验证集输入数据目录。目录中存放和模型输入匹配的npy文件数据。若模型有多个输入，同一个训练样本的多个输入npy文件文件名必须保持一致。
Validation Outputs | 验证集真值csv文件。
Quantize | 开始量化按钮。

表 2 量化感知训练代码模板说明

变量/类 | 类型 | 说明
--- | --- | ---
EPOCH_NUM | int | 训练epoch数量。
BATCH_SIZE | int | 训练时一个batch的样本数量。
LEARNING_RATE | float | 学习率。
NNModel | 模型结构定义类 | torch.nn.Module子类。在定义模型结构时请遵守如下约束： 保持类的名称为NNModel。 构造函数无不带默认参数的入参。HiSpark Studio AI按照默认参数进行模型结构类的实例化。 forward函数输入参数和输出参数数量均为1，且类型为torch.Tensor。

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

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

图 1 压缩历史显示界面

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

表 1 压缩历史

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

### 转换结果显示界面

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

图 1 转换结果显示界面

## 部署

部署界面如图1所示。

图 1 部署界面

该界面主要控件如表1所示。

表 1 部署接口主要控件说明

项目 | 说明
--- | ---
Accuracy & Latency Profiling按钮 | 单击该按钮进入Profiling界面。若SDK目录不存在已经编译好的镜像，该按钮会触发SDK的自动编译。
Download OM Model | 单击下载按钮下载模型量化转换结果。下载的压缩包中包含： convert.exeom：转换后在昇腾AI处理器运行的离线模型。 convert.dbg：图调试信息文件。

## 模型调优

### 约束说明

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

### 调优前提

- 准备精度验证数据，并保存于本地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->Baudrate | 数据传输串口波特率。
Command & Flash | 命令发送和烧录串口号。命令发送串口用于向单板发送模型推理命令。
Command & Flash->Baudrate | 命令发送和烧录串口波特率。
Flash | 开始镜像烧录按钮。

#### 性能评估界面

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

图 1 性能评估界面

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

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

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

#### 精度评估界面

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

图 1 精度评估界面

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

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

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

表 2 验证样本结果说明

元素 | 说明
--- | ---
Sample Name | 样本名称。
Output Name | 输出节点名称。
Predict | 模型上板推理的输出。
Golden | 原始浮点网络在Windows主机推理的输出。
Label | 真值标签。
Cosine Similarity | 平均余弦相似度，计算公式如下，其中表示模型上板推理的输出，表示原始浮点网络在Windows的输出，表示验证集样本的数量。

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

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

图 1 评估结果汇总界面

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

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

元素 | 说明
--- | ---
Data | 模型精度评估时间。
Trail ID | 评估结果序号。
Model Name | 网络的名称，以及模型大小和修改时间。
Avg Sim | 平均余弦相似度，计算公式如下，其中表示模型上板推理的输出，表示原始浮点网络在Windows的输出，表示验证集样本的数量。
Dbg Size | 图调试信息文件大小。
Model Size | 模型文件大小。
Inference Time | 上板推理时间。
Delete | 删除按钮，删除选中的评估结果记录。
CSV Export | 导出当前评估结果表格。

## 应用开发

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

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

   图 1 下载exeom模型

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