mindstudio-probe 1.3.0__py3-none-any.whl → 8.1.1__py3-none-any.whl

msprobe/docs/19.monitor.md

@@ -10,7 +10,7 @@
 要求：
 
 - PyTorch场景：torch不低于**2.0**
-- MindSpore场景：mindspore不低于**2.4.10**，仅支持**MindSpore动态图**，暂不支持**msadapter**套件
+- MindSpore场景：mindspore不低于**2.4.10**，仅支持**MindSpore动态图**，已支持**msadapter**套件
 
 ## 功能介绍
 下表中字段为训练状态轻量化监控工具的完整功能点：
@@ -21,12 +21,12 @@
 | [权重梯度监控](#权重梯度监控)                                | 开启权重梯度监控                                             | PyTorch、MindSpore |
 | [激活值监控](#激活值监控)                                    | 开启激活值监控                                               | PyTorch、MindSpore |
 | [优化器状态监控](#优化器状态监控)                            | 开启优化器状态监控                                           | PyTorch、MindSpore |
+| [采集module堆栈信息](#采集module堆栈信息)                               | 采集监控的第一个 step 的 module 对应的堆栈信息辅助问题定位                              | PyTorch、MindSpore |
 | [指定监控对象](#指定监控对象)                                | 指定监控的nn.Module(nn.Cell)及对应的输入输出                 | PyTorch、MindSpore |
 | [打印模型结构](#打印模型结构)                                | 打印模型结构                                                 | PyTorch           |
-| [Module全量监控](#Module全量监控)                            | 对全量module的输入输出做监控                                 | PyTorch、MindSpore |
-| [Parameter全量监控](#Parameter全量监控)                      | 对全量Parameter的输入输出做监控                              | PyTorch、MindSpore |
-| [输出格式和统计量](#输出格式和统计量)                        | format PyTorch支持`csv`、`tensorboard`和`api`，MindSpore仅支持`csv`，`ops`均支持，`ndigits`仅PyTorch支持 | PyTorch、MindSpore |
-| [梯度异常时序判断](#梯度异常时序判断)                        | 梯度异常时自动梯度落盘                                       | PyTorch           |
+| [输出格式和统计量](#输出格式和统计量)                        | format PyTorch支持`csv`、`tensorboard`和`api`，MindSpore仅支持`csv`，`ops`、`ndigits`均支持 | PyTorch、MindSpore |
+| [mbs粒度梯度监控](#mbs粒度梯度监控)                    | 开启梯度监控时，采集聚合前梯度时支持`micro_batch_size`粒度                 | PyTorch、MindSpore |
+| [异常告警](#异常告警)                    | 监控对象指标异常时自动告警，支持异常数据落盘                  | PyTorch、MindSpore |
 | [csv格式数据转tensorboard可视化显示](#csv格式数据转tensorboard可视化显示) | 将csv转为tensorboard文件显示                                 | PyTorch           |
 | [动态启停](#动态启停)                                        | 训练过程中动态修改配置开启监控                               | PyTorch、MindSpore |
 | [功能重载](#功能重载)                                        | 训练中开启激活值监控。待废弃，请使用动态启停功能代替。           | PyTorch           |
@@ -205,12 +205,26 @@ monitor.monitor_gnorm_with_ad(
 
 本工具针对分布式计算框架megatron和deepspeed框架做了适配，暂不支持其他框架。
 
+### 采集module堆栈信息
+- 工具配置示例：
+```json
+{  
+    "targets": {
+    },
+    "format": "csv",
+    "stack_info": true
+}  
+```
+开启 `stack_info` 后会采集监控的第一个 step 的所有 module 的堆栈信息，输出格式仅支持 csv 。
 
 ## 高阶功能
 
+
 ### 指定监控对象
 
-工具支持对nn.Module（**激活值监控**）和nn.Parameter（**权重监控**、**权重梯度监控、优化器监控**）对象实现相应的监控行为，在配置文件的"targets"（dict）字段指定，targets格式为{module_name/param_name: {filed: format}}。
+工具支持对指定nn.Module进行状态监控，在配置文件的`targets`字段中指定，`targets`格式为{module_name: {}}。
+
+module_name可以通过nn.Module的接口named_modules()获取。
 
 #### 打印模型结构
 工具提供可选项`print_struct`打印模型结构，帮助配置targets。工具会在在第一个step后打印结构并停止训练进程，模型结构默认打印在`$MONITOR_OUTPUT_DIR/module_struct.json`。
@@ -221,7 +235,6 @@ monitor.monitor_gnorm_with_ad(
 ```
 
 输出样例:
-字段`config`用于配置文件中指定module target。其余为各个元素的shape和dtype。   
 
 ```json
 "0:63.mlp.linear_fc2": {
@@ -245,40 +258,30 @@ monitor.monitor_gnorm_with_ad(
     }
 },
 ```
+对于module对象，通常关心前向/反向传播的输入和输出：
 
-- Module
-  对于module对象，通常关心其前向的输入(input)输出(output)和反向的输入--前向输出的梯度(output_grad)和输出--前向输入的梯度（input_grad）。同时需要声明这些对象的类型，通常为"tensor"或"tuple\[length]"。
+- 前向的输入(input)
+- 前向的输出(output)
+- 反向的输入，表示前向输出的梯度(output_grad)
+- 反向的输出，表示前向输入的梯度(input_grad)
 
-  "tensor"可以直接用来计算统计量，"tuple"需要进一步指定监控的索引。如"tuple[2]:0",表示该对象为长度2的tuple，对第0元素进行监控；不指定索引时，默认对第0元素进行监控。
 
-  module_name可以通过nn.Module的接口`named_modules()`获取。  
-```json
-// 示例：对一个名为"module.encoder.layers.0.mlp"的module，监控其前向输入第0元素和输出。
-{
-    "targets": {
-        "module.encoder.layers.0.mlp": {
-            "input": "tuple[2]:0", 
-            "output": "tensor"
-        }
-    }
-}
-```
-#### Module全量监控
-工具提供简便的全量module监控方式。或不配置targets、all_xy字段，同样表示全量监控。
+#### 指定监控对象
+
+targets字段指定监控对象示例如下：
 
 ```json
-{
-    "targets": {},
-    "all_xy": true
+// 示例：对一个名为"module.encoder.layers.0.mlp"的module。
+"targets": {
+    "module.encoder.layers.0.mlp": {}
 }
 ```
 
+对于parameter对象，通常会关注其在一个训练迭代中的梯度（weight grad）、adam类优化器中的动量（1st moment, 2nd moment）。
+parameter归属于某一module，可以通过指定module_name来监控包含在这一module中的**所有**parameter。
 
-- Parameter
-  对于parameter对象，通常会关注其在一个训练迭代中的梯度（weight grad）、adam类优化器中的动量（1st moment, 2nd moment）。
-  parameter归属于某一module，也可以通过指定module_name来监控包含在这一module中的**所有**parameter。
+param_name可以通过nn.Module的接口`named_parameters()`获取。
 
-  param_name可以通过nn.Module的接口`named_parameters()`获取。
 ```json
 // 示例：监控"module.encoder.layers.0.mlp"的所有参数和"module.embedding.word_embedding.weight"这一参数
 {
@@ -289,8 +292,9 @@ monitor.monitor_gnorm_with_ad(
 }
 ```
 
-#### Parameter全量监控
-工具提供简便的全量parameter监控方式。或不配置targets，同样表示全量监控。
+#### 全量监控
+
+工具提供简便的全量module对象监控方式。
 
 ```json
 {
@@ -298,7 +302,9 @@ monitor.monitor_gnorm_with_ad(
 }
 ```
 
+
 ### 输出格式和统计量
+
 工具配置示例：
 ```json
 {
@@ -333,7 +339,7 @@ export MONITOR_OUTPUT_DIR=/xxx/output_dir
       监控结果写入csv文件中，可以通过`ndigits`字段设置小数位数。  
       表头为 vpp_stage | name | step | micro_step(optional) | *ops |。 
       仅在激活值监控的输出文件中包含micor_step。
-      激活值监控的name为<module_name>.\<input or output>, 其他任务的name为<param_name>>
+      激活值监控的name为<module_name>.\<input or output>, 其他任务的name为<param_name>
 
     - **api** 
       监控结果不落盘，在训练过程中可以通过`generate_wgrad_metrics`、`generate_xy_metrics`等接口获取，使用方式参考[公开接口](#公开接口) 。
@@ -349,16 +355,54 @@ export MONITOR_OUTPUT_DIR=/xxx/output_dir
 
   ![step_count_per_record](img/monitor/step_count_per_record.png)
 
-### 梯度异常时序判断
+### mbs粒度梯度监控
+
+当配置梯度监控任务时，工具默认`global_batch_size`粒度进行梯度监控。当需要监控`micro_batch_size`粒度梯度信息时，在配置文件中配置`monitor_mbs_grad`为`true`，配置示例如下：
+
+```json
+{
+    "wg_distribution": true,
+    "monitor_mbs_grad": true
+}
+```
+
+应用范围
+
+- **仅支持采集聚合前梯度**，在梯度累积场景下，聚合后梯度已无法区分`micro_batch`数据。
+- PyTorch场景下，Megatron和DeepSpeed训练框架下均支持，FSDP训练框架下暂不支持。
+- MindSpore场景下均支持。
+
+### 异常告警
+
+工具的异常告警功能旨在自动判断训练过程中的异常现象，用户可通过在配置文件中配置alert字段来指定告警规则，并在训练过程中根据该规则及时打屏对用户发出告警。
+
+
 1. 训练前配置相关参数
 
-工具支持自动判断训练过程中的梯度异常，需要在配置文件中设置alert相关字段。"AnomalyTurbulence"会将当前数值与历史均值比较，如果相对偏差超过阈值，会在打屏信息中提示用户。如果打开"`dump`"选项，则会将异常梯度相关信息落盘到目录`monitor_output/anomaly_detected`，用于后续时序判断。
+当前支持的异常告警规则如下：
+
+| 异常告警         |解释| rule_name | args是否可选                                                            |
+|--------------|----|-----------|---------------------------------------------------------------------|
+| 历史均值偏离告警    |将当前数值与历史均值比较。如果相对偏差超过阈值，会在打屏信息中提示用户指标偏离。当前仅对`norm`和`mean`指标生效。| AnomalyTurbulence | 否，必须传入threshold。当指标超过`(1+threshold)*avg`时，识别为偏离历史均值。 |
+| nan值/极大值告警   |根据是否提供threshold来判断nan值或极大值| AnomalyNan  | 是， 若未配置args或未配置threshold，则默认检测nan，若提供threshold，则检测nan值以及绝对值超过阈值的极大值 |
+
+除此之外，我们在alert中支持dump配置项，如果打开"`dump`"选项，则会将异常信息落盘到目录`monitor_output/anomaly_detected`。
+
+- 历史均值偏离告警案例如下：
 ```json
     "alert": {
-        "rules": [{"rule_name": "AnomalyTurbulence", "args": {"threshold": 0.5}}],
+        "rules": [{"rule_name": "AnomalyTurbulence", "args": {"threshold": 0.5}}],  // 0.5表示偏离50%则提示偏离
         "dump": true
     },
 ```
+- nan值/极大值告警案例如下：
+```json
+    "alert": {
+        "rules": [{"rule_name": "AnomalyNan", "args": {"threshold": 1e10}}],
+        "dump": true
+    },
+```
+
 2. 实例化工具时传入流水线并行group
 ```python
 monitor = TrainerMon(
@@ -395,9 +439,9 @@ python3 -m msprobe.pytorch.monitor.anomaly_analyse -d $MONITOR_OUTPUT_DIR/anomal
 ```
 异常事件分析结束，将topk事件写入文件`anomaly_detected/anomaly_analyse.json`。异常分析支持以下参数配置：
 
-| 字段名            | 解释                                                         | 是否必选 |
-| ----------------- | ------------------------------------------------------------ | -------- |
-| -d 或 --data_path | 指定梯度异常落盘文件夹，梯度监控功能输出，一般为$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范围，默认为[]。                               | 否       |
@@ -412,14 +456,14 @@ 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"]
+#     ["actv", "actv_grad", "exp_avg", "exp_avg_sq", "grad_unreduced", "grad_reduced", "param_origin", "param_updated"]
 # 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"]
+    data_type_list=["param_origin"]
 )
 ```
 
@@ -507,7 +551,7 @@ csv2tensorboard_by_step(monitor_path, time_start, time_end, process_num=1, data_
 | 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/>不指定就转换全部数据。 | 否       |
+| 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为自动获取的当前时间戳。 | 否       |
 - 在模型任意位置获取当前参数**梯度**统计量
 ```python
@@ -569,6 +613,7 @@ TrainerMon.monitor_gnorm_with_ad(model, grad_acc_steps, optimizer, dp_group, tp_
     "mv_distribution": true,
     "param_distribution": true,
     "wg_distribution": true,
+    "monitor_mbs_grad": true,
     "cc_distribution": {"enable":true, "cc_codeline":[]},
     "alert": {
         "rules": [{"rule_name": "AnomalyTurbulence", "args": {"threshold": 0.5}}],
@@ -606,6 +651,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。                                                                                                                                                                                                                                                                                                                       |
 | "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的同步。 |
@@ -613,7 +659,7 @@ 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。**仅PyTorch场景支持此参数**。                                                                                                                                                                                                                                                                                                                          |
+| "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                                                                                                                                                                                                                                                                                                                                                   |

msprobe/docs/21.visualization_PyTorch.md

@@ -57,14 +57,14 @@ msprobe -f pytorch graph -i ./compare.json -o ./output
 ```
 **命令行参数说明**：
 
-| 参数名                    | 说明                                                                                                                                                                                                                                                                  | 是否必选 |
-|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|
-| -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-堆栈信息说明)                                                                                                                                                                                       | 否    |
+| 参数名                    | 说明                                                                                                                                                                                                                                                                                                                                             | 是否必选 |
+|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|
+| -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-堆栈信息说明)                                                                                                                                                                                                                                                                  | 否    |
 
 #### 3.1.1 匹配说明
 
@@ -344,8 +344,22 @@ ubuntu是机器地址，6008是端口号。
 **注意，ubuntu需要替换为真实的服务器地址，例如真实的服务器地址为10.123.456.78，则需要在浏览器窗口输入http://10.123.456.78:6008**
 
 ### 4.2 不可直连的服务器
-**如果链接打不开（服务器无法直连需要挂vpn才能连接等场景），可以尝试使用vscode连接服务器，在vscode终端输入：**
+**如果链接打不开（服务器无法直连需要挂vpn才能连接等场景），可以尝试以下方法，选择其一即可：**
 
+1.本地电脑网络手动设置代理，例如Windows10系统，在【手动设置代理】中添加服务器地址（例如10.123.456.78）
+
+![proxy](./img/visualization/proxy.png)
+
+然后，在服务器中输入：
+```
+tensorboard --logdir out_path --bind_all --port 6008[可选，端口号]
+```
+
+最后，在浏览器窗口输入http://10.123.456.78:6008
+
+**注意，如果当前服务器开启了防火墙，则此方法无效，需要关闭防火墙，或者尝试后续方法**
+
+2.或者使用vscode连接服务器，在vscode终端输入：
 ```
 tensorboard --logdir out_path
 ```
@@ -353,6 +367,14 @@ tensorboard --logdir out_path
 
 按住CTRL点击链接即可
 
+3.或者将构图结果件vis文件从服务器传输至本地电脑，在本地电脑中安装tb_graph_ascend插件查看构图结果
+
+电脑终端输入：
+```
+tensorboard --logdir out_path
+```
+按住CTRL点击链接即可
+
 ## 5.浏览器查看
 
 ### 5.1 浏览器打开图
@@ -384,25 +406,56 @@ tensorboard --logdir out_path
 
 ## 6.图比对说明
 
-### 颜色
+### 6.1 颜色
 
 颜色越深，精度比对差异越大，越可疑，具体信息可见浏览器页面左下角颜色图例。
 
-### 疑似有精度问题判定
-
-#### 真实数据模式
+#### 6.1.1 真实数据模式
 节点中所有输入的最小双千指标和所有输出的最小双千分之一指标的差值，反映了双千指标的下降情况，**值越大精度差距越大，颜色标记越深**。
 
 ``One Thousandth Err Ratio（双千分之一）精度指标：Tensor中的元素逐个与对应的标杆数据对比，相对误差小于千分之一的比例占总元素个数的比例，比例越接近1越好``
 
-#### 统计信息模式
+如果调试侧（NPU）节点的output指标中的最大值（MAX）或最小值（MIN）中存在 nan/inf/-inf，直接标记为最深颜色。
+
+#### 6.1.2 统计信息模式
 节点中输出的统计量相对误差，**值越大精度差距越大，颜色标记越深**。
 
 ``相对误差：abs（(npu统计值 - bench统计值) / bench统计值)``
 
-#### md5模式
+如果调试侧（NPU）节点的output指标中的最大值（MAX）或最小值（MIN）中存在 nan/inf/-inf，直接标记为最深颜色。
+
+#### 6.1.3 md5模式
 节点中任意输入输出的md5值不同。
 
+### 6.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 值
+
 ## 7.附录
 ### 7.1 自定义映射文件（Layer）
 

msprobe/docs/22.visualization_MindSpore.md

@@ -2,7 +2,7 @@
 
 分级可视化工具将msprobe工具dump的精度数据进行解析，还原模型图结构，实现模型各个层级的精度数据比对，方便用户理解模型结构、分析精度问题。
 
-工具支持MindSpore版本：2.4.0
+工具支持MindSpore版本：>=2.4.0
 
 ## 更新通知
 
@@ -61,7 +61,7 @@ msprobe -f mindspore graph -i ./compare.json -o ./output
 |-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- |
 | -i 或 --input_path   | 指定比对文件，参考[比对文件说明](#313-比对文件说明)                                                                                                                                                                                                                        | 是       |
 | -o 或 --output_path  | 配置比对结果文件存盘目录，str 类型。文件名称基于时间戳自动生成，格式为：`compare_{timestamp}.vis或build_{timestamp}.vis`。                                                                                                                                                                | 是       |
-| -lm 或 --layer_mapping| 跨框架比对，MindSpore和PyTorch的比对场景。配置该参数时表示开启跨框架Layer层的比对功能，指定模型代码中的Layer层后，可以识别对应dump数据中的模块或API。需要指定自定义映射文件*.yaml。自定义映射文件的格式请参见[自定义映射文件（Layer）](#71-自定义映射文件layer), 如何配置自定义映射文件请参考[模型分级可视化如何配置layer mapping映射文件](./visualization/layer_mapping_example.md)。 | 否    |
+| -lm 或 --layer_mapping| 跨框架比对，MindSpore和PyTorch的比对场景。配置该参数时表示开启跨框架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-堆栈信息说明)                                                                                                                                                                         | 否    |
@@ -76,7 +76,7 @@ msprobe -f mindspore graph -i ./compare.json -o ./output
 - 节点的层级一致（父节点们一致）
 
 2.模糊匹配
-- Cell节点dump名称一致，两个匹配上的Cell节点, 忽略各自节点下所有api的dump调用次数，按照名称一致+Cell节点内的调用顺序进行匹配
+- Cell节点dump名称一致，两个匹配上的Cell节点，忽略各自节点下所有api的dump调用次数，按照名称一致+Cell节点内的调用顺序进行匹配
 - ![fuzzy_match_ms.png](./img/visualization/fuzzy_match_ms.png)
 - 参数shape一致
 
@@ -97,11 +97,11 @@ msprobe -f mindspore 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 类型。                                        | 否    |
+| 参数名               | 说明                                                                         | 是否必选 |
+|-------------------|----------------------------------------------------------------------------|------|
+| npu_path   | 指定待调试侧比对路径，str类型。工具根据路径格式自动进行单rank比对、多rank批量比对或多step批量比对，具体格式参考3.2 图构建和比对。 | 是    |
+| bench_path  | 指定标杆侧比对路径，str类型。单图构建场景可以不配置。                                               | 否    |
+| is_print_compare_log  | 配置是否开启单个算子的日志打屏。可取值 true 或 false，默认为 true。关闭后则只输出常规日志，bool 类型。             | 否    |
 
 
 ### 3.2 图构建和比对
@@ -328,7 +328,7 @@ dump配置请参考[dump配置示例](./03.config_examples.md#35-task-配置为-
 得到dump数据后，若需比较特定两个rank之间的数据，请参考[3.2.2 双图比对](#322-双图比对)；若需进行多个rank或多个step的数据批量比对，请参考[3.2.3 批量构建或比对](#323-批量构建或比对)。
 
 
-## 4.启动tensorboard
+## 4.启动TensorBoard
 
 ### 4.1 可直连的服务器
 
@@ -343,11 +343,25 @@ tensorboard --logdir out_path --bind_all --port [可选，端口号]
 
 ubuntu是机器地址，6008是端口号。
 
-**注意，ubuntu需要替换为真实的服务器地址，例如真实的服务器地址为10.123.456.78，则需要在浏览器窗口输入http://10.123.456.78:6008**
+**注意，ubuntu需要替换为真实的服务器地址，例如真实的服务器地址为10.123.456.78，则需要在浏览器窗口输入 http://10.123.456.78:6008**
 
 ### 4.2 不可直连的服务器
-**如果链接打不开（服务器无法直连需要挂vpn才能连接等场景），可以尝试使用vscode连接服务器，在vscode终端输入：**
+**如果链接打不开（服务器无法直连需要挂vpn才能连接等场景），可以尝试以下方法，选择其一即可：**
 
+1.本地电脑网络手动设置代理，例如Windows10系统，在【手动设置代理】中添加服务器地址（例如10.123.456.78）
+
+![proxy](./img/visualization/proxy.png)
+
+然后，在服务器中输入：
+```
+tensorboard --logdir out_path --bind_all --port 6008[可选，端口号]
+```
+
+最后，在浏览器窗口输入 http://10.123.456.78:6008
+
+**注意，如果当前服务器开启了防火墙，则此方法无效，需要关闭防火墙，或者尝试后续方法**
+
+2.或者使用vscode连接服务器，在vscode终端输入：
 ```
 tensorboard --logdir out_path
 ```
@@ -355,6 +369,14 @@ tensorboard --logdir out_path
 
 按住CTRL点击链接即可
 
+3.或者将构图结果件vis文件从服务器传输至本地电脑，在本地电脑中安装tb_graph_ascend插件查看构图结果
+
+电脑终端输入：
+```
+tensorboard --logdir out_path
+```
+按住CTRL点击链接即可
+
 ## 5.浏览器查看
 
 ### 5.1 浏览器打开图
@@ -386,25 +408,56 @@ tensorboard --logdir out_path
 
 ## 6.图比对说明
 
-### 颜色
+### 6.1 颜色
 
 颜色越深，精度比对差异越大，越可疑，具体信息可见浏览器页面左下角颜色图例。
 
-### 疑似有精度问题判定
-
-#### 真实数据模式
+#### 6.1.1 真实数据模式
 节点中所有输入的最小双千指标和所有输出的最小双千分之一指标的差值，反映了双千指标的下降情况，**值越大精度差距越大，颜色标记越深**。
 
 ``One Thousandth Err Ratio（双千分之一）精度指标：Tensor中的元素逐个与对应的标杆数据对比，相对误差小于千分之一的比例占总元素个数的比例，比例越接近1越好``
 
-#### 统计信息模式
+如果调试侧（NPU）节点的output指标中的最大值（MAX）或最小值（MIN）中存在 nan/inf/-inf，直接标记为最深颜色。
+
+#### 6.1.2 统计信息模式
 节点中输出的统计量相对误差，**值越大精度差距越大，颜色标记越深**。
 
-``相对误差：abs（(npu统计值 - bench统计值) / bench统计值)``
+``相对误差：abs((npu统计值 - bench统计值) / bench统计值)``
 
-#### md5模式
+如果调试侧（NPU）节点的output指标中的最大值（MAX）或最小值（MIN）中存在 nan/inf/-inf，直接标记为最深颜色。
+
+#### 6.1.3 md5模式
 节点中任意输入输出的md5值不同。
 
+### 6.2 指标说明
+
+精度比对从三个层面评估 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 值
+
 ## 7.附录
 ### 7.1 自定义映射文件（Layer）