Skip to content

About

Visualisation for Safetensors

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

5 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 

Repository files navigation

SafeTensors Visualisation

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 20

数据安全与边界

SafeTensors 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 文件目录

About

Visualisation for Safetensors

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages