Skip to main content

ferrite_model/gguf/
types.rs

1use super::GgufError;
2
3#[derive(Clone, Debug, PartialEq)]
4/// A typed value from the GGUF metadata table.
5pub enum MetadataValue {
6    /// An unsigned 8-bit integer.
7    UInt8(u8),
8    /// A signed 8-bit integer.
9    Int8(i8),
10    /// An unsigned 16-bit integer.
11    UInt16(u16),
12    /// A signed 16-bit integer.
13    Int16(i16),
14    /// An unsigned 32-bit integer.
15    UInt32(u32),
16    /// A signed 32-bit integer.
17    Int32(i32),
18    /// A 32-bit floating-point number.
19    Float32(f32),
20    /// A Boolean value.
21    Bool(bool),
22    /// A UTF-8 string.
23    String(String),
24    /// A homogeneous array of metadata values.
25    Array {
26        /// The declared element type.
27        value_type: MetadataValueType,
28        /// The decoded elements in file order.
29        values: Vec<MetadataValue>,
30    },
31    /// An unsigned 64-bit integer.
32    UInt64(u64),
33    /// A signed 64-bit integer.
34    Int64(i64),
35    /// A 64-bit floating-point number.
36    Float64(f64),
37}
38
39impl MetadataValue {
40    pub(super) fn as_count(&self) -> Result<u64, GgufError> {
41        match self {
42            Self::UInt32(value) => Ok(u64::from(*value)),
43            Self::UInt64(value) => Ok(*value),
44            other => Err(GgufError::new(format!(
45                "metadata value {other:?} is not a supported count"
46            ))),
47        }
48    }
49
50    pub(super) fn as_f32(&self) -> Result<f32, GgufError> {
51        match self {
52            Self::Float32(value) => Ok(*value),
53            other => Err(GgufError::new(format!(
54                "metadata value {other:?} is not a supported float32"
55            ))),
56        }
57    }
58}
59
60#[derive(Clone, Copy, Debug, PartialEq, Eq)]
61#[repr(u32)]
62/// The type tag attached to a GGUF metadata value.
63pub enum MetadataValueType {
64    /// Unsigned 8-bit integer.
65    UInt8 = 0,
66    /// Signed 8-bit integer.
67    Int8 = 1,
68    /// Unsigned 16-bit integer.
69    UInt16 = 2,
70    /// Signed 16-bit integer.
71    Int16 = 3,
72    /// Unsigned 32-bit integer.
73    UInt32 = 4,
74    /// Signed 32-bit integer.
75    Int32 = 5,
76    /// 32-bit floating-point number.
77    Float32 = 6,
78    /// Boolean value.
79    Bool = 7,
80    /// UTF-8 string.
81    String = 8,
82    /// Homogeneous array.
83    Array = 9,
84    /// Unsigned 64-bit integer.
85    UInt64 = 10,
86    /// Signed 64-bit integer.
87    Int64 = 11,
88    /// 64-bit floating-point number.
89    Float64 = 12,
90}
91
92impl MetadataValueType {
93    pub(super) fn from_u32(value: u32) -> Result<Self, GgufError> {
94        match value {
95            0 => Ok(Self::UInt8),
96            1 => Ok(Self::Int8),
97            2 => Ok(Self::UInt16),
98            3 => Ok(Self::Int16),
99            4 => Ok(Self::UInt32),
100            5 => Ok(Self::Int32),
101            6 => Ok(Self::Float32),
102            7 => Ok(Self::Bool),
103            8 => Ok(Self::String),
104            9 => Ok(Self::Array),
105            10 => Ok(Self::UInt64),
106            11 => Ok(Self::Int64),
107            12 => Ok(Self::Float64),
108            other => Err(GgufError::new(format!(
109                "unknown GGUF metadata value type {other}"
110            ))),
111        }
112    }
113}
114
115#[derive(Clone, Copy, Debug, PartialEq, Eq)]
116#[repr(u32)]
117/// A GGML tensor storage type declared by a GGUF tensor descriptor.
118///
119/// Parsing recognizes every listed type. Byte-range validation reports an
120/// error for formats whose block sizing is not implemented by this crate.
121pub enum GgmlType {
122    /// IEEE 754 single-precision values.
123    F32 = 0,
124    /// IEEE 754 half-precision values.
125    F16 = 1,
126    /// GGML `Q4_0` quantized blocks.
127    Q4_0 = 2,
128    /// GGML `Q4_1` quantized blocks.
129    Q4_1 = 3,
130    /// GGML `Q5_0` quantized blocks.
131    Q5_0 = 6,
132    /// GGML `Q5_1` quantized blocks.
133    Q5_1 = 7,
134    /// GGML `Q8_0` quantized blocks.
135    Q8_0 = 8,
136    /// GGML `Q8_1` quantized blocks.
137    Q8_1 = 9,
138    /// GGML `Q2_K` quantized blocks.
139    Q2K = 10,
140    /// GGML `Q3_K` quantized blocks.
141    Q3K = 11,
142    /// GGML `Q4_K` quantized blocks.
143    Q4K = 12,
144    /// GGML `Q5_K` quantized blocks.
145    Q5K = 13,
146    /// GGML `Q6_K` quantized blocks.
147    Q6K = 14,
148    /// GGML `Q8_K` quantized blocks.
149    Q8K = 15,
150    /// GGML `IQ2_XXS` quantized blocks.
151    IQ2Xxs = 16,
152    /// GGML `IQ2_XS` quantized blocks.
153    IQ2Xs = 17,
154    /// GGML `IQ3_XXS` quantized blocks.
155    IQ3Xxs = 18,
156    /// GGML `IQ1_S` quantized blocks.
157    IQ1S = 19,
158    /// GGML `IQ4_NL` quantized blocks.
159    IQ4Nl = 20,
160    /// GGML `IQ3_S` quantized blocks.
161    IQ3S = 21,
162    /// GGML `IQ2_S` quantized blocks.
163    IQ2S = 22,
164    /// GGML `IQ4_XS` quantized blocks.
165    IQ4Xs = 23,
166    /// Signed 8-bit integers.
167    I8 = 24,
168    /// Signed 16-bit integers.
169    I16 = 25,
170    /// Signed 32-bit integers.
171    I32 = 26,
172    /// Signed 64-bit integers.
173    I64 = 27,
174    /// IEEE 754 double-precision values.
175    F64 = 28,
176    /// GGML `IQ1_M` quantized blocks.
177    IQ1M = 29,
178    /// Brain floating-point 16-bit values.
179    BF16 = 30,
180    /// GGML ternary `TQ1_0` quantized blocks.
181    TQ1_0 = 34,
182    /// GGML ternary `TQ2_0` quantized blocks.
183    TQ2_0 = 35,
184    /// GGML `MXFP4` quantized blocks.
185    Mxfp4 = 39,
186}
187
188impl GgmlType {
189    pub(super) fn from_u32(value: u32) -> Result<Self, GgufError> {
190        match value {
191            0 => Ok(Self::F32),
192            1 => Ok(Self::F16),
193            2 => Ok(Self::Q4_0),
194            3 => Ok(Self::Q4_1),
195            6 => Ok(Self::Q5_0),
196            7 => Ok(Self::Q5_1),
197            8 => Ok(Self::Q8_0),
198            9 => Ok(Self::Q8_1),
199            10 => Ok(Self::Q2K),
200            11 => Ok(Self::Q3K),
201            12 => Ok(Self::Q4K),
202            13 => Ok(Self::Q5K),
203            14 => Ok(Self::Q6K),
204            15 => Ok(Self::Q8K),
205            16 => Ok(Self::IQ2Xxs),
206            17 => Ok(Self::IQ2Xs),
207            18 => Ok(Self::IQ3Xxs),
208            19 => Ok(Self::IQ1S),
209            20 => Ok(Self::IQ4Nl),
210            21 => Ok(Self::IQ3S),
211            22 => Ok(Self::IQ2S),
212            23 => Ok(Self::IQ4Xs),
213            24 => Ok(Self::I8),
214            25 => Ok(Self::I16),
215            26 => Ok(Self::I32),
216            27 => Ok(Self::I64),
217            28 => Ok(Self::F64),
218            29 => Ok(Self::IQ1M),
219            30 => Ok(Self::BF16),
220            34 => Ok(Self::TQ1_0),
221            35 => Ok(Self::TQ2_0),
222            39 => Ok(Self::Mxfp4),
223            other => Err(GgufError::new(format!("unknown GGML tensor type {other}"))),
224        }
225    }
226
227    fn block_shape(self) -> Result<(u64, u64), GgufError> {
228        match self {
229            Self::F32 => Ok((1, 4)),
230            Self::F16 | Self::BF16 => Ok((1, 2)),
231            Self::Q4_0 => Ok((32, 18)),
232            Self::Q4_1 => Ok((32, 20)),
233            Self::Q5_0 => Ok((32, 22)),
234            Self::Q5_1 => Ok((32, 24)),
235            Self::Q8_0 => Ok((32, 34)),
236            Self::Q8_1 => Ok((32, 36)),
237            Self::Q2K => Ok((256, 84)),
238            Self::Q3K => Ok((256, 142)),
239            Self::Q4K => Ok((256, 144)),
240            Self::Q5K => Ok((256, 176)),
241            Self::Q6K => Ok((256, 210)),
242            Self::Q8K => Ok((256, 292)),
243            Self::I8 => Ok((1, 1)),
244            Self::I16 => Ok((1, 2)),
245            Self::I32 => Ok((1, 4)),
246            Self::I64 => Ok((1, 8)),
247            Self::F64 => Ok((1, 8)),
248            Self::IQ2Xxs
249            | Self::IQ2Xs
250            | Self::IQ3Xxs
251            | Self::IQ1S
252            | Self::IQ4Nl
253            | Self::IQ3S
254            | Self::IQ2S
255            | Self::IQ4Xs
256            | Self::IQ1M
257            | Self::TQ1_0
258            | Self::TQ2_0
259            | Self::Mxfp4 => Err(GgufError::new(format!(
260                "tensor byte sizing for {self:?} is not implemented"
261            ))),
262        }
263    }
264
265    pub(super) fn storage_bytes(self, element_count: u64) -> Result<u64, GgufError> {
266        let (block_size, type_size) = self.block_shape()?;
267        if !element_count.is_multiple_of(block_size) {
268            return Err(GgufError::new(format!(
269                "tensor with {element_count} elements is not divisible by {self:?} block size {block_size}"
270            )));
271        }
272
273        element_count
274            .checked_div(block_size)
275            .and_then(|blocks| blocks.checked_mul(type_size))
276            .ok_or_else(|| GgufError::new("tensor byte size overflow"))
277    }
278}