kali20gakki/msAgent / skills/profiler/ascend-npu-snapshot-analyzer
ascend-npu-snapshot-analyzer
Unverified分析 PyTorch memory snapshot pickle 文件(_dump_snapshot 导出的内存快照),提供内存峰值、碎片、泄漏、OOM 检测与交互式 HTML 报告。仅当用户明确提及 memory snapshot、内存快照、_dump_snapshot、pickle 内存文件 或需要对 snapshot pickle 做内存分析时才触发,不处理一般的 NPU 性能分析、SQLite 查询或通用内存问题。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.1 KB |
| references/analysis_methodology.md | markdown | 4.5 KB |
| references/analysis_templates.md | markdown | 5.4 KB |
| references/snapshot_schema.md | markdown | 2.7 KB |
| scripts/echarts.min.js | script | 1005.1 KB |
| scripts/snapshot_analyze.py | script | 41.9 KB |
| scripts/snapshot_queries.py | script | 16.0 KB |
| scripts/snapshot_to_db.py | script | 16.6 KB |
references/analysis_templates.md
View on GitHub# 典型分析套路
本文档定义 Agent 在生成内存分析报告时的模板路由规则和输出字段清单。
## 报告层级结构
```
┌──────────┐
│ 5. 建议 │ ← 怎么办
┌┴──────────┴┐
│ 4. 堆栈归因 │ ← 谁导致的
┌┴────────────┴┐
│ 3. 深度分析 │ ← 为什么
┌┴──────────────┴┐
│ 2. 设备详情 │ ← 问题在哪
┌┴────────────────┴┐
│ 1. 总览 & 结论 │ ← 有没有问题
└──────────────────┘
```
## 模板路由决策树
Agent 在生成报告时,按以下决策树选择合适的模板组合:
```
用户请求
│
├─ 包含"对比""diff""before/after" → 模板 6 (跨快照对比)
│
└─ 单文件分析
│
├─ 始终输出 → 模板 1 (总览)
│
├─ 多设备 (device_count > 1) → 模板 2 (设备详情)
│
├─ 碎片率 > 5% 或用户问"碎片" → 模板 3b (碎片分析)
│
├─ 用户问"峰值""增长""最多" → 模板 3a (峰值分析)
│
├─ 用户问"泄漏""不释放" 或检测到异常 → 模板 3c (泄漏分析)
│
├─ 存在 OOM 事件 → 模板 3d (OOM 分析)
│
├─ 任何深度分析后 → 模板 4 (堆栈归因)
│
└─ 任何深度分析后 → 模板 5 (优化建议)
```
## 模板清单
### 模板 1:总览 & 一键结论
**触发条件**:任何分析请求,始终首先输出。
**核心字段**:
- 健康状态(🟢/🟡/🔴)
- 指标卡片:Reserved、Allocated、碎片率、Segment 数、OOM 事件数
- 每个指标附带状态图标和阈值
- 一键结论(自然语言总结)
### 模板 2:设备详情
**触发条件**:多设备 snapshot,或用户询问"各卡情况"。
**核心字段**:
- 设备数量
- 设备对比表:Device ID、Reserved、Allocated、Active、碎片率、状态
- Segment 类型分布表:large 段/ small 段数量、占比、可扩容段数
- 异常设备判定(碎片率偏离均值 2 倍以上 / Reserved 偏离 30% 以上)
### 模板 3a:峰值分析
**触发条件**:用户询问"峰值""最高内存""内存增长"。
**核心字段**:
- 峰值时刻 trace_index
- 峰值 vs 基线对比:Reserved/Allocated/Active 的峰值、基线、增幅
- 峰值贡献者 TOP 5:Segment 地址、大小、分配量、堆栈特征
### 模板 3b:碎片分析
**触发条件**:碎片率 > 5%,或用户询问"碎片""内存利用率"。
**核心字段**:
- 整体碎片率 + 状态图标
- 碎片构成:空闲空间大小/占比、待释放大小/占比
- 碎片化最严重的 Segment TOP 5:地址、Reserved、使用率、碎片大小
### 模板 3c:疑似泄漏分析
**触发条件**:用户询问"泄漏""内存不释放""内存持续增长",或 Segment 数量单调递增。
**核心字段**:
- 风险等级 + 图标
- 单调增长趋势描述
- 长生命周期 Block 数量
- 泄漏嫌疑 TOP 3:累计增长量、涉及 segment/block 数、堆栈关键路径、分析解读
### 模板 3d:OOM 分析
**触发条件**:traces 表中存在 `action = 'oom'` 事件。
**核心字段**:
- OOM 发生时刻 trace_index
- OOM 时可用内存 device_free
- OOM 前最后 5 次分配:大小、类型、堆栈
- 根因推断
### 模板 4:堆栈归因汇总
**触发条件**:任何深度分析后自动输出。
**核心字段**:
- 按分配总量排序的堆栈 TOP 10
- 每项包含:堆栈关键路径、分配量、占比
- 无堆栈的分配单独归类
### 模板 5:优化建议
**触发条件**:任何深度分析后自动输出。
**核心字段**:
- 高优先级建议(🔴):OOM / 碎片率 > 15% / 高风险泄漏
- 中优先级建议(🟡):碎片率 5%~15% / 中风险泄漏 / Segment 偏多
- 每项建议包含:类别标签、描述、预期效果、参考链接
### 模板 6:跨快照对比
**触发条件**:用户提供两份 snapshot 进行对比。
**核心字段**:
- 整体变化一句话总结
- 指标对比表:A 值 / B 值 / 差异 / 趋势
- 新增 Segment TOP 5(B 有而 A 无)
- 扩容 Segment TOP 3(地址相同但 size 增大)
## 输出格式规范
### 数值格式化
- 内存大小:≥ 1GB 用 `X.XX GB`,≥ 1MB 用 `X.X MB`,否则用 `X KB`
- 百分比:保留 1 位小数
- 差异值:带正负号
### 状态图标
- 健康状态:🟢 / 🟡 / 🔴
- 趋势:↑ / ↓ / =
- 若终端不支持 emoji,回退为 ASCII:`[OK]` / `[WARN]` / `[ERR]`
### 建议类别映射
| 检测结果 | 建议类别 | 典型建议 |
|---------|---------|---------|
| 碎片率高 | [碎片] | 调用 `torch.npu.empty_cache()`;增大 `expandable_segments` |
| 疑似泄漏 | [泄漏] | 检查 DDP/FSDP gradient bucket;检查循环中 tensor 是否 detach |
| OOM | [OOM] | 减小 batch_size;启用 gradient checkpointing;使用混合精度 |
| Segment 偏多 | [扩容] | 设置 `max_split_size_mb`;调整 `PYTORCH_NPU_ALLOC_CONF` |
| 无堆栈信息 | [监控] | 增大 `max_entries`;开启 `stacks="all"` 选项 |Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |