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}