Skip to main content

ferrite_model/
gguf_config.rs

1#[derive(Clone, Copy, Debug, PartialEq, Eq)]
2/// A model architecture supported by Ferrite's GGUF configuration parser.
3pub enum ModelArchitecture {
4    /// The Llama transformer family.
5    Llama,
6    /// The Qwen2 transformer family, including Qwen2.5 models that use this
7    /// GGUF architecture identifier.
8    Qwen2,
9}
10
11impl ModelArchitecture {
12    pub(crate) fn from_metadata(value: &str) -> Option<Self> {
13        match value {
14            "llama" => Some(Self::Llama),
15            "qwen2" => Some(Self::Qwen2),
16            _ => None,
17        }
18    }
19
20    pub(crate) fn metadata_value(self) -> &'static str {
21        match self {
22            Self::Llama => "llama",
23            Self::Qwen2 => "qwen2",
24        }
25    }
26
27    pub(crate) fn metadata_prefix(self) -> &'static str {
28        self.metadata_value()
29    }
30}
31
32#[derive(Clone, Debug, PartialEq)]
33/// Validated transformer configuration selected by architecture.
34pub enum ModelConfig {
35    /// A Llama-family model configuration.
36    Llama(TransformerConfig),
37    /// A Qwen2-family model configuration.
38    Qwen2(TransformerConfig),
39}
40
41#[derive(Clone, Debug, PartialEq)]
42/// Architecture-independent transformer dimensions read from GGUF metadata.
43pub struct TransformerConfig {
44    /// The model architecture that determined the metadata prefix and defaults.
45    pub architecture: ModelArchitecture,
46    /// The maximum model context length in tokens.
47    pub context_length: u64,
48    /// The hidden-state width.
49    pub embedding_length: u64,
50    /// The number of transformer blocks.
51    pub block_count: u64,
52    /// The feed-forward network width.
53    pub feed_forward_length: u64,
54    /// The number of query attention heads.
55    pub attention_head_count: u64,
56    /// The number of key and value attention heads.
57    pub attention_head_count_kv: u64,
58    /// The key dimension for each attention head.
59    pub key_length: u64,
60    /// The value dimension for each attention head.
61    pub value_length: u64,
62    /// The RMS normalization epsilon, when the GGUF metadata specifies one.
63    pub attention_layer_norm_rms_epsilon: Option<f32>,
64    /// The number of key dimensions transformed by rotary position encoding.
65    pub rope_dimension_count: u64,
66    /// The rotary position encoding frequency base, when explicitly specified.
67    pub rope_freq_base: Option<f32>,
68}
69
70/// Backward-compatible name for a Llama transformer configuration.
71pub type LlamaConfig = TransformerConfig;
72
73impl TransformerConfig {
74    /// Returns the grouped-query attention ratio when the head layout is valid.
75    ///
76    /// A result of `None` means the key/value head count is zero or does not
77    /// divide the query head count evenly.
78    pub fn gqa_ratio(&self) -> Option<u64> {
79        if self.attention_head_count_kv == 0 {
80            return None;
81        }
82
83        if self
84            .attention_head_count
85            .is_multiple_of(self.attention_head_count_kv)
86        {
87            Some(self.attention_head_count / self.attention_head_count_kv)
88        } else {
89            None
90        }
91    }
92}