Skip to main content

littlebit_models/
patch.rs

1//! Dynamic LittleBit patching matching upstream `quantization/utils/quant_util.py`.
2
3use std::fmt;
4
5use regex::Regex;
6
7use littlebit_core::{LittleBitConfig, TrainMode};
8
9use crate::error::{ModelError, Result};
10use crate::layer::LinearLayer;
11
12/// Pattern rules for per-layer rank scaling (`KV_PATTERN`) and exclusion (`lm_head`).
13#[derive(Debug, Clone)]
14pub struct PatchPolicy {
15    /// Regex patterns matching K/V projections that receive `config.kv_factor`.
16    kv_patterns: Vec<Regex>,
17    /// Substring patterns for module names excluded from quantization (`["lm_head"]` default).
18    pub exclude_names: Vec<String>,
19}
20
21impl Default for PatchPolicy {
22    fn default() -> Self {
23        Self::new()
24    }
25}
26
27impl PatchPolicy {
28    /// Build default upstream policy (`\.k_proj$` and `\.v_proj$` receive `kv_factor`;
29    /// `lm_head` and MoE `router` projections are excluded).
30    #[must_use]
31    pub fn new() -> Self {
32        let kv_patterns = vec![
33            Regex::new(r"\.k_proj$").expect("valid k_proj regex"),
34            Regex::new(r"\.v_proj$").expect("valid v_proj regex"),
35        ];
36        Self {
37            kv_patterns,
38            exclude_names: vec!["lm_head".to_string(), "router".to_string()],
39        }
40    }
41
42    /// Return true if `module_name` matches any excluded substring.
43    #[must_use]
44    pub fn is_excluded(&self, module_name: &str) -> bool {
45        self.exclude_names
46            .iter()
47            .any(|ex| module_name.contains(ex.as_str()))
48    }
49
50    /// Compute the rank multiplier (`kv_factor` for `.k_proj` / `.v_proj`, otherwise `1.0`).
51    #[must_use]
52    pub fn ratio_factor(&self, module_name: &str, config: &LittleBitConfig) -> f64 {
53        if self.kv_patterns.iter().any(|re| re.is_match(module_name)) {
54            config.kv_factor
55        } else {
56            1.0
57        }
58    }
59}
60
61/// Deterministic FNV-1a seed derivation from `base_seed` and module name.
62#[must_use]
63pub fn derive_layer_seed(base_seed: u64, module_name: &str) -> u64 {
64    let mut hash = 0xcbf2_9ce4_8422_2325_u64 ^ base_seed;
65    for byte in module_name.as_bytes() {
66        hash ^= u64::from(*byte);
67        hash = hash.wrapping_mul(0x0100_0000_01b3);
68    }
69    hash
70}
71
72/// Summary statistics emitted after applying LittleBit quantization patch across a model.
73#[derive(Debug, Clone, PartialEq)]
74pub struct PatchSummary {
75    /// Number of linear modules quantized to `LittleBitLinear`.
76    pub patched_layers: usize,
77    /// Number of linear modules skipped due to exclusion policy (`lm_head`).
78    pub skipped_layers: usize,
79    /// Sum of `in_features * out_features` across all patched layers.
80    pub total_quantized_weights: usize,
81    /// Sum of actual bit usage across all patched layers.
82    pub total_quantized_bits: f64,
83    /// Average effective bits per weight across patched layers.
84    pub avg_eff_bits: f64,
85}
86
87impl PatchSummary {
88    pub(crate) fn record_budget(&mut self, budget: &littlebit_core::BitBudget) {
89        self.patched_layers += 1;
90        self.total_quantized_weights += budget.in_features * budget.out_features;
91        self.total_quantized_bits += budget.total_bit_usage;
92        if self.total_quantized_weights > 0 {
93            self.avg_eff_bits = self.total_quantized_bits / (self.total_quantized_weights as f64);
94        }
95    }
96
97    pub(crate) fn record_patched(&mut self, layer: &LinearLayer) {
98        if let LinearLayer::LittleBit(lb) = layer {
99            self.record_budget(lb.budget());
100        }
101    }
102
103    pub(crate) fn record_skipped(&mut self) {
104        self.skipped_layers += 1;
105    }
106}
107
108impl Default for PatchSummary {
109    fn default() -> Self {
110        Self {
111            patched_layers: 0,
112            skipped_layers: 0,
113            total_quantized_weights: 0,
114            total_quantized_bits: 0.0,
115            avg_eff_bits: 0.0,
116        }
117    }
118}
119
120impl fmt::Display for PatchSummary {
121    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
122        write!(
123            f,
124            "patched={} skipped={} weights={} avg_eff_bits={:.4}",
125            self.patched_layers,
126            self.skipped_layers,
127            self.total_quantized_weights,
128            self.avg_eff_bits
129        )
130    }
131}
132
133/// Patch a named [`LinearLayer`] according to `policy` and update `summary`.
134///
135/// # Errors
136/// Returns an error if SVD/ITQ decomposition fails.
137pub fn patch_linear_layer(
138    module_name: &str,
139    layer: &mut LinearLayer,
140    config: &LittleBitConfig,
141    policy: &PatchPolicy,
142    train_mode: TrainMode,
143    base_seed: u64,
144    summary: &mut PatchSummary,
145) -> Result<()> {
146    config.validate().map_err(ModelError::Core)?;
147    if policy.is_excluded(module_name) {
148        summary.record_skipped();
149        return Ok(());
150    }
151    let effective_cfg = config
152        .effective_for_module(module_name)
153        .map_err(ModelError::Core)?;
154    let ratio = policy.ratio_factor(module_name, &effective_cfg);
155    let seed = derive_layer_seed(base_seed, module_name);
156    layer.convert_to_littlebit(&effective_cfg, ratio, train_mode, seed)?;
157    summary.record_patched(layer);
158    Ok(())
159}