74429164创建于 6 天前历史提交

MindSpore场景分级可视化构图比对

简介

MindSpore场景分级可视化构图比对：将msProbe工具dump的精度数据进行解析，还原模型图结构，实现模型各个层级的精度数据比对，方便用户理解模型结构、分析精度问题。

基本概念

msProbe：全称MindStudio Probe，是精度调试工具包，可以定位模型训练或推理中的精度问题。
dump：精度数据采集。

使用流程

进行工具安装以及数据的采集，详见使用前准备。
使用命令行工具生成图结构文件，详见分级可视化操作指导。
启动tensorboard服务，详见启动tensorboard。
使用浏览器查看图结构，分析模型结构和精度数据，详见浏览器查看。

注意事项

多卡场景仅识别step{Step ID}或rank{Rank ID}目录的数据进行构图。

工具特性

支持重建模型的层级结构。
支持两个模型的结构差异比对。
支持两个模型的精度数据比对。
支持模型数据的溢出检测。
支持多卡场景的批量构图，能够关联各卡的通信节点，分析各卡之间的数据传递。
支持节点名称搜索，按精度比对结果筛选节点，按溢出检测结果筛选节点，支持自动跳转展开节点所在的层级。
支持跨套件、跨框架的模型比对。
支持不同切分策略下两个模型的精度数据比对：不同切分策略下的图合并。

vis_show

使用前准备

环境准备

安装msProbe工具，具体请参见《msProbe工具安装指南》。

安装方式选择“编译安装”时，编译命令须配置参数--include-mod tb_graph_ascend来构建分级可视化插件。

数据准备

采集模型结构数据：仅支持动态图场景，需要选择level为L0（cell信息）或者mix（cell信息和API信息），才能采集到模型结构数据，即采集结果文件construct.json内容不为空。详细采集方式请参见《MindSpore场景精度数据采集》。

约束

要求mindspore>=2.4.0。

分级可视化操作指导

单图构建

功能说明

展示模型结构、精度数据、堆栈信息，并且包含了溢出检测功能。适用于分析模型结构和分析数据溢出的场景。

注意事项

依赖采集的模型结构数据，需确保dump配置的level为L0（cell信息）或者mix（cell信息和API信息），采集结果文件construct.json内容不为空。

命令格式

msprobe graph_visualize -tp <target_path> -o <output_path> [-oc] [-tensor_log] [-progress_log]

参数说明

参数名	可选/必选	说明
-tp或--target_path	必选	指定待调试侧比对路径，str类型。工具根据路径格式自动进行单rank构建、多rank批量构建或多step批量构建。
-o或--output_path	必选	配置构图结果文件存盘目录，str类型。文件名称基于时间戳自动生成，格式为：`build_{timestamp}.vis.db`。
-oc或--overflow_check	可选	是否开启溢出检测模式，开启后会在输出db文件中（`build_{timestamp}.vis.db`）对每个溢出节点进行标记溢出等级。配置该参数表示开启，默认未配置表示关闭。
-tensor_log或--is_print_compare_log	可选	配置是否开启单个模块或API的日志打印，仅支持msProbe工具dump的tensor数据。配置该参数表示开启，默认未配置表示关闭。
-progress_log或--is_print_progress_log	可选	配置是否开启任务详细进度的日志打印。配置该参数表示开启，默认未配置表示关闭。

示例1：执行单rank图构建

msprobe graph_visualize -tp ./target_path -o ./output_path

target_path格式需要满足分级可视化构图所需dump文件落盘格式的单rank格式。

示例2：执行多rank批量图构建

msprobe graph_visualize -tp ./target_path -o ./output_path

target_path格式需要满足分级可视化构图所需dump文件落盘格式的多rank格式。

示例3：执行多step批量图构建

msprobe graph_visualize -tp ./target_path -o ./output_path

target_path格式需要满足分级可视化构图所需dump文件落盘格式的多step格式。

示例4：执行单图的溢出检测

msprobe graph_visualize -tp ./target_path -o ./output_path -oc

在输出结果中会对每个图节点进行溢出检测指标的标记，溢出检测指标如下：

medium：输入异常，输出正常场景；
high：输入异常，输出异常；输出norm值相较于输入存在异常增大情况；
critical：输入正常，输出异常场景。

输出说明

在配置的输出路径中，生成一个.vis.db后缀的文件，文件名称基于时间戳自动生成，格式为：build_{timestamp}.vis.db。

双图比对

功能说明

展示模型结构、结构差异、精度数据和精度比对指标、精度是否疑似有问题（精度比对指标差异越大颜色越深），且支持跨套件比对、溢出检测和模糊匹配功能。

当前比对支持三种类型的dump数据，分级可视化工具比对时会自动判断：

统计信息（statistics）：仅dump了API和cell的输入输出数据统计信息，占用磁盘空间小。
真实数据（tensor）：不仅dump了API和cell的输入输出数据统计信息，还将tensor进行存盘，占用磁盘空间大，但比对更加准确。
md5：dump了API和cell的输入输出数据统计信息和CRC-32信息。

dump类型如何配置见数据采集配置文件介绍。

注意事项

依赖采集的模型结构数据，需确保dump配置的level为L0（cell信息）或者mix（cell信息和API信息），采集结果文件construct.json内容不为空。

命令格式

msprobe graph_visualize -tp <target_path> -gp <golden_path> -o <output_path> [-lm] [-oc] [-fm] [-tensor_log] [-progress_log]

可选字段使用[]表示，变量使用<>表示。

参数说明

参数名	可选/必选	说明
-tp或--target_path	必选	指定待调试侧比对路径，str类型。工具根据路径格式自动进行单rank比对、多rank批量比对或多step批量比对，str 类型。
-gp或--golden_path	可选，但在双图比对场景必选	指定标杆侧比对路径，str类型。如果不配置此项则进行单图构建。
-o或--output_path	必选	配置构图结果文件存盘目录，str类型。文件名称基于时间戳自动生成，格式为：`compare_{timestamp}.vis.db`。
-lm或--layer_mapping	可选	跨框架比对，MindSpore和PyTorch的比对场景。配置该参数时表示开启跨框架Layer层的比对功能，指定模型代码中的Layer层后，可以识别对应dump数据中的模块或API。需要指定自定义映射文件.yaml。自定义映射文件的格式请参见自定义映射文件（Layer），如何配置自定义映射文件请参考模型分级可视化如何配置layer mapping映射文件。配置该参数后，将仅按节点名称进行比对，忽略节点的type和shape。模块节点命名格式：{Cell}.{cell_name}.{class_name}.{forward/backward}.{调用次数}*。 򴎲若cell_name不同，则-lm参数需要指定自定义映射文件，例如`-lm mapping.yaml`。 򴎲若cell_name相同，class_name不同，则直接配置-lm参数即可，例如`-lm`。 򴎲若cell_name和class_name均相同，则无需配置-lm参数。
-oc或--overflow_check	可选	是否开启溢出检测模式，开启后会在输出db文件中（`compare_{timestamp}.vis.db`）对每个溢出节点进行标记溢出等级。配置该参数表示开启，默认未配置表示关闭。
-fm或--fuzzy_match	可选	是否开启模糊匹配。配置该参数表示开启，默认未配置表示关闭。模糊匹配与默认匹配的区别详见匹配说明。
-tensor_log或--is_print_compare_log	可选	配置是否开启单个模块或API的日志打印，仅支持msProbe工具dump的tensor数据。配置该参数表示开启，默认未配置表示关闭。
-progress_log或--is_print_progress_log	可选	配置是否开启任务详细进度的日志打印。配置该参数表示开启，默认未配置表示关闭。

示例1：执行单rank图比对

msprobe graph_visualize -tp ./target_path -gp ./golden_path -o ./output_path

target_path和golden_path格式需要满足分级可视化构图所需dump文件落盘格式的单rank格式。

示例2：执行多rank批量图比对

msprobe graph_visualize -tp ./target_path -gp ./golden_path -o ./output_path

target_path和golden_path格式需要满足分级可视化构图所需dump文件落盘格式的多rank格式。

示例3：执行多step批量图比对

msprobe graph_visualize -tp ./target_path -gp ./golden_path -o ./output_path

target_path和golden_path格式需要满足分级可视化构图所需dump文件落盘格式的多step格式。

示例4：执行跨套件比对

调试侧和标杆侧节点名称相同，则仅指定-lm即可。

msprobe graph_visualize -tp ./target_path -gp ./golden_path -o ./output_path -lm

调试侧和标杆侧有节点名称不相同，则需要配置自定义映射文件，-lm参数传入自定义映射文件路径，映射文件如何配置详见参数说明。

msprobe graph_visualize -tp ./target_path -gp ./golden_path -o ./output_path -lm ./mapping.yaml

示例5：执行溢出检测

msprobe graph_visualize -tp ./target_path -gp ./golden_path -o ./output_path -oc

在输出结果中会对每个图节点进行溢出检测指标的标记，溢出检测指标如下：

medium：输入异常，输出正常场景。
high：输入异常，输出异常；输出norm值相较于输入存在异常增大情况。
critical：输入正常，输出异常场景。

示例6：执行模糊匹配

msprobe graph_visualize -tp ./target_path -gp ./golden_path -o ./output_path -fm

模糊匹配与默认匹配的区别详见匹配说明。

输出说明

在配置的输出路径中，生成一个.vis.db后缀的文件，文件名称基于时间戳自动生成，格式为：compare_{timestamp}.vis.db。

仅模型结构比对

功能说明

主要关注模型结构而非训练过程数据。例如，在模型迁移过程中，确保迁移前后模型结构的一致性，或在排查精度差异时，判断是否由模型结构差异所引起。

注意事项

使用msProbe工具对模型数据进行采集时，选择仅采集模型结构（task配置为structure），此配置将避免采集模型训练过程的数据，从而显著减少采集所需的时间。

dump配置请参考dump配置示例。

命令格式

请参考双图比对的命令格式

参数说明

请参考双图比对的参数说明

使用示例

请参考双图比对使用示例中的示例1、示例2和示例3

输出说明

在配置的输出路径中，生成一个.vis.db后缀的文件，文件名称基于时间戳自动生成，格式为：compare_{timestamp}.vis.db。

不同切分策略下的图合并

功能说明

不同模型并行切分策略下，两个模型产生了精度差异，需要进行整网数据比对，但被切分的数据或模型结构分布于多rank中无法进行比对，需要将分布在各个rank的数据或模型结构合并后再进行比对。

注意事项

当前支持的模型并行切分策略：Tensor Parallelism（TP）、Pipeline Parallelism（PP）、Virtual Pipeline Parallelism（VPP），暂不支持Context Parallelism（CP）和Expert Parallelism（EP）。
当前支持基于Megatron、MindSpeed-LLM套件的模型进行图合并，其他套件的模型图合并效果有待验证；
当前仅支持msProbe工具dump的statistics数据, level需指定L0或者mix；
图合并比对时要确保Data Parallelism（DP）切分一致，例如rank=8 tp=1 pp=8的配置，dp=1，图合并将得到一张图，rank=8 tp=1 pp=4的配置，dp=2，图合并将得到两张图，暂不支持数量不一致的图进行比对。

命令格式

msprobe graph_visualize -tp <target_path> [-gp <golden_path>] -o <output_path> [options]

参数说明

参数名	可选/必选	说明
-tp或--target_path	必选	指定待调试侧比对路径，str类型。工具根据路径格式自动进行单rank比对、多rank批量比对或多step批量比对。
-gp或--golden_path	可选	指定标杆侧比对路径，str类型。如果不配置此项则进行单图构建。
-o或--output_path	必选	配置构图结果文件存盘目录，str类型。文件名称基于时间戳自动生成，格式为：`compare_{timestamp}.vis.db`。
-lm或--layer_mapping	可选	跨框架比对，MindSpore和PyTorch的比对场景。配置该参数时表示开启跨框架Layer层的比对功能，指定模型代码中的Layer层后，可以识别对应dump数据中的模块或API。需要指定自定义映射文件.yaml。自定义映射文件的格式请参见自定义映射文件（Layer），如何配置自定义映射文件请参考模型分级可视化如何配置layer mapping映射文件。配置该参数后，将仅按节点名称进行比对，忽略节点的type和shape。模块节点命名格式：{Cell}.{cell_name}.{class_name}.{forward/backward}.{调用次数}*。 򴎲若cell_name不同，则-lm参数需要指定自定义映射文件，例如`-lm mapping.yaml`。 򴎲若cell_name相同，class_name不同，则直接配置-lm参数即可，例如`-lm`。 򴎲若cell_name和class_name均相同，则无需配置-lm参数。
-oc或--overflow_check	可选	是否开启溢出检测模式，开启后会在输出db文件中（`compare_{timestamp}.vis.db`）对每个溢出节点进行标记溢出等级。配置该参数表示开启，默认未配置表示关闭。
-fm或--fuzzy_match	可选	是否开启模糊匹配。配置该参数表示开启，默认未配置表示关闭。模糊匹配与默认匹配的区别详见匹配说明。
-tensor_log或--is_print_compare_log	可选	配置是否开启单个模块或API的日志打印，仅支持msProbe工具dump的tensor数据。配置该参数表示开启，默认未配置表示关闭。
-progress_log或--is_print_progress_log	可选	配置是否开启任务详细进度的日志打印。配置该参数表示开启，默认未配置表示关闭。
--rank_size	可选，仅图合并场景必选	模型实际训练所用加速卡的数量，int类型。`rank_size=tpppcp*dp`，由于暂不支持CP合并，图合并功能中默认cp=1。
--tp	可选，仅图合并场景必选	张量并行大小，int类型。实际训练脚本中需指定`--tensor-model-parallel-size T`，其中`T`表示张量模型并行大小，即图合并所需的参数tp，`tp=T`。
--pp	可选，仅图合并场景必选	流水线并行的阶段数，int类型。实际训练脚本中需指定`--pipeline-model-parallel-size P`，其中`P`表示流水线并行的阶段数，即图合并所需的参数pp，`pp=P`。
--vpp	可选	虚拟流水线并行阶段数，int类型。虚拟流水线并行依赖流水线并行，实际训练脚本中需指定`--num-layers-per-virtual-pipeline-stage V`，其中`V`表示每个虚拟流水线阶段的层数；指定`--num-layers L`，其中`L`表示模型总层数，图合并所需的参数vpp=`L/V/P`。vpp参数可以不配置，默认vpp=1代表未开启虚拟流水线并行。
--order	可选	模型并行维度的排序顺序，str类型。Megatron默认为`tp-cp-ep-dp-pp`。如果使用msProbe工具dump数据指定level为L0并且实际训练脚本中的order非默认值（例如实际训练脚本中指定`--use-tp-pp-dp-mapping`），请传入修改后的order。dump数据指定level为mix则无需修改。
--file_type	可选	输出文件格式，str类型。可选`db`和`json`，默认值为`db`。若选择`json`，则仅支持“不同切分策略下的图合并构建”，请参考示例5和示例6。

使用示例

示例1：不同tp切分下的图合并比对

当前示例比对场景为：target_path侧8卡，tp=8，golden_path侧4卡，tp=4。

msprobe graph_visualize -tp ./target_path -gp ./golden_path -o ./output_path --rank_size 8 4 --tp 8 4 --pp 1 1

示例2：不同pp切分下的图合并比对

当前示例比对场景为：target_path侧8卡，pp=8，golden_path侧1卡，pp=1。

msprobe graph_visualize -tp ./target_path -gp ./golden_path -o ./output_path --rank_size 8 1 --tp 1 1 --pp 8 1

示例3：不同vpp切分下的图合并比对

当前示例比对场景为：target_path侧8卡，pp=8，golden_path侧8卡，pp=8，vpp=2。

msprobe graph_visualize -tp ./target_path -gp ./golden_path -o ./output_path --rank_size 8 8 --tp 1 1 --pp 8 8 --vpp 1 2

示例4：不同pp和tp切分下的图合并比对

当前示例比对场景为：target_path侧8卡，pp=8，golden_path侧8卡，tp=8

msprobe graph_visualize -tp ./target_path -gp ./golden_path -o ./output_path --rank_size 8 8 --tp 1 8 --pp 8 1

示例5：不同tp切分下的图合并构建

当前示例比对场景为：target_path侧8卡，tp=8，不指定golden_path

msprobe graph_visualize -tp ./target_path -o ./output_path --rank_size 8 --tp 8 --pp 1

示例6：不同tp切分下的图合并构建，输出合并后的json文件

当前示例比对场景为：target_path侧8卡，tp=8

指定--file_type json后，在output_path会得到与target_path格式相同的json文件，即dump.json、stack.json和construct.json，并且文件中的数据已经过合并，可用于精度比对或者分级可视化比对。

msprobe graph_visualize -tp ./target_path -o ./output_path --rank_size 8 --tp 8 --pp 1 --file_type json

以上所有示例中，target_path和golden_path格式必须满足分级可视化构图所需dump文件落盘格式的多rank格式或多step格式

启动tensorboard

可直连的服务器

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

tensorboard --logdir out_path --bind_all

启动后会打印日志：

tensorboard_1

ubuntu是机器地址，6008是端口号。

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

不可直连的服务器

如果链接打不开（服务器无法直连需要挂vpn才能连接等场景），可以尝试以下方法，选择其一即可：

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

然后，在服务器中输入：
```
tensorboard --logdir out_path --bind_all
```
最后，在浏览器窗口输入http://10.123.456.78:6008

如果当前服务器开启了防火墙，则此方法无效，需要关闭防火墙，或者尝试后续方法
或者使用vscode连接服务器，在vscode终端输入：
```
tensorboard --logdir out_path
```
按住CTRL点击链接即可。
或者将构图结果文件从服务器传输至本地电脑，在本地电脑中安装tb_graph_ascend插件查看构图结果。

电脑终端输入：
```
tensorboard --logdir out_path
```
按住CTRL点击链接即可。

浏览器查看

浏览器打开图

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

vis_browser_1

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

vis_browser_2

查看图

详见PyTorch场景的分级可视化构图比对-查看图。

图比对说明

颜色

详见PyTorch场景的分级可视化构图比对-颜色说明。

指标说明

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

公共指标

name：参数名称，例如input.0
type：类型，例如mindspore.Tensor
dtype：数据类型，例如BFloat32
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值

附录

自定义映射文件（Layer）

文件名格式：*.yaml，*为文件名，可自定义。

文件内容示例：

ParallelAttention:                 # Layer层名称
  qkv_proj: query_key_value        # 冒号左侧为MindSpore框架模型代码中嵌套的Layer层名称，冒号右侧为PyTorch框架模型代码中嵌套的Layer层名称
  out_proj: dense

ParallelTransformerLayer:
  attention: self_attention

Embedding:
  dropout: embedding_dropout

ParallelMLP:
  mapping: dense_h_to_4h
  projection: dense_4h_to_h

PipelineCell:
  model: module

Cell:
  network_with_loss: module

Layer层名称需要从模型代码中获取。

yaml文件中只需配置MindSpore与PyTorch模型代码中功能一致但名称不同的Layer层，名称相同的Layer层会被自动识别并映射。

模型代码示例：

ms_dump

分级可视化构图所需dump文件落盘格式

单rank格式

dump_path格式：必须包含dump.json、stack.json和construct.json，且construct.json不能为空。如果construct.json为空，请检查dump的level参数是否没有选择L0或者mix。

├── dump_path
│   ├── dump_tensor_data（配置dump的task参数选择tensor时存在）
|   |    ├── MintFunctional.relu.0.backward.input.0.npy
|   |    ├── Mint.abs.0.forward.input.0.npy
|   |    ...
|   |    └── Cell.relu.ReLU.forward.0.input.0.npy
|   ├── dump.json         # 数据信息
|   ├── stack.json        # 调用栈信息
|   └── construct.json    # 分层分级结构，level为L1时，construct.json内容为空

多rank格式

dump_path格式：必须只包含rank+数字格式的文件夹，且每个rank文件夹中必须包含dump.json、stack.json和construct.json，且construct.json不能为空。如果construct.json为空，请检查dump的level参数是否没有选择L0或者mix。

├── dump_path
|   ├── rank0
|   │   ├── dump_tensor_data（仅配置dump的task参数选择tensor时存在）
|   |   |    ├── MintFunctional.relu.0.backward.input.0.npy
|   |   |    ├── Mint.abs.0.forward.input.0.npy
|   |   |    ...
|   |   |    └── Cell.relu.ReLU.forward.0.input.0.npy
|   |   ├── dump.json         # 数据信息
|   |   ├── stack.json        # 算子调用栈信息
|   |   └── construct.json    # 分层分级结构，level为L1时，construct.json内容为空
|   ├── rank1
|   |   ├── dump_tensor_data
|   |   |   └── ...
|   |   ├── dump.json
|   |   ├── stack.json
|   |   └── construct.json
|   ├── ...
|   |
|   └── rankn

多step格式

dump_path格式：必须只包含step{数字}格式的文件夹，且每个step文件夹中必须只包含rank{数字}格式的文件夹，每个rank文件夹中必须包含dump.json、stack.json和construct.json，且construct.json不能为空。如果construct.json为空，请检查dump的level参数是否没有选择L0或者mix。

├── dump_path
│   ├── step0
│   |   ├── rank0
│   |   │   ├── dump_tensor_data（仅配置dump的task参数选择tensor时存在）
|   |   |   |    ├── MintFunctional.relu.0.backward.input.0.npy
|   |   |   |    ├── Mint.abs.0.forward.input.0.npy  
|   |   |   |    ...
|   |   |   |    └── Cell.relu.ReLU.forward.0.input.0.npy
│   |   |   ├── dump.json             # 数据信息
│   |   |   ├── stack.json            # 调用栈信息
│   |   |   └── construct.json        # 分层分级结构，level为L1时，construct.json内容为空
│   |   ├── rank1
|   |   |   ├── dump_tensor_data
|   |   |   |   └── ...
│   |   |   ├── dump.json
│   |   |   ├── stack.json
|   |   |   └── construct.json
│   |   ├── ...
│   |   |
|   |   └── rankn
│   ├── step1
│   |   ├── ...
│   ├── step2

匹配说明

默认匹配
- 所有节点dump名称一致
- 节点的层级一致（父节点们一致）
模糊匹配
- 模块节点dump名称一致，两个匹配上的模块节点，忽略各自节点下所有api的dump调用次数，按照名称一致+模块节点内的调用顺序进行匹配。

dump名称 = 名称 + 调用次数，例如Torch.matmul.2.forward，matmul是名称，2是调用次数。

FAQ

详见PyTorch场景的分级可视化构图比对-FAQ。