mindstudio-probe 1.1.1__py3-none-any.whl → 1.2.1__py3-none-any.whl

msprobe/docs/19.monitor.md

@@ -9,10 +9,12 @@
     - [权重梯度监控](#权重梯度监控)
     - [激活值监控](#激活值监控)
     - [优化器状态监控](#优化器状态监控)
+    - [csv格式数据转tensorboard可视化显示](#csv格式数据转tensorboard可视化显示)
 - [详细配置](#详细配置)
 
 ## 安装
 参见[msprobe安装](./01.installation.md)
+要求torch版本不低于2.0。
 
 ## 快速上手
 根据需求监控相应对象。比如在loss上扬，grad norm正常的异常训练过程中，优先考虑监控模型前向过程；在grad norm异常的训练过程中，监控权重和激活值的梯度。
@@ -42,7 +44,9 @@ monitor.monitor_gnorm_with_ad(
     grad_acc_steps=args.global_batch_size//args.data_parallel_size//args.micro_batch_size,
     optimizer=None,
     dp_group=None,
-    tp_group=None) 
+    tp_group=None,
+    start_iteration=0
+    ) 
 
 
 # optional
@@ -52,7 +56,9 @@ reduced, unreduced = monitor.generate_wgrad_metrics()
 actv, actv_grad = monitor.generate_xy_metrics()
 ```
 
-补充deepspeed下常用框架的使能位置，提供参考
+补充deepspeed下常用框架的使能位置，提供参考。
+
+注意deepspeed与megaton的区别在于optimizer的传值不同，`optimizer=optimizer.optimizer`。若未使用deepspeed，则直接传optimizer，`optimizer=optimizer`。
 
 - accelerate
 
@@ -81,10 +87,10 @@ class Trainer:
 
 ### 指定监控对象
 
-工具支持对nn.Module（**激活值监控**）和nn.Parameter（**梯度监控、优化器监控**）对象实现相应的监控行为，在配置文件的"targets"（dict）字段指定，targets格式为{module_name/param_name: {filed: format}}。
+工具支持对nn.Module（**激活值监控**）和nn.Parameter（**权重监控**、**权重梯度监控、优化器监控**）对象实现相应的监控行为，在配置文件的"targets"（dict）字段指定，targets格式为{module_name/param_name: {filed: format}}。
 
 - 打印模型结构
-工具提供可选项"print_struct"打印模型结构，帮助配置targets。工具会在在第一个step后打印结构并停止训练进程。  
+工具提供可选项"print_struct"打印模型结构，帮助配置targets。工具会在在第一个step后打印结构并停止训练进程，模型结构默认打印在`$MONITOR_OUTPUT_DIR/module_struct.json`。
 ```json
 {
     "print_struct": true
@@ -134,7 +140,7 @@ class Trainer:
     }
 }
 ```
-**Module全量监控**：工具提供简便的全量module监控方式。
+**Module全量监控**：工具提供简便的全量module监控方式。或不配置targets、all_xy字段，同样表示全量监控。
 
 ```json
 {
@@ -159,11 +165,11 @@ class Trainer:
 }
 ```
 
-**Parameter全量监控**：工具提供简便的全量parameter监控方式。
+**Parameter全量监控**：工具提供简便的全量parameter监控方式。或不配置targets，同样表示全量监控。
 
 ```json
 {
-    "targets": {"":{}}
+    "targets": {}
 }
 ```
 
@@ -203,7 +209,7 @@ export MONITOR_OUTPUT_DIR=/xxx/output_dir
       监控结果不落盘，在训练过程中可以通过`generate_wgrad_metrics`、`generate_xy_metrics`等接口获取。
 
 - 统计量 
-通过必选配置项"ops"指定。可以是["norm", "min", "max", "mean", "nans"，"zeros"]。其中"nans"统计tensor中nan的数量，"zeros"统计tensor中数值小于"eps"的比例。  
+通过配置项"ops"指定。可以是["norm", "min", "max", "mean", "nans"，"zeros"]。其中"nans"统计tensor中nan的数量，"zeros"统计tensor中数值小于"eps"的比例。  
 
 ### 权重监控
 - 工具配置示例：
@@ -262,7 +268,7 @@ monitor.monitor_gnorm_with_ad(
 ### 梯度异常时序判断
 1. 训练前配置相关参数
 
-工具支持自动判断训练过程中的梯度异常，需要在配置文件中设置alert相关字段。"AnomalyTurbulence"会将当前数值与历史均值比较，如果相对偏差超过阈值，会在打屏信息中提示用户。如果打开"dump"选项，则会将异常梯度相关信息落盘到目录`monitor_output/anomaly_detected`，用于后续时序判断。
+工具支持自动判断训练过程中的梯度异常，需要在配置文件中设置alert相关字段。"AnomalyTurbulence"会将当前数值与历史均值比较，如果相对偏差超过阈值，会在打屏信息中提示用户。如果打开"`dump`"选项，则会将异常梯度相关信息落盘到目录`monitor_output/anomaly_detected`，用于后续时序判断。
 ```json
     "alert": {
         "rules": [{"rule_name": "AnomalyTurbulence", "args": {"threshold": 0.5}}],
@@ -273,22 +279,40 @@ monitor.monitor_gnorm_with_ad(
 ```python
 monitor = TrainerMon("./monitor_config.json", process_group=mpu.get_pipeline_model_parallel_group(), params_have_main_grad=True)
 ```
-照常开始训练
+训练过程中，检测到异常后打屏提示，并将异常信息按照rank分组写入json文件，文件路径默认为`monitor_output/anomaly_detected`，异常信息示例如下：
+
+```json
+{
+    "0:1.self_attention.core_attention_flash_0/rank0/input_grad_step_1_call_112": {
+        "rank": 0,
+        "step": 1,
+        "micro_step": 0,
+        "pp_stage": 0,
+        "vpp_stage": 0,
+        "call_id": 112,
+        "tag_name": "0:1.self_attention.core_attention_flash_0/rank0/input_grad",
+        "message": "Rule AnomalyTurbulence reports anomaly signal in ('0:1.self_attention.core_attention_flash_0/rank0/input_grad', 'min') at step 1.",
+        "group_mates": [0, 1]
+    },
+    ...
+}
+```
+
+3. 异常事件排序
 
-3. 启动异常分析脚本：
+当模型训练过程中出现较多异常数据，需要对异常事件排序。工具提供topk的异常排序能力，按照api的执行顺序进行排序，便于定界首次异常点。异常分析命令示例：
 
 ```shell
 python3 -m msprobe.pytorch.monitor.anomaly_analyse -d $MONITOR_OUTPUT_DIR/anomaly_detected
 ```
-支持以下参数配置
-| 字段名                                                       | 解释    | 是否必选   | 
-| ------ | -------- | -------- | 
-|-d 或 --data_path| 指定梯度异常落盘文件夹，梯度监控功能输出，一般为$MONITOR_OUTPUT_DIR/anomaly_detected。|是 |
-|-o 或 --out_path| 排序后的异常落盘文件地址，默认在--data_path路径下落盘一个anomaly_analyse.json文件| 否 |
-|-k 或 --topk| 指定保留前topk个异常，默认为8| 否 |
-|-s 或 --step_list| 指定分析的step范围，默认为[]| 否 |
-
+异常事件分析结束，将topk事件写入文件`anomaly_detected/anomaly_analyse.json`。异常分析支持以下参数配置：
 
+| 字段名                                                       | 解释    | 是否必选   |
+| ------ | -------- | -------- |
+|-d 或 --data_path| 指定梯度异常落盘文件夹，梯度监控功能输出，一般为$MONITOR_OUTPUT_DIR/anomaly_detected。|是 |
+|-o 或 --out_path| 排序后的异常落盘文件地址，默认在--data_path路径下落盘一个anomaly_analyse.json文件。 | 否 |
+|-k 或 --topk| 指定保留前topk个异常，默认为8。 | 否 |
+|-s 或 --step_list| 指定分析的step范围，默认为[]。 | 否 |
 
 ### 激活值监控
 
@@ -368,6 +392,50 @@ monitor.monitor_gnorm_with_ad(
         model, grad_acc_steps=model.grad_acc_steps, optimizer=optimizer)
 ```
 
+### csv格式数据转tensorboard可视化显示
+
+将csv数据转换为tensorboard格式数据。
+
+```python
+from msprobe.pytorch.monitor.csv2tb import csv2tensorboard_by_step
+# 前三个参数用来指定需要转换的一批文件，指定monitor输出目录及一个时间范围，会对这个范围内的文件进行转换
+# process_num指定拉起的进程个数，默认为1，更多的进程个数可以加速转换
+# data_type_list是一个列表，指定需要转换的数据类型, 数据类型应来自输出件文件前缀，所有类型数据：
+# ["actv", "actv_grad", "exp_avg", "exp_avg_sq", "grad_unreduced", "grad_reduced", "param"]
+# 不指定就转换全部数据
+# output_dirpath可指定输出目录， 不传值时保存到"{curtime}_csv2tensorboard_by_step"文件夹，其中curtime为自动获取的当前时间戳
+csv2tensorboard_by_step(
+    monitor_path="~/monitor_output",
+    time_start="Dec03_21-34-40",
+    time_end="Dec03_21-34-42",
+    process_num=8,
+    data_type_list=["param"]
+)
+```
+
+### 动态启停
+动态启停模式：支持用户在训练过程中随时启动/更新监控。
+
+用户可在训练开始前通过配置环境变量DYNAMIC_MONITOR=True来确认开启动态启停模式，该模式下需要配合config.json文件中的switch字段来使用。
+
+在动态启停模式下，启动和停止分别由如下控制：
+
+- 启动：
+  首次监控：config.json文件中switch字段为true，代表是否需要开启监控。
+  非首次监控：config文件时间戳更新且config.json文件中switch字段为true。
+- 停止：
+  到达collect_times之后自动停止并改config.json文件中switch字段为false，可再通过上述操作重启。
+
+大部分情况下，用户可在看到异常趋势后再手动更新config.json文件并打开switch开关；此外，使用时若想要在一开始就启动监控，可直接打开switch开关做基础配置的监测（首次不要求时间戳更新）
+
+注意事项：
+
+- 默认监控启动皆统一在配置初始化或查询到更新后的下一步，也就是若第n步挂上hook则第n+1步才启动采集，如需采集第0步数据请用静态模式。
+- config中途修改出错时，若此时不在监控就不生效，若在监控则用原配置继续。
+- 达到collect_times之后会自动将该值置为false待下次改true重启。
+
+
+
 ## 公开接口
 
 ```python
@@ -379,10 +447,10 @@ TrainerMon.__init__(config_file_path, process_group=None, params_have_main_grad=
 | config_file_path |json配置文件路径。 | 是       |
 | process_group | 传入ProcessGroup对象，用以确定pipeline并行不同rank异常间时序，megatron下通过core.parallel_state.get_pipeline_model_parallel_group()获得。 | 否       |
 | params_have_main_grad |权重是否使用main_grad，通常megatron为True，deepspeed为False。默认为True。 | 否       |
-| opt_ty |优化器类型，默认为None。<br>-Megatron_DistributedOptimizer：megatron分布式优化器；<br/>-Megatron_Float16OptimizerWithFloat16Params：megatron混合精度优化器；<br/>-DeepSpeedZeroOptimizer_Stage1_or_2：DeepSpeed Zero1和Zero2；<br/>-DeepSpeedZeroOptimizer_Stage3：DeepSpeed Zero3。 | 否      |
+| opt_ty |优化器类型，默认为None。<br>-Megatron_DistributedOptimizer：megatron分布式优化器；<br/>-Megatron_Float16OptimizerWithFloat16Params：megatron混合精度优化器；<br/>-Megatron_ChainedDistributedOptimizer：megatron分布式优化器序列；<br/>-Megatron_ChainedFloat16OptimizerWithFloat16Params：megatron混合精度优化器序列；<br/>-DeepSpeedZeroOptimizer_Stage1_or_2：DeepSpeed Zero1和Zero2；<br/>-DeepSpeedZeroOptimizer_Stage3：DeepSpeed Zero3。 | 否      |
 
 ```python
-TrainerMon.monitor_gnorm_with_ad(model, grad_acc_steps, optimizer, dp_group, tp_group) -> None
+TrainerMon.monitor_gnorm_with_ad(model, grad_acc_steps, optimizer, dp_group, tp_group, start_iteration) -> None
 ```
 | 参数  | 说明                  | 是否必选 |
 | ----- | -------------------- | -------- |
@@ -391,6 +459,7 @@ TrainerMon.monitor_gnorm_with_ad(model, grad_acc_steps, optimizer, dp_group, tp_
 | optimizer | 需要patch的优化器 | 否      |
 | dp_group | 数据并行的通信组。<br>dp域通信后，且没有使用分布式优化器时，group内所有rank的梯度相同，落盘数据冗余。<br>提供dp_group后，工具仅保留每个dp_group的第一个rank的梯度。 | 否      |
 | tp_group | 张量并行的通信组。<br/>tp域通信后，group内部分参数所有rank的梯度相同，落盘数据冗余。<br/>提供tp_group后，工具仅保留每个tp_group中冗余参数在第一个rank的梯度。<br/>当前适配Megatron core_v0.6.0, 通过权重属性"tensor_model_parallel"判断是否冗余。 | 否      |
+| start_iteration | 训练的起始iteration，影响工具计数 | 否      |
 
 
 ```python
@@ -401,6 +470,17 @@ TrainerMon.set_wrapped_optimizer(_wrapped_optimizer) -> None
 | ----- | -------------------- | -------- |
 | _wrapped_optimizer |megatron、deepspeed创建好的混合精度优化器。 | 是       |
 
+```python
+csv2tensorboard_by_step(monitor_path, time_start, time_end, process_num=1, data_type_list=None) -> None
+```
+| 参数  | 说明                  | 是否必选 |
+| ----- | -------------------- | -------- |
+| monitor_path | 待转换的csv存盘目录。 | 是       |
+| time_start | 起始时间戳。搭配time_end一起使用。指定一个时间范围，会对这个范围内的文件进行转换。左闭右闭的区间。 | 是      |
+| time_end | 结束时间戳。搭配time_start一起使用。指定一个时间范围，会对这个范围内的文件进行转换。左闭右闭的区间。 | 是      |
+| process_num | 指定拉起的进程个数，默认为1，更多的进程个数可以加速转换。 | 否      |
+| data_type_list | 指定需要转换的数据类型, 数据类型应来自输出件文件前缀，所有类型数据：<br/> ["actv", "actv_grad", "exp_avg", "exp_avg_sq", "grad_unreduced", "grad_reduced", "param"]。<br/>不指定就转换全部数据。 | 否      |
+
 ```python
 TrainerMon.generate_wgrad_metrics() -> tuple[dict[dict]]
 ```
@@ -410,6 +490,7 @@ TrainerMon.generate_xy_metrics() -> tuple[dict[dict]]
 ```
 
 
+
 ##  详细配置
 
 ```json
@@ -417,6 +498,10 @@ TrainerMon.generate_xy_metrics() -> tuple[dict[dict]]
     "targets": {  
         "language_model.encoder.layers.0": {"input": "tuple[2]:0", "output": "tensor", "input_grad":"tuple[2]:0", "output_grad":"tuple[1]:0"}  
     },
+    "switch": false,  
+	"start_step": 0,
+    "collect_times": 100000000,
+    "step_interval": 1,
     "print_struct": false,
     "module_ranks": [0,1,2,3],
     "ur_distribution": true,
@@ -436,7 +521,9 @@ TrainerMon.generate_xy_metrics() -> tuple[dict[dict]]
     "ops": ["min", "max", "norm", "zeros", "nans", "mean"],
     "eps": 1e-8,
     "ndigits": 12,
-    "step_count_per_record": 1
+    "step_count_per_record": 1,
+    "append_output": [],
+    "squash_name": true
 }  
 ```
 
@@ -444,25 +531,31 @@ TrainerMon.generate_xy_metrics() -> tuple[dict[dict]]
 
 | 字段名字                                                       | 是否必选    | 解释   |
 | ------------------------------------------------------------ | -------- | -------- |
-|"targets"| 必选 |指定需要监控的模型层， 例如transformer的第0层language_model.encoder.layers.0。如果不清楚模型结构， 可以将 "print_struct" 字段设置为 true， 监控工具会打印模型中torch module的名字和详细结构，并在第1个step后退出。|
+|"targets"| 可选 |指定需要监控的模型层和监控对象， 例如transformer的第0层language_model.encoder.layers.0，可选择监控input、output、input_grad、output_grad。如果不清楚模型结构， 可以将 "print_struct" 字段设置为 true， 监控工具会打印模型中torch module的名字和详细结构，并在第1个step后退出。未配置时默认为全量监控。|
 |"input"| 可选 |"tuple[2]:0"的意思是目标module的前向input参数为长度为2的tuple， 我们关心的是tuple第0个元素。|
 |"output"| 必选 |"tensor"的意思是目标module的前向output参数类型为tensor|
 |"input_grad"| 可选 |"tuple[2]:0"的意思是目标module的后向input_grad参数是长度为2的tuple， 我们关心的是tuple的第0个元素。|
 |"output_grad"| 必选 |"tuple[1]:0"的意思是目标module的后向input_grad参数是长度为1的tuple， 我们关心的是tuple的第0个元素。|
+|"switch"| 可选 | 在动态启停时使用，true代表打开监控，false代表关闭监控，默认值为false，且达到collect_times之后会自动将该值置为false待下次改true重启。|
+|"collect_times"| 可选 | 设置采集次数，达到该次数后停止监控，默认值为100000000，目的是一直采集。|
+|"start_step"| 可选 | 设置开始采集step，模型训练达到start_step后开始监控采集，默认值为0，表示从step0开始监控采集。|
+|"step_interval"| 可选 | 设置采集step间隔，默认值为1，表示每个step均采集监控数据。|
 |"print_struct"| 可选 |设置为true后监控工具会打印模型中torch module的名字和详细结构，并在第1个step后退出。不填默认为false。|
 |"module_ranks"| 可选 |用于在分布式训练场景中希望控制在哪些rank开启module监控。如果不填，则默认在所有rank开启。|
 |"ur_distribution"| 可选 |若为true则会统计adam优化器指定模块（targets中指定）参数的update和ratio向量的数值分布，并展示在heatmap里，默认为false，同时format字段必须设置为tensorboard。<br/>依赖histc算子， 需要CANN8.0.rc2以上版本， 否则会有严重的性能问题。 |
 |"xy_distribution"| 可选 |若为true则会监控指定module（targets中指定）的输入输出张量。 默认为false。|
-|"all_xy"| 可选 |开启xy_distribution后生效，若为true，监控所有module。默认为false。|
+|"all_xy"| 可选 |开启xy_distribution后生效，若为true，监控所有module。默认为false。<br/>与targets同时生效，all_xy配置为true时，若targets配置module_xx和指定对象，则module_xx按targets配置生效，其他module则监控全部对象，包含input、output、input_grad、output_grad。|
 |"forward_only"| 可选 |开启xy_distribution后生效，若为true，仅监控指定module的前向，targets中的input_grad、output_grad不生效。默认为false。|
 |"backward_only"| 可选 |开启xy_distribution后生效，若为true，仅监控指定module的反向，targets中的input、output不生效。默认为false。|
-|"mv_distribution"| 可选 |若为true则会监控指定模块中的参数的优化器状态， 默认为false。需要在TrainerMon构造函数正确指定opt_ty。 目前支持megatron和Deepspeed的分布式优化器。<br/>-Megatron_DistributedOptimizer：megatron分布式优化器；<br/>-Megatron_Float16OptimizerWithFloat16Params：megatron混合精度优化器；<br/>-DeepSpeedZeroOptimizer_Stage0：DeepSpeed Zero0<br/>-DeepSpeedZeroOptimizer_Stage1_or_2：DeepSpeed Zero1和Zero2；<br/>-DeepSpeedZeroOptimizer_Stage3：DeepSpeed Zero3。 |
+|"mv_distribution"| 可选 |若为true则会监控指定模块中的参数的优化器状态， 默认为false。需要在TrainerMon构造函数正确指定opt_ty。 目前支持megatron和Deepspeed的分布式优化器。<br/>-Megatron_DistributedOptimizer：megatron分布式优化器；<br/>-Megatron_Float16OptimizerWithFloat16Params：megatron混合精度优化器；<br/>-Megatron_ChainedDistributedOptimizer：megatron分布式优化器序列；<br/>-Megatron_ChainedFloat16OptimizerWithFloat16Params：megatron混合精度优化器序列；<br/>-DeepSpeedZeroOptimizer_Stage0：DeepSpeed Zero0<br/>-DeepSpeedZeroOptimizer_Stage1_or_2：DeepSpeed Zero1和Zero2；<br/>-DeepSpeedZeroOptimizer_Stage3：DeepSpeed Zero3。<br/>未使用megatron和deepspeed框架时，opt_ty默认为None，无需传入。 |
 |"wg_distribution"| 可选 |若为true则会监控指定模块的参数梯度， 默认为false。 |
 |"param_distribution"| 可选 |若为true则会监控指定模块的参数， 默认为false。 |
 |"alert"| 可选 | "rules": 指定自动报警的异常检测机制及其相应的阈值。目前实现的异常检测是AnomalyTurbulence， 如果统计标量超出历史均值的指定浮动范围（threshold 0.5意味着上浮或者下浮50%）则在控制台打印报警信息。当"dump"字段配置为true表示异常事件写入文件，默认为false。 |
 |"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的同步。|
 |"format"| 可选 | 数据落盘格式，默认为tensorboard，可选 \["tensorboard", "csv", "api"\]。 |
-|"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"| 可选 |类型为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"为"api"时，设置落盘文件中的小数位数，默认为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"]。默认为[]，不续写。 |
+|"squash_name"| 可选 | 是否简化参数名/模块名，多模态场景建议关闭，默认为True |

msprobe/docs/21.visualization_PyTorch.md

@@ -4,23 +4,29 @@
 
 工具支持PyTorch版本：2.1/2.2
 
+## 展示示例
+
+支持重建模型的层级结构；
+
+支持两个模型的结构差异比对；
+
+支持两个模型的精度数据比对，支持疑似有精度问题节点的快速搜索，自动跳转展开节点所在的层级。
+
+![vis_show](./img/visualization/vis_showcase.png)
+
 ## 1.依赖安装
 
 分级可视化工具依赖**msprobe工具**和**tensorboard。**
 
 ### 1.1 安装msprobe工具
 
-现阶段分级可视化工具还未集成在已发布的msprobe工具中，需要从源码安装，请参考从源码安装章节。
-
 [msprobe工具安装](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/docs/01.installation.md)
 
 ### 1.2 安装tb_graph_ascend
 
 **请安装tb_graph_ascend，否则无法解析构图结果。**
 
-[tb_graph_ascend下载](https://mindstudio-sample.obs.cn-north-4.myhuaweicloud.com/GRAPH_ASCEND/tb_graph_ascend-0.1.0-py3-none-any.whl)
-
-``pip3 install``即可。
+``pip3 install tb-graph-ascend``即可。
 
 ## 2.模型结构数据采集
 [PyTorch场景的数据采集](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/docs/05.data_dump_PyTorch.md)
@@ -37,19 +43,35 @@ msprobe -f pytorch graph -i ./compare.json -o ./output
 ```
 **命令行参数说明**：
 
-| 参数名                    | 说明                                                                                                                                                                           | 是否必选 |
-|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|
-| -i 或 --input_path      | 指定比对文件，str 类型。                                                                                                                                                               | 是    |
-| -o 或 --output_path     | 配置比对结果文件存盘目录，str 类型。文件名称基于时间戳自动生成，格式为：`compare_{timestamp}.vis`。                                                                                                             | 是    |
-| -lm 或 --layer_mapping  | 跨套件比对，例如同一个模型分别使用了DeepSpeed和Megatron套件的比对场景。配置该参数时表示开启跨套件Layer层的比对功能，指定模型代码中的Layer层后，可以识别对应dump数据中的模块或API。需要指定自定义映射文件*.yaml。自定义映射文件的格式请参见[自定义映射文件（Layer）](#71-自定义映射文件layer)。 | 否    |
-| -oc 或 --overflow_check | 是否开启溢出检测模式，开启后会在输出vis文件中（`compare_{timestamp}.vis`）对每个溢出节点进行标记溢出等级，溢出等级说明参考如下                                                                                                                         | 否    |
+| 参数名                    | 说明                                                                                                                                                                                                                                                                  | 是否必选 |
+|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|
+| -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)。 | 否    |
+| -oc 或 --overflow_check | 是否开启溢出检测模式，开启后会在输出vis文件中（`compare_{timestamp}.vis或build_{timestamp}.vis`）对每个溢出节点进行标记溢出等级，溢出等级说明参考[溢出等级说明](#312-溢出等级说明)                                                                                                                                              | 否    |
+| -f 或 --fuzzy_match     | 是否开启模糊匹配，bool类型。模糊匹配说明参考[匹配说明](#311-匹配说明)                                                                                                                                                                                                                           | 否    |
+| -cs 或 --complete_stack | 是否使用完整的堆栈信息，bool类型。默认使用精简的堆栈信息，数据量小有助于增加流畅度。完整堆栈和精简堆栈信息参考[堆栈信息说明](#72-堆栈信息说明)                                                                                                                                                                                       | 否    |
+
+#### 3.1.1 匹配说明
+
+**注：dump名称 = 名称 + 调用次数**，例如Torch.matmul.2.forward，matmul是名称，2是调用次数
+
+1.默认匹配
+- 所有节点dump名称一致
+- 节点输入输出参数数量一致，参数type、shape一致
+- 节点的层级一致（父节点们一致）
+
+2.模糊匹配
+- Module节点dump名称一致，两个匹配上的Module节点, 忽略各自节点下所有api的dump调用次数，按照名称一致+Module节点内的调用顺序进行匹配
+- ![fuzzy_match_pt.png](./img/visualization/fuzzy_match_pt.png)
+- 参数shape一致
 
-**溢出等级说明**
+#### 3.1.2 溢出等级说明
 - medium：输入异常，输出正常场景
 - high：输入异常，输出异常；输出norm值相较于输入存在异常增大情况
 - critical：输入正常，输出异常场景
 
-**比对文件说明**：
+#### 3.1.3 比对文件说明
 以在当前目录创建 ./compare.json 为例。
 ```
 {
@@ -282,31 +304,58 @@ msprobe -f pytorch graph -i ./compare.json -o ./output
 
 ## 4.启动tensorboard
 
+### 4.1 可直连的服务器
+
 将生成vis文件的路径**out_path**传入--logdir
 
 ```
 tensorboard --logdir out_path --bind_all --port [可选，端口号]
 ```
+启动后会打印日志:
+
+![tensorboard_1](./img/visualization/tensorboard_1.png)
+
+ubuntu是机器地址，6008是端口号。
 
-启动后会打印日志。
-``TensorBoard 2.15.1 at http://localhost.localdomain:6008/ (Press CTRL+C to quit)``
-localhost.localdomain是机器地址，6008是端口号。
+**注意，ubuntu需要替换为真实的服务器地址，例如真实的服务器地址为10.123.456.78，则需要在浏览器窗口输入http://10.123.456.78:6008**
 
-**如果链接打不开，可以尝试使用vscode连接服务器，在vscode终端输入：**
+### 4.2 不可直连的服务器
+**如果链接打不开（服务器无法直连需要挂vpn才能连接等场景），可以尝试使用vscode连接服务器，在vscode终端输入：**
 
 ```
 tensorboard --logdir out_path
 ```
+![tensorboard_2](./img/visualization/tensorboard_2.png)
 
-CTRL+C点击链接即可
+按住CTRL点击链接即可
 
 ## 5.浏览器查看
 
-推荐使用谷歌浏览器，在浏览器中输入机器地址+端口号回车，出现TensorBoard页面，右上方选择GRAPHS_ASCEND即可展示模型结构图。
+### 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)
+
+### 5.3 名称搜索
+![vis_search_info.png](./img/visualization/vis_search_info.png)
 
-节点需要双击打开。
+### 5.4 精度筛选
+![vis_precision_info.png](./img/visualization/vis_precision_info.png)
 
-键盘WS可放大缩小，AD可左右移动，鼠标滚轮可上下移动。
+### 5.5 未匹配节点筛选
+节点匹配规则：
+
+1.名称一致
+
+2.节点输入输出参数数量一致，参数type、shape一致
+
+3.节点的层级一致（父节点们一致）
+
+![vis_unmatch_info.png](./img/visualization/vis_unmatch_info.png)
 
 ## 6.图比对说明
 
@@ -326,20 +375,6 @@ CTRL+C点击链接即可
 
 ``相对误差：abs（(npu统计值 - bench统计值) / bench统计值)``
 
-其中小值不使用相对误差来判断精度差异，而是使用**绝对误差**来判断精度差异
-
-**判定为小值的阈值：**
-
-   - torch.float32：e-6
-   - torch.float16：e-3
-   - torch.bfloat16：e-3
-
-**小值域的绝对误差阈值：**
-
-   - torch.float32：e-6
-   - torch.float16：e-3
-   - torch.bfloat16：e-3
-
 #### md5模式
 节点中任意输入输出的md5值不同。
 
@@ -384,3 +419,48 @@ 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. 图比对场景，节点呈现灰色，且没有精度比对数据，怎么处理？
+
+节点呈现灰色，代表左边待调试侧节点与右边标杆侧节点没有匹配上，可能有以下几点原因：
+
+- **标杆侧确实没有能与待调试侧匹配上的节点**，属于代码实现上的差异，请确认此差异是否正常，是否会影响到整网精度。
+- **节点的输入或输出type、shape不一致，参数个数不一致，节点所在层级的父层级不一致**，导致节点无法匹配，具体匹配规则见[匹配说明](#311-匹配说明)，可尝试使用模糊匹配功能，如何使用此功能请参考[构图命令行说明](#31-构图命令行说明)。如果是参数shape不一致，即使是模糊匹配功能也无法让节点匹配上，请检查参数shape不一致是否合理。
+- **节点名称不一致**，导致节点无法匹配，可使用layer mapping功能，如何使用此功能请参考[构图命令行说明](#31-构图命令行说明)，如何自定义映射文件请参考[模型分级可视化如何配置layer mapping映射文件](./visualization/layer_mapping_example.md)。