littlebit_models/
patch.rs1use std::fmt;
4
5use regex::Regex;
6
7use littlebit_core::{LittleBitConfig, TrainMode};
8
9use crate::error::{ModelError, Result};
10use crate::layer::LinearLayer;
11
12#[derive(Debug, Clone)]
14pub struct PatchPolicy {
15 kv_patterns: Vec<Regex>,
17 pub exclude_names: Vec<String>,
19}
20
21impl Default for PatchPolicy {
22 fn default() -> Self {
23 Self::new()
24 }
25}
26
27impl PatchPolicy {
28 #[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 #[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 #[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#[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#[derive(Debug, Clone, PartialEq)]
74pub struct PatchSummary {
75 pub patched_layers: usize,
77 pub skipped_layers: usize,
79 pub total_quantized_weights: usize,
81 pub total_quantized_bits: f64,
83 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
133pub 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}