Skip to content

Ascend/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 查询或通用内存问题。

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"` 选项 |
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall