GitHub - las7/weight-inspect: Deterministic analyzer for ML file formats

Inspect GGUF, safetensors, and ONNX model files to see architecture, tensor shapes, dtypes, quantization, and metadata.

Quickly answer:

What model architecture is this?
What quantization is used?
What are the tensor shapes?
How does this compare to another model?

Also provides a deterministic structural fingerprint to verify if two models have the same structure.

The Problem

Model files are opaque blobs. When you download or convert a model, you can't easily see what's inside.

The Solution

weight-inspect reads model file headers and shows you the structure — tensor names, shapes, dtypes, metadata — without loading any weight data.

This lets you:

See what's in any model file
Compare two models
Get a deterministic fingerprint to verify structural identity

Quick Start

weight-inspect summary model.gguf   # Quick glance (for scripts)
weight-inspect inspect model.gguf   # Full structure details
weight-inspect id model.gguf       # Stable fingerprint
weight-inspect diff a.gguf b.gguf  # Compare two models

Installation

cargo install weight-inspect

Or build from source:

ONNX Support

ONNX support is optional. To enable:

cargo install weight-inspect --features onnx
# or
cargo build --release --features onnx

Usage Examples

Get a fingerprint

$ weight-inspect id model.gguf
Structural identity
──────────────────
ID:        wi:gguf:3:9c1f3d2a
Stable:    yes (machine independent)
Includes:  header, tensor names, shapes, dtypes
Excludes:  raw weight bytes

format: GGUF
structural_hash: 9c1f3d2a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1
tensor_count: 291
metadata_count: 12

One-line summary (for scripting/CI)

$ weight-inspect summary model.gguf
gguf,3,291,12,9c1f3d2a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1

summary is designed to fit on a single line and be safe for scripting, CI pipelines, and automation.

Inspect full details

$ weight-inspect inspect model.gguf --verbose
gguf
───
Version:  3
Tensors:  291
Metadata: 12

Structural summary
──────────────────
Dtypes:  f16 (92%), q4_k (8%)

Structural ID
─────────────
Hash: 9c1f3d2a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1

Tensors (first 10)
──────────────────
Name                                    Dtype     Shape               Bytes
────────────────────────────────────────────────────────────────────────────────
token_embd.weight                      f32       [32000, 4096]      524288000
blk.0.attn.wq.weight                  f16       [4096, 4096]       33554432
blk.0.attn.wk.weight                  f16       [4096, 4096]       33554432
blk.0.attn.wv.weight                  f16       [4096, 4096]       33554432
blk.0.attn.wo.weight                  f16       [4096, 4096]       33554432
blk.0.mlp.gate_proj.weight            f16       [11008, 4096]      90596966
...

Compare two files

$ weight-inspect diff a.gguf b.gguf
DIFFERENT
--------------------
Added tensors:    2
Removed tensors:  0
Modified tensors: 3
Structural ID:    changed

Tensor changes
─────────────
  blk.12.attn.wq.weight
    dtype: f16 -> q4_k
    shape: [4096, 4096] -> [4096, 5120]
  blk.18.mlp.up_proj
    dtype: f16 -> q4_k
  output.weight
    shape: [32000, 4096] -> [32000, 5120]

Or for PR comments:

$ weight-inspect diff a.gguf b.gguf --format md
## Structural Diff

**Status:** [DIFFERENT]

| Change Type | Count |
|-------------|-------|
| Added tensors | 2 |
| Removed tensors | 0 |
| Modified tensors | 3 |

Compare with exit codes (CI)

# Exit code 0 if identical, 1 if different
weight-inspect diff a.gguf b.gguf --fail-on-diff

Show only changes

weight-inspect diff a.gguf b.gguf --only-changes

Verbose output

weight-inspect inspect model.gguf --verbose
weight-inspect diff a.gguf b.gguf --verbose

HTML output (for visualization)

weight-inspect inspect model.gguf --html > inspection.html

JSON output (for tooling)

$ weight-inspect id model.gguf --json
{
  "schema": 1,
  "format": "gguf",
  "structural_hash": "2de46f849506b6a34b02d75796396ab6e1b9e24844a732de2a498463aa98376d",
  "tensor_count": 0,
  "metadata_count": 22
}

What it does

Parses GGUF and safetensors headers
Extracts metadata (hyperparameters, tokenizer config, etc.)
Lists tensor names, dtypes, and shapes
Computes structural hash (deterministic JSON → SHA256)
Compares two files showing structural differences
Unknown or unsupported fields are surfaced explicitly and do not silently affect identity

Structural hashes are versioned implicitly by format and canonicalization rules.

Library Usage

weight-inspect is also available as a Rust library for programmatic use:

use weight_inspect::{gguf, hash, types::Artifact};

let file = std::fs::File::open("model.gguf")?;
let mut reader = std::io::BufReader::new(file);
let artifact = gguf::parse_gguf(&mut reader)?;
let structural_hash = hash::compute_structural_hash(&artifact)?;

println!("Hash: {}", structural_hash);

Add to your Cargo.toml:

[dependencies]
weight-inspect = "0.1"

For ONNX support:

[dependencies]
weight-inspect = { version = "0.1", features = ["onnx"] }

API Modules

Module	Description
`gguf`	Parse GGUF model files
`safetensors`	Parse safetensors files
`onnx`	Parse ONNX files (with `features = ["onnx"]`)
`hash`	Compute structural hashes
`types`	Core types: `Artifact`, `Tensor`, `CanonicalValue`
`diff`	Compare artifacts

What it does NOT do

Never loads weight data - Only reads headers and tensor descriptors
Execute models
Predict runtime compatibility
Security scanning

Why no weight data?

We intentionally only read headers/metadata because:

Fast: Works on huge models without loading gigabytes
Memory safe: No memory spikes on large files
Cross-platform: Deterministic across any machine
Structural focus: Answer "are these the same model?" not "are these identical files?"

If you need content equality (byte-for-byte), that's a separate mode that would require loading all weights.

Design Principles

Deterministic: Same input → same output across machines
Canonical: Floats serialized as bit patterns, maps sorted
No heuristics: Pure structural comparison
Fail fast: Invalid files produce clear errors
Stable output: The same input file will always produce identical output across runs and machines

See SPEC.md for full specification.

Diff Output

Diffs are grouped by type of structural change rather than interpreted for semantic impact.

Use --format md for markdown output suitable for PR comments.

Use cases

"What model is this?" - Get instant structural identity
"Is this the same model?" - Compare structural hashes
"Why are these two models different?" - See exact differences
Verify model file integrity
Compare quantization variants
Detect structural changes in converted models

Roadmap

Support for more formats (PyTorch .pt, TensorFlow .pb)
Configurable hash inputs (include/exclude metadata)
Output format plugins
Git-like status porcelain

Stability Guarantees

Output ordering: Alphabetically sorted (BTreeMap)
Hash versioning: Schema field in JSON output for future compatibility
Breaking changes: Will bump major version in CLI and JSON schema
CI-safe: Use --fail-on-diff for exit codes

Contributing

Contributions are welcome, but please note:

Output stability and determinism are prioritized over new features
Changes that affect identity or ordering require discussion before PR
Please run cargo clippy -- -D warnings before submitting