| name | mindspeed-mm-train-profiler |
| description | 指导并自动化完成昇腾 NPU 上 MindSpeed-MM 模型训练的 Profiling 数据采集。通过识别训练脚本，自动找到配置文件并启用内置 Profiler，支持静态采集（指定起止 step）和动态采集（运行时动态开关），支持 Megatron 引擎（tools.json）和独立 FSDP2 引擎（YAML）两种配置方式。生成的 Profiling 数据可用 MindStudio Insight 进行性能分析。当用户需要在多模态模型训练中采集 Profiling 数据、进行训练性能分析、或执行 性能数据采集/Profiling采集 时触发。触发关键词：profiling、性能分析、性能数据采集、Profiling采集、多模态训练profiling、MindSpeed-MM profiling。 |
MindSpeed-MM 训练 Profiling 数据采集（昇腾 NPU）
- 使用用户的语言回复。
- 以下内容不要翻译：命令、文件路径、环境变量、包名、错误信息。
第 0 步：收集训练脚本并确认配置
回复用户：
开始 Profiling 采集前，请提供训练脚本路径（.sh）— 已配置好模型、数据、权重的可运行训练脚本。
没有训练脚本则无法采集。
用户未提供任何信息时： 停止。回复："Profiling 需要可运行的训练脚本，请先准备好再进行采集。"
用户提供了脚本后： 读取脚本内容，自动检测训练引擎并定位配置文件。
检测训练引擎
| 查找目标 | 用途 |
|---|
MM_TOOL 变量 | 直接定位 tools.json（Megatron 引擎） |
pretrain_sora.py / pretrain_transformers.py | 确认是 MM 训练入口 |
| YAML 路径（torchrun 后第一个非选项参数） | 读 YAML 进一步判断 |
YAML 中 MM_TOOL_PATH 字段 | 定位 tools.json（Megatron 引擎） |
YAML 中 tools.profile 结构 | 直接在 YAML 配置（独立 FSDP2 引擎） |
如果脚本不引用 mindspeed_mm，停止并建议使用 pytorch-profiling-collection 通用采集技能。
逐项选择 Profiling 配置
按顺序使用 question 工具逐一选择配置项，每项给出默认值：
① 采集类型： 使用 question 工具，选项为 静态（推荐，固定起止 step） / 动态（运行中通过文件控制），默认选中静态。
② 采集级别： 使用 question 工具，选项为 level0（基础） / level1（推荐，含 AICore 利用率） / level2（全量），默认选中 level1。
③ 采集起止 step（仅静态模式）： 使用 question 工具，选项为 10~12（推荐） / 5~8 / 自定义，默认选中 10~12。如选自定义，再使用 question 工具让用户输入或选择 start/end step。
④ 采集卡号： 使用 question 工具，选项为 仅 rank 0（推荐） / 全部 rank / 自定义（如 0,1,2），默认选中 仅 rank 0。
⑤ 采集内容（可多选）： 使用 question 工具，一次性列出所有选项，设置 multiple: true，允许用户同时选择多项。选项为：
CPU 事件（默认选中）内存占用算子调用栈Tensor 输入形状数据简化模式
⑥ AI Core 指标类型： 使用 question 工具，选项为 PipeUtilization（默认） / ArithmeticUtilization，默认选中前者。
⑦ 在线解析： 使用 question 工具，选项为 开启（推荐，训练完自动解析） / 关闭（需手动跑离线解析），默认选中开启。
⑧ 训练步数： 使用 question 工具，让用户输入训练总步数。选项为：20 / 100 / 1000 / 10000，默认选中 100。用户也可选择「自定义」自行输入步数。确认后，将脚本副本的 --train-iters 改为该值。
展示完整配置确认表
收集完所有回答后，展示最终配置表等待用户确认：
| 配置项 | 值 |
|---|
| 运行脚本 | <路径> |
| 训练引擎 | Megatron / 独立 FSDP2 |
| 配置文件 | <路径> |
| 采集类型 | static / dynamic |
| 采集级别 | level1 |
| 采集步骤 | step N ~ M |
| 采集卡号 | rank 0 |
| 采集内容 | CPU事件、内存占用、算子调用栈、Tensor形状、数据简化（多选） |
| AI Core 指标 | PipeUtilization |
| 在线解析 | 开启/关闭 |
| 训练步数 | 用户指定（如 100） |
确认后开始配置。需修改请说明。
禁止下载模型、转换权重或创建训练脚本。
用户输入与变量映射
| question 工具返回值 | 变量 | 默认值 |
|---|
| 训练脚本（.sh） | TRAIN_SCRIPT | （必填） |
| "静态" / "static" | PROFILE_TYPE=static | static |
| "动态" / "dynamic" | PROFILE_TYPE=dynamic | — |
| "Level0/1/2" | PROFILE_LEVEL | level1 |
| "step N 到 M" | START_STEP=N END_STEP=M | 10, 12 |
| rank 0 / 全部 / "0,1,2" | PROFILE_RANKS | [0]（仅 rank 0） |
| "CPU 事件" | WITH_CPU=true | true |
| "内存占用" | WITH_MEMORY=true | false |
| "算子调用栈" | WITH_STACK=true | false |
| "Tensor 输入形状" | RECORD_SHAPES=true | false |
| "数据简化模式" | DATA_SIMPLIFICATION=true | false |
| "PipeUtilization" / "ArithmeticUtilization" | AIC_METRICS_TYPE | PipeUtilization |
| "开启" / "关闭" | ANALYSE_FLAG=true/false | true |
| "全部 rank" | PROFILE_RANKS=[-1] | [0] |
| "20" / "100" / "1000" / "10000" / 自定义 | TRAIN_ITERS=用户指定值 | 100 |
第 1 步：检查环境
source /usr/local/Ascend/ascend-toolkit/set_env.sh 2>/dev/null || source /usr/local/Ascend/cann/set_env.sh 2>/dev/null
npu-smi info
python -c "import torch; import torch_npu; print(f'torch_npu: {torch_npu.__version__}'); print(f'NPU available: {torch.npu.is_available()}')"
- NPU 不可用 → 停止："当前环境未检测到 NPU，请在有 Ascend NPU 的环境中运行。"
- torch_npu 不可用 → 停止："请安装 torch_npu 后再试。"
第 2 步：配置并执行 Profiling
禁止修改用户的原始脚本和配置文件。 先创建脚本副本，再创建配置文件副本进行修改。
-
读取原始脚本，检查其引用的关键路径是否存在（权重目录、数据文件、配置文件）。
-
如有路径不存在，停止并报告：
训练脚本中引用的路径不存在：
请检查脚本中的路径配置，确保训练环境就绪后再进行 Profiling 采集。
-
根据第 0 步检测的引擎类型，确定要修改的配置目标：
| 检测结果 | 配置方式 | 修改目标 |
|---|
脚本有 MM_TOOL 变量 | tools.json | MM_TOOL 指向的 JSON 文件 |
YAML 中有 MM_TOOL_PATH 字段 | tools.json | MM_TOOL_PATH 指向的 JSON 文件 |
YAML 中有 tools.profile 结构 | YAML tools.profile | YAML 配置文件本身 |
-
创建新的脚本和配置文件（使用带时间戳的文件名）。
-
根据引擎类型修改配置：
Megatron 引擎（修改 tools.json）：
复制 tools.json，在原内容基础上添加或覆盖 profile 字段：
{
"profile": {
"enable": true,
"profile_type": "static",
"ranks": [0],
"static_param": {
"level": "level1",
"with_stack": false,
"with_memory": false,
"record_shapes": false,
"with_cpu": true,
"save_path": "./npu_profiling",
"start_step": 10,
"end_step": 12,
"data_simplification": false,
"aic_metrics_type": "PipeUtilization",
"analyse_flag": true
}
}
}
如果 tools.json 中原有 memory_profile 等配置，保留不变。
独立 FSDP2 引擎（修改 YAML）：
复制 YAML 配置文件，在末尾添加 tools 字段：
tools:
profile:
enable: true
profile_type: static
ranks:
- 0
static_param:
level: level1
with_stack: false
with_memory: false
record_shapes: false
with_cpu: true
save_path: ./npu_profiling
start_step: 10
end_step: 12
data_simplification: false
aic_metrics_type: PipeUtilization
analyse_flag: true
-
根据用户的 Profiling 配置（第 0 步的变量映射），逐一替换对应字段的值。
-
在脚本副本中找到 --train-iters 参数，将其值改为用户指定的训练步数。如果脚本中没有 --train-iters（如使用 train-iters），同样处理。
-
如果创建了配置文件副本，同步修改脚本副本中的路径变量（MM_TOOL / MM_TOOL_PATH），使其指向新副本。
-
创建 Profiling 输出目录：
mkdir -p <save_path>
-
运行脚本副本。原始脚本和原始配置文件必须保持不变。
-
如训练失败（非零退出码），向用户报告错误：
训练执行失败（退出码: N）。Profiling 采集需要训练正常运行。
请修复训练配置后重试。
动态采集说明
如果用户选择动态采集：
- 设置
profile_type: dynamic。
- 在
dynamic_param.config_path 指定一个空目录（如 ./dynamic_profile_config）。
- 运行训练后，该目录下会自动生成
profiler_config.json 文件。
- 训练运行时，修改
profiler_config.json 中的 start_step / end_step，Profiling 会在下一个 step 自动开启。
离线解析
如果 analyse_flag 为 false，或需要重新解析，按引擎类型执行：
Megatron 引擎：
python mindspeed_mm/tools/profiler.py --mm-tool <tools.json 路径> --profiler-path <profiling 数据目录>
独立 FSDP2 引擎：
python mindspeed_mm/fsdp/tools/profiler.py --profiler-path <profiling 数据目录>
第 3 步：验证并报告结果
训练完成后，验证 Profiling 输出：
- 检查
save_path 目录是否存在，是否包含 *_ascend_pt/ 子目录。
- 至少应包含
PROF_*/device_*/data/（NPU 数据）或 ASCEND_PROF_* 目录。
- 向用户报告：输出位置、使用的配置、目录结构。
- 建议使用 MindStudio Insight 进行可视化分析。
如输出缺失或为空，检查：start_step >= 1、训练是否执行到了采集步骤、CANN 环境是否已加载。
故障排查
| 症状 | 解决方法 |
|---|
NPU out of memory | 减小 micro_batch_size 或启用 data_simplification |
| Profiling 目录为空 | start_step 必须 >= 1；训练必须执行到该步骤 |
Address already in use | 修改训练脚本中的 MASTER_PORT |
| 动态采集未生效 | 检查 config_path 目录下的 profiler_config.json |
| 仅采集了部分 rank | 检查 ranks 参数配置是否正确 |
找不到 tools.json | 确认 MM_TOOL 或 MM_TOOL_PATH 路径正确 |
禁止事项
- 禁止修改用户的原始训练脚本（
.sh），必须创建副本后再做任何修改。
- 禁止修改用户的原始配置文件（YAML/JSON），必须创建副本。
- 禁止安装框架、下载模型或转换权重。
- 禁止设置
start_step = 0 — 必须 >= 1。
- 禁止在大规模训练中采集所有步骤 — 2-3 步即可。
- 没有可运行的训练脚本禁止继续执行。
- 除非用户明确要求，禁止采集全部 rank（
ranks: [-1]），防止数据量过大。
参考文档
详见 reference/mindspeed-mm-profiling-config.md 获取完整配置参数表。
