1use uqa_storage::InvertedIndex;
10
11use super::{
12 storage_sql_error, BM25Params, BTreeMap, DocId, Engine, ParameterLearner, SQLError,
13 ScoringMode, UnsupervisedBm25ScoreEstimator,
14};
15
16impl Engine {
17 pub fn learn_scoring_params(
18 &self,
19 table: &str,
20 field: &str,
21 query: &str,
22 labels: &[u8],
23 ) -> Result<std::collections::BTreeMap<String, f64>, SQLError> {
24 self.with_implicit_transaction(|engine| {
25 engine.learn_scoring_params_inner(table, field, query, labels)
26 })
27 }
28
29 pub(super) fn learn_scoring_params_inner(
30 &self,
31 table: &str,
32 field: &str,
33 query: &str,
34 labels: &[u8],
35 ) -> Result<std::collections::BTreeMap<String, f64>, SQLError> {
36 if self
37 .try_table(table)
38 .map_err(|error| storage_sql_error("resolve scoring table", error))?
39 .is_none()
40 {
41 return Err(SQLError::UnknownTable(table.to_string()));
42 }
43 let doc_ids = self.query_table_doc_ids(table)?;
44 if labels.len() != doc_ids.len() {
45 return Err(SQLError::TypeMismatch(format!(
46 "labels length ({}) must match document count ({})",
47 labels.len(),
48 doc_ids.len()
49 )));
50 }
51 if labels.iter().any(|label| *label > 1) {
52 return Err(SQLError::TypeMismatch(
53 "labels must contain only 0 or 1".into(),
54 ));
55 }
56
57 let mode = ScoringMode::BM25(BM25Params::default());
58 let score_map: std::collections::BTreeMap<DocId, f64> = self
59 .search(table, field, query, &mode, usize::MAX)?
60 .into_iter()
61 .map(|entry| (entry.doc_id, entry.score))
62 .collect();
63 let scores: Vec<f64> = doc_ids
64 .iter()
65 .map(|doc_id| score_map.get(doc_id).copied().unwrap_or(0.0))
66 .collect();
67 let labels_f: Vec<f64> = labels.iter().map(|label| f64::from(*label)).collect();
68 let mut learner = ParameterLearner::default();
69 let params = learner
70 .fit_with_options(&scores, &labels_f)
71 .map_err(|error| SQLError::Internal(format!("learn scoring parameters: {error}")))?;
72 let json = serde_json::to_string(¶ms)
73 .map_err(|err| SQLError::Internal(format!("serialize scoring params: {err}")))?;
74 self.save_scoring_params(&format!("{table}.{field}"), &json)?;
75 Ok(params)
76 }
77
78 pub fn estimate_scoring_params(
81 &self,
82 table: &str,
83 field: &str,
84 n_samples: usize,
85 tokens_per_query: usize,
86 seed: i64,
87 ) -> Result<BTreeMap<String, f64>, SQLError> {
88 self.with_implicit_transaction(|engine| {
89 engine.estimate_scoring_params_inner(table, field, n_samples, tokens_per_query, seed)
90 })
91 }
92
93 pub(super) fn estimate_scoring_params_inner(
94 &self,
95 table: &str,
96 field: &str,
97 n_samples: usize,
98 tokens_per_query: usize,
99 seed: i64,
100 ) -> Result<BTreeMap<String, f64>, SQLError> {
101 if n_samples == 0 || tokens_per_query == 0 {
102 return Err(SQLError::TypeMismatch(
103 "n_samples and tokens_per_query must be positive".into(),
104 ));
105 }
106 if n_samples.checked_mul(tokens_per_query).is_none() {
107 return Err(SQLError::TypeMismatch(
108 "n_samples * tokens_per_query exceeds usize".into(),
109 ));
110 }
111 self.validate_text_search_field(table, field)?;
112 let Some(table_state) = self
113 .try_table(table)
114 .map_err(|error| storage_sql_error("resolve scoring table", error))?
115 else {
116 return Err(SQLError::UnknownTable(table.to_string()));
117 };
118 let estimator = UnsupervisedBm25ScoreEstimator::new(n_samples, tokens_per_query, seed)
119 .map_err(|error| SQLError::TypeMismatch(error.to_string()))?;
120 let queries = self.sample_calibration_queries(table, field, &estimator)?;
121 let (params, doc_count) = {
122 let index = table_state.inverted_index.read();
123 let index = uqa_execution::serializable::text::ObservedTextIndex::new(
124 index.as_ref(),
125 self.serializable_table_read(table)?,
126 table_state.columns.snapshot(),
127 );
128 let params = if queries.is_empty() {
129 estimator.estimate(&index, field, BM25Params::default())
130 } else {
131 estimator.estimate_with_query_keys(&index, field, BM25Params::default(), &queries)
132 }
133 .map_err(|error| storage_sql_error("estimate Bayesian BM25 parameters", error))?;
134 let doc_count = index
135 .doc_count()
136 .map_err(|error| storage_sql_error("read indexed document count", error))?;
137 (params, doc_count)
138 };
139 let values = BTreeMap::from([
140 ("alpha".to_string(), params.alpha),
141 ("beta".to_string(), params.beta),
142 ("base_rate".to_string(), params.base_rate),
143 ("calibration_tokens".to_string(), params.calibration_tokens),
144 ("beta_slope".to_string(), params.beta_slope),
145 ("sigma_slope".to_string(), params.sigma_slope),
146 ("estimated_doc_count".to_string(), doc_count as f64),
147 ]);
148 let json = serde_json::to_string(&values)
149 .map_err(|err| SQLError::Internal(format!("serialize scoring params: {err}")))?;
150 self.save_scoring_params(&format!("{table}.{field}"), &json)?;
151 Ok(values)
152 }
153
154 pub fn update_scoring_params(
155 &self,
156 table: &str,
157 field: &str,
158 score: f64,
159 label: u8,
160 ) -> Result<(), SQLError> {
161 self.with_implicit_transaction(|engine| {
162 engine.update_scoring_params_inner(table, field, score, label)
163 })
164 }
165
166 pub(super) fn update_scoring_params_inner(
167 &self,
168 table: &str,
169 field: &str,
170 score: f64,
171 label: u8,
172 ) -> Result<(), SQLError> {
173 self.validate_text_search_field(table, field)?;
174 if !score.is_finite() {
175 return Err(SQLError::TypeMismatch(
176 "score must be a finite raw BM25 score".into(),
177 ));
178 }
179 if label > 1 {
180 return Err(SQLError::TypeMismatch("label must be 0 or 1".into()));
181 }
182 let key = format!("{table}.{field}");
183 self.lock_scoring_parameter_write(&key)?;
184 let saved = self.load_scoring_params(&key)?;
185 let has_saved_params = match saved.as_deref() {
186 Some(json) => {
187 serde_json::from_str::<BTreeMap<String, f64>>(json).map_err(|error| {
188 SQLError::Internal(format!(
189 "decode persisted scoring parameters `{key}`: {error}"
190 ))
191 })?;
192 true
193 }
194 None => false,
195 };
196 let mut learner = if has_saved_params {
197 let current = self.bayesian_params_for(table, field)?;
198 let base_rate = (current.base_rate > 0.0).then_some(current.base_rate);
199 ParameterLearner::new(current.alpha, current.beta, base_rate).map_err(|error| {
200 SQLError::Internal(format!("restore scoring parameter learner: {error}"))
201 })?
202 } else {
203 ParameterLearner::default()
204 };
205 learner
206 .update(score, f64::from(label), 0.1)
207 .map_err(|error| SQLError::Internal(format!("update scoring parameters: {error}")))?;
208 let json = serde_json::to_string(&learner.params())
209 .map_err(|err| SQLError::Internal(format!("serialize scoring params: {err}")))?;
210 self.save_scoring_params(&key, &json)
211 }
212}