1use super::{
3 attention,
4 weights::{self, Nvfp4Projection},
5 LayerPlan, Plan, Profile,
6};
7use crate::inference::moe::ftw_loader::FtwModelPackage;
8use etalon_model::inference::{
9 qwen_attention::{QkNorm, Qwen35AttentionGeometry},
10 qwen_roles::{Qwen35Geometry, Qwen35Packing},
11 TensorInfo,
12};
13use serde_json::Value;
14use sha2::{Digest, Sha256};
15use std::io::Read;
16use std::{path::Path, sync::Arc};
17
18#[derive(Clone, Copy, Debug)]
22pub enum ExportContract {
23 FreeTokenQwen35MixedFp8V1,
24}
25
26const RECEIPT: [(&str, &str); 3] = [
33 (
34 "freetoken_weight.json",
35 "79bb256dc54229377986d1863f91cb123b43d7d015cc7418ddbf580aa8c9249d",
36 ),
37 (
38 "config.json",
39 "58aefa1c9eff7989f431d748f2ddec39446cb1fd2a69acc46e285c6a37b0cecc",
40 ),
41 (
42 "hf_quant_config.json",
43 "75fe7cc8d5836b58734e05ee67423a4ce91d602aaad45c8173a1b7597cd57663",
44 ),
45];
46const CONFIG_LIMIT: usize = 2 * 1024 * 1024;
47
48fn bounded_read(path: &Path, budget: usize) -> Result<Vec<u8>, String> {
49 let len = usize::try_from(std::fs::metadata(path).map_err(|e| e.to_string())?.len())
50 .map_err(|_| "Qwen metadata size overflow")?;
51 if len > CONFIG_LIMIT || len > budget {
52 return Err("Qwen metadata budget exhausted".into());
53 }
54 let mut file = std::fs::File::open(path).map_err(|e| e.to_string())?;
55 let mut bytes = vec![0; len];
56 file.read_exact(&mut bytes).map_err(|e| e.to_string())?;
57 if file.read(&mut [0]).map_err(|e| e.to_string())? != 0 {
58 return Err("Qwen metadata changed while reading".into());
59 }
60 Ok(bytes)
61}
62
63pub fn admit_known(
64 pkg: Arc<FtwModelPackage>,
65 dir: &Path,
66 max_context: usize,
67 byte_budget: usize,
68) -> Result<Arc<Plan>, String> {
69 let mut verified_config = None;
70 for (name, expected) in RECEIPT {
71 let bytes = bounded_read(&dir.join(name), byte_budget)?;
72 let digest = Sha256::digest(&bytes);
73 let mut encoded = [0u8; 64];
74 for (index, &byte) in digest.iter().enumerate() {
75 encoded[index * 2] = b"0123456789abcdef"[(byte >> 4) as usize];
76 encoded[index * 2 + 1] = b"0123456789abcdef"[(byte & 15) as usize];
77 }
78 if encoded != expected.as_bytes() {
79 return Err(format!("Qwen exporter receipt mismatch: {name}"));
80 }
81 if name == "freetoken_weight.json" {
82 let manifest: crate::inference::moe::ftw_loader::FtwManifest =
83 serde_json::from_slice(&bytes).map_err(|e| e.to_string())?;
84 if manifest.format != pkg.manifest.format
85 || manifest.version != pkg.manifest.version
86 || manifest.quant_format != pkg.manifest.quant_format
87 || manifest.expert_bank_num_layers != pkg.manifest.expert_bank_num_layers
88 || manifest.total_bytes != pkg.manifest.total_bytes
89 || manifest.tensors.len() != pkg.manifest.tensors.len()
90 || manifest.shards.len() != pkg.manifest.shards.len()
91 || manifest
92 .tensors
93 .iter()
94 .zip(&pkg.manifest.tensors)
95 .any(|(a, b)| {
96 a.name != b.name
97 || a.kind != b.kind
98 || a.dtype != b.dtype
99 || a.shape != b.shape
100 || a.nbytes != b.nbytes
101 || a.global_off != b.global_off
102 })
103 || manifest
104 .shards
105 .iter()
106 .zip(&pkg.manifest.shards)
107 .any(|(a, b)| {
108 a.file != b.file || a.global_off != b.global_off || a.nbytes != b.nbytes
109 })
110 {
111 return Err("Qwen receipt does not describe retained package".into());
112 }
113 }
114 if name == "config.json" {
115 verified_config = Some(bytes);
116 }
117 }
118 admit_config(
119 pkg,
120 &verified_config.ok_or("Qwen receipt missing config")?,
121 max_context,
122 byte_budget,
123 ExportContract::FreeTokenQwen35MixedFp8V1,
124 )
125}
126
127fn number(v: &Value, key: &str) -> Result<usize, String> {
128 usize::try_from(
129 v[key]
130 .as_u64()
131 .ok_or_else(|| format!("Qwen missing integer {key}"))?,
132 )
133 .map_err(|_| format!("Qwen integer overflow {key}"))
134}
135fn tensor(pkg: &FtwModelPackage, name: &str, shape: &[u64]) -> Result<TensorInfo, String> {
136 let entry = weights::entry(pkg, name).map_err(|e| format!("Qwen {name}: {e:?}"))?;
137 if entry.shape != shape || !matches!(entry.dtype.as_str(), "bfloat16" | "float16" | "float32") {
138 return Err(format!("Qwen scalar tensor shape/encoding {name}"));
139 }
140 let count = shape
141 .iter()
142 .try_fold(1u64, |n, &d| n.checked_mul(d))
143 .ok_or("Qwen tensor size overflow")?;
144 let bytes = count
145 .checked_mul(if entry.dtype == "float32" { 4 } else { 2 })
146 .ok_or("Qwen tensor byte overflow")?;
147 if bytes != entry.nbytes
148 || pkg
149 .fetch_by_global_offset(
150 entry.global_off,
151 usize::try_from(bytes).map_err(|_| "Qwen tensor byte overflow")?,
152 )
153 .is_none()
154 {
155 return Err(format!("Qwen tensor bounds {name}"));
156 }
157 let mut dims = [0; 4];
158 for (slot, &size) in dims.iter_mut().zip(shape.iter().rev()) {
159 *slot = size;
160 }
161 Ok(TensorInfo {
162 dims,
163 n_dims: shape.len() as u32,
164 byte_offset: entry.global_off,
165 ggml_type: match entry.dtype.as_str() {
166 "bfloat16" => crate::ggml_quants::GGML_TYPE_BF16,
167 "float16" => crate::ggml_quants::GGML_TYPE_F16,
168 _ => crate::ggml_quants::GGML_TYPE_F32,
169 },
170 })
171}
172
173pub fn admit(
174 pkg: Arc<FtwModelPackage>,
175 dir: &Path,
176 max_context: usize,
177 byte_budget: usize,
178 _contract: ExportContract,
179) -> Result<Arc<Plan>, String> {
180 let bytes = bounded_read(&dir.join("config.json"), byte_budget)?;
181 admit_config(pkg, &bytes, max_context, byte_budget, _contract)
182}
183
184fn admit_config(
185 pkg: Arc<FtwModelPackage>,
186 bytes: &[u8],
187 max_context: usize,
188 byte_budget: usize,
189 _contract: ExportContract,
190) -> Result<Arc<Plan>, String> {
191 let config: Value = serde_json::from_slice(&bytes).map_err(|e| e.to_string())?;
192 if config["model_type"] != "qwen3_5_moe"
193 || config["architectures"] != serde_json::json!(["Qwen3_5MoeForConditionalGeneration"])
194 {
195 return Err("Qwen architecture contract mismatch".into());
196 }
197 let c = &config["text_config"];
198 if c["model_type"] != "qwen3_5_moe_text"
201 || c["attention_bias"] != false
202 || c["attn_output_gate"] != true
203 || c["hidden_act"] != "silu"
204 || (!c["norm_topk_prob"].is_null() && c["norm_topk_prob"] != true)
205 {
206 return Err("Qwen text execution contract mismatch".into());
207 }
208 let h = pkg.tensor_index.hyperparams;
209 let hidden = number(c, "hidden_size")?;
210 let layers = number(c, "num_hidden_layers")?;
211 let vocab = number(c, "vocab_size")?;
212 let experts = number(c, "num_experts")?;
213 let topk = number(c, "num_experts_per_tok")?;
214 let intermediate = number(c, "moe_intermediate_size")?;
215 if hidden != h.n_embd as usize
216 || layers != h.n_layer as usize
217 || layers > 1024
218 || experts != 256
219 || topk == 0
220 || topk > 8
221 || hidden > 16384
222 || intermediate == 0
223 || intermediate > 8192
224 || intermediate % 16 != 0
225 || intermediate != number(c, "shared_expert_intermediate_size")?
226 || max_context == 0
227 || max_context > number(c, "max_position_embeddings")?
228 {
229 return Err("Qwen geometry mismatch".into());
230 }
231 let epsilon = c["rms_norm_eps"].as_f64().ok_or("Qwen missing epsilon")? as f32;
232 if !epsilon.is_finite() || epsilon <= 0.0 {
233 return Err("Qwen invalid epsilon".into());
234 }
235 let rope = &c["rope_parameters"];
236 if rope["rope_type"] != "default" || rope["mrope_interleaved"] != true {
237 return Err("Qwen unsupported rotary contract".into());
238 }
239 let head_dim = number(c, "head_dim")?;
240 if head_dim != h.effective_head_dim() as usize || head_dim > 1024 {
241 return Err("Qwen head dimension config/index mismatch".into());
242 }
243 let partial = rope["partial_rotary_factor"]
244 .as_f64()
245 .ok_or("Qwen missing rotary fraction")?;
246 let theta = rope["rope_theta"]
247 .as_f64()
248 .ok_or("Qwen missing rotary base")?;
249 let rotary = (head_dim as f64) * partial;
250 if !theta.is_finite()
251 || theta <= 0.0
252 || !rotary.is_finite()
253 || rotary.fract() != 0.0
254 || rotary <= 0.0
255 || rotary > head_dim as f64
256 || rotary as usize % 2 != 0
257 {
258 return Err("Qwen invalid rotary geometry".into());
259 }
260 let attention_geometry = Qwen35AttentionGeometry {
261 hidden,
262 query_heads: number(c, "num_attention_heads")?,
263 kv_heads: number(c, "num_key_value_heads")?,
264 head_dim,
265 rotary_dim: rotary as usize,
266 };
267 attention_geometry
268 .validate()
269 .map_err(|e| format!("Qwen attention geometry {e:?}"))?;
270 let linear_geometry = Qwen35Geometry::from_hyperparams(h.into())
271 .map_err(|e| format!("Qwen linear geometry {e:?}"))?;
272 if linear_geometry.key_heads != number(c, "linear_num_key_heads")?
273 || linear_geometry.value_heads != number(c, "linear_num_value_heads")?
274 || linear_geometry.key_dim != number(c, "linear_key_head_dim")?
275 || linear_geometry.value_dim != number(c, "linear_value_head_dim")?
276 || linear_geometry.kernel != number(c, "linear_conv_kernel_dim")?
277 {
278 return Err("Qwen recurrent config/index mismatch".into());
279 }
280 let metadata = layers
281 .checked_mul(std::mem::size_of::<LayerPlan>())
282 .and_then(|n| n.checked_add(std::mem::size_of::<Plan>()))
283 .and_then(|n| n.checked_add((rotary as usize / 2) * 4))
284 .and_then(|n| n.checked_add(pkg.prepared_metadata_bytes()?))
285 .ok_or("Qwen plan budget overflow")?;
286 if metadata > byte_budget {
287 return Err("Qwen plan budget exhausted".into());
288 }
289 let profile = Profile {
290 hidden,
291 layers,
292 vocab,
293 intermediate,
294 experts,
295 topk,
296 max_context,
297 epsilon,
298 linear_geometry,
299 attention_geometry,
300 rotary_inv_freq: (0..rotary as usize / 2)
301 .map(|i| (1.0 / theta.powf((2 * i) as f64 / rotary)) as f32)
302 .collect(),
303 packing: Qwen35Packing::FusedGlobal,
304 ordinary_norm: QkNorm::FoldedMultiplier,
305 };
306 let kinds = c["layer_types"]
307 .as_array()
308 .ok_or("Qwen missing explicit layer schedule")?;
309 if kinds.len() != layers {
310 return Err("Qwen layer schedule mismatch".into());
311 }
312 let mut plans = Vec::with_capacity(layers);
313 for (layer, kind) in kinds.iter().enumerate() {
314 let is_linear = match kind.as_str() {
315 Some("linear_attention") => true,
316 Some("full_attention") => false,
317 _ => return Err("Qwen unsupported layer kind".into()),
318 };
319 let base = format!("model.layers.{layer}");
320 let attention = attention::resolve(&pkg, &profile, layer, is_linear)?;
321 let plan = LayerPlan {
322 attention,
323 input_norm: tensor(
324 &pkg,
325 &format!("{base}.input_layernorm.weight"),
326 &[hidden as u64],
327 )?,
328 post_norm: tensor(
329 &pkg,
330 &format!("{base}.post_attention_layernorm.weight"),
331 &[hidden as u64],
332 )?,
333 router: tensor(
334 &pkg,
335 &format!("{base}.mlp.gate.weight"),
336 &[experts as u64, hidden as u64],
337 )?,
338 shared_gate: tensor(
339 &pkg,
340 &format!("{base}.mlp.shared_expert_gate.weight"),
341 &[1, hidden as u64],
342 )?,
343 shared_up: Nvfp4Projection::admit(
344 &pkg,
345 &format!("{base}.mlp.shared_expert.gate_up_proj"),
346 2 * intermediate,
347 hidden,
348 )
349 .map_err(|e| format!("Qwen shared gate/up {e:?}"))?,
350 shared_down: Nvfp4Projection::admit(
351 &pkg,
352 &format!("{base}.mlp.shared_expert.down_proj"),
353 hidden,
354 intermediate,
355 )
356 .map_err(|e| format!("Qwen shared down {e:?}"))?,
357 };
358 for (name, dtype, shape, expected) in [
359 (
360 "gate_up_packed",
361 "uint8",
362 vec![
363 experts as u64,
364 (2 * intermediate) as u64,
365 (hidden / 2) as u64,
366 ],
367 experts * intermediate * hidden,
368 ),
369 (
370 "gate_up_scale",
371 "float8_e4m3fn",
372 vec![
373 experts as u64,
374 (2 * intermediate) as u64,
375 (hidden / 16) as u64,
376 ],
377 experts * 2 * intermediate * hidden / 16,
378 ),
379 (
380 "gate_up_global",
381 "float16",
382 vec![experts as u64, (2 * intermediate) as u64],
383 experts * 2 * intermediate * 2,
384 ),
385 (
386 "down_packed",
387 "uint8",
388 vec![experts as u64, hidden as u64, (intermediate / 2) as u64],
389 experts * hidden * intermediate / 2,
390 ),
391 (
392 "down_scale",
393 "float8_e4m3fn",
394 vec![experts as u64, hidden as u64, (intermediate / 16) as u64],
395 experts * hidden * intermediate / 16,
396 ),
397 (
398 "down_global",
399 "float16",
400 vec![experts as u64, hidden as u64],
401 experts * hidden * 2,
402 ),
403 ] {
404 let name = format!("{name}#L{layer:05}");
405 let bank =
406 weights::entry(&pkg, &name).map_err(|e| format!("Qwen bank {name}: {e:?}"))?;
407 if bank.dtype != dtype || bank.shape != shape || bank.nbytes != expected as u64 {
408 return Err(format!("Qwen bank encoding/shape {name}"));
409 }
410 }
411 for expert in 0..experts {
412 let data = pkg
413 .get_expert_data(layer as u16, expert as u16)
414 .ok_or("Qwen missing expert bank")?;
415 if data.gate_up_packed.len() != 2 * intermediate * hidden / 2
416 || data.gate_up_scale.len() != 2 * intermediate * hidden / 16
417 || data.gate_up_global.len() != 2 * intermediate * 2
418 || data.down_packed.len() != hidden * intermediate / 2
419 || data.down_scale.len() != hidden * intermediate / 16
420 || data.down_global.len() != hidden * 2
421 {
422 return Err("Qwen expert bank shape mismatch".into());
423 }
424 }
425 plans.push(plan);
426 }
427 let output = Nvfp4Projection::admit(&pkg, "lm_head", vocab, hidden)
428 .map_err(|e| format!("Qwen output {e:?}"))?;
429 let final_norm = tensor(&pkg, "model.norm.weight", &[hidden as u64])?;
430 let embedding = tensor(
431 &pkg,
432 "model.embed_tokens.weight",
433 &[vocab as u64, hidden as u64],
434 )?;
435 Ok(Arc::new(Plan {
436 pkg,
437 profile,
438 layers: plans,
439 output,
440 final_norm,
441 embedding,
442 reserved_bytes: metadata,
443 }))
444}