ascend-profiler-data-validation

name	ascend-profiler-data-validation
description	当用户提供 MindStudio profiler 采集的性能数据（框架 profiler、msprof 命令行）时，对数据完整性、采集状态及关键配置进行校验，确保后续分析工具能正常运行。
keywords	["profiler","性能分析","数据检查"]

MindStudio Profiler 数据校验

技能目标

在深入性能分析前，对 profiler 数据进行「体检」，确保：

• 正确识别数据类型（框架 profiler / msprof）
• 采集过程正常结束（流程正常 Stop）
• 数据已解析，关键交付件存在
• 识别 profiler 配置，预判后续分析可行性

数据类型特征

类型	标识特征	采集方式
框架 profiler	[*]_ascend_pt（PyTorch）或 [*]_ascend_ms（MindSpore）	代码内嵌，进程级
msprof	含 PROF_{} 目录	命令行，进程级

框架 profiler 含 torch_npu/MindSpore 框架 API、CANN API、device 算子、硬件指标；msprof 含 CANN API、device 算子、硬件指标。

依赖与资源

• MCP 工具：msprof-mcp__get_profiler_config(profiler_path) — 解析 profiler_info.json（仅框架 profiler）
• 离线解析：
  • 框架 profiler：scripts/offline_parse_pytorch.py <profiler_path>（PyTorch），scripts/offline_parse_mindspore.py <profiler_path>（MindSpore）
  • msprof：msprof --export=on --output=<output_path>（output 指向 PROF_{} 所在路径或导出目录）

分析步骤

• 多卡原则：多卡数据默认只抽查一张卡（如 Rank0）；仅当用户明确要求「每张卡都检查」「逐卡校验」时，再逐卡检查。
• 类型绑定原则（必须严格遵守）：数据类型的判定依据是用户给定的顶层路径。判定后，全程只执行该类型对应的步骤，不得混用。
  • 若顶层路径以 [*]_ascend_pt 或 [*]_ascend_ms 结尾 → 仅用框架 profiler 规则。
  • 若顶层路径为 PROF_[*] 目录 → 仅用 msprof 规则。

1. 识别数据类型

• [*]_ascend_pt → 框架 profiler（PyTorch）；多子目录→多卡，单目录→单卡
• [*]_ascend_ms → 框架 profiler（MindSpore）；多子目录→多卡，单目录→单卡
• PROF_[*] → msprof 命令行；多子目录 → 多卡，单目录 → 单卡

2. 校验采集状态 (Stop Check)

• 框架 profiler：检查 profiler_info.json 或 profiler_info_{Rank_ID}.json；缺失则提示「采集未正常 Stop」，终止，建议检查 profiler.stop()
• msprof：检查 PROF_{}/device_{}/ 下是否存在 end_info.{}（{} 为 device 编号占位）；缺失则提示「采集未正常结束」，终止

3. 解析配置（仅框架 profiler）

• 框架 profiler：调用 get_profiler_config 读取 profiler_info.json，关注 profiler_level、with_stack、with_modules、record_shapes、profile_memory。
• msprof：无需检查配置，跳过本步骤。

4. 校验解析状态 (Parse Check)

• 框架 profiler：检查是否存在 ASCEND_PROFILER_OUTPUT 或对应解析输出目录；若缺失则停止分析，询问用户是否协助解析，同意则执行 offline_parse_pytorch.py（PyTorch）或 offline_parse_mindspore.py（MindSpore）。
• msprof：检查 PROF_{} 下是否存在 mindstudio_profiler_output 目录（即 msprof --export=on 的导出结果）；若缺失则停止分析，询问是否协助执行 msprof --export=on --output=<path>。
• 解析完成（或已存在解析结果）后，继续第 5 步。

5. 检查关键交付件

• 框架 profiler：按 export_type 检查——Text 模式需 trace_view.json、kernel_details.csv；DB 模式需 [*]_profiler_[*].db。缺失则警告影响 Timeline/算子分析。
• msprof：检查 PROF_{} 下是否含 msprof_[*].db，或 mindstudio_profiler_output 下是否含 msprof_{timestamp}.json、op_summary.csv。都缺失则警告。

输出策略

本技能为前置校验，不必每次都输出完整报告：

• 用户明确要求「检查数据」「看校验结果」时，输出简洁结构化报告，按以下格式（每项一行，无则略过）：

  【类型】框架 profiler (PyTorch/MindSpore) 或 msprof 命令行采集 | 单卡/多卡
  【状态】valid / invalid / unparsed
  【配置】level、with_stack、profile_memory、采集步数等关键项（仅框架 profiler）
  【缺失】trace_view.json、kernel_details.csv 等（如有）
  【建议】需解析 / 检查 profiler.stop / 无
  【下一步】推荐的分析技能或操作
  

• 前置调用（用户在做 Timeline / 算子分析等）：
  • invalid（未 Stop）→ 必须告知并终止
  • unparsed（未解析）→ 告知需先解析并询问是否协助
  • 校验通过 → 静默进入后续分析

约束

• invalid（未正常 Stop）必须终止流程
• unparsed（未解析）必须优先引导解析，否则后续工具无法运行