Monitor训练状态轻量化监测工具
简介
Monitor训练状态轻量化监测工具，能够在较低性能损耗下收集和记录模型训练过程中的激活值、权重梯度、优化器状态和通信算子的中间值，实时呈现训练状态。
使用前准备
安装
安装msProbe工具，详情请参见《msProbe安装指南》。
约束
- PyTorch场景：torch不低于2.1
- MindSpore场景：mindspore不低于2.4.10，仅支持MindSpore动态图，支持MSAdapter套件
快速入门
根据需求监测相应对象。比如在loss上扬，grad norm正常的异常训练过程中，优先考虑监测模型前向过程；在grad norm异常的训练过程中，监测权重和激活值的梯度。 推荐使用方式：权重梯度的监测性能损耗小（20B dense模型全量权重梯度监测，时间增加<1%，内存增加<1%），可以长期开启。激活值监测性能损耗大，在必要时开启或者仅监测部分。
配置文件准备
请在当前目录下创建一个config.json文件（配置文件各个字段具体信息请查看详细配置），此处以最常见的权重梯度采集为例：
{
"targets": {},
"wg_distribution": true,
"format": "csv",
"ops": ["min","max", "mean", "norm"],
"ndigits": 16
}
工具使能
在实际训练代码中找到模型、优化器定义完成后、训练开始前的位置，加入工具使能代码，不同场景使能方式如下：
- Pytorch使能方式:
# Megatron-LM(core_r0.6.0) training.py
model, optimizer, opt_param_scheduler = setup_model_and_optimizer(model_provider, model_type)
...
# 紧跟着model、optimizer定义完成后即插入monitor工具
+from msprobe.pytorch import TrainerMon
+monitor = TrainerMon(
+ config_file_path="./monitor_config.json",
+ params_have_main_grad=True, # 权重是否使用main_grad，通常megatron类为True，其他为False，默认为True。
+)
+monitor.set_monitor(
+ model,
+ grad_acc_steps=args.global_batch_size//args.data_parallel_size//args.micro_batch_size,
+ optimizer=optimizer
+)
deepspeed与accelerate、transformers同时使用时，optimizer传值方式为optimizer=optimizer.optimizer，若未使用deepspeed，单独使用accelerate、transformers，optimizer传值方式为optimizer=optimizer。
同时使用deepspeed和accelerate时，工具使能位置参考如下：
model, optimizer, trainloader, evalloader, schedular = accelerator.prepare(...)
...
+monitor = TrainerMon(...)
+monitor.set_monitor(....optimizer=optimizer.optimizer)
同时使用deepspeed和transformers时，工具使能位置参考如下：
# src/transformers/trainer.py
class Trainer:
def _inner_training_loop:
...
+ monitor = TrainerMon(...)
+ monitor.set_monitor(....optimizer=self.optimizer.optimizer)
for epoch in range(epochs_trained, num_train_epochs):
...
- MindSpore使能方式:
# Megatron-LM(core_r0.6.0) training.py
model, optimizer, opt_param_scheduler = setup_model_and_optimizer(model_provider, model_type)
...
# 紧跟着model、optimizer定义完成后即插入monitor工具
+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，其他为False，默认为True。
+)
# 挂载监测对象
+monitor.set_monitor(
+ model,
+ grad_acc_steps=args.global_batch_size//args.data_parallel_size//args.micro_batch_size,
+ optimizer=optimizer
+)
注意事项
若框架为FSDP1，请先保证model包裹FSDP时设置use_orig_params=True。
训练状态监测工具功能介绍
下表中字段为训练状态轻量化监测工具的完整功能点：
| 功能 | 说明 | 支持场景 |
|---|---|---|
| 权重监测 | 开启权重监测 | PyTorch、MindSpore |
| 权重梯度监测 | 开启权重梯度监测 | PyTorch、MindSpore |
| 激活值监测 | 开启激活值监测 | PyTorch、MindSpore |
| 优化器状态监测 | 开启优化器状态监测 | PyTorch、MindSpore |
| 采集module堆栈信息 | 采集监测的第一个 step 的 module 对应的堆栈信息辅助问题定位 | PyTorch、MindSpore |
| 指定监测对象 | 指定监测的nn.Module(nn.Cell)及对应的输入输出 | PyTorch、MindSpore |
| 打印模型结构 | 打印模型结构 | PyTorch |
| l2可解释特征监测 | 开启模型状态的高阶监测 | PyTorch、MindSpore |
| mbs粒度梯度监测 | 开启梯度监测时，采集聚合前梯度时支持micro_batch_size粒度 |
PyTorch、MindSpore |
| 异常告警 | 监测对象指标异常时自动告警，支持异常数据落盘 | PyTorch、MindSpore |
| csv格式数据转tensorboard可视化显示 | 将csv转为tensorboard文件显示 | PyTorch |
| 动态启停 | 训练过程中动态修改配置开启监测 | PyTorch、MindSpore |
| 功能重载 | 训练中开启激活值监测。待废弃，请使用动态启停功能代替。 | PyTorch |
权重监测
- 该功能可开启权重监测，工具配置示例：
{
"targets": {
},
"param_distribution": true,
"format": "csv",
"ops": ["norm", "min", "max", "nans"]
}
targets中指定module包含的所有权重都会被监测。targets为空时，默认监测全部module。
设置param_distribution为true，表示开启权重监测功能，默认值为false。
权重梯度监测
- 该功能可开启权重梯度监测，监测聚合前后的权重梯度，工具配置示例：
{
"targets": {
},
"wg_distribution": true,
"format": "csv",
"ops": ["norm", "min", "max", "nans"]
}
targets中指定module包含的所有权重都会被监测。targets为空时，默认监测全部module。
设置wg_distribution(weight grad, noted as wg) 为true，表示开启权重梯度监测功能，默认值为false。
激活值监测
- 该功能可开启激活值监测，工具配置示例：
{
"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时，前反向均采集。
优化器状态监测
- 该功能可开启优化器状态监测，工具配置示例：
{
"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
本工具针对分布式计算框架megatron和deepspeed框架做了适配，暂不支持其他框架。
采集module堆栈信息
- 该功能可采集module堆栈详细信息，工具配置示例：
{
"targets": {
},
"format": "csv",
"stack_info": true
}
开启 stack_info 后会采集监测的第一个 step 的所有 module 的堆栈信息，输出格式仅支持 csv 。
指定监测对象
工具支持对指定nn.Module进行状态监测，在配置文件的targets字段中指定，targets格式为{module_name: {}}。
module_name可以通过nn.Module的接口named_modules()获取。
打印模型结构
工具提供可选项print_struct打印模型结构，帮助配置targets。工具会在在第一个step后打印结构并停止训练进程，每张卡上的模型结构默认保存在$MONITOR_OUTPUT_DIR/module_struct/rank{rank}/module_struct.json, 其中{rank}为对应的卡号。
{
"print_struct": true
}
输出样例:
"0:63.mlp.linear_fc2": {
"input": {
"config": "tuple[1]",
"0": "size=(4096, 4, 1024), dtype=torch.bfloat16"
},
"output": {
"config": "tuple[2]",
"0": "size=(2048, 4, 512), dtype=torch.bfloat16",
"1": "size=(512,), dtype=torch.bfloat16"
},
"input_grad": {
"config": "tuple[1]",
"0": "size=(4096, 4, 1024), dtype=torch.bfloat16"
},
"output_grad": {
"config": "tuple[2]",
"0": "size=(2048, 4, 512), dtype=torch.bfloat16",
"1": "size=(512,), dtype=torch.bfloat16"
}
},
对于module对象，通常关心前向/反向传播的输入和输出：
- 前向的输入(input)
- 前向的输出(output)
- 反向的输入，表示前向输出的梯度(output_grad)
- 反向的输出，表示前向输入的梯度(input_grad)
指定监测对象
targets字段指定监测对象示例如下：
// 示例：对一个名为"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。
param_name可以通过nn.Module的接口named_parameters()获取。
// 示例：监测"module.encoder.layers.0.mlp"的所有参数和"module.embedding.word_embedding.weight"这一参数
{
"targets": {
"module.encoder.layers.0.mlp": {},
"module.embedding.word_embedding.weight": {}
}
}
全量监测
工具提供简便的全量module对象监测方式。
{
"targets": {}
}
l2可解释特征监测
- 该功能可开启模型状态的高阶监测，工具配置示例：
{
"l2_targets": {
"attention_hook": ["0:0.self_attention.core_attention.flash_attention"],
"linear_hook": ["0:0.self_attention.linear_qkv", "0:1.self_attention.linear_qkv"]
},
"recording_l2_features": true,
"sa_order": "b,s,h,d"
}
| 配置项 | 可选/必选 | 类型 | 说明 |
|---|---|---|---|
| l2_targets | 必选 | Dict[str, List[str]] | 指定需要监测的模型层配置 支持的hook类型： • attention_hook：监测注意力层▪️ 采集指标： entropy softmax_max▪️ 必须通过打印模型结构获取准确层名 ▪️ 不配置或配置空列表均表示不采集 • linear_hook：监测线性层▪️ 采集指标： sr, kernel_norm▪️ 必须通过打印模型结构获取准确层名, 不配置表示不采集 ▪️ 配置空列表会自动识别符合条件的层（包含 weight或wg2D参数属性的层） |
| recording_l2_features | 可选 | bool | 是否开启L2层特征数据采集，默认为false表示不采集 |
| sa_order | 可选 | str | 计算attention_hook内指标时，指定Attention输入(Q，K)的张量维度排列顺序，支持"s,b,h,d"和"b,s,h,d", 默认为"s,b,h,d"表示输入维度顺序为sequence_len->batch_size->num_heads->head_dim |
L2可解释特征监测指标说明
| 指标名称 | 适用Hook类型 | 数学定义/计算方式 | 监测意义 |
|---|---|---|---|
| entropy | attention_hook | H(p)=−∑pilogpiH(p)=-\sum p_i \log p_i，其中pip_i为注意力权重 | 衡量注意力分布的不确定性，低熵值表示注意力集中 |
| softmax_max | attention_hook | max(softmax(QKT/d))\max(\text{softmax}(QK^T/\sqrt{d})) | 反映注意力机制的聚焦程度，高值表示存在显著主导的注意力token |
| sr(stable_rank) | linear_hook | ∣W∣F∣W∣2\frac{|W|_F}{|W|_2}（稳定秩，Frobenius范数除以谱范数） | 评估权重矩阵的有效秩，低值表示矩阵接近低秩不稳定状态 |
| kernel_norm | linear_hook | ∣W∣F|W|_F（Frobenius范数） | 权重矩阵的缩谱范数，反映输入在矩阵最大奇异向量张成空间的放大系数 |
mbs粒度梯度监测
当配置梯度监测任务时，工具默认global_batch_size粒度进行梯度监测。当需要监测micro_batch_size粒度梯度信息时，在配置文件中配置monitor_mbs_grad为true，配置示例如下：
{
"wg_distribution": true,
"monitor_mbs_grad": true
}
应用范围
- 仅支持采集聚合前梯度，在梯度累积场景下，聚合后梯度已无法区分
micro_batch数据。 - PyTorch场景下，Megatron和DeepSpeed训练框架下均支持，FSDP训练框架下暂不支持。
- MindSpore场景下均支持。
异常告警
工具的异常告警功能旨在自动判断训练过程中的异常现象，用户可通过在配置文件中配置alert字段来指定告警规则，并在训练过程中根据该规则及时打印告警信息。
异常告警规则
当前支持的异常告警规则如下：
| 异常告警 | 解释 | 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。
- 历史均值偏离告警案例如下：
"alert": {
"rules": [{"rule_name": "AnomalyTurbulence", "args": {"threshold": 0.5}}], // 0.5表示偏离50%则提示偏离
"dump": true
},
- nan值/极大值告警案例如下：
"alert": {
"rules": [{"rule_name": "AnomalyNan", "args": {"threshold": 1e10}}],
"dump": true
},
注：当配置多条异常告警规则时，优先告警第一条，如以下配置时每一层会优先报AnomalyNan的告警（一般不建议配置多条规则）：
"alert": {
"rules": [
{"rule_name": "AnomalyNan", "args": {"threshold": 1e10}},
{"rule_name": "AnomalyTurbulence", "args": {"threshold": 0.5}}
],
"dump": true
},
异常提示说明
训练过程中，检测到异常后打印提示信息，并将异常信息按照rank分组写入json文件，文件路径默认为monitor_output/anomaly_detected，异常信息示例如下：
{
"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]
},
...
}
其中call_{xxx}中的xxx为API的执行调用顺序，为后续异常事件排序做准备。
异常事件排序
当模型训练过程中出现较多异常数据，需要对异常事件排序。工具提供topk的异常排序能力，按照api的执行顺序进行排序，便于定界首次异常点。异常分析命令示例：
python3 -m msprobe.core.monitor.anomaly_processor -d $MONITOR_OUTPUT_DIR/anomaly_detected
异常事件分析结束，将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可视化显示
将csv数据转换为tensorboard格式数据。
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_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_origin"]
)
参数详细介绍请参见公开接口的“csv输出件转tensorboard输出件”
动态启停
动态启停模式：支持用户在训练过程中随时启动/更新监测。
用户可在训练开始前通过配置环境变量DYNAMIC_MONITOR=True来确认进入动态启停模式，该模式下需要配合config.json文件中的dynamic_on字段来使用。
在动态启停模式下，启动和停止分别由如下控制：
- 启动：
- 首次监测：查看config.json文件中
dynamic_on字段，若为true则在下一步开启监测。 - 非首次监测：查看config.json文件时间戳，若时间戳更新且config.json文件中
dynamic_on字段为true则在下一步开启监测。
- 首次监测：查看config.json文件中
- 停止：
到达
collect_times之后自动停止并修改config.json文件中dynamic_on字段为false，可再通过上述操作重启。
注意事项：：
- 默认监测启动皆统一在配置初始化或查询到更新后的下一步，即第n步挂载hook将在第n+1步启动采集，如需采集第0步数据请使用静态模式。
- config.json中途修改错误时，若此时不在监测则不生效，若在监测则用原配置继续。
- 达到
collect_times之后程序会自动将该值置为false，待下次修改为true时重启。
支持的使用场景说明如下：
| 场景 | 监测模式 | 操作步骤 | 结果描述 |
|---|---|---|---|
| 场景1: 使用默认静态模式 | 静态 | 1. 配置环境变量：export DYNAMIC_MONITOR=False 或不设置该环境变量 |
走默认分支进行数据采集和保存，不受config.json中dynamic_on影响 |
| 场景2: 进入动态启停模式，初始不启动监测 | 动态 | 1.配置环境变量：export DYNAMIC_MONITOR=True 2.配置config.json中 dynamic_on: false或不设置该字段 |
初始状态下无监测，不进行数据采集和保存 |
| 场景3: 进入动态启停模式，初始即启动监测 | 动态 | 1.配置环境变量：export DYNAMIC_MONITOR=True 2.配置config.json中 dynamic_on: true |
根据初始配置在第1步（初始计数为0）开启监测并保存，采集collect_times次数后结束监测 |
| 场景4: 进入动态启停模式，初始暂不启动监测，训练中途启动 | 动态 | 1.配置环境变量：export DYNAMIC_MONITOR=True 2.开始时配置config.json中 dynamic_on: false或不设置该字段3.训练中途修改config.json中 dynamic_on: true |
训练中途根据最新配置在下一步开启监测并保存，采集collect_times次数后结束监测 |
| 场景5: 进入动态启停模式，监测还未结束时中途修改config.json采集配置 | 动态 | 1.配置环境变量：export DYNAMIC_MONITOR=True 2.期间配置 dynamic_on: true启动采集3.在采集还未达到 collect_times次数前，中途修改config.json配置 |
更新前按旧配置采集并保存，更新后下一步以最新config.json采集且collect_times重新从0开始计数。此功能可配合中途collect_times改0来实现提前停止监测。 |
场景6: 进入动态启停模式，在根据collect_times结束监测后，需重新启动监测 |
动态 | 1.配置环境变量：export DYNAMIC_MONITOR=True 2.期间 dynamic_on: true启动采集3.采集达到 collect_times次数后结束监测，程序自动改dynamic_on:false4.配置config.json中 dynamic_on:true重启监测 |
更新前按旧配置采集并保存，中途停止监测后无采集，重启后下一步以最新config.json重启采集且collect_times重新从0开始计数。 |
功能重载
此功能将在2026年废弃。请使用动态启停功能代替。
- 统计量
可以在训练过程中修改
TrainerMon实例的ops属性, 调整监测的统计量。
if {some condition}:
monitor.ops = ["min", "max"]
- 训练过程中开关激活值监测 激活值监测的性能损耗较大, 推荐仅在必要时开启, 比如发现loss出现尖刺, 根据loss的异常开启激活值监测.
if {some condition}:
monitor.reload_xy(xy_distribution=True)
输出结果
输出路径
通过环境变量MONITOR_OUTPUT_DIR设置monitor输出路径，默认为./monitor_output/。
export MONITOR_OUTPUT_DIR=/xxx/output_dir
输出格式
通过可选配置项format指定，当前仅支持csv（默认值）。
- csv
监测结果写入csv文件中，可以通过
ndigits字段设置小数位数。
表头为 vpp_stage | name | step | micro_step(optional) | *ops |。 仅在激活值监测的输出文件中包含micro_step。 激活值监测的name为<module_name>.<input or output>, 其他任务的name为<param_name>。
如需将csv转为tensorboard格式进行可视化，可使用csv格式数据转tensorboard可视化显示功能。
csv输出件合并
提供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的聚合前梯度数据。
公开接口
- monitor工具初始化
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。 |
| opt_ty（该参数废弃） | 可选 | 表示优化器类型。 |
- 模型挂载monitor工具
TrainerMon.set_monitor(model, grad_acc_steps, optimizer, dp_group=None, tp_group=None, start_iteration=0) -> None
| 参数 | 可选/必选 | 说明 |
|---|---|---|
| model | 必选 | 需要监测的模型，需要是一个torch.nn.Module或者mindspore.nn.Cell。 |
| grad_acc_steps | 必选 | 梯度累积步数。 |
| optimizer | 必选 | 需要patch的优化器。 |
| dp_group | 可选 | 数据并行的通信组。 dp域通信后，且没有使用分布式优化器时，group内所有rank的梯度相同，落盘数据冗余。 提供dp_group后，工具仅保留每个dp_group的第一个rank的梯度。 |
| tp_group | 可选 | 张量并行的通信组。 tp域通信后，group内部分参数所有rank的梯度相同，落盘数据冗余。 提供tp_group后，工具仅保留每个tp_group中冗余参数在第一个rank的梯度。 当前适配Megatron core_r0.6.0, 通过权重属性"tensor_model_parallel"判断是否冗余。 |
| start_iteration | 可选 | 训练的起始iteration，影响工具计数。仅PyTorch场景支持此参数。 |
- csv输出件转tensorboard输出件
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 | 可选 | 指定需要转换的数据类型, 数据类型应来自输出件文件前缀，所有类型数据： ["actv", "actv_grad", "exp_avg", "exp_avg_sq", "grad_unreduced", "grad_reduced", "param_origin", "param_updated"]。 不指定就转换全部数据。 |
| output_dirpath | 可选 | 指定转换后的输出路径，默认输出到"{curtime}_csv2tensorboard_by_step"文件夹，其中curtime为自动获取的当前时间戳。 |
- 在模型任意位置获取当前参数梯度统计量
TrainerMon.generate_wgrad_metrics() -> tuple[dict, dict]
具体使用方式如下：
reduced, unreduced = monitor.generate_wgrad_metrics()
- 在模型任意位置获取当前参数激活值统计量
TrainerMon.generate_xy_metrics() -> tuple[dict, dict]
具体使用方式如下：
actv, actv_grad = monitor.generate_xy_metrics()
- 老版接口说明， 将在2026年废弃：
TrainerMon.set_wrapped_optimizer(optimizer) -> None
| 参数 | 可选/必选 | 说明 |
|---|---|---|
| optimizer | 必选 | megatron、deepspeed创建好的混合精度优化器 |
TrainerMon.monitor_gnorm_with_ad(model, grad_acc_steps, optimizer, dp_group, tp_group, start_iteration) -> None
| 参数 | 可选/必选 | 说明 |
|---|---|---|
| model | 必选 | 需要监测的模型，需要是一个torch.nn.Module或者mindspore.nn.Cell。 |
| grad_acc_steps | 必选 | 梯度累积步数。 |
| optimizer | 可选 | 需要patch的优化器。 |
| dp_group | 可选 | 数据并行的通信组。 dp域通信后，且没有使用分布式优化器时，group内所有rank的梯度相同，落盘数据冗余。 提供dp_group后，工具仅保留每个dp_group的第一个rank的梯度。 |
| tp_group | 可选 | 张量并行的通信组。 tp域通信后，group内部分参数所有rank的梯度相同，落盘数据冗余。 提供tp_group后，工具仅保留每个tp_group中冗余参数在第一个rank的梯度。 当前适配Megatron core_r0.6.0, 通过权重属性"tensor_model_parallel"判断是否冗余。 |
| start_iteration | 可选 | 训练的起始iteration，影响工具计数。仅PyTorch场景支持此参数。 |
具体接口变更说明如下：
| 变更 | 说明 |
|---|---|
| 初始化接口统一精简 | TrainerMon.init(config_file_path, process_group=None, param_have_main_grad=True) |
| 主调接口修改 | 从monitor_gnorm_with_ad(...)改名为set_monitor(...)， 且此时optimizer从可选项改为必传项 |
| 优化器包装接口废除 | set_wrapped_optimizer接口废除， optimizer传入由set_monitor主调完成 |
详细配置
{
"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,
"xy_distribution": true,
"all_xy": true,
"forward_only": false,
"backward_only": false,
"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}}],
"dump": false
},
"format": "csv",
"ops": ["min", "max", "norm", "zeros", "nans", "mean"],
"eps": 1e-8,
"ndigits": 12,
"step_count_per_record": 1,
"append_output": [],
"squash_name": false
}
下面详细解释各个字段：
| 字段名字 | 可选/必选 | 解释 |
|---|---|---|
| "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的后向output_grad参数是长度为1的tuple， 我们关心的是tuple的第0个元素。 |
| "dynamic_on" | 可选 | 在动态启停时使用，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后监测工具会打印每张卡模型中module的名字和详细结构，并在第1个step后退出。不填默认为false。 |
| "module_ranks" | 可选 | 用于在分布式训练场景中希望控制在哪些rank开启module监测。如果不填，则默认在所有rank开启。 列表内rank要求为int类型。 |
| "ur_distribution" | 可选 | 若为true则会统计adam优化器指定模块（targets中指定）参数的update和ratio向量的数值分布，并展示在heatmap里。默认为false。 依赖histc算子， 需要CANN8.0.rc2以上版本， 否则会有严重的性能问题。仅PyTorch场景支持此参数。 |
| "xy_distribution" | 可选 | 若为true则会监测指定module（targets中指定）的输入输出张量。 默认为false。 |
| "all_xy" | 可选 | 开启xy_distribution后生效，若为true，监测所有module。默认为false。 与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。 |
| "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的同步。 |
| "mg_direction" | 可选 | 若为true则会计算权重梯度和动量方向一致的比例，默认为false。 |
| "format" | 可选 | 数据落盘格式，仅支持"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。 |
| "step_count_per_record" | 可选 | "format"为"csv"时生效，每个csv记录多少个step的数据，默认为1。 |
| "append_output" | 可选 | 适用于断点续训场景。多卡场景下生效，指定两个时间戳，将输出续写到这两个时间戳范围间的输出件中，不在范围内的rank不被续写。时间戳应来自原有输出件目录前缀，例如["Dec03_21-34-40", "Dec03_21-34-41"]。默认为[]，不续写。仅PyTorch场景支持此参数。 |
| "squash_name" | 可选 | 是否简化参数名/模块名，多模态场景建议关闭，默认为False。 |