Repository navigation
Description
概要
pt-snap-cli 已经形成较完整的离线内存诊断工具链:核心分层清晰,测试基础扎实,近期正在强化 Agent 调用契约。当前最值得优先改进的是数据库连接生命周期,其次是运行时边界覆盖和类型告警治理。
本 Issue 记录一次项目整体分析及本地验证结果,并作为后续改进的跟踪入口;以下建议为分析时提出的事项;已完成实施,证据见文末收尾记录。
分析基线
- 分析日期:2026-10-02
- 仓库:
codeasier/pt-snap-cli - 分支:
main - 提交:
c85a357(chore(release): 0.4.0 (#158)) - CLI 版本:
0.4.0 - 验证环境:Linux、Python 3.13.11、临时虚拟环境
- 本次未修改项目代码,验证后 Git 工作区保持干净。
1. 项目定位与能力
项目将 PyTorch 内存快照转换为可查询的 SQLite 数据库,用于分析内存峰值、分配行为、泄漏候选和分配器状态。
| 能力 | 实现方式 |
|---|---|
| 快照导入 | pickle → 分配器回放 → SnapshotDB,支持来源 metadata 和缓存复用 |
| 快照拆分 | 按设备和事件范围生成可独立回放的切片 |
| 数据查询 | YAML 定义参数、SQL、输出字段及解释语义 |
| 高层报告 | 组合查询生成峰值内存归因报告 |
| Python 集成 | SnapshotAnalyzer 提供查询、焦点、元数据和概览接口 |
| Agent 集成 | 结构化 CLI 输出、能力发现和随包 skills |
技术栈为 Python 3.10+、Typer、PyYAML、Jinja2、SQLite 和 setuptools-scm。运行依赖不包含 PyTorch,适合将采集环境和分析环境分开。0.4.0 已移除 MCP 服务,Agent 入口收敛为 skills + CLI。
本次实际加载了 11 个查询模板,分为基础查询、业务分析和统计分析三类;仓库有 6 个随包 skill。
2. 架构与核心流程
Typer CLI / SnapshotAnalyzer
│
▼
core 服务层
┌─────┴─────────┐
▼ ▼
查询、概览、报告 导入、拆分
│ │
query + Context snapshot runtime
│ │
只读 SQLite 回放、建库、切片
| 路径 | 职责 |
|---|---|
src/pt_snap_cli/cli.py |
命令注册、参数适配、终端及 JSON 输出 |
src/pt_snap_cli/api.py |
Python API 门面 |
src/pt_snap_cli/core/ |
共享业务语义、错误转换和结果模型 |
src/pt_snap_cli/query/ |
模板注册、参数校验、SQL 渲染和执行 |
src/pt_snap_cli/context.py |
只读数据库连接、设备发现、布局识别 |
src/pt_snap_cli/snapshot/ |
快照表示、分配器回放、数据库适配和切片 |
skills/ |
Agent 操作与诊断工作流 |
CLI 与 API 共用核心服务,业务规则集中维护;tests/test_contract_cli_api.py 约束两者的归一化行为。
查询链路
核心入口:core/query_service.py:182。
- 按显式路径 →
PT_SNAP_DB_PATH→ 最近祖先项目 focus → 旧版全局配置解析数据库。 - 验证数据库,确定目标设备。
- 从缓存获取只读
Context。 - 校验参数,用 Jinja2 渲染 SQL。
- 根据数据库布局选择 v1/v2 callstack SQL。
- 执行查询,返回分页完整性和语义信息。
值得保留的设计:
- SQLite 使用
mode=ro,分析路径不会写入数据库。 - 未声明的参数会报错,排序字段、排序方向使用
choices限定。 max_rows下沉至 SQL,有限分页通过多取一行判断has_more。- 精确总数按需计算,页面查询和可选计数共享查询时限。
- 长期存活的 API 实例复用连接和已编译模板。
导入与拆分链路
- 导入先生成临时数据库,写入并验证 metadata 后再发布。
- 导入前后比较源文件哈希,检测过程中源文件变化。
- 请求更新 focus 时保留回滚机制,避免报告失败却覆盖原数据库。
- 拆分先在 staging 目录生成文件,逐个回放验证,再以不覆盖目标的方式发布。
相关入口:core/import_service.py、core/snapshot_import_backend.py、core/split_service.py。
3. 突出的设计与工程基础
查询结果有解释边界
模板除字段名称和类型外,还能定义 units、metric_semantics、scope、denominator、sentinel 和 interpretation_limits。
leak_detection返回捕获范围内没有释放完成记录的候选,不直接认定泄漏。allocator_gap明确 reserved 与 active 的差值不能直接认定为碎片。- event ID 被定义为顺序标记,而非时间戳。
这对自动化诊断很有价值:既约束查询输入,也约束结果应该如何被解释。
新旧数据库兼容边界清楚
通过只读结构检查识别 inline callstack 和去重 callstack 两种布局。布局损坏或冲突时,只阻断依赖该布局的查询,不让所有分析能力都失效。
工程验证覆盖面广
CI 配置包含 Python 3.10–3.13 测试矩阵、Ruff、Black、basedpyright、fixture 来源及校验和验证、CLI/API 契约测试、干净 wheel Agent 验收,以及发布版本与 Git tag 一致性检查。发布流程复用质量检查。
4. 本次实际验证结果
在临时虚拟环境中安装 pip install -e '.[dev]' 后运行检查。主要工具版本:pytest 9.1.1、pytest-cov 7.1.0、Ruff 0.16.10、Black 26.5.1、basedpyright 1.40.1、Typer 0.27.2。
| 检查 | 结果 |
|---|---|
pytest tests/test_fixture_provenance.py |
7 通过,先于反序列化测试运行 |
| 全量 pytest + coverage | 1024 通过,1 个预期失败,约 104.69 秒 |
| 总体覆盖率,包含分支 | 约 90% |
ruff check . |
通过 |
black --check . |
通过,155 个文件无需调整 |
| basedpyright | 0 errors,831 warnings,符合当前零错误门槛 |
| CLI 版本和 JSON 模板列表 | 正常,11 个模板可加载 |
全量测试命令(虚拟环境 Python):
python -m pytest --cov --cov-report=term -o addopts='-q --tb=short'类型检查命令(虚拟环境 Python):
python -m basedpyright --pythonpath "$(python -c 'import sys; print(sys.executable)')" --outputjson注意:
- 全量测试报告 142 条警告,其中出现多处 SQLite 连接未显式关闭的
ResourceWarning。 - 唯一预期失败是已记录的兼容性缺口:SQLite 类型映射尚不识别
int | None,见tests/snapshot/test_sqlite_meta.py:34。 - 以上为本机验证结果;本次未重跑其他 Python 版本或完整发布流水线,也未重新测量历史性能基准。
5. 建议的改进优先级
优先级一:补齐数据库连接生命周期接口
本次已单独复现。 SnapshotAnalyzer 持有持久化连接缓存,但没有直接提供 close() 或上下文管理器接口。创建 analyzer、调用 get_database_overview()、丢弃实例并触发垃圾回收,会出现 unclosed database 警告。
最小复现,不依赖快照 fixture:
import gc
import sqlite3
import tempfile
import warnings
from pathlib import Path
from pt_snap_cli.api import SnapshotAnalyzer
with tempfile.TemporaryDirectory() as directory:
db = Path(directory) / "minimal.db"
conn = sqlite3.connect(db)
conn.executescript(
"CREATE TABLE dictionary (id INTEGER);"
"CREATE TABLE trace_entry_0 (id INTEGER);"
)
conn.close()
analyzer = SnapshotAnalyzer(db)
analyzer.get_database_overview()
print(hasattr(analyzer, "close")) # False
print(hasattr(analyzer, "__enter__")) # False
gc.collect()
with warnings.catch_warnings(record=True) as recorded:
warnings.simplefilter("always", ResourceWarning)
del analyzer
gc.collect()
print([str(item.message) for item in recorded])
# Python 3.13: unclosed database in <sqlite3.Connection ...>底层 ContextCache.close() 已存在,调用方可以显式清理缓存,但公共 API 的资源管理不够直观。这说明缺少确定性的清理入口,不据此断言连接会永久泄漏。
- 增加
SnapshotAnalyzer.close()和with支持。 - 明确外部传入缓存时的所有权。
- 为短生命周期服务和测试 fixture 补齐资源清理,定位并消除相关
ResourceWarning。
位置:api.py:40、core/context_cache.py:96。
优先级二:针对核心边界建立回归门槛
总体覆盖率不错,但部分复杂模块相对偏低:
| 模块 | 本次覆盖率 |
|---|---|
snapshot/simulate/simulated_caching_allocator.py |
72% |
snapshot/simulate/snapshot_mutator.py |
74% |
core/snapshot_import_backend.py |
76% |
- 优先补充回放状态边界、异常清理、发布失败和回滚行为测试。
- 基于当前基线建立覆盖率回归约束;
pyproject.toml:119当前fail_under = 0,报告尚未形成门槛。
目标是保护核心行为,不是单纯提高总体百分比。
优先级三:逐步治理类型告警
831 条告警不等同于 831 个功能缺陷,也不阻断当前零错误门槛,但会降低新增问题的可见性。
- 优先收敛公共 API、核心结果结构和 snapshot 数据边界中的
Any/Unknown。 - 修复已有 xfail 记录的 PEP 604 类型映射问题。
优先级四:控制 CLI 模块复杂度
src/pt_snap_cli/cli.py 已有 1539 行,同时处理命令定义、JSON 序列化、文本展示及错误适配。
- 后续扩展时按命令组拆分 CLI 模块,并抽取输出适配逻辑。
- 保留业务规则在
core/,以现有 CLI/API 和 JSON 契约测试保护重构。
结论
项目当前具备较好的可维护基础,核心价值在于“可回放的数据处理 + 有语义约束的查询 + Agent 可消费的接口”。下一阶段优先完善资源管理和回归门槛,会比继续增加命令更有收益。
2026-10-03 实施收尾
全部建议已按独立 PR 落实并合入 main:
| 范围 | 合入 PR | 结果 |
|---|---|---|
| analyzer 生命周期与共享缓存所有权 | #171 | close/with、异常清理、关闭后契约 |
| PEP 604 映射 | #173 | 可空类型正确 affinity,移除既有 xfail |
| 回放/导入异常边界与覆盖率门槛 | #174 | 28 个回放边界和 8 个导入故障测试;修复短写备份及异常 fd 泄漏;总体 90%,backend 90%、allocator 88%、mutator 84% 独立门槛 |
| 剩余资源清理 | #175 | 修复 completion 连接泄漏、fixture/测试自有服务清理;ResourceWarning 和未处理析构异常默认视为错误 |
| 边界优先的渐进类型治理 | #176 | API TypedDict、核心/表示层 object 收窄;三个边界 Any/Unknown 升级为错误 |
| CLI 命令组与输出适配 | #177 | report/skill 独立模块,统一输出与错误适配,core 语义保留 |
最终 main:7f0df45cd476c4748f040df151ee39126b08bc7f。本地全量 1186 passed,无 xfail/资源警告,分支覆盖率 91.39%;basedpyright 0 errors / 767 warnings(同环境原 831,降低 64)。类型治理是本 issue 所要求的渐进、边界优先收敛,不声称全仓所有类型警告已清零。
最终 main CI:Python 3.10–3.13、覆盖率门槛、Ruff/Black/basedpyright、provenance、wheel 构建与干净 wheel Agent 验收全部通过。
Activity
codeasier commentedon Oct 2, 2026
主要架构事实和改进方向成立。已复现 analyzer 回收时的 unclosed database,现有 invalidate_context_cache 或 context_cache.close 可消除警告。建议优先增加直观的 close/上下文管理契约,并明确外部共享缓存的所有权。发布与 focus 回滚已有测试,覆盖率改进应针对具体未覆盖分支。PEP 604 映射缺陷建议独立修复,类型治理和 CLI 拆分分别跟踪。
codeasier commentedon Oct 3, 2026
所有 checklist 项已通过 #171、#173、#174、#175、#176、#177 落实并合入;逐项证据已补入正文。最终 main 7f0df45 的完整 CI 全绿(https://github.com/codeasier/pt-snap-cli/actions/runs/37094723215)。按完成关闭。