1use std::collections::HashMap;
14use trustformers_core::{
15 errors::{Result, TrustformersError},
16 tensor::Tensor,
17};
18
19#[derive(Debug, Clone)]
21pub struct AdvancedQuantizationConfig {
22 pub method: QuantizationMethod,
24 pub block_size: usize,
26 pub double_quantization: bool,
28 pub compute_dtype: ComputeDataType,
30 pub outlier_threshold: f32,
32 pub nested_quantization: bool,
34}
35
36impl Default for AdvancedQuantizationConfig {
37 fn default() -> Self {
38 Self {
39 method: QuantizationMethod::NF4,
40 block_size: 64,
41 double_quantization: true,
42 compute_dtype: ComputeDataType::BFloat16,
43 outlier_threshold: 6.0,
44 nested_quantization: false,
45 }
46 }
47}
48
49#[derive(Debug, Clone, PartialEq)]
51pub enum QuantizationMethod {
52 NF4,
54 FP4,
56 Int4Asymmetric,
58 Int8BlockWise,
60 MixedPrecision { primary_bits: u8, outlier_bits: u8 },
62}
63
64#[derive(Debug, Clone, PartialEq)]
66pub enum ComputeDataType {
67 Float32,
68 Float16,
69 BFloat16,
70}
71
72const NF4_QUANT_TABLE: [f32; 16] = [
74 -1.0,
75 -0.696_192_8,
76 -0.525_073_05,
77 -0.394_917_5,
78 -0.284_441_38,
79 -0.184_773_43,
80 -0.091_050_036,
81 0.0,
82 0.079_580_3,
83 0.160_930_2,
84 0.246_112_3,
85 0.337_915_24,
86 0.440_709_83,
87 0.562_617,
88 0.722_956_84,
89 1.0,
90];
91
92pub struct FP4Format {
94 pub sign_bits: u8,
95 pub exponent_bits: u8,
96 pub mantissa_bits: u8,
97}
98
99impl Default for FP4Format {
100 fn default() -> Self {
101 Self {
102 sign_bits: 1,
103 exponent_bits: 2,
104 mantissa_bits: 1,
105 }
106 }
107}
108
109#[derive(Debug, Clone)]
111pub struct QuantizedTensor {
112 pub data: Vec<u8>,
114 pub scales: Vec<f32>,
116 pub zero_points: Option<Vec<f32>>,
118 pub shape: Vec<usize>,
120 pub metadata: QuantizationMetadata,
122}
123
124#[derive(Debug, Clone)]
126pub struct QuantizationMetadata {
127 pub method: QuantizationMethod,
128 pub block_size: usize,
129 pub outlier_indices: Option<Vec<usize>>,
130 pub outlier_values: Option<Vec<f32>>,
131 pub double_quantized: bool,
132 pub compute_dtype: ComputeDataType,
133}
134
135pub struct AdvancedQuantizer {
137 config: AdvancedQuantizationConfig,
138 #[allow(dead_code)]
139 nf4_lookup: HashMap<u8, f32>,
140 #[allow(dead_code)]
141 inv_nf4_lookup: HashMap<u32, u8>, }
143
144impl AdvancedQuantizer {
145 pub fn new(config: AdvancedQuantizationConfig) -> Self {
147 let mut nf4_lookup = HashMap::new();
148 let mut inv_nf4_lookup = HashMap::new();
149
150 for (i, &value) in NF4_QUANT_TABLE.iter().enumerate() {
152 nf4_lookup.insert(i as u8, value);
153 inv_nf4_lookup.insert(value.to_bits(), i as u8);
154 }
155
156 Self {
157 config,
158 nf4_lookup,
159 inv_nf4_lookup,
160 }
161 }
162
163 pub fn quantize(&self, tensor: &Tensor) -> Result<QuantizedTensor> {
165 match &self.config.method {
166 QuantizationMethod::NF4 => self.quantize_nf4(tensor),
167 QuantizationMethod::FP4 => self.quantize_fp4(tensor),
168 QuantizationMethod::Int4Asymmetric => self.quantize_int4_asymmetric(tensor),
169 QuantizationMethod::Int8BlockWise => self.quantize_int8_blockwise(tensor),
170 QuantizationMethod::MixedPrecision {
171 primary_bits,
172 outlier_bits,
173 } => self.quantize_mixed_precision(tensor, *primary_bits, *outlier_bits),
174 }
175 }
176
177 pub fn dequantize(&self, quantized: &QuantizedTensor) -> Result<Tensor> {
179 match &quantized.metadata.method {
180 QuantizationMethod::NF4 => self.dequantize_nf4(quantized),
181 QuantizationMethod::FP4 => self.dequantize_fp4(quantized),
182 QuantizationMethod::Int4Asymmetric => self.dequantize_int4_asymmetric(quantized),
183 QuantizationMethod::Int8BlockWise => self.dequantize_int8_blockwise(quantized),
184 QuantizationMethod::MixedPrecision { .. } => self.dequantize_mixed_precision(quantized),
185 }
186 }
187
188 fn quantize_nf4(&self, tensor: &Tensor) -> Result<QuantizedTensor> {
190 let tensor_data = tensor.data_f32()?;
191 let total_elements = tensor_data.len();
192 let num_blocks = total_elements.div_ceil(self.config.block_size);
193
194 let mut quantized_data = Vec::with_capacity(total_elements.div_ceil(2)); let mut scales = Vec::with_capacity(num_blocks);
196 let mut outlier_indices = Vec::new();
197 let mut outlier_values = Vec::new();
198
199 for block_idx in 0..num_blocks {
200 let start_idx = block_idx * self.config.block_size;
201 let end_idx = (start_idx + self.config.block_size).min(total_elements);
202 let block_data = &tensor_data[start_idx..end_idx];
203
204 let abs_max = block_data.iter().map(|x| x.abs()).fold(0.0f32, f32::max);
206
207 let mut processed_block = Vec::with_capacity(block_data.len());
209 for (local_idx, &value) in block_data.iter().enumerate() {
210 if value.abs() > self.config.outlier_threshold * abs_max {
211 outlier_indices.push(start_idx + local_idx);
212 outlier_values.push(value);
213 processed_block.push(0.0); } else {
215 processed_block.push(value);
216 }
217 }
218
219 let scale = abs_max;
221 scales.push(scale);
222
223 for chunk in processed_block.chunks(2) {
225 let val1 = self.quantize_nf4_value(chunk[0] / scale);
226 let val2 =
227 if chunk.len() > 1 { self.quantize_nf4_value(chunk[1] / scale) } else { 0 };
228
229 let packed = (val1 & 0xF) | ((val2 & 0xF) << 4);
231 quantized_data.push(packed);
232 }
233 }
234
235 let final_scales = if self.config.double_quantization {
237 self.double_quantize_scales(&scales)?
238 } else {
239 scales
240 };
241
242 let outliers = if outlier_indices.is_empty() {
243 (None, None)
244 } else {
245 (Some(outlier_indices), Some(outlier_values))
246 };
247
248 Ok(QuantizedTensor {
249 data: quantized_data,
250 scales: final_scales,
251 zero_points: None,
252 shape: tensor.shape().to_vec(),
253 metadata: QuantizationMetadata {
254 method: QuantizationMethod::NF4,
255 block_size: self.config.block_size,
256 outlier_indices: outliers.0,
257 outlier_values: outliers.1,
258 double_quantized: self.config.double_quantization,
259 compute_dtype: self.config.compute_dtype.clone(),
260 },
261 })
262 }
263
264 fn quantize_nf4_value(&self, value: f32) -> u8 {
266 let clamped = value.clamp(-1.0, 1.0);
267
268 let mut best_idx = 0;
270 let mut best_error = (clamped - NF4_QUANT_TABLE[0]).abs();
271
272 for (idx, &quant_val) in NF4_QUANT_TABLE.iter().enumerate().skip(1) {
273 let error = (clamped - quant_val).abs();
274 if error < best_error {
275 best_error = error;
276 best_idx = idx;
277 }
278 }
279
280 best_idx as u8
281 }
282
283 fn quantize_fp4(&self, tensor: &Tensor) -> Result<QuantizedTensor> {
285 let tensor_data = tensor.data_f32()?;
286 let total_elements = tensor_data.len();
287 let num_blocks = total_elements.div_ceil(self.config.block_size);
288
289 let mut quantized_data = Vec::with_capacity(total_elements.div_ceil(2));
290 let mut scales = Vec::with_capacity(num_blocks);
291
292 for block_idx in 0..num_blocks {
293 let start_idx = block_idx * self.config.block_size;
294 let end_idx = (start_idx + self.config.block_size).min(total_elements);
295 let block_data = &tensor_data[start_idx..end_idx];
296
297 let abs_max = block_data.iter().map(|x| x.abs()).fold(0.0f32, f32::max);
299
300 let scale = abs_max / 7.0; scales.push(scale);
302
303 for chunk in block_data.chunks(2) {
305 let val1 = self.quantize_fp4_value(chunk[0] / scale);
306 let val2 =
307 if chunk.len() > 1 { self.quantize_fp4_value(chunk[1] / scale) } else { 0 };
308
309 let packed = (val1 & 0xF) | ((val2 & 0xF) << 4);
311 quantized_data.push(packed);
312 }
313 }
314
315 Ok(QuantizedTensor {
316 data: quantized_data,
317 scales,
318 zero_points: None,
319 shape: tensor.shape().to_vec(),
320 metadata: QuantizationMetadata {
321 method: QuantizationMethod::FP4,
322 block_size: self.config.block_size,
323 outlier_indices: None,
324 outlier_values: None,
325 double_quantized: false,
326 compute_dtype: self.config.compute_dtype.clone(),
327 },
328 })
329 }
330
331 fn quantize_fp4_value(&self, value: f32) -> u8 {
333 if value == 0.0 {
334 return 0;
335 }
336
337 let sign = if value < 0.0 { 1u8 } else { 0u8 };
338 let abs_val = value.abs();
339
340 let quantized = if abs_val <= 0.25 {
343 0 } else if abs_val <= 0.75 {
345 1 } else if abs_val <= 1.25 {
347 2 } else if abs_val <= 1.75 {
349 3 } else if abs_val <= 2.5 {
351 4 } else if abs_val <= 3.5 {
353 5 } else if abs_val <= 5.0 {
355 6 } else {
357 7 };
359
360 (sign << 3) | (quantized & 0x7)
361 }
362
363 fn quantize_int4_asymmetric(&self, tensor: &Tensor) -> Result<QuantizedTensor> {
365 let tensor_data = tensor.data_f32()?;
366 let total_elements = tensor_data.len();
367 let num_blocks = total_elements.div_ceil(self.config.block_size);
368
369 let mut quantized_data = Vec::with_capacity(total_elements.div_ceil(2));
370 let mut scales = Vec::with_capacity(num_blocks);
371 let mut zero_points = Vec::with_capacity(num_blocks);
372
373 for block_idx in 0..num_blocks {
374 let start_idx = block_idx * self.config.block_size;
375 let end_idx = (start_idx + self.config.block_size).min(total_elements);
376 let block_data = &tensor_data[start_idx..end_idx];
377
378 let min_val = block_data.iter().fold(f32::INFINITY, |a, &b| a.min(b));
380 let max_val = block_data.iter().fold(f32::NEG_INFINITY, |a, &b| a.max(b));
381
382 let scale = (max_val - min_val) / 15.0; let zero_point = -min_val / scale;
384
385 scales.push(scale);
386 zero_points.push(zero_point);
387
388 for chunk in block_data.chunks(2) {
390 let val1 = ((chunk[0] / scale + zero_point).round() as i32).clamp(0, 15) as u8;
391 let val2 = if chunk.len() > 1 {
392 ((chunk[1] / scale + zero_point).round() as i32).clamp(0, 15) as u8
393 } else {
394 0
395 };
396
397 let packed = (val1 & 0xF) | ((val2 & 0xF) << 4);
398 quantized_data.push(packed);
399 }
400 }
401
402 Ok(QuantizedTensor {
403 data: quantized_data,
404 scales,
405 zero_points: Some(zero_points),
406 shape: tensor.shape().to_vec(),
407 metadata: QuantizationMetadata {
408 method: QuantizationMethod::Int4Asymmetric,
409 block_size: self.config.block_size,
410 outlier_indices: None,
411 outlier_values: None,
412 double_quantized: false,
413 compute_dtype: self.config.compute_dtype.clone(),
414 },
415 })
416 }
417
418 fn quantize_int8_blockwise(&self, tensor: &Tensor) -> Result<QuantizedTensor> {
420 let tensor_data = tensor.data_f32()?;
421 let total_elements = tensor_data.len();
422 let num_blocks = total_elements.div_ceil(self.config.block_size);
423
424 let mut quantized_data = Vec::with_capacity(total_elements);
425 let mut scales = Vec::with_capacity(num_blocks);
426
427 for block_idx in 0..num_blocks {
428 let start_idx = block_idx * self.config.block_size;
429 let end_idx = (start_idx + self.config.block_size).min(total_elements);
430 let block_data = &tensor_data[start_idx..end_idx];
431
432 let abs_max = block_data.iter().map(|x| x.abs()).fold(0.0f32, f32::max);
433
434 let scale = abs_max / 127.0;
435 scales.push(scale);
436
437 for &value in block_data {
438 let quantized = ((value / scale).round() as i32).clamp(-127, 127) as i8;
439 quantized_data.push(quantized as u8);
440 }
441 }
442
443 Ok(QuantizedTensor {
444 data: quantized_data,
445 scales,
446 zero_points: None,
447 shape: tensor.shape().to_vec(),
448 metadata: QuantizationMetadata {
449 method: QuantizationMethod::Int8BlockWise,
450 block_size: self.config.block_size,
451 outlier_indices: None,
452 outlier_values: None,
453 double_quantized: false,
454 compute_dtype: self.config.compute_dtype.clone(),
455 },
456 })
457 }
458
459 fn quantize_mixed_precision(
500 &self,
501 tensor: &Tensor,
502 primary_bits: u8,
503 outlier_bits: u8,
504 ) -> Result<QuantizedTensor> {
505 if primary_bits == 0 || primary_bits > 8 {
506 return Err(TrustformersError::invalid_input_simple(format!(
507 "MixedPrecision primary_bits must be in 1..=8, got {primary_bits}"
508 )));
509 }
510 if outlier_bits == 0 || outlier_bits > 8 {
511 return Err(TrustformersError::invalid_input_simple(format!(
512 "MixedPrecision outlier_bits must be in 1..=8, got {outlier_bits}"
513 )));
514 }
515 if outlier_bits < primary_bits {
516 return Err(TrustformersError::invalid_input_simple(format!(
517 "MixedPrecision outlier_bits ({outlier_bits}) must be at least primary_bits \
518 ({primary_bits}): outliers are the values that need *more* precision, not less"
519 )));
520 }
521
522 let tensor_data = tensor.data_f32()?;
523 let total_elements = tensor_data.len();
524 if total_elements == 0 {
525 return Err(TrustformersError::invalid_input_simple(
526 "cannot quantize an empty tensor".to_string(),
527 ));
528 }
529 let block_size = self.config.block_size.max(1);
530 let num_blocks = total_elements.div_ceil(block_size);
531
532 let primary_levels = ((1u32 << (primary_bits - 1)) - 1).max(1) as f32;
535 let outlier_levels = ((1u32 << (outlier_bits - 1)) - 1).max(1) as f32;
536
537 let mut quantized_data = Vec::with_capacity(total_elements);
538 let mut scales = Vec::with_capacity(num_blocks);
539 let mut outlier_indices = Vec::new();
540 let mut outlier_values = Vec::new();
541
542 for block_idx in 0..num_blocks {
543 let start_idx = block_idx * block_size;
544 let end_idx = (start_idx + block_size).min(total_elements);
545 let block_data = &tensor_data[start_idx..end_idx];
546
547 let abs_max = block_data.iter().map(|x| x.abs()).fold(0.0f32, f32::max);
548
549 let mut primary_abs_max = 0.0f32;
554 let mut is_outlier = Vec::with_capacity(block_data.len());
555 for &value in block_data {
556 let outlier = value.abs() >= self.config.outlier_threshold;
557 if !outlier {
558 primary_abs_max = primary_abs_max.max(value.abs());
559 }
560 is_outlier.push(outlier);
561 }
562
563 let primary_scale =
564 if primary_abs_max > 0.0 { primary_abs_max / primary_levels } else { 1.0 };
565 let outlier_scale = if abs_max > 0.0 { abs_max / outlier_levels } else { 1.0 };
566 scales.push(primary_scale);
567
568 for (local_idx, (&value, &outlier)) in
570 block_data.iter().zip(is_outlier.iter()).enumerate()
571 {
572 if outlier {
573 let level =
578 (value / outlier_scale).round().clamp(-outlier_levels, outlier_levels);
579 outlier_indices.push(start_idx + local_idx);
580 outlier_values.push(level * outlier_scale);
581 quantized_data.push(128u8);
584 } else {
585 let level =
586 (value / primary_scale).round().clamp(-primary_levels, primary_levels);
587 quantized_data.push((level as i32 + 128) as u8);
588 }
589 }
590 }
591
592 let final_scales = if self.config.double_quantization {
593 self.double_quantize_scales(&scales)?
594 } else {
595 scales
596 };
597
598 let outliers = if outlier_indices.is_empty() {
599 (None, None)
600 } else {
601 (Some(outlier_indices), Some(outlier_values))
602 };
603
604 Ok(QuantizedTensor {
605 data: quantized_data,
606 scales: final_scales,
607 zero_points: None,
608 shape: tensor.shape().to_vec(),
609 metadata: QuantizationMetadata {
610 method: QuantizationMethod::MixedPrecision {
611 primary_bits,
612 outlier_bits,
613 },
614 block_size,
615 outlier_indices: outliers.0,
616 outlier_values: outliers.1,
617 double_quantized: self.config.double_quantization,
618 compute_dtype: self.config.compute_dtype.clone(),
619 },
620 })
621 }
622
623 fn dequantize_nf4(&self, quantized: &QuantizedTensor) -> Result<Tensor> {
625 let total_elements: usize = quantized.shape.iter().product();
626 let mut dequantized_data = vec![0.0f32; total_elements];
627 let num_blocks = quantized.scales.len();
628
629 let mut data_idx = 0;
630 let mut elem_idx = 0;
631
632 for block_idx in 0..num_blocks {
633 let scale = quantized.scales[block_idx];
634 let block_size = if block_idx == num_blocks - 1 {
635 total_elements - block_idx * quantized.metadata.block_size
637 } else {
638 quantized.metadata.block_size
639 };
640
641 let mut block_elem_count = 0;
642
643 while block_elem_count < block_size && data_idx < quantized.data.len() {
644 let packed = quantized.data[data_idx];
645 data_idx += 1;
646
647 let val1_idx = (packed & 0xF) as usize;
649 let val2_idx = ((packed >> 4) & 0xF) as usize;
650
651 if elem_idx < total_elements {
652 dequantized_data[elem_idx] = NF4_QUANT_TABLE[val1_idx] * scale;
653 elem_idx += 1;
654 block_elem_count += 1;
655 }
656
657 if block_elem_count < block_size && elem_idx < total_elements {
658 dequantized_data[elem_idx] = NF4_QUANT_TABLE[val2_idx] * scale;
659 elem_idx += 1;
660 block_elem_count += 1;
661 }
662 }
663 }
664
665 if let (Some(outlier_indices), Some(outlier_values)) = (
667 &quantized.metadata.outlier_indices,
668 &quantized.metadata.outlier_values,
669 ) {
670 for (&idx, &value) in outlier_indices.iter().zip(outlier_values.iter()) {
671 if idx < dequantized_data.len() {
672 dequantized_data[idx] = value;
673 }
674 }
675 }
676
677 Tensor::from_vec(dequantized_data, &quantized.shape)
678 }
679
680 fn dequantize_fp4(&self, quantized: &QuantizedTensor) -> Result<Tensor> {
682 let total_elements: usize = quantized.shape.iter().product();
683 let mut dequantized_data = vec![0.0f32; total_elements];
684 let num_blocks = quantized.scales.len();
685
686 let mut data_idx = 0;
687 let mut elem_idx = 0;
688
689 for block_idx in 0..num_blocks {
690 let scale = quantized.scales[block_idx];
691 let block_size = if block_idx == num_blocks - 1 {
692 total_elements - block_idx * quantized.metadata.block_size
693 } else {
694 quantized.metadata.block_size
695 };
696
697 let mut block_elem_count = 0;
698
699 while block_elem_count < block_size && data_idx < quantized.data.len() {
700 let packed = quantized.data[data_idx];
701 data_idx += 1;
702
703 let val1_bits = packed & 0xF;
704 let val2_bits = (packed >> 4) & 0xF;
705
706 if elem_idx < total_elements {
707 dequantized_data[elem_idx] = self.dequantize_fp4_value(val1_bits) * scale;
708 elem_idx += 1;
709 block_elem_count += 1;
710 }
711
712 if block_elem_count < block_size && elem_idx < total_elements {
713 dequantized_data[elem_idx] = self.dequantize_fp4_value(val2_bits) * scale;
714 elem_idx += 1;
715 block_elem_count += 1;
716 }
717 }
718 }
719
720 Tensor::from_vec(dequantized_data, &quantized.shape)
721 }
722
723 fn dequantize_fp4_value(&self, bits: u8) -> f32 {
725 if bits == 0 {
726 return 0.0;
727 }
728
729 let sign = if (bits >> 3) & 1 == 1 { -1.0 } else { 1.0 };
730 let magnitude_bits = bits & 0x7;
731
732 let magnitude = match magnitude_bits {
733 1 => 0.5,
734 2 => 1.0,
735 3 => 1.5,
736 4 => 2.0,
737 5 => 3.0,
738 6 => 4.0,
739 7 => 6.0,
740 _ => 0.0,
741 };
742
743 sign * magnitude
744 }
745
746 fn dequantize_int4_asymmetric(&self, quantized: &QuantizedTensor) -> Result<Tensor> {
748 let total_elements: usize = quantized.shape.iter().product();
749 let mut dequantized_data = vec![0.0f32; total_elements];
750 let num_blocks = quantized.scales.len();
751 let zero_points = quantized.zero_points.as_ref().ok_or_else(|| {
752 TrustformersError::config_error(
753 "Zero points required for asymmetric quantization",
754 "dequantize_int4",
755 )
756 })?;
757
758 let mut data_idx = 0;
759 let mut elem_idx = 0;
760
761 for block_idx in 0..num_blocks {
762 let scale = quantized.scales[block_idx];
763 let zero_point = zero_points[block_idx];
764 let block_size = if block_idx == num_blocks - 1 {
765 total_elements - block_idx * quantized.metadata.block_size
766 } else {
767 quantized.metadata.block_size
768 };
769
770 let mut block_elem_count = 0;
771
772 while block_elem_count < block_size && data_idx < quantized.data.len() {
773 let packed = quantized.data[data_idx];
774 data_idx += 1;
775
776 let val1 = (packed & 0xF) as f32;
777 let val2 = ((packed >> 4) & 0xF) as f32;
778
779 if elem_idx < total_elements {
780 dequantized_data[elem_idx] = (val1 - zero_point) * scale;
781 elem_idx += 1;
782 block_elem_count += 1;
783 }
784
785 if block_elem_count < block_size && elem_idx < total_elements {
786 dequantized_data[elem_idx] = (val2 - zero_point) * scale;
787 elem_idx += 1;
788 block_elem_count += 1;
789 }
790 }
791 }
792
793 Tensor::from_vec(dequantized_data, &quantized.shape)
794 }
795
796 fn dequantize_int8_blockwise(&self, quantized: &QuantizedTensor) -> Result<Tensor> {
798 let total_elements: usize = quantized.shape.iter().product();
799 let mut dequantized_data = vec![0.0f32; total_elements];
800 let num_blocks = quantized.scales.len();
801
802 let mut data_idx = 0;
803 let mut elem_idx = 0;
804
805 for block_idx in 0..num_blocks {
806 let scale = quantized.scales[block_idx];
807 let block_size = if block_idx == num_blocks - 1 {
808 total_elements - block_idx * quantized.metadata.block_size
809 } else {
810 quantized.metadata.block_size
811 };
812
813 for _ in 0..block_size {
814 if data_idx < quantized.data.len() && elem_idx < total_elements {
815 let quantized_val = quantized.data[data_idx] as i8;
816 dequantized_data[elem_idx] = quantized_val as f32 * scale;
817 data_idx += 1;
818 elem_idx += 1;
819 }
820 }
821 }
822
823 Tensor::from_vec(dequantized_data, &quantized.shape)
824 }
825
826 fn dequantize_mixed_precision(&self, quantized: &QuantizedTensor) -> Result<Tensor> {
841 let QuantizationMethod::MixedPrecision { .. } = quantized.metadata.method else {
842 return Err(TrustformersError::invalid_input_simple(format!(
843 "dequantize_mixed_precision called on a {:?} tensor",
844 quantized.metadata.method
845 )));
846 };
847
848 let total_elements: usize = quantized.shape.iter().product();
849 if quantized.data.len() != total_elements {
850 return Err(TrustformersError::shape_error(format!(
851 "mixed-precision payload holds {} element(s) but the shape {:?} needs \
852 {total_elements}",
853 quantized.data.len(),
854 quantized.shape
855 )));
856 }
857 let block_size = quantized.metadata.block_size.max(1);
858 let expected_blocks = total_elements.div_ceil(block_size);
859 if quantized.scales.len() != expected_blocks {
860 return Err(TrustformersError::shape_error(format!(
861 "mixed-precision tensor carries {} scale(s) but {expected_blocks} block(s) of \
862 size {block_size} were quantized",
863 quantized.scales.len()
864 )));
865 }
866
867 let mut dequantized = vec![0.0f32; total_elements];
868 for (index, &byte) in quantized.data.iter().enumerate() {
869 let block = index / block_size;
870 let scale = quantized.scales[block];
871 let level = byte as i32 - 128;
872 dequantized[index] = level as f32 * scale;
873 }
874
875 match (
877 &quantized.metadata.outlier_indices,
878 &quantized.metadata.outlier_values,
879 ) {
880 (Some(indices), Some(values)) => {
881 if indices.len() != values.len() {
882 return Err(TrustformersError::invalid_input_simple(format!(
883 "mixed-precision tensor records {} outlier position(s) but {} value(s)",
884 indices.len(),
885 values.len()
886 )));
887 }
888 for (&index, &value) in indices.iter().zip(values.iter()) {
889 if index >= total_elements {
890 return Err(TrustformersError::shape_error(format!(
891 "outlier index {index} is out of range for {total_elements} elements"
892 )));
893 }
894 dequantized[index] = value;
895 }
896 },
897 (None, None) => {},
898 _ => {
899 return Err(TrustformersError::invalid_input_simple(
900 "mixed-precision tensor records outlier indices without values (or the \
901 reverse)"
902 .to_string(),
903 ))
904 },
905 }
906
907 Tensor::from_vec(dequantized, &quantized.shape)
908 }
909
910 fn double_quantize_scales(&self, scales: &[f32]) -> Result<Vec<f32>> {
912 if scales.is_empty() {
913 return Ok(Vec::new());
914 }
915
916 let max_scale = scales.iter().fold(0.0f32, |a, &b| a.max(b.abs()));
918 let scale_scale = max_scale / 127.0;
919
920 let mut quantized_scales = Vec::with_capacity(scales.len());
921 for &scale in scales {
922 let quantized = ((scale / scale_scale).round() as i32).clamp(-127, 127) as i8;
923 quantized_scales.push(quantized as f32 * scale_scale);
924 }
925
926 Ok(quantized_scales)
927 }
928
929 pub fn get_stats(&self, quantized: &QuantizedTensor) -> QuantizationStats {
931 let original_size = quantized.shape.iter().product::<usize>() * 4; let compressed_size = quantized.data.len() + quantized.scales.len() * 4;
933 let compression_ratio = original_size as f32 / compressed_size as f32;
934
935 QuantizationStats {
936 original_size_bytes: original_size,
937 compressed_size_bytes: compressed_size,
938 compression_ratio,
939 method: quantized.metadata.method.clone(),
940 block_size: quantized.metadata.block_size,
941 outlier_count: quantized
942 .metadata
943 .outlier_indices
944 .as_ref()
945 .map(|indices| indices.len())
946 .unwrap_or(0),
947 }
948 }
949}
950
951#[derive(Debug, Clone)]
953pub struct QuantizationStats {
954 pub original_size_bytes: usize,
955 pub compressed_size_bytes: usize,
956 pub compression_ratio: f32,
957 pub method: QuantizationMethod,
958 pub block_size: usize,
959 pub outlier_count: usize,
960}
961
962#[cfg(test)]
963mod tests {
964 use super::*;
965
966 #[test]
967 fn test_nf4_quantization() -> Result<()> {
968 let config = AdvancedQuantizationConfig::default();
969 let quantizer = AdvancedQuantizer::new(config);
970
971 let data = vec![0.1, -0.5, 0.8, -1.2, 0.0, 0.3, -0.7, 2.1];
973 let tensor = Tensor::from_vec(data.clone(), &[8])?;
974
975 let quantized = quantizer.quantize(&tensor)?;
977 assert_eq!(quantized.metadata.method, QuantizationMethod::NF4);
978
979 let dequantized = quantizer.dequantize(&quantized)?;
981 let dequant_data = dequantized.data_f32()?;
982
983 for (orig, dequant) in data.iter().zip(dequant_data.iter()) {
986 let abs_error = (orig - dequant).abs();
987 let rel_error = abs_error / orig.abs().max(1e-6);
988
989 let tolerance_met = rel_error < 1.0 || abs_error < 0.5;
992 assert!(
993 tolerance_met,
994 "Quantization error too large: {} vs {} (abs_error: {:.4}, rel_error: {:.4})",
995 orig, dequant, abs_error, rel_error
996 );
997 }
998
999 Ok(())
1000 }
1001
1002 #[test]
1003 fn test_fp4_quantization() -> Result<()> {
1004 let config = AdvancedQuantizationConfig {
1005 method: QuantizationMethod::FP4,
1006 ..AdvancedQuantizationConfig::default()
1007 };
1008 let quantizer = AdvancedQuantizer::new(config);
1009
1010 let data = vec![0.5, -1.0, 2.0, -3.5, 0.0, 1.5, -0.25, 4.0];
1011 let tensor = Tensor::from_vec(data.clone(), &[8])?;
1012
1013 let quantized = quantizer.quantize(&tensor)?;
1014 let dequantized = quantizer.dequantize(&quantized)?;
1015 let dequant_data = dequantized.data_f32()?;
1016
1017 assert_eq!(dequant_data.len(), data.len());
1019
1020 Ok(())
1021 }
1022
1023 #[test]
1024 fn test_quantization_stats() -> Result<()> {
1025 let config = AdvancedQuantizationConfig::default();
1026 let quantizer = AdvancedQuantizer::new(config);
1027
1028 let data = vec![1.0; 1024]; let tensor = Tensor::from_vec(data, &[1024])?;
1030
1031 let quantized = quantizer.quantize(&tensor)?;
1032 let stats = quantizer.get_stats(&quantized);
1033
1034 assert!(stats.compression_ratio > 4.0); assert_eq!(stats.original_size_bytes, 1024 * 4); Ok(())
1038 }
1039
1040 #[test]
1041 fn test_int4_asymmetric_quantization() -> Result<()> {
1042 let config = AdvancedQuantizationConfig {
1043 method: QuantizationMethod::Int4Asymmetric,
1044 ..AdvancedQuantizationConfig::default()
1045 };
1046 let quantizer = AdvancedQuantizer::new(config);
1047
1048 let data = vec![0.1, 0.3, 0.7, 0.9, 1.1, 1.3, 1.7, 1.9]; let tensor = Tensor::from_vec(data.clone(), &[8])?;
1050
1051 let quantized = quantizer.quantize(&tensor)?;
1052 assert!(quantized.zero_points.is_some());
1053
1054 let dequantized = quantizer.dequantize(&quantized)?;
1055 let dequant_data = dequantized.data_f32()?;
1056
1057 assert_eq!(dequant_data.len(), data.len());
1059
1060 Ok(())
1061 }
1062
1063 #[test]
1064 fn test_nf4_lookup_table() {
1065 let config = AdvancedQuantizationConfig::default();
1066 let quantizer = AdvancedQuantizer::new(config);
1067
1068 assert_eq!(quantizer.nf4_lookup.len(), 16);
1070
1071 assert_eq!(quantizer.nf4_lookup[&0], -1.0);
1073 assert_eq!(quantizer.nf4_lookup[&7], 0.0);
1074 assert_eq!(quantizer.nf4_lookup[&15], 1.0);
1075 }
1076
1077 #[test]
1081 fn test_nf4_table_monotone_increasing() {
1082 for i in 1..NF4_QUANT_TABLE.len() {
1083 assert!(
1084 NF4_QUANT_TABLE[i] > NF4_QUANT_TABLE[i - 1],
1085 "NF4 table must be strictly monotone: table[{}]={} <= table[{}]={}",
1086 i,
1087 NF4_QUANT_TABLE[i],
1088 i - 1,
1089 NF4_QUANT_TABLE[i - 1]
1090 );
1091 }
1092 }
1093
1094 #[test]
1096 fn test_nf4_table_zero_at_index_7() {
1097 assert_eq!(
1098 NF4_QUANT_TABLE[7], 0.0,
1099 "NF4 table index 7 must be 0.0 (zero is always a quantization level)"
1100 );
1101 }
1102
1103 #[test]
1105 fn test_nf4_table_values_in_unit_range() {
1106 for &v in NF4_QUANT_TABLE.iter() {
1107 assert!(
1108 (-1.0..=1.0).contains(&v),
1109 "NF4 quantile {} must be in [-1, 1]",
1110 v
1111 );
1112 }
1113 }
1114
1115 #[test]
1121 fn test_smoothquant_migration_scale_balance() {
1122 let alpha = 0.5f64;
1123 let act_max = [10.0f64, 5.0, 20.0];
1125 let weight_max = [1.0f64, 2.0, 0.5];
1126
1127 for i in 0..act_max.len() {
1128 let scale = weight_max[i].powf(alpha) / act_max[i].powf(1.0 - alpha);
1129 let new_act = act_max[i] * scale;
1133 let new_weight = weight_max[i] / scale;
1134 assert!(
1136 (new_act - new_weight).abs() < 1e-9,
1137 "SmoothQuant α=0.5 must equalise act/weight magnitudes; {} != {}",
1138 new_act,
1139 new_weight
1140 );
1141 }
1142 }
1143
1144 #[test]
1146 fn test_smoothquant_higher_alpha_smoothes_activations_more() {
1147 let act_max = 16.0f64;
1148 let weight_max = 1.0f64;
1149
1150 let scale_low_alpha = weight_max.powf(0.25) / act_max.powf(0.75); let scale_high_alpha = weight_max.powf(0.75) / act_max.powf(0.25); let new_act_low = act_max * scale_low_alpha;
1155 let new_act_high = act_max * scale_high_alpha;
1156
1157 assert!(
1158 new_act_high > new_act_low,
1159 "Higher α must give larger activation smoothing; got {} <= {}",
1160 new_act_high,
1161 new_act_low
1162 );
1163 }
1164
1165 #[test]
1169 fn test_outlier_detection_threshold() {
1170 let outlier_threshold = 6.0f32;
1171 let block = [0.1f32, 0.3, 50.0, -0.2, 0.8]; let abs_max = block.iter().map(|x| x.abs()).fold(0.0f32, f32::max);
1173
1174 let _outliers: Vec<usize> = block
1175 .iter()
1176 .enumerate()
1177 .filter(|(_, &v)| v.abs() > outlier_threshold * abs_max / outlier_threshold)
1178 .map(|(i, _)| i)
1179 .collect();
1180
1181 let strict_outliers: Vec<usize> = block
1185 .iter()
1186 .enumerate()
1187 .filter(|(_, &v)| v.abs() > abs_max * 0.9) .map(|(i, _)| i)
1189 .collect();
1190 assert_eq!(
1191 strict_outliers,
1192 vec![2],
1193 "Only index 2 (50.0) should be an outlier"
1194 );
1195 }
1196
1197 #[test]
1199 fn test_quantization_stats_tracks_outliers() -> Result<()> {
1200 let config = AdvancedQuantizationConfig {
1202 method: QuantizationMethod::NF4,
1203 outlier_threshold: 0.01, ..Default::default()
1205 };
1206 let quantizer = AdvancedQuantizer::new(config);
1207 let data: Vec<f32> = (0..64).map(|i| (i as f32) * 0.1).collect();
1208 let tensor = Tensor::from_vec(data, &[64])?;
1209 let quantized = quantizer.quantize(&tensor)?;
1210 let stats = quantizer.get_stats(&quantized);
1211 assert_eq!(
1214 stats.outlier_count,
1215 quantized.metadata.outlier_indices.as_ref().map(|v| v.len()).unwrap_or(0)
1216 );
1217 Ok(())
1218 }
1219
1220 #[test]
1225 fn test_awq_scaling_reduces_quantization_error() {
1226 let delta = 0.25f64; let quantize = |x: f64| (x / delta).round() * delta;
1231
1232 let w = 0.137f64; let act_scale = 2.0f64; let _err_without = (w - quantize(w)).abs();
1236 let _err_with = (w - quantize(w * act_scale) / act_scale).abs();
1237
1238 let bound_with = delta / act_scale;
1242 let bound_without = delta;
1243 assert!(
1244 bound_with < bound_without,
1245 "AWQ scaling must reduce quantization error bound: {} < {}",
1246 bound_with,
1247 bound_without
1248 );
1249 }
1250
1251 #[test]
1255 fn test_per_group_quantization_error_bound() {
1256 let bits = 4u32;
1260 let levels = (1u32 << bits) - 1; let min_val = -1.0f64;
1262 let max_val = 1.0f64;
1263 let scale = (max_val - min_val) / levels as f64;
1264 let max_error = scale / 2.0;
1265
1266 let a: u64 = 6364136223846793005;
1267 let c_lcg: u64 = 1442695040888963407;
1268 let mut lcg: u64 = 0x1122_3344_5566_7788;
1269
1270 for _ in 0..32 {
1272 lcg = lcg.wrapping_mul(a).wrapping_add(c_lcg);
1273 let x = min_val + (lcg as f64 / u64::MAX as f64) * (max_val - min_val);
1274 let q = ((x - min_val) / scale).round().clamp(0.0, levels as f64);
1275 let x_hat = q * scale + min_val;
1276 let error = (x - x_hat).abs();
1277 assert!(
1278 error <= max_error + 1e-10,
1279 "Quantization error {} must be <= bound {}",
1280 error,
1281 max_error
1282 );
1283 }
1284 }
1285
1286 #[test]
1290 fn test_double_quantization_preserves_scale_count() -> Result<()> {
1291 let config = AdvancedQuantizationConfig {
1292 double_quantization: true,
1293 ..Default::default()
1294 };
1295 let quantizer = AdvancedQuantizer::new(config);
1296 let data = vec![0.5f32; 128];
1297 let tensor = Tensor::from_vec(data, &[128])?;
1298 let quantized = quantizer.quantize(&tensor)?;
1299 let expected_blocks = 128usize.div_ceil(quantizer.config.block_size);
1301 assert_eq!(quantized.scales.len(), expected_blocks);
1302 Ok(())
1303 }
1304
1305 #[test]
1308 fn test_mixed_precision_config() -> Result<()> {
1309 let config = AdvancedQuantizationConfig {
1310 method: QuantizationMethod::MixedPrecision {
1311 primary_bits: 4,
1312 outlier_bits: 8,
1313 },
1314 ..Default::default()
1315 };
1316 let quantizer = AdvancedQuantizer::new(config);
1317 let data = vec![0.1f32, 0.2, 0.3, 0.4, 10.0, 0.5, 0.6, 0.7]; let tensor = Tensor::from_vec(data.clone(), &[8])?;
1319 let quantized = quantizer.quantize(&tensor)?;
1320 let dequantized = quantizer.dequantize(&quantized)?;
1323 let dequant_data = dequantized.data_f32()?;
1324 assert_eq!(
1325 dequant_data.len(),
1326 data.len(),
1327 "Mixed-precision must preserve element count"
1328 );
1329 Ok(())
1330 }
1331
1332 #[test]
1335 fn test_int8_blockwise_compression_ratio() -> Result<()> {
1336 let config = AdvancedQuantizationConfig {
1337 method: QuantizationMethod::Int8BlockWise,
1338 block_size: 32,
1339 double_quantization: false,
1340 ..Default::default()
1341 };
1342 let quantizer = AdvancedQuantizer::new(config);
1343 let data = vec![1.0f32; 128];
1344 let tensor = Tensor::from_vec(data, &[128])?;
1345 let quantized = quantizer.quantize(&tensor)?;
1346 let stats = quantizer.get_stats(&quantized);
1347 assert!(
1349 stats.compression_ratio > 2.0,
1350 "Int8 block-wise must achieve > 2x compression; got {}",
1351 stats.compression_ratio
1352 );
1353 Ok(())
1354 }
1355
1356 fn mixed_config(
1359 primary_bits: u8,
1360 outlier_bits: u8,
1361 threshold: f32,
1362 ) -> AdvancedQuantizationConfig {
1363 AdvancedQuantizationConfig {
1364 method: QuantizationMethod::MixedPrecision {
1365 primary_bits,
1366 outlier_bits,
1367 },
1368 block_size: 8,
1369 double_quantization: false,
1370 outlier_threshold: threshold,
1371 ..AdvancedQuantizationConfig::default()
1372 }
1373 }
1374
1375 #[test]
1379 fn mixed_precision_does_not_silently_produce_nf4() -> Result<()> {
1380 let quantizer = AdvancedQuantizer::new(mixed_config(4, 8, 6.0));
1381 let data: Vec<f32> = (0..16).map(|i| i as f32 * 0.1 - 0.8).collect();
1382 let tensor = Tensor::from_vec(data.clone(), &[16])?;
1383
1384 let quantized = quantizer.quantize(&tensor)?;
1385 assert_eq!(
1386 quantized.metadata.method,
1387 QuantizationMethod::MixedPrecision {
1388 primary_bits: 4,
1389 outlier_bits: 8,
1390 },
1391 "the method recorded must be the method actually used"
1392 );
1393 assert_eq!(
1394 quantized.data.len(),
1395 data.len(),
1396 "mixed precision stores one element per byte; NF4 packs two, so a 16-element \
1397 tensor would have produced 8 bytes under the old delegation"
1398 );
1399 Ok(())
1400 }
1401
1402 #[test]
1406 fn mixed_precision_honours_primary_bits() -> Result<()> {
1407 let data: Vec<f32> = (0..32).map(|i| (i as f32 * 0.37).sin()).collect();
1408 let tensor = Tensor::from_vec(data.clone(), &[32])?;
1409
1410 let error_at = |bits: u8| -> Result<f32> {
1411 let quantizer = AdvancedQuantizer::new(mixed_config(bits, 8, 100.0));
1412 let quantized = quantizer.quantize(&tensor)?;
1413 let restored = quantizer.dequantize(&quantized)?.data_f32()?;
1414 Ok(data
1415 .iter()
1416 .zip(restored.iter())
1417 .map(|(a, b)| (a - b).abs())
1418 .fold(0.0f32, f32::max))
1419 };
1420
1421 let coarse = error_at(2)?;
1422 let fine = error_at(8)?;
1423 assert!(
1424 fine < coarse,
1425 "more primary bits must reduce the reconstruction error: 8-bit gave {fine}, \
1426 2-bit gave {coarse}"
1427 );
1428 assert!(
1429 fine < 0.05,
1430 "8-bit reconstruction must be close, got {fine}"
1431 );
1432 Ok(())
1433 }
1434
1435 #[test]
1439 fn mixed_precision_preserves_outliers_at_higher_precision() -> Result<()> {
1440 let mut data = vec![0.05f32; 16];
1442 data[3] = 40.0;
1443 data[11] = -35.0;
1444 let tensor = Tensor::from_vec(data.clone(), &[16])?;
1445
1446 let quantizer = AdvancedQuantizer::new(mixed_config(4, 8, 10.0));
1447 let quantized = quantizer.quantize(&tensor)?;
1448
1449 let indices = quantized
1450 .metadata
1451 .outlier_indices
1452 .as_ref()
1453 .expect("the outliers must be recorded, not folded into the primary stream");
1454 assert_eq!(indices, &vec![3usize, 11], "both spikes must be detected");
1455 assert_eq!(
1456 quantized.metadata.outlier_values.as_ref().map(Vec::len),
1457 Some(2)
1458 );
1459
1460 let restored = quantizer.dequantize(&quantized)?.data_f32()?;
1461 assert!(
1462 (restored[3] - 40.0).abs() < 1.0,
1463 "the outlier must survive at high precision, got {}",
1464 restored[3]
1465 );
1466 assert!(
1467 (restored[11] + 35.0).abs() < 1.0,
1468 "the outlier must survive at high precision, got {}",
1469 restored[11]
1470 );
1471 assert!(
1474 (restored[0] - 0.05).abs() < 0.02,
1475 "excluding outliers from the block scale must preserve the small values, got {}",
1476 restored[0]
1477 );
1478 Ok(())
1479 }
1480
1481 #[test]
1484 fn mixed_precision_stats_describe_the_mixed_precision_result() -> Result<()> {
1485 let mut data = vec![0.1f32; 16];
1486 data[7] = 50.0;
1487 let tensor = Tensor::from_vec(data, &[16])?;
1488 let quantizer = AdvancedQuantizer::new(mixed_config(4, 8, 10.0));
1489 let quantized = quantizer.quantize(&tensor)?;
1490 let stats = quantizer.get_stats(&quantized);
1491
1492 assert_eq!(
1493 stats.method,
1494 QuantizationMethod::MixedPrecision {
1495 primary_bits: 4,
1496 outlier_bits: 8,
1497 }
1498 );
1499 assert_eq!(stats.outlier_count, 1);
1500 Ok(())
1501 }
1502
1503 #[test]
1504 fn mixed_precision_rejects_impossible_bit_widths() {
1505 let tensor = Tensor::from_vec(vec![1.0, 2.0], &[2]).expect("tensor must build");
1506
1507 for (primary, outlier) in [(0u8, 8u8), (4, 0), (9, 9), (8, 4)] {
1508 let quantizer = AdvancedQuantizer::new(mixed_config(primary, outlier, 6.0));
1509 assert!(
1510 quantizer.quantize(&tensor).is_err(),
1511 "primary_bits={primary}, outlier_bits={outlier} must be rejected"
1512 );
1513 }
1514 }
1515
1516 #[test]
1517 fn mixed_precision_round_trips_without_any_outlier() -> Result<()> {
1518 let data: Vec<f32> = (0..24).map(|i| i as f32 * 0.01).collect();
1519 let tensor = Tensor::from_vec(data.clone(), &[24])?;
1520 let quantizer = AdvancedQuantizer::new(mixed_config(8, 8, 1000.0));
1522 let quantized = quantizer.quantize(&tensor)?;
1523 assert!(quantized.metadata.outlier_indices.is_none());
1524
1525 let restored = quantizer.dequantize(&quantized)?.data_f32()?;
1526 for (original, back) in data.iter().zip(restored.iter()) {
1527 assert!(
1528 (original - back).abs() < 0.005,
1529 "8-bit round trip must be accurate: {original} vs {back}"
1530 );
1531 }
1532 Ok(())
1533 }
1534}