Ascend NPU Memory Snapshot Analyzer
1. 技能目标
分析 torch_npu.npu.memory._dump_snapshot() 导出的 pickle 文件，提供多维度的内存分析能力和交互式可视化报告。
2. 输入规范
- 输入数据：
torch_npu.npu.memory._dump_snapshot() 或 torch.cuda.memory._dump_snapshot() 导出的 pickle 文件（支持 dict 和 list 两种格式）
- 前置条件：需要先通过
snapshot_to_db.py 将 pickle 转换为 SQLite DB
3. 分析能力
Track A：快速通道（CTE 宏）
以下 CTE 宏可直接嵌入 SQL 查询，覆盖 80% 常见分析场景：
-- 宏1：设备内存概览
WITH device_overview AS (
SELECT
d.device_index,
SUM(s.total_size) AS reserved_bytes,
SUM(s.allocated_size) AS allocated_bytes,
SUM(s.active_size) AS active_bytes,
ROUND((SUM(s.total_size) - SUM(s.allocated_size)) * 100.0 / NULLIF(SUM(s.total_size), 0), 2) AS frag_pct,
COUNT(s.id) AS segment_count,
SUM(s.is_expandable) AS expandable_segments
FROM segments s
JOIN devices d ON s.device_id = d.id
GROUP BY d.device_index
)
-- 宏2：块状态分布
WITH block_state_dist AS (
SELECT
d.device_index,
b.state,
COUNT(b.id) AS block_count,
SUM(b.size) AS total_size,
AVG(b.size) AS avg_size
FROM blocks b
JOIN segments s ON b.segment_id = s.id
JOIN devices d ON s.device_id = d.id
GROUP BY d.device_index, b.state
)
-- 宏3：扩容事件时间线
WITH expansion_timeline AS (
SELECT
d.device_index,
t.trace_index,
t.action,
t.size,
t.addr,
cs.frames_json
FROM traces t
JOIN devices d ON t.device_id = d.id
LEFT JOIN call_stacks cs ON t.stack_id = cs.id
WHERE t.action IN ('segment_alloc', 'segment_map', 'segment_free', 'segment_unmap')
ORDER BY d.device_index, t.trace_index
)
-- 宏4：大块分配 TOP N
WITH top_allocations AS (
SELECT
d.device_index,
b.size,
b.requested_size,
b.state,
cs.frames_json
FROM blocks b
JOIN segments s ON b.segment_id = s.id
JOIN devices d ON s.device_id = d.id
LEFT JOIN call_stacks cs ON b.stack_id = cs.id
WHERE b.state = 'active_allocated'
ORDER BY b.size DESC
LIMIT 20
)
Track B：深度分析（脚本调用）
# 总体概览
python scripts/snapshot_analyze.py snapshot.db --mode overview
# 峰值分析（时序重放 + 峰值贡献者）
python scripts/snapshot_analyze.py snapshot.db --mode peak
# 碎片分析（整体 + 逐段 + 假性碎片）
python scripts/snapshot_analyze.py snapshot.db --mode fragment
# 泄漏检测（单调增长 + 长生命周期 + 堆栈归因）
python scripts/snapshot_analyze.py snapshot.db --mode leak
# OOM 分析（上下文回溯 + 根因推断）
python scripts/snapshot_analyze.py snapshot.db --mode oom
# 跨快照对比（ATTACH DATABASE）
python scripts/snapshot_analyze.py snapshot.db --mode compare --ref other.db
# 全模式 + HTML 报告
python scripts/snapshot_analyze.py snapshot.db --mode all -o report.html
4. 工作流
初始分析流程
- 用户提供 snapshot pickle 文件路径
- 转换:
python scripts/snapshot_to_db.py snapshot.pkl
- 总览:
python scripts/snapshot_analyze.py snapshot.db --mode overview
- 根据总览结果，按需执行深度分析
问题诊断流程
用户问题
│
├─ "峰值/最高内存" → --mode peak
├─ "碎片/内存利用率" → --mode fragment
├─ "泄漏/不释放" → --mode leak
├─ "OOM/崩溃" → --mode oom
├─ "对比/差异" → --mode compare --ref other.db
└─ "全面分析" → --mode all -o report.html
5. 输出规范
问题 → 证据 → 建议 三段式
每个分析结果包含：
- 问题描述：现象是什么
- 数据证据：具体数值和来源
- 可执行建议：优先级 + 预期效果 + 参考链接
报告模板路由
分析结果按五层金字塔组织：
- 总览 & 一键结论（健康状态 + 核心指标卡片）
- 设备详情（各设备对比 + Segment 类型分布）
- 深度分析（峰值/碎片/泄漏/OOM 按需展开）
- 堆栈归因（TOP 10 堆栈 + 分配量占比）
- 优化建议（高/中优先级 + 类别标签 + 预期效果）
详见 references/analysis_templates.md。
6. 数据格式参考
详见 references/snapshot_schema.md。
7. 分析方法论
详见 references/analysis_methodology.md。
8. 脚本工具
| 脚本 | 用途 |
|---|
scripts/snapshot_to_db.py | pickle → SQLite DB 转换 |
scripts/snapshot_queries.py | SQL 查询函数库（供 Agent 直接调用） |
scripts/snapshot_analyze.py | 高层分析（6 种模式 + HTML 报告） |
9. 使用示例
# 1. 转换
python scripts/snapshot_to_db.py snapshot_before.pkl
# 2. 总览
python scripts/snapshot_analyze.py snapshot_before.db --mode overview
# 3. 碎片分析
python scripts/snapshot_analyze.py snapshot_before.db --mode fragment
# 4. 泄漏检测
python scripts/snapshot_analyze.py snapshot_before.db --mode leak
# 5. 生成完整报告
python scripts/snapshot_analyze.py snapshot_before.db --mode all -o report.html
10. 约束与限制
- 仅支持离线 pickle 文件，不支持实时采集
- Phase 1 不解析 device_traces 的时序关联（仅存储）
- 大文件 (>1GB) 导入时建议使用
--no-indexes 先导入，后手动建索引