z4ai

A lossless compression codec for AI model checkpoints.

Keep model checkpoints small for storage and transfer - bit-for-bit reversible, with per-tensor random access. Most useful on collections of related checkpoints (training runs, fine-tune families, model registries), and in environments the Hugging Face Hub's Xet backend doesn't cover - self-hosted registries, internal MLOps, plain object storage.

Documentation - quickstart, full usage, how it works, and the API reference.

pip install z4ai

import z4ai

blob = z4ai.compress(weights_bytes)   # smaller, self-describing
data = z4ai.decompress(blob)          # byte-identical original
assert data == weights_bytes

Its strongest case is a sequence of related checkpoints - consecutive ones are ~95-99% identical, so each is stored as a tiny delta from the one before:

# store checkpoint N as the bit-exact delta from checkpoint N-1
delta    = z4ai.compress_delta(step_2000, reference=step_1000)
restored = z4ai.decompress_delta(delta, reference=step_1000)   # exact == step_2000

# only the changed bytes cost anything - often 10-100x smaller than a full compress

Or from the command line, on files:

z4ai compress   weights.bin -o weights.z4ai
z4ai decompress weights.z4ai -o weights.bin
z4ai info       weights.z4ai            # ratio + per-plane breakdown

Requires Python >= 3.9; pure Python (NumPy + zstandard), with optional native acceleration.

TL;DR

z4ai is a codec built for the byte structure of float tensors. Compared with ZipNN (the closest weights-specific codec):

• Ties on dense weights, with a slight edge on real models (distilgpt2 +1.6-8.2%, pythia-70m +11-29%) from an order-1 context exponent coder.
• Wins big on repeated structure - tied embeddings, duplicated layers, multi-shard concatenations - which z4ai dedups across the whole tensor.
• 2.3-3.0x on reduced-precision fp32 files (fp16/bf16-origin values), automatically.
• 2.4-10.8x on quantized weights shipped in a wide container - INT4/INT8/FP8 (GPTQ / AWQ / compressed-tensors) dequantised into bf16/fp16/fp32 - via an automatic lossless palette transform. This is the common deployed format, and z4ai beats ZipNN on every case here (e.g. INT8-in-fp32 4.72x vs 1.94x; INT4-in-fp32 10.8x vs 4.6x).
• Big wins on sparse / pruned weights, and 10-180x on checkpoint sequences via the lossless compress_delta mode - which ZipNN has no equivalent for.
• Slower to compress than ZipNN's compiled-C core; decompress is competitive.

Honest ceiling. On a dense checkpoint a trained float's mantissa is near-random and its exponent carries only ~2.6 bits, capping any lossless codec at ~1.5x (bf16) / ~1.2x (fp32). ZipNN already hits that wall, so z4ai can't meaningfully out-ratio it there - it wins by a hair via order-1 rANS on the exponent. The large wins come from redundancy the entropy bound assumes away: reduced precision, sparsity, structure, and cross-checkpoint deltas.

All numbers below are measured on this repo and reproducible with one command.

Benchmarks vs ZipNN

_{Machine: 16 cores | Python 3.14 | zstandard 0.25.0 | zipnn (latest) | 32 MB per dtype | best-of-3 timing. Every codec is verified byte-exact (lossless).}

Compression ratio (higher is better)

_{Quantized rows: per-tensor INT4/INT8 weights dequantised back into a wide float container (the format most quantized models ship in), same 32 MB/dtype config as above. z4ai auto-selects the lossless palette transform; several ZipNN entries here are not byte-exact on the tested build. Reproduce with python benchmarks/bench_palette.py (which reports a stronger zstd-19 baseline, so z4ai's margin there is conservative).}

Real & production workloads

python benchmarks/benchmark.py --mb 32 --dtypes bf16 fp32 --scenario iid
python benchmarks/benchmark.py --mb 32 --dtypes bf16 fp32 --scenario structured
python benchmarks/benchmark.py --mb 32 --dtypes bf16 fp32 --scenario sparse
python benchmarks/bench_real_checkpoint.py        # downloads a real .bin checkpoint
python benchmarks/bench_safetensors.py --layers 8 --d 1024
python benchmarks/checkpoint_bench.py --mb 96     # realistic structured checkpoint

Throughput

z4ai compresses ~6x slower and decompresses ~1.2x slower than ZipNN's compiled-C core - the deliberate trade for a write-once, read-many artifact. A fused multithreaded native codec (z4ai.chunked) and effort="fast"/"max" tiers trade decode latency against file size.

How it works

A float is [ sign | exponent | mantissa ]: in trained weights the exponent bits repeat heavily while the mantissa looks like noise, and the two are interleaved byte-by-byte - so a general-purpose zip can't separate them (plain zstd on raw fp32 barely reaches ~1.06x). z4ai pulls the bytes apart, matches redundancy across the whole tensor, then entropy-codes each part near its floor:

flowchart TD
    IN["Float tensor bytes<br/>(bf16 / fp16 / fp32 / fp64)"]
    IN -->|split by dtype| SPLIT["Plane / bit-field split"]
    SPLIT --> EXP["Exponent / sign plane<br/>(low entropy)"]
    SPLIT --> MAN["Mantissa plane<br/>(noise-like)"]
    EXP --> ENT["Entropy coding<br/>(rANS / zstd)"]
    MAN --> STORE["Store verbatim, or zstd"]
    ENT --> LDM["Whole-tensor long-distance matching<br/>dedups tied / repeated weights"]
    STORE --> LDM
    LDM --> BEST["Best-of selection: keep the smallest<br/>never worse than plain zstd"]
    BEST --> OUT["Self-describing container<br/>(.z4ai / .zstn)"]

Decoding is the exact inverse, driven entirely by the self-describing header - no side-channel metadata, and the output is never larger than the input. Pruned weights take a zero-aware path; the safetensors/ZSTN container adds a per-tensor index for random-access reads and stores tied weights once.

References

z4ai's building blocks are well-studied; the contribution is applying them to the byte structure of model weights and matching across the whole tensor - and across checkpoints. On dense weights it cannot meaningfully out-ratio ZipNN (the entropy ceiling binds every lossless codec equally); the wins come from structure, reduced precision, sparsity, and cross-checkpoint deltas.

• Float field decorrelation - Lindstrom & Isenburg, fpzip, IEEE TVCG 2006 (project); applied to NN weights by ZipNN (the codec benchmarked against here).
• Long-distance LZ matching - Ziv & Lempel, LZ77 (1977), via Zstandard (RFC 8878).
• Entropy coding (rANS) - Duda, Asymmetric Numeral Systems (2013).
• Cross-checkpoint / cross-model delta - ZipLLM (NSDI 2026) - the basis for compress_delta / model_delta.

The full survey (DFloat11, NeuZip, DietGPU, ECF8, ALP, Pcodec, the BF16 entropy ceiling) is in the docs.