SafeTensors Visualisation 是一个面向 LoRA 与 .safetensors 模型文件的结构可视化与架构差异分析工具。项目以轻量、可复现、非侵入式为设计原则,适用于模型转换校验、LoRA 结构审查、训练产物归档检查,以及不同生态格式之间的架构一致性分析。
本工具只解析 .safetensors 文件头部的 JSON metadata,不读取、不加载、也不比较权重 payload。因此,它可以在不触碰模型参数内容的前提下,对 tensor 名称、dtype、shape、offset 与 metadata 进行快速分析。
- 单文件结构概览:统计 tensor 数量、dtype 分布、shape 推导参数量、LoRA rank 分布与 metadata keys。
- 架构树可视化:按 tensor name 的层级片段展开结构,并在 group 层显示聚合 dtype。
- Tensor 表格检索:以列表方式查看所有 tensor 的 name、dtype、shape、参数量与 data offsets。
- Metadata 查看:展示
.safetensors中的__metadata__内容。 - 架构差异报告:对比两个
.safetensors文件的结构差异,不比较权重值。 - 表格化 diff:通过
Name | Left | Right | Diff的形式快速定位结构不一致项。
Architecture Diff 只比较结构层面的信息,主要包括:
- tensor name 是否同时存在于左右文件;
- 共享 tensor name 的 dtype 是否一致;
- 共享 tensor name 的 shape 是否一致;
- LoRA module signature 是否一致;
- 经过常见前缀归一化后的 LoRA module signature 是否一致;
- 忽略 tensor name 后的 shape/dtype inventory 是否一致;
__metadata__的 key 与 value 差异。
状态列含义如下:
| 状态 | 含义 |
|---|---|
Same |
左右文件中同名 tensor 的 dtype 与 shape 完全一致 |
Diff |
左右文件中同名 tensor 存在 dtype 或 shape 差异 |
Only left |
tensor 只存在于左侧文件 |
Only right |
tensor 只存在于右侧文件 |
示例:
diffusion_model.double_blocks.4.txt_attn.proj.lora_A.weight | BF16 [32, 3072] | F16 [32, 4096] | Diff
该项目使用 Python 标准库实现主要功能,并使用 Tkinter 提供桌面界面。通常不需要额外安装第三方依赖。
建议环境:
- Python 3.10 或更高版本;
- 可用的 Tkinter 运行环境;
- 本地存在待分析的
.safetensors文件。
默认读取当前项目下的 ./loras 目录:
python3 safetensors_visualizer.py指定其他 LoRA 或模型目录:
python3 safetensors_visualizer.py --dir /path/to/loras界面包含以下视图:
Summary:文件结构摘要;Architecture Tree:按层级展示 tensor group;Tensor Table:可搜索、可排序的 tensor 明细表;Metadata:文件头部 metadata;Architecture Diff:文本形式的完整结构差异报告;Arch Diff (Table):表格形式的逐项结构 diff。
左侧文件栏支持拖动调整宽度,便于查看长文件名或扩展主工作区。
查看单个文件摘要:
python3 safetensors_visualizer.py --summary loras/comfy-style.safetensors比较两个文件的架构差异:
python3 safetensors_visualizer.py \
--diff loras/comfy-style.safetensors loras/diffusers-style-comfy.safetensors限制每个 diff 区块展示的明细行数:
python3 safetensors_visualizer.py --diff left.safetensors right.safetensors --limit 20SafeTensors Visualisation 的分析范围限定在文件头部 JSON。工具不会执行以下操作:
- 不读取 tensor 权重 payload;
- 不计算权重数值差异;
- 不修改原始
.safetensors文件; - 不上传本地文件或依赖远程服务。
这使其适合在研究工作流中作为结构审查工具使用,尤其适用于需要避免泄露或处理模型权重内容的场景。
- 比较不同 LoRA 导出格式的架构差异;
- 检查模型转换前后的 tensor name、dtype 与 shape 是否一致;
- 快速定位缺失 tensor 或额外 tensor;
- 审查 LoRA rank 分布与模块覆盖范围;
- 为实验记录、模型发布和复现实验提供结构摘要。
.
├── safetensors_visualizer.py # 主程序:GUI、header parser 与 CLI diff
├── README.md # 项目说明
└── loras/ # 示例或待分析的 .safetensors 文件目录