GGUF Parsing

GGUF Parsing

Modules: src/gguf/{mod,cursor,layout,tensor}.rs.

Entry points

Function	Behavior
load_gguf(path)	fs::read whole file → parse_bytes
parse_bytes(bytes, path)	Parse in-memory buffer; path for errors

Pipeline

1. Header — magic GGUF, version 3, tensor_count, kv_count (bounded ≤ 1_000_000 each)
2. KV metadata — strings / numerics / f32 / f64 maps; arrays skipped; general.alignment sets alignment (default 32)
3. Tensor directory — name, dims (≤ 8), ggml_type, relative offset → Tensor metadata
4. Finalize — align cursor to compute tensor_data_offset and absolute offsets

GgufLayout

Field	Meaning
path	Source path for diagnostics
metadata	GgufMetadata
tensors	HashMap<String, Tensor>
alignment	File alignment
tensor_data_offset	Start of payload region
bytes	Full file contents

Helpers: tensor(name), tensor_bytes(&Tensor), find_tensors_with_suffix(suffix).

GgufMetadata

• architecture() → general.architecture or "unknown"
• numeric(key) → Option<usize> from coerced u64 map

Cursor

GgufCursor — little-endian scalars, length-prefixed UTF-8 strings, numeric coercion, skip_value for arrays/unknowns.

Related

• Tensor and DType
• Errors

---

Last updated: July 29, 2026 Updated by: Grok Build: Grok 4.5 Package tip reference: 07a5558 (main)