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

msprobe/docs/19.monitor.md

@@ -4,67 +4,77 @@
 
 训练状态轻量化监控工具，能够在较低性能损耗下收集和记录模型训练过程中的激活值、权重梯度、优化器状态和通信算子的中间值，实时呈现训练状态。
 
-- [快速上手](#快速上手)
-    - [权重监控](#权重监控)
-    - [权重梯度监控](#权重梯度监控)
-    - [激活值监控](#激活值监控)
-    - [优化器状态监控](#优化器状态监控)
-- [详细配置](#详细配置)
-
 ## 安装
-参见[msprobe安装](./01.installation.md)
+参见[msprobe安装](./01.installation.md)。
+
+要求：
+
+- PyTorch场景：torch不低于**2.0**
+- MindSpore场景：mindspore不低于**2.4.10**，仅支持**MindSpore动态图**，暂不支持**msadapter**套件
+
+## 功能介绍
+下表中字段为训练状态轻量化监控工具的完整功能点：
+
+| 功能                                                         | 说明                                                         | 支持场景           |
+| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------ |
+| [权重监控](#权重监控)                                        | 开启权重监控                                                 | PyTorch、MindSpore |
+| [权重梯度监控](#权重梯度监控)                                | 开启权重梯度监控                                             | PyTorch、MindSpore |
+| [激活值监控](#激活值监控)                                    | 开启激活值监控                                               | PyTorch、MindSpore |
+| [优化器状态监控](#优化器状态监控)                            | 开启优化器状态监控                                           | 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            |
+| [csv格式数据转tensorboard可视化显示](#csv格式数据转tensorboard可视化显示) | 将csv转为tensorboard文件显示                                 | PyTorch            |
+| [动态启停](#动态启停)                                        | 训练过程中动态修改配置开启监控                               | PyTorch            |
+| [功能重载](#功能重载)                                        | 训练中开启激活值监控。待废弃，请使用动态启停功能代替。           | PyTorch            |
 
 ## 快速上手
 根据需求监控相应对象。比如在loss上扬，grad norm正常的异常训练过程中，优先考虑监控模型前向过程；在grad norm异常的训练过程中，监控权重和激活值的梯度。
 推荐使用方式：权重梯度的监控性能损耗小（20B dense模型全量权重梯度监控，时间增加<1%，内存增加<1%），可以长期开启。激活值监控性能损耗大，在必要时开启或者仅监控部分。  
 
 ### 工具使能
-在训练脚本中使能工具，在配置文件（json）中控制工具行为。
+在实际训练代码中找到模型、优化器定义的位置，使能monitor工具，通过配置文件（json）控制工具行为。如下分别为Pytorch场景和MindSpore场景下的使能方式。
+
+- Pytorch使能方式:
 ```python
-# megatorn中构建初始化模型和优化器。在实际训练代码中找到模型、优化器（optional）定义的位置
-# Megatron-LM(core_r0.6.0)  megatron/training.py, def pretrain:
+# Megatron-LM(core_r0.6.0)  training.py
 model, optimizer, opt_param_scheduler = setup_model_and_optimizer(
         model_provider, model_type) 
 
-# 使能工具
+...
 from msprobe.pytorch import TrainerMon
-# 监控工具初始化
 monitor = TrainerMon(
     config_file_path="./monitor_config.json",
-    process_group=None,
     params_have_main_grad=True,  # 权重是否使用main_grad，通常megatron为True，deepspeed为False。默认为True。
-    opt_ty=None  # 优化器类型，默认为None，具体取值参考公开接口
 ) 
-monitor.set_wrapped_optimizer(optimizer)
 # 挂载监控对象
-monitor.monitor_gnorm_with_ad(
+monitor.set_monitor(
     model,
     grad_acc_steps=args.global_batch_size//args.data_parallel_size//args.micro_batch_size,
-    optimizer=None,
+    optimizer=optimizer,
     dp_group=None,
-    tp_group=None) 
-
-
-# optional
-# 可以在任意位置获取当前的参数梯度统计量
-reduced, unreduced = monitor.generate_wgrad_metrics()
-# 可以在任意位置获取当前的激活值、激活值梯度统计量
-actv, actv_grad = monitor.generate_xy_metrics()
+    tp_group=None,
+    start_iteration=0  # 断点续训时提供当前iteration，默认从0开始
+) 
 ```
 
-补充deepspeed下常用框架的使能位置，提供参考
+*注意*：补充deepspeed下常用框架的使能位置。
+
+deepspeed与accelerate、transformers同时使用时，optimizer传值方式为`optimizer=optimizer.optimizer`，若未使用deepspeed，单独使用accelerate、transformers，optimizer传值方式为`optimizer=optimizer`。
 
-- accelerate
+1) 同时使用deepspeed和accelerate时，工具使能位置参考如下：
 
 ```python
 model, optimizer, trainloader, evalloader, schedular = accelerator.prepare(...)
-
+...
 monitor = TrainerMon(...)
-monitor.set_wrapped_optimizer(optimizer.optimizer)  # optimizer.optimizer为DeepSpeedZeroOptimizer
-monitor.monitor_gnorm_with_ad(....optimizer=optimizer.optimizer)
+monitor.set_monitor(....optimizer=optimizer.optimizer)
 ```
 
-- transformers
+2. 同时使用deepspeed和transformers时，工具使能位置参考如下：
 
 ```python
 # src/transformers/trainer.py
@@ -72,19 +82,107 @@ class Trainer:
     def _inner_training_loop:
         ...
         monitor = TrainerMon(...)
-        monitor.set_wrapped_optimizer(self.optimizer.optimizer)
-        monitor.monitor_gnorm_with_ad(....optimizer=self.optimizer.optimizer)
+        monitor.set_monitor(....optimizer=self.optimizer.optimizer)
 
         for epoch in range(epochs_trained, num_train_epochs):
             ...
 ```
 
+- MindSpore使能方式:
+```python
+...
+from msprobe.mindspore import TrainerMon
+monitor = TrainerMon(
+    config_file_path="./monitor_config.json",
+    process_group=None,
+    params_have_main_grad=True,  # 权重是否使用main_grad，通常megatron为True，deepspeed为False。默认为True。
+) 
+# 挂载监控对象
+monitor.set_monitor(
+    model,
+    grad_acc_steps=args.global_batch_size//args.data_parallel_size//args.micro_batch_size,
+    optimizer=optimizer,
+    dp_group=None,
+    tp_group=None
+) 
+```
+
+
+### 权重监控
+- 工具配置示例：
+```json
+{  
+    "targets": {
+    },
+    "param_distribution": true,
+    "format": "csv",
+    "ops": ["norm", "min", "max", "nans"]
+}  
+```
+`targets`中指定module包含的所有权重都会被监控。`targets`为空时，默认监控全部module。
+设置`param_distribution`为true，表示开启权重监控功能，默认值为false。
+
+### 权重梯度监控
+- 工具配置示例：
+```json
+{  
+    "targets": {
+    },
+    "wg_distribution": true,
+    "format": "csv",
+    "ops": ["norm", "min", "max", "nans"]
+}  
+```
+`targets`中指定module包含的所有权重都会被监控。`targets`为空时，默认监控全部module。
+设置`wg_distribution`(weight grad, noted as `wg`) 为true，表示开启权重梯度监控功能，默认值为false。
+
+### 激活值监控
+
+- 工具配置
+```json
+{  
+    "targets": {
+    },
+    "xy_distribution": true,
+    "forward_only": false,
+    "backward_only": false,
+    "all_xy": true,
+    "format": "csv",
+    "ops": ["norm", "min", "max", "nans"]
+}  
+```
+`all_xy`为true表示监控全量module激活值，若需要对指定模块设置监控对象，在`targets`中进行配置，配置方式参考 [指定监控对象](#指定监控对象) 。
+
+设置`xy_distribution`为true表示开启激活值监控功能，默认值为false。
+
+注意：`forward_only`和`backward_only`均为true时，触发warning，前反向均不采集；默认值均为false时，前反向均采集。
+
+
+### 优化器状态监控
+- 工具配置示例：
+```json
+{  
+    "targets": {
+    },
+    "mv_distribution": true,
+    "format": "csv",
+    "ops": ["norm", "min", "max", "nans"]
+}  
+```
+`targets`中指定module包含的所有权重都会被监控。`targets`为空时，默认监控全部module。
+设置`mv_distribution`为true表示开启优化监控功能（1st moment noted as `m`, 2nd moment noted as `v`），默认值为false。[什么是mv](https://arxiv.org/pdf/1412.6980)
+
+本工具针对分布式计算框架megatron和deepspeed框架做了适配，暂不支持其他框架。
+
+
+## 高阶功能
+
 ### 指定监控对象
 
-工具支持对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
@@ -92,7 +190,7 @@ class Trainer:
 ```
 
 输出样例:
-"config"字段用于配置文件中指定module target。其余为各个元素的shape和dtype。   
+字段`config`用于配置文件中指定module target。其余为各个元素的shape和dtype。   
 
 ```json
 "0:63.mlp.linear_fc2": {
@@ -134,7 +232,8 @@ class Trainer:
     }
 }
 ```
-**Module全量监控**：工具提供简便的全量module监控方式。
+#### Module全量监控
+工具提供简便的全量module监控方式。或不配置targets、all_xy字段，同样表示全量监控。
 
 ```json
 {
@@ -159,11 +258,12 @@ class Trainer:
 }
 ```
 
-**Parameter全量监控**：工具提供简便的全量parameter监控方式。
+#### Parameter全量监控
+工具提供简便的全量parameter监控方式。或不配置targets，同样表示全量监控。
 
 ```json
 {
-    "targets": {"":{}}
+    "targets": {}
 }
 ```
 
@@ -177,17 +277,19 @@ class Trainer:
 }
 ```
 
-- 输出路径 
-通过环境变量`MONITOR_OUTPUT_DIR`设置，默认为"monitor_output"。
+#### 输出路径 
+通过环境变量`MONITOR_OUTPUT_DIR`设置monitor输出路径，默认为`./monitor_output/`。
 ```shell
 export MONITOR_OUTPUT_DIR=/xxx/output_dir
 ```
 
 - 输出格式 
-  通过可选配置项`format`指定。可以是\["tensorboard"（缺省值）, "csv", "api"\]。
+  通过可选配置项`format`指定，当前支持`csv`， `tensorboard`， `api`。其中`csv`为默认缺省值。
 
-    - format: tensorboard 
-      监控结果写入tensorboard的event文件，启动tensorboard查看
+    - **tensorboard** 
+      监控结果写入tensorboard的event文件，启动tensorboard查看。  
+      激活值监控任务的tag为{vpp_stage}:{module_name}.{input or output}:{micro_step}/{rank}/{task}\_{ops}
+      其他监控任务的tag为{vpp_stage}:{param_name}/{rank}/{task}\_{ops} 
     ```shell
     tensorboard --logdir=$MONITOR_OUTPUT_DIR
     ```
@@ -196,73 +298,30 @@ export MONITOR_OUTPUT_DIR=/xxx/output_dir
     ssh -N -L localhost:6006:localhost:6006 your_username@remote_server_address
     ```
 
-    - format: csv 
-      监控结果写入csv文件中，可以通过`ndigits`字段设置小数位数.
+    - **csv**
+      监控结果写入csv文件中，可以通过`ndigits`字段设置小数位数。  
+      表头为 vpp_stage | name | step | micro_step(optional) | *ops |。 
+      仅在激活值监控的输出文件中包含micor_step。
+      激活值监控的name为<module_name>.\<input or output>, 其他任务的name为<param_name>>
 
-    - format: api 
-      监控结果不落盘，在训练过程中可以通过`generate_wgrad_metrics`、`generate_xy_metrics`等接口获取。
+    - **api** 
+      监控结果不落盘，在训练过程中可以通过`generate_wgrad_metrics`、`generate_xy_metrics`等接口获取，使用方式参考[公开接口](#公开接口) 。
 
 - 统计量 
-通过必选配置项"ops"指定。可以是["norm", "min", "max", "mean", "nans"，"zeros"]。其中"nans"统计tensor中nan的数量，"zeros"统计tensor中数值小于"eps"的比例。  
-
-### 权重监控
-- 工具配置示例：
-```json
-{  
-    "targets": {
-        "": {}
-    },
-    "param_distribution": true,
-    "format": "csv",
-    "ops": ["norm", "min", "max", "nans"]
-}  
-```
-"targets"中指定module包含的所有权重都会被监控。整个model的name为空字符串可以覆盖全量权重。
-设置"param_distribution"开启权重监控功能。
-
-使用deepspeed的zero优化器时，需要在工具中指定优化器类型并传入优化器，获取梯度切分行为已还原参数梯度。
-```python
-from msprobe.pytorch import TrainerMon
-# 以zero1优化器举例，opt_ty取值DeepSpeedZeroOptimizer_Stage1_or_2
-# 示例为deepspeed，params_have_main_grad取值False
-monitor = TrainerMon("./monitor_config.json", params_have_main_grad=False, opt_ty="DeepSpeedZeroOptimizer_Stage1_or_2")
-monitor.set_wrapped_optimizer(optimizer) # optimzier为训练框架自定义的优化器
-monitor.monitor_gnorm_with_ad(
-        model, grad_acc_steps=model.grad_acc_steps, optimizer=optimizer)
-```
-
+通过配置项`ops`指定。当前支持`norm`, `min`, `max`, `mean`, `nans`，`zeros`。其中`nans`监控tensor中`nan`的数量，`zeros`统计tensor中数值小于`eps`的比例。
 
-### 权重梯度监控
-- 工具配置示例：
-```json
-{  
-    "targets": {
-        "": {}
-    },
-    "wg_distribution": true,
-    "format": "csv",
-    "ops": ["norm", "min", "max", "nans"]
-}  
-```
-"targets"中指定module包含的所有权重都会被监控。整个model的name为空字符串可以覆盖全量梯度。
-设置"wg_distribution"(weight grad, noted as `wg`)开启梯度监控功能。
+- csv输出件合并
 
-使用deepspeed的zero优化器时，需要在工具中指定优化器类型并传入优化器，获取梯度切分行为已还原参数梯度。
-```python
-from msprobe.pytorch import TrainerMon
-# 以zero1优化器举例，opt_ty取值DeepSpeedZeroOptimizer_Stage1_or_2
-# 示例为deepspeed，params_have_main_grad取值False
-monitor = TrainerMon("./monitor_config.json", params_have_main_grad=False, opt_ty="DeepSpeedZeroOptimizer_Stage1_or_2")
-monitor.set_wrapped_optimizer(optimizer) # optimzier为训练框架自定义的优化器
-monitor.monitor_gnorm_with_ad(
-        model, grad_acc_steps=model.grad_acc_steps, optimizer=optimizer)
-```
+  提供csv输出件合并功能，在配置json文件中设置`step_count_per_record`，表示每个csv文件存储多个step的监控数据。默认值为1，表示每个csv文件记录一个step的监控数据。
+  
+  如下图所示为梯度监控结果示例，配置`step_count_per_record`为5，连续监控10个step，每个csv文件记录了5个step的梯度数据。其中`grad_reduced_0-4.csv`为step0至step4共计5个step的聚合后梯度数据，`grad_unreduced_0-4.csv`为step0至step4共计5个step的聚合前梯度数据。
 
+  ![step_count_per_record](img/monitor/step_count_per_record.png)
 
 ### 梯度异常时序判断
 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}}],
@@ -271,61 +330,93 @@ monitor.monitor_gnorm_with_ad(
 ```
 2. 实例化工具时传入流水线并行group
 ```python
-monitor = TrainerMon("./monitor_config.json", process_group=mpu.get_pipeline_model_parallel_group(), params_have_main_grad=True)
+monitor = TrainerMon(
+    "./monitor_config.json",
+    process_group=mpu.get_pipeline_model_parallel_group(),
+    params_have_main_grad=True  # 权重是否使用main_grad，通常megatron为True，deepspeed为False。默认为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范围，默认为[]。                               | 否       |
 
 
-### 激活值监控
+### csv格式数据转tensorboard可视化显示
 
-- 工具配置
-```json
-{  
-    "targets": {
-        "module.module.language_model.encoder.layers.0": {
-            "input": "tuple[2]", 
-            "output": "tensor"
-        }
-    },
-    "print_struct": false,
-    "xy_distribution": true,
-    "forward_only": true,
-    "backward_only": false,
-    "all_xy": true,
-    "format": "csv",
-    "ops": ["norm", "min", "max", "nans"]
-}  
-```
-设置"xy_distribution"为true表示开启激活值监控功能，"all_xy"为true表示监控全量module激活值。
+将csv数据转换为tensorboard格式数据。
 
-forward_only和backward_only均为true时，触发warning，前反向均不采集；均为false时，前反向均采集。
 ```python
-from msprobe.pytorch import TrainerMon
-# 以zero1优化器举例，opt_ty取值DeepSpeedZeroOptimizer_Stage1_or_2
-# 示例为deepspeed，params_have_main_grad取值False
-monitor = TrainerMon("./monitor_config.json", params_have_main_grad=False, opt_ty="DeepSpeedZeroOptimizer_Stage1_or_2")
-monitor.set_wrapped_optimizer(optimizer) # optimzier为训练框架自定义的优化器
-monitor.monitor_gnorm_with_ad(
-        model, grad_acc_steps=model.grad_acc_steps, optimizer=optimizer)
+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文件中的dynamic_on字段来使用。
+
+在动态启停模式下，启动和停止分别由如下控制：
+
+- 启动：
+  首次监控：config.json文件中dynamic_on字段为true，代表是否需要开启监控。
+  非首次监控：config文件时间戳更新且config.json文件中dynamic_on字段为true。
+- 停止：
+  到达collect_times之后自动停止并改config.json文件中dynamic_on字段为false，可再通过上述操作重启。
 
+大部分情况下，用户可在看到异常趋势后再手动更新config.json文件并打开dynamic_on开关；此外，使用时若想要在一开始就启动监控，可直接打开dynamic_on开关做基础配置的监测（首次不要求时间戳更新）
+
+注意事项：
+
+- 默认监控启动皆统一在配置初始化或查询到更新后的下一步，也就是若第n步挂上hook则第n+1步才启动采集，如需采集第0步数据请用静态模式。
+- config中途修改出错时，若此时不在监控就不生效，若在监控则用原配置继续。
+- 达到collect_times之后会自动将该值置为false待下次改true重启。
 
 ### 功能重载
+此功能将在2026年废弃。请使用[动态启停](#动态启停)功能代替。
+
 - 统计量
 可以在训练过程中修改`TrainerMon`实例的`ops`属性, 调整监控的统计量。
 ```python
@@ -340,76 +431,63 @@ if {some condition}:
     monitor.reload_xy(xy_distribution=True)
 ```
 
-### 优化器状态监控
-- 工具配置示例：
-```json
-{  
-    "targets": {
-        "module.encoder.layers.0": {},
-        "module.embedding.word_embedding.weight": {}
-    },
-    "mv_distribution": true,
-    "format": "csv",
-    "ops": ["norm", "min", "max", "nans"]
-}  
-```
-"targets"中指定module包含的所有权重都会被监控。
-设置"mv_distribution"表示开启优化监控功能（1st moment noted as `m`, 2nd moment noted as `v`）。[什么是mv](https://arxiv.org/pdf/1412.6980)
-
-本工具针对分布式计算框架megatron和deepspeed框架做了适配，暂不支持其他框架。
-
+## 公开接口
+- monitor工具初始化
 ```python
-from msprobe.pytorch import TrainerMon
-# 以zero1优化器举例，opt_ty取值DeepSpeedZeroOptimizer_Stage1_or_2
-# 示例为deepspeed，params_have_main_grad取值False
-monitor = TrainerMon("./monitor_config.json", params_have_main_grad=False, opt_ty="DeepSpeedZeroOptimizer_Stage1_or_2")
-monitor.set_wrapped_optimizer(optimizer) # optimzier为训练框架自定义的优化器
-monitor.monitor_gnorm_with_ad(
-        model, grad_acc_steps=model.grad_acc_steps, optimizer=optimizer)
+TrainerMon.__init__(config_file_path, process_group=None, params_have_main_grad=True) -> None
 ```
 
-## 公开接口
+| 参数                  | 说明                                                         | 是否必选 |
+| --------------------- | ------------------------------------------------------------ | -------- |
+| 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。 | 否       |
 
+- 模型挂载monitor工具
 ```python
-TrainerMon.__init__(config_file_path, process_group=None, params_have_main_grad=True, opt_ty=None) -> None
+TrainerMon.set_monitor(model, grad_acc_steps, optimizer, dp_group=None, tp_group=None, start_iteration=0) -> None
 ```
-
-| 参数  | 说明                  | 是否必选 |
-| ----- | -------------------- | -------- |
-| 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。 | 否      |
-
+| 参数            | 说明                                                         | 是否必选 |
+| --------------- | ------------------------------------------------------------ | -------- |
+| model           | 需要监控的模型，需要是一个torch.nn.Module或者mindspore.nn.Cell。 | 是       |
+| grad_acc_steps  | 梯度累积步数。                                               | 是       |
+| 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_r0.6.0, 通过权重属性"tensor_model_parallel"判断是否冗余。 | 否       |
+| start_iteration | 训练的起始iteration，影响工具计数。**仅PyTorch场景支持此参数**。 | 否       |
+
+- csv输出件转tensorboard输出件
 ```python
-TrainerMon.monitor_gnorm_with_ad(model, grad_acc_steps, optimizer, dp_group, tp_group) -> None
+csv2tensorboard_by_step(monitor_path, time_start, time_end, process_num=1, data_type_list=None) -> None
 ```
-| 参数  | 说明                  | 是否必选 |
-| ----- | -------------------- | -------- |
-| model |需要监控的模型，需要是一个torch.nn.Module。 | 是       |
-| grad_acc_steps | 梯度累积步数。 | 是      |
-| 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"判断是否冗余。 | 否      |
-
-
+| 参数           | 说明                                                         | 是否必选 |
+| -------------- | ------------------------------------------------------------ | -------- |
+| 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.set_wrapped_optimizer(_wrapped_optimizer) -> None
+TrainerMon.generate_wgrad_metrics() -> tuple[dict, dict]
 ```
-
-| 参数  | 说明                  | 是否必选 |
-| ----- | -------------------- | -------- |
-| _wrapped_optimizer |megatron、deepspeed创建好的混合精度优化器。 | 是       |
-
+具体使用方式如下：
 ```python
-TrainerMon.generate_wgrad_metrics() -> tuple[dict[dict]]
+reduced, unreduced = monitor.generate_wgrad_metrics()
 ```
 
+- 在模型任意位置获取当前参数**激活值**统计量
 ```python
-TrainerMon.generate_xy_metrics() -> tuple[dict[dict]]
+TrainerMon.generate_xy_metrics() -> tuple[dict, dict]
+```
+具体使用方式如下：
+```python 
+actv, actv_grad = monitor.generate_xy_metrics()
 ```
 
 
+
 ##  详细配置
 
 ```json
@@ -417,6 +495,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"}  
     },
+    "dynamic_on": false,  
+    "start_step": 0,
+    "collect_times": 100000000,
+    "step_interval": 1,
     "print_struct": false,
     "module_ranks": [0,1,2,3],
     "ur_distribution": true,
@@ -432,37 +514,45 @@ TrainerMon.generate_xy_metrics() -> tuple[dict[dict]]
         "rules": [{"rule_name": "AnomalyTurbulence", "args": {"threshold": 0.5}}],
         "dump": false
     },
-    "format": "tensorboard",
+    "format": "csv",
     "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
 }  
 ```
 
 下面详细解释各个字段：
 
-| 字段名字                                                       | 是否必选    | 解释   |
-| ------------------------------------------------------------ | -------- | -------- |
-|"targets"| 必选 |指定需要监控的模型层， 例如transformer的第0层language_model.encoder.layers.0。如果不清楚模型结构， 可以将 "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个元素。|
-|"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。|
-|"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。 |
-|"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的数量。|
-|"eps"|  可选 |若ops里包含"zeros"则需要配置，默认为1e-8。|
-|"ndigits"| 可选 |"format"为"api"时，设置落盘文件中的小数位数，默认为6。|
-|"step_count_per_record"| 可选 | "format"为"csv"时生效，每个csv记录多少个step的数据，默认为1。|
+| 字段名字                | 是否必选 | 解释                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ----------------------- | -------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| "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个元素。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| "dynamic_on"            | 可选     | 在动态启停时使用，true代表打开监控，false代表关闭监控，默认值为false，且达到collect_times之后会自动将该值置为false待下次改true重启。**仅PyTorch场景支持此参数**。                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| "collect_times"         | 可选     | 设置采集次数，达到该次数后停止监控，默认值为100000000，目的是一直采集。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| "start_step"            | 可选     | 设置开始采集step，模型训练达到start_step后开始监控采集，默认值为0，表示从step0开始监控采集。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| "step_interval"         | 可选     | 设置采集step间隔，默认值为1，表示每个step均采集监控数据。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| "print_struct"          | 可选     | 设置为true后监控工具会打印模型中torch module的名字和详细结构，并在第1个step后退出。不填默认为false。**仅PyTorch场景支持此参数**。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| "module_ranks"          | 可选     | 用于在分布式训练场景中希望控制在哪些rank开启module监控。如果不填，则默认在所有rank开启。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| "ur_distribution"       | 可选     | 若为true则会统计adam优化器指定模块（targets中指定）参数的update和ratio向量的数值分布，并展示在heatmap里，默认为false，同时format字段必须设置为tensorboard。<br/>依赖histc算子， 需要CANN8.0.rc2以上版本， 否则会有严重的性能问题。**仅PyTorch场景支持此参数**。                                                                                                                                                                                                                                                                                                                                                                                                    |
+| "xy_distribution"       | 可选     | 若为true则会监控指定module（targets中指定）的输入输出张量。 默认为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/>-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。**仅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的同步。**仅PyTorch场景支持此参数**。                                                                                                                                                                                      |
+| "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场景支持此参数**。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| "step_count_per_record" | 可选     | "format"为"csv"时生效，每个csv记录多少个step的数据，默认为1。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| "append_output"         | 可选     | 适用于断点续训场景。多卡场景下生效，指定两个时间戳，将输出续写到这两个时间戳范围间的输出件中，不在范围内的rank不被续写。时间戳应来自原有输出件目录前缀，例如["Dec03_21-34-40", "Dec03_21-34-41"]。默认为[]，不续写。**仅PyTorch场景支持此参数**。                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| "squash_name"           | 可选     | 是否简化参数名/模块名，多模态场景建议关闭，默认为True                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |