English | 中文
从已有输入得到一份可读的峰值内存报告。默认路径是单个 SnapshotDB,无需先选择分库格式。
在希望使用 CLI 的环境中准备 Python 3.10 或更新版本:
python -m pip install pt-snap-cli
pt-snap --help离线导入和分析不需要 PyTorch、TorchNPU、CUDA 或加速器硬件。采集则不同:它在运行 工作负载的、兼容的 PyTorch/CUDA 或 TorchNPU/Ascend 环境中进行。贡献者请使用独立的 开发与完整检查入口。
| 你已有的输入 | 最短下一步 |
|---|---|
SnapshotDB .db |
跳过导入,在第二步直接使用其路径。 |
完整的原生或 compatibility-v1 数据集目录 / manifest.json |
跳过导入,在第二步显式指定该目标。保留全部成员,不能只拿一个 ready 分片。 |
可信的 .pkl / .pickle 快照 |
完成第一步,再分析生成的 DB。 |
| 尚无快照 | 先看下面的采集入口,随后单独决定是否进行可信导入。 |
- CUDA/PyTorch: 在工作负载的 GPU 环境中,按 PyTorch 官方快照指南 记录分配器历史。核实已安装 PyTorch 版本的 API,选择有界记录窗口,在相关工作负载 阶段结束后导出快照。安装离线 CLI 不会自动插桩或启动训练任务。
- 昇腾 NPU: 使用 pt-snap-ascend-npu-collect 检查 TorchNPU API/环境并选择框架对应的采集路径。明确采集 rank、step 窗口和输出位置。 宿主已加载该 skill 时,无需先有 CLI 即可指导采集;参见 Agent Skills。
- CSV、SVG 或截图不是 SnapshotDB。请获取数据库或原始可信 pickle,不要将可视化文件
改名为
.db。
采集会改变工作负载的记录行为并写出 pickle,不是只读分析,应单独审阅采集计划。 把 pickle 复制到离线机器并不会使反序列化变得安全。
安全警告: 只能导入你信任的 pickle 快照。反序列化可能执行任意代码;实现会 拒绝非
builtins全局对象,但pt-snap import不是沙箱。Agent 的 setup 或采集 授权不等于 pickle 导入授权。
pt-snap import snapshot.pkl默认在源 pickle 旁生成 snapshot.pkl.db,并更新当前工作目录中的
.pt-snap/focus.json(项目 focus)。--output-dir captures 改变输出父目录,不改变
文件名。若希望创建或复用 DB,但不修改 focus:
pt-snap import snapshot.pkl --no-focus--no-focus 不等于 no-replace: 单库缓存未命中或使用 --force 时,可能替换
已有同名 .db。请先确认该输出可被替换,或在导入前选择另一个 --output-dir。
下面的分析示例均显式传入路径和设备,两种导入选择都可使用。将 snapshot.pkl.db
换成实际 DB 或完整数据集路径。导入是写操作;overview、内建查询和报告不修改源数据,
也不持久化 focus。数据集查询可能在工作限额内使用私有临时
scratch 存储。
pt-snap overview snapshot.pkl.db --json检查 db_path,从 devices 中选择 device_id。下文以 0 为例,请替换为实际返回的
设备。数据集还需检查 dataset.status、format 和 fingerprint。目标无效或
import_metadata.status: "invalid" 时停止;旧数据的 "unavailable" 且 reason 为
"metadata_missing" 表示导入来源未知,不等于已确认损坏。其他未知状态/原因应先调查,
再进行诊断。
pt-snap query snapshot.pkl.db --device 0 --template-use memory_peak --json以下是示意的 rows[0],不是对你的快照输出的承诺:
{
"peak_allocated": 8388608,
"peak_allocated_event_id": 10,
"peak_active": 10485760,
"peak_active_event_id": 12,
"peak_reserved": 16777216,
"peak_reserved_event_id": 10
}三个大小均以**字节(bytes)**为单位,此例分别为 8、10、16 MiB
(1 MiB = 1048576 bytes)。
| 计数器 | 分配器回放历史中的含义 |
|---|---|
allocated |
已分配 block 的字节数,不含已标为 pending free 的 block;是 block 大小,不是请求的 tensor payload 大小。 |
active |
已分配与 pending-free、尚不可复用的 block 字节数之和。 |
reserved |
分配器持有的 segment 总字节数,包含 inactive 容量;不是整个进程/设备的全部内存。 |
各指标独立选取最早达到峰值的事件,event ID 表示顺序而非时间戳。不能把不同事件的峰值 直接相减当作同一时刻的差值。真实事件范围为空时峰值为 null,不得虚构事件。 reserved/active 差值大,本身不能证明碎片、泄漏或 OOM 原因。
pt-snap report peak-memory snapshot.pkl.db --device 0 --metric active --limit 20输出包含 Peak memory report、选定的设备/指标/事件、各项独立峰值、同事件分配器
差值和 Active memory by callstack。报告解释所选峰值事件的 active blocks,
不是分解全部 reserved 字节。下结论前检查归因完整性标签和 active 字节覆盖率:
分组百分比以过滤/排名后 included_bytes 为分母,并非全部 active 内存。
有上限的报告可能不完整;预算错误不等于部分分析成功。自动化可加 --json。
限额与分母详见报告合同。
pt-snap focus snapshot.pkl.db --device 0
pt-snap report peak-memory与上面的显式路径分析不同,focus <path> 会写项目 focus。不想改变共享项目状态就跳过。
默认导入可能已经选择了 DB;此命令还会选择你指定的设备。参见
focus 优先级与会话隔离。
这些都是可选项,不是第一份报告的前置条件。
--events-per-slice 显式启用原生数据集,但不会让 pickle 加载变为流式,也不限制峰值
RSS。输出路径、完整成员校验、force/恢复行为及支持的内建查询见
原生导入合同和
全局支持矩阵。原生产物不是 msinsight 兼容格式。
--format msinsight 是显式选择。已有兼容目标即使 --force 也不替换;兼容性、
缓存校验、GUI 入口及固定版本证据有独立的
协议合同。声称 GUI 复用前请阅读
已记录的互操作验收,仅 hash 相同不等于 GUI 验收通过。
当前导出使用 parser v3。固定的 101f65b revision 及 targetRevision 仅为历史
v2 schema/身份参考,不是当前导出的已核验 GUI 消费端;目前尚无已核验的 v3 消费端
固定 revision/build。不要用旧 GUI 打开当前缓存,它可能重新解析并改写缓存。
后续 v3 验收必须使用独立可信 pickle 副本及新建邻接缓存,保留原始产物。
兼容复用检查源身份、sourceFile、选项、合同版本、完整成员清单及必要的只读结构。
历史成员哈希字段仅作为清单,不比较摘要值。导入不对数据库内容取哈希,也不扫描任意
行值,因此结构合法的内容编辑可以被复用。查询和显式验证器独立执行准入检查;
复用成功不证明数据库内容完整或 GUI 缓存复用。--output-dir 选择其他父目录,
搬迁数据集不意味着建立 GUI 入口。
pt-snap split 生成可独立回放的文件,不是待查询数据集。它同样需要可信 pickle,
只选一种拆分策略,并使用尚不存在的输出目录;不会改变 focus。参见拆分快照。
单库导入保存源 SHA-256 和兼容性 metadata,相同内容/选项可复用 DB;缓存未命中
(包括缺失/无效 metadata)和 --force 都会重建,并可能替换同名 DB。它与原生/兼容
目录的策略不同,并没有未知目标保护门禁。请先确认输出所有权或选择其他 --output-dir。
不要仅因分析失败就强制重建,应先检查错误。
导入会在回放前完整加载 pickle;--device 减少后续工作,不降低最初的加载峰值。
请预留足够内存。snapshot 运行时模块不是公开 API。
- Agent Skills — 安装、重启、验证并发起诊断
- 查询指南 — 模板、有界结果、栈详情与报告
- Focus 管理 — 可选的持久化/会话目标
- 数据库格式 — 计数器、metadata 与哨兵含义
- SnapshotAnalyzer API — 明确资源生命周期的 Python 分析