| name | mindspeed-llm-train-profiler |
| description | 指导并自动化完成昇腾 NPU 上 MindSpeed-LLM 训练的 Profiling 数据采集。支持配置并运行带 Profiling 的模型训练，包括 CPU 采集、内存采集、不同采集级别（level0/level1/level2）和自定义 step 范围。生成的 Profiling 数据可用 MindStudio Insight 进行性能分析。当用户需要在模型训练中采集 Profiling 数据、进行训练性能分析、或执行 性能数据采集/Profiling采集 时触发。触发关键词：profiling、性能分析、性能数据采集、Profiling采集、训练框架profiling、MindSpeed-LLM profiling。 |
MindSpeed-LLM 训练 Profiling 数据采集（昇腾 NPU）
- 使用用户的语言回复。
- 以下内容不要翻译：命令、文件路径、环境变量、包名、错误信息。
第 0 步：确认前置条件
回复用户：
开始 Profiling 采集前，请提供以下信息：
必要：
- 训练脚本路径（
.sh）— 已配置好模型、数据、权重的可运行脚本
可选（有默认值）：
- 采集级别：level0 / level1（推荐）/ level2
- 采集步骤：默认 step 2 ~ 4（不含 step 4，实际采集 step 2 和 3）
- 采集内容：CPU（默认开启）、内存、堆栈、tensor 形状
- NPU 卡数：默认单卡
没有训练脚本则无法采集。
用户未提供任何信息时： 停止。回复："Profiling 需要可运行的训练脚本，请先准备好再进行采集。"
用户提供了训练脚本后： 展示最终配置表，等待用户确认后再执行。
| 配置项 | 值 |
|---|
| 模型 | （从脚本中读取） |
| 训练脚本 | （路径） |
| NPU 卡数 | （从脚本中读取 NPUS_PER_NODE） |
| 采集级别 | level1（推荐） |
| 采集步骤 | step 2 ~ 4（不含 4） |
| 采集卡号 | rank 0 |
| CPU 采集 | 开启 |
| 内存采集 | 关闭 |
| 堆栈采集 | 关闭 |
| Tensor 形状采集 | 关闭 |
确认后开始。如需修改请说明。
禁止下载模型、转换权重或创建训练脚本。
用户输入与变量映射
| 用户说 | 变量 | 默认值 |
|---|
| 训练脚本（.sh） | TRAINING_SCRIPT | （必填） |
| "CPU" / "采集CPU" | PROFILE_WITH_CPU=true | true |
| "内存" / "memory" | PROFILE_WITH_MEMORY=true | false |
| "Level0/1/2" | PROFILE_LEVEL | level1 |
| "step N 到 M" | PROFILE_STEP_START=N PROFILE_STEP_END=M | 2, 4 |
| "堆栈" / "stack" | PROFILE_WITH_STACK=true | false |
| "shape" / "维度" | PROFILE_RECORD_SHAPES=true | false |
| "所有卡" / "all ranks" | PROFILE_RANKS=-1 | 0（仅 rank 0） |
说明：NPU 卡数从训练脚本中读取（NPUS_PER_NODE 或 --nproc_per_node）。Profiling 默认只采集 rank 0。仅在用户明确要求时才设置 PROFILE_RANKS=-1 采集所有卡。
第 1 步：检查环境
运行 npu-smi info 确认 NPU 可用。如不可用，停止："当前环境未检测到 NPU，请在有 Ascend NPU 的环境中运行。"
如需加载 CANN 环境：source /usr/local/Ascend/ascend-toolkit/set_env.sh
第 2 步：验证脚本并执行 Profiling
禁止修改用户的原始训练脚本。 基于原始脚本创建新脚本。
- 读取原始脚本，检查其引用的关键路径是否存在（权重目录、数据文件、tokenizer 目录）。
- 如有路径不存在，停止并报告：
训练脚本中引用的路径不存在：
请检查脚本中的路径配置，确保训练环境就绪后再进行 Profiling 采集。
- 创建新的 Profiling 脚本（使用带时间戳的文件名，如
run_profiling_$(date +%Y%m%d%H%M%S).sh，避免覆盖已有文件）。复制原始脚本内容，在 torchrun 命令中添加以下 Profiling 参数（在 | tee 之前；如无 | tee 则追加到 torchrun 命令末尾；如无法识别命令格式则展示参数并请用户指定插入位置）：
--profile --profile-step-start 2 --profile-step-end 4 \
--profile-ranks 0 --profile-level level1 --profile-with-cpu \
--profile-save-path ./profiling_output
- 如果原始脚本已包含
--profile 参数，标注已有配置并询问用户是保留还是覆盖。
- 根据用户的 Profiling 配置调整参数值。运行前创建输出目录。
- 运行新脚本。原始脚本必须保持不变。
- 如训练失败（非零退出码），向用户报告错误：
训练脚本执行失败（退出码: N）。Profiling 采集需要训练正常运行。
请修复训练脚本后重试。
第 3 步：验证并报告结果
训练完成后，验证 Profiling 输出：
- 检查 Profiling 输出目录是否存在，是否包含
*_ascend_pt/ 子目录。
- 至少应包含
PROF_*/device_*/data/（NPU 数据）。
- 向用户报告：输出位置、使用的配置、目录结构。
- 建议使用 MindStudio Insight 进行可视化分析。
如输出缺失或为空，检查：PROFILE_STEP_START >= 1、训练是否执行到了采集步骤、CANN 环境是否已加载。
故障排查
| 症状 | 解决方法 |
|---|
NPU out of memory | 减小训练脚本中的 batch size |
| Profiling 目录为空 | PROFILE_STEP_START 必须 >= 1；训练必须执行到该步骤 |
Address already in use | 修改训练脚本中的 MASTER_PORT |
| 权重形状不匹配 | 权重的 TP/PP 与训练配置不一致，通知用户后停止采集 |
禁止事项
- 禁止修改用户的原始训练脚本，必须创建新脚本。
- 禁止安装框架、下载模型或转换权重。
- 禁止设置
--profile-step-start 0 — 必须 >= 1。
- 禁止在大规模训练中采集所有步骤 — 2-3 步即可。
- 没有训练脚本禁止继续执行。
- 除非用户明确要求，禁止设置
--profile-ranks -1。
参考文档
详见 reference/mindspeed-profiling-args.md 获取完整参数表（Mcore CLI 参数 + FSDP2 YAML 配置）。
