qualia_core_db/inference/
safetensor.rs1#[derive(Debug, Clone, Copy, PartialEq, Eq)]
20pub enum SourceFormat {
21 Safetensor,
23 Gguf,
25 Unknown,
27}
28
29pub fn detect_format(head: &[u8]) -> SourceFormat {
32 if head.len() >= 4 && &head[0..4] == b"GGUF" {
33 return SourceFormat::Gguf;
34 }
35 if head.len() >= 9 {
36 let hlen = u64::from_le_bytes(head[0..8].try_into().unwrap()) as usize;
37 if hlen > 0 && hlen < (1 << 30) && head[8] == b'{' {
39 return SourceFormat::Safetensor;
40 }
41 }
42 SourceFormat::Unknown
43}
44
45#[derive(Debug, Clone, PartialEq, Eq)]
47pub struct SafeTensorEntry {
48 pub name: String,
49 pub dtype: String,
50 pub shape: Vec<usize>,
51 pub begin: usize,
53 pub end: usize,
54}
55
56impl SafeTensorEntry {
57 #[inline]
58 pub fn byte_len(&self) -> usize {
60 self.end - self.begin
61 }
62}
63
64#[derive(Debug, Clone)]
66pub struct SafeTensorPlan {
67 pub tensors: Vec<SafeTensorEntry>,
68 pub data_start: usize,
70 pub is_mlx: bool,
72}
73
74pub fn parse_safetensor_header(src: &[u8]) -> Result<SafeTensorPlan, String> {
77 if src.len() < 8 {
78 return Err("safetensor: too small for 8-byte header length".to_string());
79 }
80 let hlen = u64::from_le_bytes(src[0..8].try_into().unwrap()) as usize;
81 let data_start = 8usize
82 .checked_add(hlen)
83 .ok_or("safetensor: header length overflow")?;
84 if data_start > src.len() {
85 return Err("safetensor: header length exceeds file".to_string());
86 }
87 let json: serde_json::Value = serde_json::from_slice(&src[8..data_start])
88 .map_err(|e| format!("safetensor: header JSON parse error: {e}"))?;
89 let obj = json
90 .as_object()
91 .ok_or("safetensor: header is not a JSON object")?;
92
93 let is_mlx = obj
94 .get("__metadata__")
95 .and_then(|m| m.get("format"))
96 .and_then(|f| f.as_str())
97 .map(|s| s.eq_ignore_ascii_case("mlx"))
98 .unwrap_or(false);
99
100 let data_len = src.len() - data_start;
101 let mut tensors = Vec::new();
102 for (name, spec) in obj {
103 if name == "__metadata__" {
104 continue;
105 }
106 let dtype = spec
107 .get("dtype")
108 .and_then(|d| d.as_str())
109 .ok_or_else(|| format!("safetensor: tensor '{name}' missing dtype"))?
110 .to_string();
111 let shape = spec
112 .get("shape")
113 .and_then(|s| s.as_array())
114 .ok_or_else(|| format!("safetensor: tensor '{name}' missing shape"))?
115 .iter()
116 .map(|v| v.as_u64().unwrap_or(0) as usize)
117 .collect::<Vec<_>>();
118 let offs = spec
119 .get("data_offsets")
120 .and_then(|o| o.as_array())
121 .ok_or_else(|| format!("safetensor: tensor '{name}' missing data_offsets"))?;
122 if offs.len() != 2 {
123 return Err(format!(
124 "safetensor: tensor '{name}' data_offsets must be [begin,end]"
125 ));
126 }
127 let begin = offs[0].as_u64().unwrap_or(0) as usize;
128 let end = offs[1].as_u64().unwrap_or(0) as usize;
129 if end < begin || end > data_len {
130 return Err(format!("safetensor: tensor '{name}' offsets out of bounds"));
131 }
132 tensors.push(SafeTensorEntry {
133 name: name.clone(),
134 dtype,
135 shape,
136 begin,
137 end,
138 });
139 }
140 tensors.sort_by(|a, b| a.begin.cmp(&b.begin));
142 Ok(SafeTensorPlan {
143 tensors,
144 data_start,
145 is_mlx,
146 })
147}
148
149pub const GGML_F32: u32 = 0;
154pub const GGML_F16: u32 = 1;
155pub const GGML_Q8_0: u32 = 8;
156pub const GGML_BF16: u32 = 30;
157
158pub fn safetensor_dtype_to_ggml(dtype: &str) -> Option<u32> {
161 match dtype {
162 "F32" => Some(GGML_F32),
163 "F16" => Some(GGML_F16),
164 "BF16" => Some(GGML_BF16),
165 _ => None, }
167}
168
169pub fn is_high_fidelity_ggml(ggml_type: u32) -> bool {
173 matches!(ggml_type, GGML_F32 | GGML_F16 | GGML_Q8_0 | GGML_BF16)
174}
175
176pub fn ggml_elem_bytes(ggml_type: u32) -> Option<usize> {
178 match ggml_type {
179 GGML_F32 => Some(4),
180 GGML_F16 | GGML_BF16 => Some(2),
181 GGML_Q8_0 => Some(1), _ => None,
183 }
184}
185
186#[cfg(test)]
187mod tests {
188 use super::*;
189
190 fn synth_safetensor(t: &[(&str, &str, Vec<usize>, usize)]) -> Vec<u8> {
192 let mut entries = serde_json::Map::new();
194 let mut cursor = 0usize;
195 for (name, dtype, shape, nbytes) in t {
196 let begin = cursor;
197 let end = cursor + nbytes;
198 cursor = end;
199 entries.insert(
200 (*name).to_string(),
201 serde_json::json!({ "dtype": dtype, "shape": shape, "data_offsets": [begin, end] }),
202 );
203 }
204 let header = serde_json::Value::Object(entries);
205 let header_bytes = serde_json::to_vec(&header).unwrap();
206 let mut out = Vec::new();
207 out.extend_from_slice(&(header_bytes.len() as u64).to_le_bytes());
208 out.extend_from_slice(&header_bytes);
209 out.resize(out.len() + cursor, 0u8); out
211 }
212
213 #[test]
214 fn detects_formats() {
215 let st = synth_safetensor(&[("w", "F16", vec![2, 2], 8)]);
216 assert_eq!(detect_format(&st), SourceFormat::Safetensor);
217 assert_eq!(detect_format(b"GGUF\0\0\0\0"), SourceFormat::Gguf);
218 assert_eq!(detect_format(b"not a model"), SourceFormat::Unknown);
219 }
220
221 #[test]
222 fn parses_header_and_offsets() {
223 let st = synth_safetensor(&[("a", "F16", vec![4], 8), ("b", "F32", vec![2, 2], 16)]);
224 let plan = parse_safetensor_header(&st).unwrap();
225 assert_eq!(plan.tensors.len(), 2);
226 assert_eq!(plan.tensors[0].name, "a");
227 assert_eq!(plan.tensors[0].byte_len(), 8);
228 assert_eq!(plan.tensors[1].dtype, "F32");
229 assert_eq!(plan.tensors[1].byte_len(), 16);
230 assert!(!plan.is_mlx);
231 }
232
233 #[test]
234 fn dtype_gate_accepts_high_fidelity_rejects_q4() {
235 assert_eq!(safetensor_dtype_to_ggml("F16"), Some(GGML_F16));
236 assert_eq!(safetensor_dtype_to_ggml("BF16"), Some(GGML_BF16));
237 assert_eq!(safetensor_dtype_to_ggml("U8"), None);
238
239 assert!(is_high_fidelity_ggml(GGML_F16));
240 assert!(is_high_fidelity_ggml(GGML_Q8_0));
241 assert!(!is_high_fidelity_ggml(12)); assert!(!is_high_fidelity_ggml(2)); }
244}