Checkpoint import audit
Memory and loading Before loading an imported checkpoint, the engine reads only its Safetensors headers and index, and checks that every tensor it needs is there with the exact type, shape and packed layout.
In an engine
No slot holds it: a model plugin calls it before loading.
The problem
- A converted, renamed or sharded checkpoint can be full of plausible tensor names and still lack one the engine needs, such as a projection of its multi-token prediction (MTP) layer.
- Labels and counts prove nothing about storage. A model called BF16 can hold a tensor stored in another data type (dtype).
- Packed low-bit weights can arrive with group scales cut for a different slice of the matrix.
How it works
- Each Safetensors file starts with 8 bytes that give the length of its JSON header. The audit reads that header, up to a set limit, and never the tensor data after it.
- The header is strict JSON. Each tensor's size, worked out from its stored dtype and shape, must match its byte offsets, and the tensors must cover the data in order with no gap or overlap.
- The index must agree with the headers. Every name is in the shard it points to, none appears twice, and
total_sizeequals the summed sizes. - The engine's schema asks for each role it needs by exact key, dtype and shape, and the header must match. A feature such as MTP passes only when all of its roles are bound.
- A packed matrix may be split along K, the length of its rows. The slice of K a file holds fixes how many packed words and how many group scales each row must have, and scales for any other slice are rejected.
Pays off when
- The checkpoint was converted, renamed, fused or split by a tool the engine does not control.
- The engine needs optional parts such as an MTP layer, or loads packed low-bit weights with group scales.
- The weights are large, so a problem is cheaper to find in a few kilobytes of headers than after loading gigabytes.
Doesn't pay off when
- An importer the engine already trusts makes the same checks.
- The model comes as GGUF, a PyTorch pickle or in 4-bit or 6-bit storage dtypes, which the audit does not read.
- The question is whether the numbers are right. The audit never reads values, so NaNs, bad scales or a wrong codebook pass it.
What must stay true
- The audit trusts the dtype and shape each header actually stores, never names, counts or a descriptive label.
- A shard map that disagrees with the headers, an unsupported dtype or a missing requested role rejects the import.
- Packed words and their scales cover the same slice of K and sit under the same matrix name.
- Passing says the metadata fits. It never proves the arithmetic, the quality or the speed.
crit-hub