GGUF byte layout and validation

Build a teaching container

Parsed tensor layout

Offsets below are decimal. Scroll horizontally to inspect every column.

Actual file bytes

Hexadecimal addresses and bytes, sixteen bytes per row. The dump remains visible when parsing rejects a corrupted file.

Build bytes, then read them back

This experiment serializes a tiny binary container in your browser and then runs a separate parser over those bytes. The result table comes from the parser, not from the control values. Two one-dimensional tensors, demo.weight and demo.bias, each contain the repeating sequence zero through seven. These deliberately small exact integers let you distinguish a storage-layout error from a rounding error. The fixture is educational data, not a trained language model, and its lab architecture is not an executable llama.cpp model.

Change one control at a time

Elements per tensor accepts an integer from one through sixty-four and changes both arrays. Tensor format selects F32 or F16 for both payloads. Alignment selects eight, sixteen, thirty-two or sixty-four bytes. Model name changes a string in metadata; it does not rename the tensors. Fault changes the generated bytes after serialization. Restore defaults returns five elements, F32, alignment thirty-two, name Demo and no fault. Every edit computes immediately. There is no simulated loading delay or artificial playback clock, and the evidence stays available until your next edit.

Trace the container structure

The four magic bytes are 47 47 55 46 in hexadecimal. The next fields encode version three and two counts. Metadata precedes tensor descriptors. Each descriptor identifies dimensions, type and a byte offset relative to the tensor-data section. Padding aligns the data start and tensor offsets. The displayed absolute position adds the data start to the relative offset. Strings carry a UTF-8 byte length, without a terminating zero. This lesson handles little-endian files and a deliberately restricted metadata and tensor subset. See the linked GGUF specification for the broader format.

Reproduce a padding boundary

At defaults, each F32 tensor occupies twenty bytes. The second tensor starts at relative offset thirty-two, leaving twelve bytes between payloads. Change the format to F16: each payload becomes ten bytes, but the second relative offset remains thirty-two and the gap becomes twenty-two. The file therefore shrinks by only ten bytes, not by half. Change alignment to eight: the second F16 tensor starts at sixteen, leaving six gap bytes. Inspect the parsed positions and the hex dump together to see why file size is not simply element count times bits per weight.

Separate metadata from tensor values

Edit Model name from Demo to a longer name and compare the metadata end, index end and data start. The data start changes in alignment-sized steps, while the payload values remain identical. Try an accented character or an emoji: the sixty-four-byte limit counts UTF-8 bytes, not displayed characters. Empty names are allowed in this bounded experiment. Invalid names or element counts clear the old result instead of retaining a successful table beneath an error message. The fixed architecture, three metadata entries and two tensor names make each change easy to isolate.

Investigate rejected containers

Choose Bad magic to corrupt the first byte. Unsupported version writes ninety-nine into the version field. Misaligned offset moves only the second tensor offset by one byte. Overlap makes both tensors claim the same payload range. Truncated payload removes the final byte. Each fault is detected by parsing the resulting bytes; the parser does not receive the selected fault name. Rejected files retain their hex dump for inspection, but never receive a validated tensor table. Return Fault to None to recover the current experiment without resetting your other controls.

Read the evidence carefully

The summary reports the end of metadata and descriptors, the aligned data start, payload bytes and total padding. Table offsets and sizes are decimal; hex-dump row addresses and bytes are hexadecimal. Every row contains up to sixteen actual bytes. Scroll the table or byte dump horizontally on a narrow screen. Complete state evidence includes the entire serialized byte array, writer section markers, independently parsed tensor positions and values, or an explicit rejection reason. Comparing writer markers with parser positions is useful, but matching markers alone would not prove that payload values were decoded correctly.

Respect the scope of the inspector

This is not a general upload validator, quantization benchmark or memory-usage predictor. It supports only two small one-dimensional F32 or F16 arrays, string and unsigned-integer metadata, and four alignment choices. It rejects unsupported structures instead of guessing their sizes. It omits tokenizers, split files, architecture-specific required tensors, quantized blocks and inference. A smaller file does not establish faster cold starts or better model quality. Real quantized containers may mix tensor types; a filename suffix is not enough to calculate every tensor size. Use an appropriate runtime and independent quality measurements for deployment decisions.

Primary format reference: GGML GGUF specification.