Struct GgufReader 

pub struct GgufReader {
    pub version: u32,
    pub tensor_count: u64,
    pub tensors: Vec<GgufTensorMeta>,
    pub data_offset: usize,
    pub metadata: BTreeMap<String, GgufValue>,
    /* private fields */
}

Parsed GGUF file for import

Fields

version: u32

Format version

tensor_count: u64

Number of tensors

tensors: Vec<GgufTensorMeta>

Tensor infos (name, dims, dtype, data_offset)

data_offset: usize

Offset where tensor data section starts

metadata: BTreeMap<String, GgufValue>

Metadata key-value pairs (extracted from GGUF)

Implementations

impl GgufReader

pub fn from_file<P>(path: P) -> Result<GgufReader, AprenderError>

where P: AsRef<Path>,

Load and parse a GGUF file

pub fn from_file_full<P>(path: P) -> Result<GgufReader, AprenderError>

where P: AsRef<Path>,

Load a GGUF file preserving ALL metadata keys (no architecture whitelist).

Used by the sharded-GGUF merge (super::merge::merge_gguf_shards) so arbitrary <arch>.* config keys (gemma., phi3., deepseek2.*, …) survive into the merged file — otherwise the merged model is unloadable for any architecture outside the parse whitelist.

pub fn from_bytes(data: Vec<u8>) -> Result<GgufReader, AprenderError>

Parse GGUF from bytes (whitelist metadata — back-compat default).

pub fn from_bytes_keep( data: Vec<u8>, keep_all: bool, ) -> Result<GgufReader, AprenderError>

Parse GGUF from bytes. When keep_all is true EVERY metadata key is retained; otherwise only tokenizer. / general. / known-arch keys are parsed (the rest skipped for efficiency).

pub fn vocabulary(&self) -> Option<Vec<String>>

Get vocabulary tokens from metadata

Returns the token strings indexed by token ID. Uses “tokenizer.ggml.tokens” key from GGUF metadata.

pub fn tokenizer_model(&self) -> Option<String>

Get tokenizer model type (e.g., “llama”, “gpt2”)

pub fn bos_token_id(&self) -> Option<u32>

Get BOS (beginning of sequence) token ID

pub fn eos_token_id(&self) -> Option<u32>

Get EOS (end of sequence) token ID

pub fn merges(&self) -> Option<Vec<String>>

Get BPE merge rules from metadata (PMAT-171)

Returns the merge rules as “token1 token2” strings for BPE encoding. Uses “tokenizer.ggml.merges” key from GGUF metadata.

pub fn architecture(&self) -> Option<String>

Get general architecture name (e.g., “llama”, “qwen2”)

pub fn model_name(&self) -> Option<String>

Get model name from metadata

pub fn hidden_size(&self) -> Option<usize>

Get hidden dimension (embedding_length)

pub fn num_layers(&self) -> Option<usize>

Get number of transformer layers (block_count)

pub fn num_heads(&self) -> Option<usize>

Get number of attention heads

pub fn num_kv_heads(&self) -> Option<usize>

Get number of key-value heads (for GQA)

pub fn vocab_size(&self) -> Option<usize>

Get vocabulary size

pub fn intermediate_size(&self) -> Option<usize>

Get FFN intermediate dimension

pub fn context_length(&self) -> Option<usize>

Get maximum context length

pub fn rope_theta(&self) -> Option<f32>

Get RoPE theta (frequency base)

pub fn rms_norm_eps(&self) -> Option<f32>

Get RMS norm epsilon (or standard LayerNorm epsilon for GPT-2)

pub fn token_type(&self) -> Option<Vec<i32>>

Get per-token type array (tokenizer.ggml.token_type) Values: 1=normal, 2=unknown, 3=control/special, 4=user_defined, etc.

pub fn padding_token_id(&self) -> Option<u32>

Get padding token ID (tokenizer.ggml.padding_token_id)

pub fn add_bos_token(&self) -> Option<bool>

Get add_bos_token flag (tokenizer.ggml.add_bos_token)

pub fn chat_template(&self) -> Option<String>

Get chat template (tokenizer.chat_template)

pub fn pre_tokenizer_type(&self) -> Option<String>

GH-277: Get pre-tokenizer type (tokenizer.ggml.pre)

impl GgufReader

pub fn get_tensor_f32( &self, name: &str, ) -> Result<(Vec<f32>, Vec<usize>), AprenderError>

Extract a tensor as F32 data (dequantizing if needed)

Postcondition: data.len() == shape.iter().product()

pub fn get_all_tensors_f32( &self, ) -> Result<BTreeMap<String, (Vec<f32>, Vec<usize>)>, AprenderError>

Get all tensors as F32

pub fn get_all_tensors_f32_with_progress( &self, progress: impl Fn(usize, usize, &str), ) -> Result<BTreeMap<String, (Vec<f32>, Vec<usize>)>, AprenderError>

Get all tensors as F32 with per-tensor progress callback.

Contract: GH-692 — progress feedback for large GGUF dequantization. Callback receives (current_index, total_count, tensor_name).

pub fn get_tensor_raw( &self, name: &str, ) -> Result<(Vec<u8>, Vec<usize>, u32), AprenderError>

Get raw tensor bytes without dequantization (preserves Q4K/Q6K)

Returns (raw_bytes, shape, ggml_dtype) where dtype is per GGML spec:

• 0=F32, 1=F16, 2=Q4_0, 3=Q4_1, 8=Q8_0
• 10=Q2_K, 11=Q3_K, 12=Q4_K, 13=Q5_K, 14=Q6_K

pub fn get_all_tensors_raw( &self, ) -> Result<BTreeMap<String, (Vec<u8>, Vec<usize>, u32)>, AprenderError>

Get all tensors as raw bytes (preserves quantization)

Returns BTreeMap of name -> (raw_bytes, shape, ggml_dtype)

Trait Implementations

impl Debug for GgufReader

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.