The MOG File Format

File layout

The first part of the file contains metadata. It identifies the model architecture with the model configuration, contains the tokenizer, and records the location of every tensor. The remainder of the file contains encoded tensor data.

Header

Every MOG file begins with a small preamble followed by the model configuration. The preamble contains the file magic, format version, and architecture identifier, allowing the runtime to verify the file format. The configuration contains the parameters required to construct the model, such as its hidden dimension, layer count, and context length. MOG uses a single configuration structure that can represent every supported architecture. The configuration is written directly to the file during export and loaded with a single structure read, requiring no manual parsing.

Tokenizer

The tokenizer section contains the data required to reproduce the model’s byte-pair encoding (BPE) tokenizer during inference. It stores the vocabulary together with the merge graph that defines how tokens are combined during encoding.

The vocabulary is stored in forms optimized for both directions of tokenization: a direct mapping from token IDs to text for decoding, and a lexicographically sorted vocabulary for binary-search lookup during encoding. The merge graph is stored as a sorted array of token pairs, enabling efficient lookup of merge rules during encoding.

Tensor directory

The tensor directory is an array of fixed-size records, with one record for every tensor slot defined by the model architecture. Each record stores the tensor's dimensions, encoding, and the absolute offsets of its data and optional scale buffer within the payload.

The directory layout matches the runtime tensor structure, allowing it to be loaded with a single memory copy. During loading, the stored offsets are resolved into pointers relative to the mapped file. Records corresponding to tensors that are not present in the current model are left empty.

Payload

The payload is a contiguous sequence of encoded tensors stored in tensor directory order. Each tensor occupies a contiguous data buffer and may optionally include a contiguous scale buffer.

Recipes

MOG files can be generated from a local Hugging Face checkpoint with qpack. It uses a recipe to select the configuration values, tokenizer data, and tensors stored in the output file. The recipe also assigns each tensor its runtime name and encoding, allowing you to change the model's quantization tensor by tensor.

The distinction between source and runtime names matters because model repositories do not use one naming convention. This entry selects an embedding tensor from the checkpoint, assigns it the MOG name embed, and chooses its encoding:

{
"name": "embed",
"file": "weights",
"path": "model.language_model.embed_tokens.weight",
"encoding": "int4_g64_f32"
}

Transformer layers repeat the same tensor roles. A recipe can express those mappings once with a loop:

{
"for": "layer",
"range": [0, 4],
"entries": [
{
"name": "layers.{layer}.q_proj",
"file": "weights",
"path": "model.language_model.layers.{layer}.self_attn.q_proj.weight",
"encoding": "int4_g64_f32"
}
]
}

Recipes make encoding experiments quick. To test a new combination, change the JSON recipe and export another MOG file. For example, you can replace 16-bit floating point with grouped 8-bit integers for a projection, try a different 4-bit integer packing scheme, or keep selected weights in 32-bit floating point. You can then benchmark each encoding for model size and inference speed using the same runtime.

Try it

Qpack includes a consumer.c, a minimal loader for trusted MOG files. It reads the model configuration, tokenizer, and tensor directory, then resolves the recorded payload offsets into tensor pointers.

For more details about the MOG format, see the MOG specification.