mindstudio-probe 8.1.2__py3-none-any.whl → 8.2.1__py3-none-any.whl

msprobe/docs/19.monitor.md

@@ -24,6 +24,7 @@
 | [采集module堆栈信息](#采集module堆栈信息)                               | 采集监控的第一个 step 的 module 对应的堆栈信息辅助问题定位                              | PyTorch、MindSpore |
 | [指定监控对象](#指定监控对象)                                | 指定监控的nn.Module(nn.Cell)及对应的输入输出                 | PyTorch、MindSpore |
 | [打印模型结构](#打印模型结构)                                | 打印模型结构                                                 | PyTorch           |
+| [l2可解释特征监控](#l2可解释特征监控)                         | 开启模型状态的高阶监控                                        | PyTorch           |
 | [输出格式和统计量](#输出格式和统计量)                        | format PyTorch支持`csv`、`tensorboard`和`api`，MindSpore仅支持`csv`，`ops`、`ndigits`均支持 | PyTorch、MindSpore |
 | [mbs粒度梯度监控](#mbs粒度梯度监控)                    | 开启梯度监控时，采集聚合前梯度时支持`micro_batch_size`粒度                 | PyTorch、MindSpore |
 | [异常告警](#异常告警)                    | 监控对象指标异常时自动告警，支持异常数据落盘                  | PyTorch、MindSpore |
@@ -61,6 +62,8 @@ monitor.set_monitor(
 ) 
 ```
 
+*注意*：若框架为FSDP1，请先保证model包裹FSDP时设置use_orig_params=True。
+
 *注意*：补充deepspeed下常用框架的使能位置。
 
 deepspeed与accelerate、transformers同时使用时，optimizer传值方式为`optimizer=optimizer.optimizer`，若未使用deepspeed，单独使用accelerate、transformers，optimizer传值方式为`optimizer=optimizer`。
@@ -227,7 +230,7 @@ monitor.monitor_gnorm_with_ad(
 module_name可以通过nn.Module的接口named_modules()获取。
 
 #### 打印模型结构
-工具提供可选项`print_struct`打印模型结构，帮助配置targets。工具会在在第一个step后打印结构并停止训练进程，模型结构默认打印在`$MONITOR_OUTPUT_DIR/module_struct.json`。
+工具提供可选项`print_struct`打印模型结构，帮助配置targets。工具会在在第一个step后打印结构并停止训练进程，每张卡上的模型结构默认保存在`$MONITOR_OUTPUT_DIR/module_struct/rank{rank}/module_struct.json`, 其中{rank}为对应的卡号。
 ```json
 {
     "print_struct": true
@@ -302,6 +305,34 @@ param_name可以通过nn.Module的接口`named_parameters()`获取。
 }
 ```
 
+### l2可解释特征监控
+- 工具配置示例
+```json
+{
+    "l2_targets": {
+        "attention_hook": ["0:0.self_attention.core_attention.flash_attention"],
+        "linear_hook": ["0:0.self_attention.linear_qkv", "0:1.self_attention.linear_qkv"]
+    },
+    "recording_l2_features": true,
+    "sa_order": "b,s,h,d"
+}
+```
+| 配置项 | 类型 | 说明 | 是否必选 |
+|--------|------|------|--------|
+| **l2_targets** | Dict[str, List[str]] | 指定需要监控的模型层配置<br>**支持的hook类型**：<br> • `attention_hook`：监控注意力层<br>&nbsp;&nbsp;▪️ 采集指标：`entropy` `softmax_max`<br>&nbsp;&nbsp;▪️ 必须通过[打印模型结构](#打印模型结构)获取准确层名<br>&nbsp;&nbsp;▪️ 不配置或配置空列表均表示不采集<br>• `linear_hook`：监控线性层<br>&nbsp;&nbsp;▪️ 采集指标：`sr`, `kernel_norm`<br>&nbsp;&nbsp;▪️ 必须通过[打印模型结构](#打印模型结构)获取准确层名, 不配置表示不采集<br>&nbsp;&nbsp;▪️ 配置空列表会自动识别符合条件的层（包含`weight`或`wg`2D参数属性的层） | 是 |
+| **recording_l2_features** | bool | 是否开启L2层特征数据采集，默认为false表示不采集 | 否 |
+| **sa_order** | str | 计算`attention_hook`内指标时，指定Attention输入(Q，K)的张量维度排列顺序，支持"s,b,h,d"和"b,s,h,d", 默认为"s,b,h,d"表示输入维度顺序为**s**equence_len​->**b**atch_size​->num_**h**eads​->head_**d**im	 | 否 |
+
+
+#### L2可解释特征监控指标说明
+
+| **指标名称**       | **适用Hook类型**   | **数学定义/计算方式**                                                                 | **监控意义**                                                                                     |
+|--------------------|-------------------|-------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|
+| **entropy**        | attention_hook    | $H(p)=-\sum p_i \log p_i$，其中$p_i$为注意力权重                                     | 衡量注意力分布的不确定性，**低熵值**表示注意力集中                          |
+| **softmax_max**    | attention_hook    | $\max(\text{softmax}(QK^T/\sqrt{d}))$                                               | 反映注意力机制的聚焦程度，**高值**表示存在显著主导的注意力token                                     |
+| **sr(stable_rank)**            | linear_hook       | $\frac{\|W\|_F}{\|W\|_2}$（稳定秩，Frobenius范数除以谱范数）                        | 评估权重矩阵的有效秩，**低值**表示矩阵接近低秩不稳定状态  |
+| **kernel_norm**    | linear_hook       | $\|W\|_F$（Frobenius范数）                                                          | 权重矩阵的缩谱范数，反映输入在矩阵最大奇异向量张成空间的放大系数                                                   |
+
 
 ### 输出格式和统计量
 
@@ -403,6 +434,17 @@ export MONITOR_OUTPUT_DIR=/xxx/output_dir
     },
 ```
 
+注：当配置多条异常告警规则时，优先告警第一条，如以下配置时每一层会优先报AnomalyNan的告警（一般不建议配置多条规则）：
+```json
+    "alert": {
+        "rules": [
+                  {"rule_name": "AnomalyNan", "args": {"threshold": 1e10}},
+                  {"rule_name": "AnomalyTurbulence", "args": {"threshold": 0.5}}
+        ],
+        "dump": true
+    },
+```
+
 2. 实例化工具时传入流水线并行group
 ```python
 monitor = TrainerMon(
@@ -430,12 +472,14 @@ monitor = TrainerMon(
 }
 ```
 
+其中call_{xxx}中的xxx为API的执行调用顺序，为后续异常事件排序做准备。
+
 3. 异常事件排序
 
 当模型训练过程中出现较多异常数据，需要对异常事件排序。工具提供topk的异常排序能力，按照api的执行顺序进行排序，便于定界首次异常点。异常分析命令示例：
 
 ```shell
-python3 -m msprobe.pytorch.monitor.anomaly_analyse -d $MONITOR_OUTPUT_DIR/anomaly_detected
+python3 -m msprobe.core.monitor.anomaly_processor -d $MONITOR_OUTPUT_DIR/anomaly_detected
 ```
 异常事件分析结束，将topk事件写入文件`anomaly_detected/anomaly_analyse.json`。异常分析支持以下参数配置：
 
@@ -449,7 +493,7 @@ python3 -m msprobe.pytorch.monitor.anomaly_analyse -d $MONITOR_OUTPUT_DIR/anomal
 
 ### csv格式数据转tensorboard可视化显示
 
-将csv数据转换为tensorboard格式数据。
+**将csv数据转换为tensorboard格式数据。**
 
 ```python
 from msprobe.pytorch.monitor.csv2tb import csv2tensorboard_by_step
@@ -466,6 +510,31 @@ csv2tensorboard_by_step(
     data_type_list=["param_origin"]
 )
 ```
+参数详细介绍请参见[公开接口](#公开接口)的“csv输出件转tensorboard输出件”
+
+**将csv数据转换为sqlite db数据。**
+1. 创建Python脚本，以`csv2db.py`命名为例，将以下配置拷贝到文件中, 并按实际情况修改。
+
+```python
+from msprobe.core.monitor.csv2db import CSV2DBConfig, csv2db
+config = CSV2DBConfig(
+    monitor_path="~/monitor_output",
+    time_start="Dec03_21-34-40",
+    time_end="Dec03_21-34-42",
+    process_num=8,
+    data_type_list=["grad_unreduced"],
+    step_partition=500,
+    output_dirpath="~/monitor_output"
+)
+csv2db(config)
+```
+参数详细介绍请参见[公开接口](#公开接口)的“csv转sqlite数据库接口”
+
+2. 执行如下命令开启转换。
+```shell
+python csv2db.py
+```
+完成转换，在`~/monitor_output`目录下生成`monitor_metrics.db`文件。
 
 ### 动态启停
 动态启停模式：支持用户在训练过程中随时启动/更新监控。
@@ -553,6 +622,24 @@ csv2tensorboard_by_step(monitor_path, time_start, time_end, process_num=1, data_
 | process_num    | 指定拉起的进程个数，默认为1，更多的进程个数可以加速转换。    | 否       |
 | data_type_list | 指定需要转换的数据类型, 数据类型应来自输出件文件前缀，所有类型数据：<br/> ["actv", "actv_grad", "exp_avg", "exp_avg_sq", "grad_unreduced", "grad_reduced", "param_origin", "param_updated"]。<br/>不指定就转换全部数据。 | 否       |
 | output_dirpath | 指定转换后的输出路径，默认输出到"{curtime}_csv2tensorboard_by_step"文件夹，其中curtime为自动获取的当前时间戳。 | 否       |
+
+- csv转sqlite数据库接口
+```python
+csv2db(config: CSV2DBConfig) -> None
+```
+配置参数 (CSV2DBConfig)
+
+| 参数           | 说明                                                         | 是否必选 |
+| -------------- | ------------------------------------------------------------ | -------- |
+| monitor_path   | 待转换的csv存盘目录。                                        | 是       |
+| time_start     | 起始时间, 例如"Dec03_21-34-40"。搭配time_end一起使用，从而指定一个时间范围（闭区间），会对这个范围内的文件进行转换。默认为None不限制。 | 否       |
+| time_end       | 结束时间，例如"Dec03_21-34-41"。搭配time_start一起使用，从而指定一个时间范围（闭区间），会对这个范围内的文件进行转换。默认为None不限制。 | 否       |
+| process_num    | 指定拉起的进程个数，默认为1，更多的进程个数可以加速转换。    | 否       |
+| data_type_list | 指定需要转换的数据类型, 数据类型应来自输出件文件前缀，所有类型数据：<br/> ["actv", "actv_grad", "exp_avg", "exp_avg_sq", "grad_unreduced", "grad_reduced", "param_origin", "param_updated", "other"]。<br/>不指定就转换全部数据。 | 否       |
+| step_partition | 控制数据库中按step分区的间隔，默认每500步一个表。           | 否       |
+| output_dirpath | 指定转换后的输出路径，默认输出到"{curtime}_csv2db"文件夹，其中curtime为自动获取的当前时间戳。 | 否       |
+
+
 - 在模型任意位置获取当前参数**梯度**统计量
 ```python
 TrainerMon.generate_wgrad_metrics() -> tuple[dict, dict]
@@ -642,7 +729,7 @@ TrainerMon.monitor_gnorm_with_ad(model, grad_acc_steps, optimizer, dp_group, tp_
 | "collect_times"         | 可选     | 设置采集次数，达到该次数后停止监控，默认值为100000000，目的是一直采集。                                                                                                                                                                                                                                                                                                                                        |
 | "start_step"            | 可选     | 设置开始采集step，模型训练达到start_step后开始监控采集，默认值为0，表示从step0开始监控采集。注：在动态启停模式下该设置不生效，只会从下一步开始监控采集。                                                                                                                                                                                                                                                                                          |
 | "step_interval"         | 可选     | 设置采集step间隔，默认值为1，表示每个step均采集监控数据。                                                                                                                                                                                                                                                                                                                                               |
-| "print_struct"          | 可选     | 设置为true后监控工具会打印模型中torch module的名字和详细结构，并在第1个step后退出。不填默认为false。**仅PyTorch场景支持此参数**。                                                                                                                                                                                                                                                                                             |
+| "print_struct"          | 可选     | 设置为true后监控工具会打印每张卡模型中module的名字和详细结构，并在第1个step后退出。不填默认为false。                                                                                                                                                                                                                                                                                                                    |
 | "module_ranks"          | 可选     | 用于在分布式训练场景中希望控制在哪些rank开启module监控。如果不填，则默认在所有rank开启。 列表内rank要求为int类型。                                                                                                                                                                                                                                                                                                            |
 | "ur_distribution"       | 可选     | 若为true则会统计adam优化器指定模块（targets中指定）参数的update和ratio向量的数值分布，并展示在heatmap里，默认为false，同时format字段必须设置为tensorboard。<br/>依赖histc算子， 需要CANN8.0.rc2以上版本， 否则会有严重的性能问题。**仅PyTorch场景支持此参数**。                                                                                                                                                                                                    |
 | "xy_distribution"       | 可选     | 若为true则会监控指定module（targets中指定）的输入输出张量。 默认为false。                                                                                                                                                                                                                                                                                                                                |
@@ -651,7 +738,7 @@ TrainerMon.monitor_gnorm_with_ad(model, grad_acc_steps, optimizer, dp_group, tp_
 | "backward_only"         | 可选     | 开启xy_distribution后生效，若为true，仅监控指定module的反向，targets中的input、output不生效。默认为false。                                                                                                                                                                                                                                                                                                   |
 | "mv_distribution"       | 可选     | 若为true则会监控指定模块中的参数的优化器状态， 默认为false。版本<msprobe1.2.2时需要在TrainerMon构造函数正确指定opt_ty。                                                                                                                                                                                                                                                                                                 |
 | "wg_distribution"       | 可选     | 若为true则会监控指定模块的参数梯度， 默认为false。                                                                                                                                                                                                                                                                                                                                                  |
-| "monitor_mbs_grad" | 可选     | 若为true则会监控mbs粒度梯度统计量，默认为false。                                                                                                                                                                                                                                                                                                                       |
+| "monitor_mbs_grad" | 可选     | 若为true则会监控mbs粒度梯度统计量，默认为false。                                                                                                                                                                                                                                                                                                                                                  |
 | "param_distribution"    | 可选     | 若为true则会监控指定模块的参数， 默认为false。                                                                                                                                                                                                                                                                                                                                                    |
 | "alert"                 | 可选     | "rules": 指定自动报警的异常检测机制及其相应的阈值。目前实现的异常检测是AnomalyTurbulence， 如果统计标量超出历史均值的指定浮动范围（threshold 0.5意味着上浮或者下浮50%）则在控制台打印报警信息。当"dump"字段配置为true表示异常事件写入文件，默认为false。**仅PyTorch场景支持此参数**。                                                                                                                                                                                                   |
 | "cc_distribution"       | 可选     | 其中"enable"字段控制通信监控模块的开关，仅支持在多卡训练时开启；需要监控通信算子时，务必尽量早地实例化`TrainerMon`, 因为监控通过劫持原始func后挂hook实现，部分加速库初始化时会保存原始function，避免监控失效。"cc_codeline"字段指定监控的代码行，如:`train.py\\[23\\]`，默认为空列表，不特别指定；"cc_pre_hook"字段控制是否监控通输入； 模块会在第二个optimize.step之前打印通信日志，包括通信api的调用栈、输入dtype、通信group。 "cc_log_only"为true时，仅打印日志，不监控通信的输入输出，并在打印后中断训练。可以根据通信日志设置"cc_codeline"，规避与训练过程不相关的通信，比如一些时间、metrics的同步。 |
@@ -659,8 +746,8 @@ TrainerMon.monitor_gnorm_with_ad(model, grad_acc_steps, optimizer, dp_group, tp_
 | "format"                | 可选     | 数据落盘格式，默认值为"csv"，可选 \["csv", "tensorboard", "api"\]。仅PyThon和MindSpore动态图场景支持此参数，且MindSpore动态图场景仅支持\["csv"\]。                                                                                                                                                                                                                                                                    |
 | "ops"                   | 可选     | 类型为list，与ur_distribution、xy_distribution、mv_distribution、wg_distribution、mg_direction、cc_distribution配合，监控所选张量的统计指标，目前支持"min"、"max"、"norm"、"mean"、"zeros"、"nans"。其中，zeros代表监控所选张量的元素小于eps的比例，nans代表张量中nan的数量。当ops中无有效指标时，默认监控norm指标。                                                                                                                                            |
 | "eps"                   | 可选     | 若ops里包含"zeros"则需要配置，默认为1e-8。                                                                                                                                                                                                                                                                                                                                                    |
-| "ndigits"               | 可选     | "format"为"csv"时，设置落盘文件中的小数位数，默认为6。                                                                                                                                                                                                                                                                                                                          |
+| "ndigits"               | 可选     | "format"为"csv"时，设置落盘文件中的小数位数，默认为6。                                                                                                                                                                                                                                                                                                                                              |
 | "step_count_per_record" | 可选     | "format"为"csv"时生效，每个csv记录多少个step的数据，默认为1。                                                                                                                                                                                                                                                                                                                                       |
 | "append_output"         | 可选     | 适用于断点续训场景。多卡场景下生效，指定两个时间戳，将输出续写到这两个时间戳范围间的输出件中，不在范围内的rank不被续写。时间戳应来自原有输出件目录前缀，例如["Dec03_21-34-40", "Dec03_21-34-41"]。默认为[]，不续写。**仅PyTorch场景支持此参数**。                                                                                                                                                                                                                             |
-| "squash_name"           | 可选     | 是否简化参数名/模块名，多模态场景建议关闭，默认为True                                                                                                                                                                                                                                                                                                                                                   |
+| "squash_name"           | 可选     | 是否简化参数名/模块名，多模态场景建议关闭，默认为True。                                                                                                                                                                                                                                                                                                                                                  |
 

msprobe/docs/21.visualization_PyTorch.md

@@ -4,18 +4,6 @@
 
 工具支持PyTorch版本：2.1/2.2
 
-## 更新通知
-
-请注意，tb_graph_ascend插件已于2025/3/12更新到1.0.0版本，如果当前环境已安装旧版本插件，推荐升级。
-
-更新内容如下：
-
-- 优化了信息栏，使用了更人性化、更美观的展示界面；
-- 提升了节点渲染和搜索性能；
-- 双图比对场景画布分离，操作左图时不会影响到右图；
-- 新增浏览器匹配节点功能，双图比对场景有未匹配节点时，可通过在浏览器页面手动选中调试侧和标杆侧的未匹配节点进行精度比对；
-- 新增颜色图例可配置功能。
-
 ## 工具特性
 
 - 支持重建模型的层级结构；
@@ -25,6 +13,7 @@
 - 支持多卡场景的批量构图，能够关联各卡的通信节点，分析各卡之间的数据传递；
 - 支持节点名称搜索，按精度比对结果筛选节点，按溢出检测结果筛选节点，支持自动跳转展开节点所在的层级；
 - 支持跨套件、跨框架的模型比对。
+- 支持不同切分策略下两个模型的精度数据比对：[不同切分策略下的图合并](#325-不同切分策略下的图合并)。
 
 ![vis_show](./img/visualization/vis_showcase.png)
 
@@ -32,18 +21,16 @@
 
 ### 1.1 安装msprobe工具
 
-[msprobe工具安装](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/docs/01.installation.md)
+[msprobe工具安装](./01.installation.md)
 
 ### 1.2 安装tb_graph_ascend
 
 **请安装tb_graph_ascend，否则无法解析构图结果。**
 
-``pip3 install tb-graph-ascend``即可。
-
-如需升级工具，请先``pip3 uninstall tb-graph-ascend``再``pip3 install tb-graph-ascend``即可。
+[tb_graph_ascend安装](../../../../plugins/tensorboard-plugins/tb_graph_ascend#2-安装方式)
 
 ## 2.模型结构数据采集
-[PyTorch场景的数据采集](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/docs/05.data_dump_PyTorch.md)
+[PyTorch场景的数据采集](./05.data_dump_PyTorch.md)
 
 **需要选择level为L0（module信息）或者mix（module信息+api信息），才能采集到模型结构数据，即采集结果件construct.json内容不为空**。
 
@@ -57,15 +44,14 @@ msprobe -f pytorch graph -i ./compare.json -o ./output
 ```
 **命令行参数说明**：
 
-| 参数名                    | 说明                                                                                                                                                                                                                                                                                                                                                                                   | 是否必选 |
-|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|
-| -f 或 --framework       | 指定训练框架。pytorch。                                                                                                                                                                                                                                                                                                                                                                      | 是                                 |
-| -i 或 --input_path      | 指定比对文件，参考[比对文件说明](#313-比对文件说明)                                                                                                                                                                                                                                                                                                                                                       | 是    |
-| -o 或 --output_path     | 配置比对结果文件存盘目录，str 类型。文件名称基于时间戳自动生成，格式为：`compare_{timestamp}.vis或build_{timestamp}.vis`。                                                                                                                                                                                                                                                                                               | 是    |
-| -lm 或 --layer_mapping  | 跨套件比对，例如同一个模型分别使用了DeepSpeed和Megatron套件的比对场景。配置该参数时表示开启跨套件Layer层的比对功能，指定模型代码中的Layer层后，可以识别对应dump数据中的模块或API。需要指定自定义映射文件*.yaml。自定义映射文件的格式请参见[自定义映射文件（Layer）](#71-自定义映射文件layer)，如何配置自定义映射文件请参考[模型分级可视化如何配置layer mapping映射文件](./visualization/layer_mapping_example.md)。 配置该参数后，将仅按节点名称进行比对，忽略节点的 type 和 shape。如果调试侧和标杆侧有名称不同的节点，则需要配置自定义映射文件，-lm参数传入自定义映射文件路径；如果调试侧和标杆侧节点名称相同，则仅指定-lm即可。 | 否    |
-| -oc 或 --overflow_check | 是否开启溢出检测模式，开启后会在输出vis文件中（`compare_{timestamp}.vis或build_{timestamp}.vis`）对每个溢出节点进行标记溢出等级，溢出等级说明参考[溢出等级说明](#312-溢出等级说明)                                                                                                                                                                                                                                                               | 否    |
-| -f 或 --fuzzy_match     | 是否开启模糊匹配，bool类型。模糊匹配说明参考[匹配说明](#311-匹配说明)                                                                                                                                                                                                                                                                                                                                            | 否    |
-| -cs 或 --complete_stack | 是否使用完整的堆栈信息，bool类型。默认使用精简的堆栈信息，数据量小有助于增加流畅度。完整堆栈和精简堆栈信息参考[堆栈信息说明](#72-堆栈信息说明)                                                                                                                                                                                                                                                                                                        | 否    |
+| 参数名                    | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | 是否必选 |
+|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|
+| -f 或 --framework       | 指定训练框架。pytorch。                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | 是                                 |
+| -i 或 --input_path      | 指定比对文件，参考[比对文件说明](#313-比对文件说明)                                                                                                                                                                                                                                                                                                                                                                                                                                                              | 是    |
+| -o 或 --output_path     | 配置比对结果文件存盘目录，str 类型。文件名称基于时间戳自动生成，格式为：`compare_{timestamp}.vis.db或build_{timestamp}.vis.db`。                                                                                                                                                                                                                                                                                                                                                                                                | 是    |
+| -lm 或 --layer_mapping  | 跨套件比对，例如同一个模型分别使用了DeepSpeed和Megatron套件的比对场景。配置该参数时表示开启跨套件Layer层的比对功能，指定模型代码中的Layer层后，可以识别对应dump数据中的模块或API。需要指定自定义映射文件*.yaml。自定义映射文件的格式请参见[自定义映射文件（Layer）](#71-自定义映射文件layer)，如何配置自定义映射文件请参考[模型分级可视化如何配置layer mapping映射文件](./visualization/layer_mapping_example.md)。 配置该参数后，将仅按节点名称进行比对，忽略节点的 type 和 shape。如果调试侧和标杆侧有名称不同的节点，则需要配置自定义映射文件，-lm参数传入自定义映射文件路径；如果调试侧和标杆侧节点名称相同，则仅指定-lm即可。<br/><br/>可参考的实际案例：[MindSpeed&LLamaFactory数据采集和自动比对](./visualization/mindspeed_llamafactory_mapping.md) | 否    |
+| -oc 或 --overflow_check | 是否开启溢出检测模式，开启后会在输出db文件中（`compare_{timestamp}.vis.db或build_{timestamp}.vis.db`）对每个溢出节点进行标记溢出等级，溢出等级说明参考[溢出等级说明](#312-溢出等级说明)                                                                                                                                                                                                                                                                                                                                                                 | 否    |
+| -f 或 --fuzzy_match     | 是否开启模糊匹配，bool类型。模糊匹配说明参考[匹配说明](#311-匹配说明)                                                                                                                                                                                                                                                                                                                                                                                                                                                   | 否    |
 
 #### 3.1.1 匹配说明
 
@@ -102,7 +88,7 @@ msprobe -f pytorch graph -i ./compare.json -o ./output
 | npu_path   | 指定待调试侧比对路径，str类型。工具根据路径格式自动进行单rank比对、多rank批量比对或多step批量比对，具体格式参考3.2 图构建和比对。 | 是    |
 | bench_path  | 指定标杆侧比对路径，str类型。单图构建场景可以不配置。                                               | 否    |
 | is_print_compare_log  | 配置是否开启单个算子的日志打屏。可取值 true 或 false，默认为 true。关闭后则只输出常规日志，bool 类型。             | 否    |
-
+| parallel_merge  | 配置是否开启不同切分策略下的图合并，dict类型。rank_size、tp、pp参数按实际情况进行配置。比对时配置npu、bench，只构图配置npu。 配置示例见[3.2.5 不同切分策略下的图合并](#325-不同切分策略下的图合并)。 | 否    |
 
 ### 3.2 图构建和比对
 
@@ -150,7 +136,7 @@ msprobe -f pytorch graph -i ./compare.json -o ./output
 
 3.md5：dump了API和Module的输入输出数据统计信息和md5信息。
 
-dump类型如何配置见[数据采集配置文件介绍](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/docs/02.config_introduction.md)
+dump类型如何配置见[数据采集配置文件介绍](https://gitcode.com/Ascend/mstt/blob/master/debug/accuracy_tools/msprobe/docs/02.config_introduction.md)
 
 **1. 准备比对文件**：
 
@@ -179,7 +165,7 @@ npu_path或bench_path格式：必须包含dump.json、stack.json和construct.jso
 msprobe -f pytorch graph -i ./compare.json -o ./output
 ```
 
-比对完成后将在**output**下生成一个**vis后缀文件**。
+比对完成后将在**output**下生成一个**vis.db后缀文件**。
 
 #### 3.2.3 批量构建或比对
 ##### 3.2.3.1 多rank批量构建或比对
@@ -223,25 +209,15 @@ npu_path或bench_path格式：必须只包含rank+数字格式的文件夹，且
 ```
 msprobe -f pytorch graph -i ./compare.json -o ./output
 ```
-比对完成后将在**output**下生成n个**vis后缀文件**。
+比对完成后将在**output**下生成1个**vis.db后缀文件**。
 
 图构建：
 ```
-├── build_rank0_{timestamp}.vis
-├── build_rank1_{timestamp}.vis
-├── build_rank2_{timestamp}.vis
-├── build_rank3_{timestamp}.vis
-├── ...
-├── build_rankn_{timestamp}.vis
+├── build_{timestamp}.vis.db
 ```
 图比对：
 ```
-├── compare_rank0_{timestamp}.vis
-├── compare_rank1_{timestamp}.vis
-├── compare_rank2_{timestamp}.vis
-├── compare_rank3_{timestamp}.vis
-├── ...
-├── compare_rankn_{timestamp}.vis
+├── compare_{timestamp}.vis.db
 ```
 ##### 3.2.3.2 多step批量构建或比对
 批量构建或比对多个step下的所有rank的数据
@@ -288,33 +264,15 @@ npu_path或bench_path格式：必须只包含step+数字格式的文件夹，且
 ```
 msprobe -f pytorch graph -i ./compare.json -o ./output
 ```
-比对完成后将在**output**下生成若干个**vis后缀文件**。
+比对完成后将在**output**下生成1个**vis.db后缀文件**。
 
 图构建：
 ```
-├── build_step0_rank0_{timestamp}.vis
-├── build_step0_rank1_{timestamp}.vis
-├── build_step0_rank2_{timestamp}.vis
-├── build_step0_rank3_{timestamp}.vis
-├── build_step1_rank0_{timestamp}.vis
-├── build_step1_rank1_{timestamp}.vis
-├── build_step1_rank2_{timestamp}.vis
-├── build_step1_rank3_{timestamp}.vis
-├── ...
-├── build_stepn_rankn_{timestamp}.vis
+├── build_{timestamp}.vis.db
 ```
 图比对：
 ```
-├── compare_step0_rank0_{timestamp}.vis
-├── compare_step0_rank1_{timestamp}.vis
-├── compare_step0_rank2_{timestamp}.vis
-├── compare_step0_rank3_{timestamp}.vis
-├── compare_step1_rank0_{timestamp}.vis
-├── compare_step1_rank1_{timestamp}.vis
-├── compare_step1_rank2_{timestamp}.vis
-├── compare_step1_rank3_{timestamp}.vis
-├── ...
-├── compare_stepn_rankn_{timestamp}.vis
+├── compare_{timestamp}.vis.db
 ```
 
 #### 3.2.4 仅模型结构比对
@@ -327,6 +285,49 @@ dump配置请参考[dump配置示例](./03.config_examples.md#16-task-配置为-
 
 得到dump数据后，若需比较特定两个rank之间的数据，请参考[3.2.2 双图比对](#322-双图比对)；若需进行多个rank或多个step的数据批量比对，请参考[3.2.3 批量构建或比对](#323-批量构建或比对)。
 
+#### 3.2.5 不同切分策略下的图合并
+
+适用场景：不同模型并行切分策略下，两个模型产生了精度差异，需要进行整网数据比对，但被切分的数据或模型结构分布于多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，图合并将得到两张图，暂不支持数量不一致的图进行比对。
+
+使能方式：
+
+在compare.json里增加parallel_merge配置项， rank_size、tp、pp和vpp参数按实际情况进行配置。
+
+参数说明：
+
+所需tp、pp和vpp参数来自于Megatron、MindSpeed-LLM套件中的训练脚本实际配置。
+
+| 参数名       | 说明                                                                                                                       | 是否必填 |
+|-----------|--------------------------------------------------------------------------------------------------------------------------|------|
+| rank_size | 模型实际训练所用加速卡的数量，int类型。`rank_size=tp*pp*cp*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则无需修改。                         | 否    |
+
+npu_path、bench_path的配置以及执行命令请参考[3.2.3 批量构建或比对](#323-批量构建或比对)
+
+如果只进行图构建，"bench_path"和"parallel_merge"中的"bench"参数可不配置。
+
+```
+{
+  "npu_path": "./npu_dump",
+  "bench_path": "./bench_dump",
+  "is_print_compare_log": true,
+  "parallel_merge": {
+    "npu": {"rank_size": 8, "tp": 8, "pp": 1},
+    "bench": {"rank_size": 8, "tp": 1, "pp": 8}
+  }
+}
+```
+
 ## 4.启动tensorboard
 
 ### 4.1 可直连的服务器
@@ -380,13 +381,18 @@ tensorboard --logdir out_path
 
 ### 5.1 浏览器打开图
 推荐使用谷歌浏览器，在浏览器中输入机器地址+端口号回车，出现TensorBoard页面，其中/#graph_ascend会自动拼接。
+
 ![vis_browser_1](./img/visualization/vis_browser_1.png)
+
 如果您切换了TensorBoard的其他功能，此时想回到模型分级可视化页面，可以点击左上方的**GRAPH_ASCEND**
+
 ![vis_browser_2](./img/visualization/vis_browser_2.png)
 
 ### 5.2 查看图
 ![vis_show_info.png](./img/visualization/vis_show_info.png)
 
+MicroStep是指在一次完整的权重更新前执行的多次前向和反向传播过程，一次完整的训练迭代（step）可以进一步细分为多个更小的步骤（micro step）。其中分级可视化工具通过识别模型首层结构中一次完整的前反向作为一次micro step。
+
 ### 5.3 名称搜索
 ![vis_search_info.png](./img/visualization/vis_search_info.png)
 
@@ -412,14 +418,14 @@ tensorboard --logdir out_path
 颜色越深，精度比对差异越大，越可疑，具体信息可见浏览器页面左下角颜色图例。
 
 #### 6.1.1 真实数据模式
-节点中所有输入的最小双千指标和所有输出的最小双千分之一指标的差值，反映了双千指标的下降情况，**值越大精度差距越大，颜色标记越深**。
+节点中所有输入的最小双千指标和所有输出的最小双千分之一指标的差值，反映了双千指标的下降情况，**该数值越大，表明两组模型的精度差异越大，在图中标注的对应颜色会更深**。
 
 ``One Thousandth Err Ratio（双千分之一）精度指标：Tensor中的元素逐个与对应的标杆数据对比，相对误差小于千分之一的比例占总元素个数的比例，比例越接近1越好``
 
 如果调试侧（NPU）节点的output指标中的最大值（MAX）或最小值（MIN）中存在 nan/inf/-inf，直接标记为最深颜色。
 
 #### 6.1.2 统计信息模式
-节点中输出的统计量相对误差，**值越大精度差距越大，颜色标记越深**。
+节点中输出的统计量相对误差，**该数值越大，表明两组模型的精度差异越大，在图中标注的对应颜色会更深**。
 
 ``相对误差：abs（(npu统计值 - bench统计值) / bench统计值)``
 
@@ -499,42 +505,6 @@ yaml文件中只需配置待调试侧与标杆侧模型代码中功能一致但
 
 ![ms_dump](./img/ms_layer.png)
 
-### 7.2 堆栈信息说明
-
-**精简堆栈**
-
-保留一条当前模块或api的调用信息
-
-```json
-{
-    "Module.layer1.0.bn1.BatchNorm2d.forward.0": [
-        "File /home/torchvision/models/resnet.py, line 93, in forward, \n out = self.bn1(out)"
-       ]
-}
-```
-
-**完整堆栈**
-
-当前模块或api完整的调用信息
-
-```json
-{
-    "Module.layer1.0.bn1.BatchNorm2d.forward.0": [
-        "File /home/torchvision/models/resnet.py, line 93, in forward, \n out = self.bn1(out)",
-        "File /home/torch/nn/modules/module.py, line 1568, in _call_impl, \n result = forward_call(*args, **kwargs)",
-        "File /home/torch/nn/modules/module.py, line 1518, in _wrapped_call_impl, \n return self._call_impl(*args, **kwargs)",
-        "File /home/torch/nn/modules/container.py, line 215, in forward, \n input = module(input)",
-        "File /home/torch/nn/modules/module.py, line 1568, in _call_impl, \n result = forward_call(*args, **kwargs)",
-        "File /home/torch/nn/modules/module.py, line 1518, in _wrapped_call_impl, \n return self._call_impl(*args, **kwargs)",
-        "File /home/torchvision/models/resnet.py, line 273, in _forward_impl, \n x = self.layer1(x)",
-        "File /home/torchvision/models/resnet.py, line 285, in forward, \n return self._forward_impl(x)",
-        "File /home/torch/nn/modules/module.py, line 1527, in _call_impl, \n return forward_call(*args, **kwargs)",
-        "File /home/torch/nn/modules/module.py, line 1518, in _wrapped_call_impl, \n return self._call_impl(*args, **kwargs)",
-        "File /home/visualization/resnet18.py, line 40, in <module>, \n outputs = model(inputs)"
-       ]
-}
-
-```
 # FAQ
 1. 图比对场景，节点呈现灰色，且没有精度比对数据，怎么处理？