tb-graph-ascend

一、 介绍

该 TensorBoard 插件用于对模型结构进行分级可视化展示。可将模型的层级关系、精度数据进行可视化，并支持将调试模型和标杆模型进行分视图展示和关联比对，方便用户快速定位精度问题。

二、快速安装

1. 相关依赖

python >= 3.8 ，tensorboard >= 2.11.2

2. 安装方式

2.1 版本配套关系

tb_graph_ascend 版本	msprobe 版本	说明
大于等于 8.2.0	大于等于 8.2.1	msprobe 工具的分级可视化构图比对功能自 8.2.1 版本起，输出件切换为 db 格式，需要对应版本的 tb_graph_ascend 进行解析
小于 8.2.0	小于 8.2.1	无

2.2 环境和依赖

• msprobe工具安装请参见《安装指导》。
• 硬件环境请参见《昇腾产品形态说明》。
• 软件环境请参见《CANN 软件安装指南》安装昇腾设备开发或运行环境，即toolkit软件包。

以上环境依赖请根据实际环境选择适配的版本。

2.3 pip 安装（推荐）

• 现本插件已经上传到 pypi 社区，用户可在 python 环境下直接通过以下 pip 指令进行安装：

  pip install tb-graph-ascend
  

• 也可在 pypi 社区上下载离线 whl 包，传输到无法访问公网的环境上离线安装使用。访问下载链接选择 whl 包进行下载，之后便可使用指令安装（此处{version}为 whl 包实际版本）

  pip install tb-graph_ascend_{version}-py3-none-any.whl
  

• 请注意: 如果在 Linux/Unix 环境上安装使用，请在 whl 包安装之前对本环境的 umask 码进行确认(建议至少配置为 0027)，确保 pip 安装后的文件对其他用户及同组用户不可写，以规避可能出现的安全风险。

2.4 从源代码安装

1. 从仓库下载源码并切换到 master 分支:

   git clone https://gitcode.com/Ascend/mstt.git -b master
   

2. 进入目录 plugins/tensorboard-plugins/tb_graph_ascend 下

3. 编译前端代码，根据操作系统选取不同指令

   cd fe
   // 安装前端依赖
   npm install --force
   // Windows系统
   npm run buildWin
   // 其他可使用cp指令的系统，如Linux或Mac
   npm run buildLinux
   

   注意: 此步骤需要安装 Node.js 环境

4. 回到上级目录直接安装:

   cd ../
   python setup.py develop
   

• 或： 构建 whl 包安装 用户应确保在安全的环境下进行 whl 包的构建

  python secure_build.py
  

  在 plugins/tensorboard-plugins/tb_graph_ascend/dist 目录下取出 whl 包，使用以下指令安装（此处{version}为 whl 包实际版本）

  pip install tb-graph_ascend_{version}-py3-none-any.whl
  

三. 解析数据说明

将通过msprobe工具构图功能采集得到的文件后缀为.vis.db 的模型结构文件放置于某个文件夹中，路径名称下文称之为 output_path

图构建：

├── output_path
|    ├── build_{timestamp}.vis.db

图比对：

├── output_path
|    ├── compare_{timestamp}.vis.db

4.启动 TensorBoard

1. 启动 TensorBoard

   tensorboard --logdir output_path
   

   注意：确保默认端口 6006 可连通。

   如果需要切换端口号需要在尾部加上指定的端口号，如--port=6007

   tensorboard --logdir output_path --port=6007
   

2. 在浏览器上打开 TensorBoard

   在浏览器中打开 URL： http://localhost:6006。

   注意：如果--logdir 指定目录下的文件太大或太多，请等候，刷新浏览器查看加载结果。

3. 建议在本地启动 tensorboard，如果网络浏览器与启动 TensorBoard 的机器不在同一台机器上，需要远程启动，可参照远程启动方式，但需用户自行评估安全风险。

五.浏览器查看

1 浏览器打开图

推荐使用谷歌浏览器，在浏览器中输入机器地址+端口号回车，出现 TensorBoard 页面，其中/#graph_ascend 会自动拼接。

如果您切换了 TensorBoard 的其他功能，此时想回到模型分级可视化页面，可以点击左上方的GRAPH_ASCEND

2 查看图

MicroStep 是指在一次完整的权重更新前执行的多次前向和反向传播过程，一次完整的训练迭代（step）可以进一步细分为多个更小的步骤（micro step）。其中分级可视化工具通过识别模型首层结构中一次完整的前反向作为一次 micro step。

3 名称搜索

4 精度筛选

5 未匹配节点筛选

不符合匹配规则的节点为无匹配节点，颜色标灰。适用于排查两个模型结构差异的场景。

6 手动选择节点匹配

可通过浏览器界面，通过鼠标选择两个待匹配的灰色节点进行匹配。当前暂不支持真实数据模式。

六. 图比对说明

1 颜色

颜色越深，精度比对差异越大，越可疑，具体信息可见浏览器页面左下角颜色图例。

1.1 真实数据模式

节点中所有输入的最小双千指标和所有输出的最小双千分之一指标的差值，反映了双千指标的下降情况，该数值越大，表明两组模型的精度差异越大，在图中标注的对应颜色会更深。

One Thousandth Err Ratio（双千分之一）精度指标：Tensor中的元素逐个与对应的标杆数据对比，相对误差小于千分之一的比例占总元素个数的比例，比例越接近1越好

如果调试侧（NPU）节点的 output 指标中的最大值（MAX）或最小值（MIN）中存在 nan/inf/-inf，直接标记为最深颜色。

1.2 统计信息模式

节点中输出的统计量相对误差，该数值越大，表明两组模型的精度差异越大，在图中标注的对应颜色会更深。

相对误差：abs（(npu统计值 - bench统计值) / bench统计值)

如果调试侧（NPU）节点的 output 指标中的最大值（MAX）或最小值（MIN）中存在 nan/inf/-inf，直接标记为最深颜色。

1.3 md5 模式

节点中任意输入输出的 md5 值不同。

2 指标说明

精度比对从三个层面评估 API 的精度，依次是：真实数据模式、统计数据模式和 MD5 模式。比对结果分别有不同的指标。

公共指标：

• name: 参数名称，例如 input.0
• type: 类型，例如 torch.Tensor
• dtype: 数据类型，例如 torch.float32
• shape: 张量形状，例如[32, 1, 32]
• Max: 最大值
• Min: 最小值
• Mean: 平均值
• Norm: L2-范数

真实数据模式指标：

• Cosine: tensor 余弦相似度
• EucDist: tensor 欧式距离
• MaxAbsErr: tensor 最大绝对误差
• MaxRelativeErr: tensor 最大相对误差
• One Thousandth Err Ratio: tensor 相对误差小于千分之一的比例（双千分之一）
• Five Thousandth Err Ratio: tensor 相对误差小于千分之五的比例（双千分之五）

统计数据模式指标

• (Max, Min, Mean, Norm) diff: 统计量绝对误差
• (Max, Min, Mean, Norm) RelativeErr: 统计量相对误差

MD5 模式指标

• md5: CRC-32 值

七、附录

1 安全加固建议

1.1 免责声明

本工具为基于 TensorBoard 底座开发的插件，使用本插件需要基于 TensorBoard 运行，请自行关注 TensorBoard 相关安全配置和安全风险。

打开本工具时，本工具会对 logdir 目录下的 vis 文件以及其父目录进行安全检查，如果存在安全风险，本工具会展示如下提示信息，询问用户是否继续执行，用户选择继续执行后，可以操作未通过安全检查的文件和目录，用户需要自行承担操作风险。如果用户选择不继续执行，则用户只能操作通过安全检查的文件。

1.2 TensorBoard 版本说明

满足相关依赖中要求的 TensorBoard 版本皆可正常使用本插件功能，但为 TensorBoard 本身安全风险考虑，建议使用最新版本 TensorBoard 。

1.3 远程查看数据

如果网络浏览器与启动 TensorBoard 的机器不在同一台机器上， TensorBoard 提供了远程查看数据的指令启动方式，但此种方式会将服务器对应端口在局域网内公开（全零监听），请用户自行关注安全风险。

• 在启动指令尾部加上--bind_all或--host={服务器IP}参数启用远程查看方式

(1) 可直连的服务器

将生成 vis 文件的路径out_path传入--logdir

tensorboard --logdir out_path --bind_all --port [可选，端口号]

默认为 6006 端口，以下示例以 --port 6008 为例

启动后会打印日志:

DESKTOP-F7A7KD0.localdomain 是机器地址，6008 是端口号。

DESKTOP-F7A7KD0.localdomain 需要替换为真实的服务器地址，例如真实的服务器地址为 10.123.456.78，则需要在浏览器窗口输入http://10.123.456.78:6008

(2) 不可直连的服务器

如果链接打不开，可以尝试以下方法，选择其一即可：

1.本地电脑网络手动设置代理，例如 Windows10 系统，在【手动设置代理】中添加服务器地址（例如 10.123.456.78）

然后，在服务器中输入：

tensorboard --logdir out_path --bind_all --port 6008[可选，端口号]

最后，在浏览器窗口输入http://10.123.456.78:6008

注意，如果当前服务器开启了防火墙，则此方法无效，需要关闭防火墙，或者尝试后续方法

2.或者使用 vscode 连接服务器，在 vscode 终端输入：

tensorboard --logdir out_path

按住 CTRL 点击链接即可

3.或者将构图结果件 vis 文件从服务器传输至本地电脑，在本地电脑中安装 tb_graph_ascend 插件查看构图结果

电脑终端输入：

tensorboard --logdir out_path

按住 CTRL 点击链接即可

2 通信矩阵

序号	代码仓	功能	源设备	源 IP	源端口	目的设备	目的 IP	目的端口 （侦听）	协议	端口说明	端口配置	侦听端口是否可更改	所属平面	版本	特殊场景	备注
1	tensorboard-plugins	TensorBoard 底座前后端通信	访问 TensorBoard 浏览器所在机器	访问 TensorBoard 浏览器所在机器 ip		TensorBoard 服务所在机器	TensorBoard 服务所在服务器的 ip	6006	HTTP	TensorBoard 服务通信	--port	可修改	业务面	所有版本	无
2	tensorboard-plugins	TensorBoard 底座可能存在向公网地址(如CDN)等请求静态资源文件css、woff2等情况	访问TensorBoard浏览器所在设备	访问TensorBoard浏览器所在设备IP	随机端口	静态资源文件站点	目标静态资源文件站点IP	443	HTTPS	通过HTTPS协议请求静态资源时默认的443端口	不涉及监听	业务面	所有版本	无

mindstudio仅交付模型分级可视化插件，TensorBoard及插件依赖一些三方开源组件(如polymer及其相关间接依赖)，使用时可能存在发起向公网地址如CDN请求样式文件或字体文件的情况，说明如下：

1、模型分级可视化插件已通过在CSP响应头中添加策略拦截，但仍然会在浏览器调试窗口中记录对应请求的拦截记录，不影响功能正常使用。

2、TensorBoard底座CSP响应头策略由TensorBoard底座自身配置，不受插件加固影响，因此仍然可能存在请求公网地址的情况，出于安全考虑，建议不要在跨机或不安全的网络环境中使用

3 公网地址说明

公网地址说明