1use super::binary::BinaryVector;
9use super::int4::Int4Vector;
10use super::quantized::{QuantizedVector, cosine_similarity_i8_trusted, dot_product_i8_trusted};
11use super::{cosine_similarity, dot_product};
12use crate::error::{Result, SimdError};
13
14#[derive(Debug, Clone, Copy, PartialEq, Eq)]
19#[non_exhaustive]
20pub enum NormalizationHint {
21 Unknown,
23 Unit,
25}
26
27#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
31#[non_exhaustive]
32pub enum QuantizationTier {
33 Full,
35 Int8,
37 Int4,
39 Binary,
41}
42
43impl QuantizationTier {
44 pub fn bytes_per_dim(&self) -> f32 {
46 match self {
47 Self::Full => 4.0,
48 Self::Int8 => 1.0,
49 Self::Int4 => 0.5,
50 Self::Binary => 0.125,
51 }
52 }
53
54 pub fn compression_ratio(&self) -> f32 {
56 4.0 / self.bytes_per_dim()
57 }
58
59 pub fn storage_bytes(&self, dims: usize) -> usize {
61 match self {
62 Self::Full => dims * 4,
63 Self::Int8 => dims,
64 Self::Int4 => dims.div_ceil(2),
65 Self::Binary => dims.div_ceil(8),
66 }
67 }
68
69 pub fn from_age_seconds(age_secs: u64) -> Self {
74 const HOUR: u64 = 3600;
75 const DAY: u64 = 86400;
76 const WEEK: u64 = 604800;
77
78 if age_secs < HOUR {
79 Self::Full
80 } else if age_secs < DAY {
81 Self::Int8
82 } else if age_secs < WEEK {
83 Self::Int4
84 } else {
85 Self::Binary
86 }
87 }
88}
89
90#[derive(Debug, Clone)]
95#[non_exhaustive]
96pub enum QuantizedData {
97 Full(Vec<f32>),
99 Int8(QuantizedVector),
101 Int4(Int4Vector),
103 Binary(BinaryVector),
105}
106
107impl QuantizedData {
108 pub fn tier(&self) -> QuantizationTier {
110 match self {
111 Self::Full(_) => QuantizationTier::Full,
112 Self::Int8(_) => QuantizationTier::Int8,
113 Self::Int4(_) => QuantizationTier::Int4,
114 Self::Binary(_) => QuantizationTier::Binary,
115 }
116 }
117
118 pub fn dims(&self) -> usize {
120 match self {
121 Self::Full(v) => v.len(),
122 Self::Int8(q) => q.len(),
123 Self::Int4(q) => q.dims,
124 Self::Binary(q) => q.dims,
125 }
126 }
127
128 pub fn storage_bytes(&self) -> usize {
130 match self {
131 Self::Full(v) => v.len() * 4,
132 Self::Int8(q) => q.len(),
133 Self::Int4(q) => q.data.len(),
134 Self::Binary(q) => q.data.len(),
135 }
136 }
137
138 pub fn from_f32(vector: &[f32], tier: QuantizationTier) -> Self {
140 match tier {
141 QuantizationTier::Full => Self::Full(vector.to_vec()),
142 QuantizationTier::Int8 => Self::Int8(QuantizedVector::from_f32(vector)),
143 QuantizationTier::Int4 => Self::Int4(Int4Vector::from_f32(vector)),
144 QuantizationTier::Binary => Self::Binary(BinaryVector::from_f32(vector)),
145 }
146 }
147
148 pub fn to_f32(&self) -> Vec<f32> {
150 match self {
151 Self::Full(v) => v.clone(),
152 Self::Int8(q) => q.to_f32(),
153 Self::Int4(q) => q.to_f32(),
154 Self::Binary(q) => q.to_f32(),
155 }
156 }
157
158 pub fn promote(&self, target: QuantizationTier) -> Self {
160 let f32_data = self.to_f32();
161 Self::from_f32(&f32_data, target)
162 }
163
164 pub fn demote(&self, target: QuantizationTier) -> Self {
166 self.promote(target) }
168}
169
170#[derive(Debug, Clone)]
172#[non_exhaustive]
173pub enum PreparedQuery {
174 Full(Vec<f32>),
176 Int8(QuantizedVector),
178 Int4(Int4Vector),
180 Binary(BinaryVector),
182}
183
184impl PreparedQuery {
185 #[inline]
187 pub fn from_f32(query_f32: &[f32], tier: QuantizationTier) -> Self {
188 match tier {
189 QuantizationTier::Full => Self::Full(query_f32.to_vec()),
190 QuantizationTier::Int8 => Self::Int8(QuantizedVector::from_f32(query_f32)),
191 QuantizationTier::Int4 => Self::Int4(Int4Vector::from_f32(query_f32)),
192 QuantizationTier::Binary => Self::Binary(BinaryVector::from_f32(query_f32)),
193 }
194 }
195
196 #[inline]
198 pub fn tier(&self) -> QuantizationTier {
199 match self {
200 Self::Full(_) => QuantizationTier::Full,
201 Self::Int8(_) => QuantizationTier::Int8,
202 Self::Int4(_) => QuantizationTier::Int4,
203 Self::Binary(_) => QuantizationTier::Binary,
204 }
205 }
206
207 #[inline]
209 pub fn dims(&self) -> usize {
210 match self {
211 Self::Full(v) => v.len(),
212 Self::Int8(q) => q.len(),
213 Self::Int4(q) => q.dims,
214 Self::Binary(q) => q.dims,
215 }
216 }
217}
218
219#[inline]
221pub fn prepare_query(query_f32: &[f32], tier: QuantizationTier) -> PreparedQuery {
222 PreparedQuery::from_f32(query_f32, tier)
223}
224
225#[derive(Debug, Clone)]
227pub struct PreparedQueryWithMeta {
228 pub query: PreparedQuery,
230 pub norm: NormalizationHint,
232}
233
234impl PreparedQueryWithMeta {
235 #[inline]
237 pub fn from_f32(query_f32: &[f32], tier: QuantizationTier, norm: NormalizationHint) -> Self {
238 Self {
239 query: PreparedQuery::from_f32(query_f32, tier),
240 norm,
241 }
242 }
243
244 #[inline]
246 pub fn tier(&self) -> QuantizationTier {
247 self.query.tier()
248 }
249
250 #[inline]
252 pub fn dims(&self) -> usize {
253 self.query.dims()
254 }
255}
256
257#[inline]
265pub fn is_unit_norm(v: &[f32]) -> bool {
266 let sq = dot_product(v, v);
267 (sq - 1.0).abs() < 1e-4
268}
269
270#[inline]
272pub fn prepare_query_with_norm(
273 query_f32: &[f32],
274 tier: QuantizationTier,
275 norm: NormalizationHint,
276) -> PreparedQueryWithMeta {
277 PreparedQueryWithMeta::from_f32(query_f32, tier, norm)
278}
279
280#[inline]
285pub fn approximate_cosine_distance_prepared(
286 query: &PreparedQuery,
287 stored: &QuantizedData,
288) -> Result<f32> {
289 match (query, stored) {
290 (PreparedQuery::Full(q), QuantizedData::Full(s)) => Ok(1.0 - cosine_similarity(q, s)),
291 (PreparedQuery::Int8(q), QuantizedData::Int8(s)) => {
292 Ok(1.0 - cosine_similarity_i8_trusted(s, q))
293 }
294 (PreparedQuery::Int4(q), QuantizedData::Int4(s)) => Ok(s.cosine_distance(q)),
295 (PreparedQuery::Binary(q), QuantizedData::Binary(s)) => Ok(s.cosine_distance_approx(q)),
296 _ => Err(SimdError::TierMismatch {
297 op: "approximate_cosine_distance_prepared",
298 expected: stored.tier(),
299 actual: query.tier(),
300 }),
301 }
302}
303
304#[inline]
306pub fn try_approximate_cosine_distance_prepared(
307 query: &PreparedQuery,
308 stored: &QuantizedData,
309) -> Result<f32> {
310 approximate_cosine_distance_prepared(query, stored)
311}
312
313#[inline]
315pub fn try_approximate_dot_product_prepared(
316 query: &PreparedQuery,
317 stored: &QuantizedData,
318) -> Result<f32> {
319 approximate_dot_product_prepared(query, stored)
320}
321
322#[inline]
335pub fn approximate_cosine_distance_prepared_with_meta(
336 meta: &PreparedQueryWithMeta,
337 stored: &QuantizedData,
338 _stored_norm: NormalizationHint,
339) -> Result<f32> {
340 approximate_cosine_distance_prepared(&meta.query, stored)
341}
342
343#[inline]
348pub fn approximate_dot_product_prepared(
349 query: &PreparedQuery,
350 stored: &QuantizedData,
351) -> Result<f32> {
352 match (query, stored) {
353 (PreparedQuery::Full(q), QuantizedData::Full(s)) => Ok(dot_product(q, s)),
354 (PreparedQuery::Int8(q), QuantizedData::Int8(s)) => Ok(dot_product_i8_trusted(q, s)),
355 (PreparedQuery::Int4(q), QuantizedData::Int4(s)) => Ok(s.dot_product(q)),
356 (PreparedQuery::Binary(_), QuantizedData::Binary(_)) => Err(SimdError::Internal(
357 "Binary has no prepared dot product; use approximate_cosine_distance_prepared".into(),
358 )),
359 _ => Err(SimdError::TierMismatch {
360 op: "approximate_dot_product_prepared",
361 expected: stored.tier(),
362 actual: query.tier(),
363 }),
364 }
365}
366
367#[inline]
371pub fn batch_approximate_cosine_distance_prepared(
372 query: &PreparedQuery,
373 stored: &[QuantizedData],
374) -> Result<Vec<f32>> {
375 stored
376 .iter()
377 .map(|item| approximate_cosine_distance_prepared(query, item))
378 .collect()
379}
380
381#[inline]
386pub fn batch_approximate_cosine_distance_prepared_into(
387 query: &PreparedQuery,
388 stored: &[QuantizedData],
389 out: &mut Vec<f32>,
390) -> Result<()> {
391 out.clear();
392 out.reserve(stored.len());
393 for item in stored {
394 match approximate_cosine_distance_prepared(query, item) {
395 Ok(distance) => out.push(distance),
396 Err(e) => {
397 out.clear();
398 return Err(e);
399 }
400 }
401 }
402 Ok(())
403}
404
405#[inline]
409pub fn approximate_int8_batch_prepared(
410 query: &PreparedQuery,
411 candidates: &[QuantizedVector],
412) -> Result<Vec<f32>> {
413 let PreparedQuery::Int8(q) = query else {
414 return Err(SimdError::TierMismatch {
415 op: "approximate_int8_batch_prepared",
416 expected: QuantizationTier::Int8,
417 actual: query.tier(),
418 });
419 };
420 Ok(candidates
421 .iter()
422 .map(|candidate| 1.0 - cosine_similarity_i8_trusted(candidate, q))
423 .collect())
424}
425
426#[inline]
430pub fn approximate_int8_batch_prepared_into(
431 query: &PreparedQuery,
432 candidates: &[QuantizedVector],
433 out: &mut Vec<f32>,
434) -> Result<()> {
435 out.clear();
436 let PreparedQuery::Int8(q) = query else {
437 return Err(SimdError::TierMismatch {
438 op: "approximate_int8_batch_prepared_into",
439 expected: QuantizationTier::Int8,
440 actual: query.tier(),
441 });
442 };
443 out.reserve(candidates.len());
444 out.extend(
445 candidates
446 .iter()
447 .map(|candidate| 1.0 - cosine_similarity_i8_trusted(candidate, q)),
448 );
449 Ok(())
450}
451
452#[inline]
456pub fn approximate_int4_batch_prepared(
457 query: &PreparedQuery,
458 candidates: &[Int4Vector],
459) -> Result<Vec<f32>> {
460 let PreparedQuery::Int4(q) = query else {
461 return Err(SimdError::TierMismatch {
462 op: "approximate_int4_batch_prepared",
463 expected: QuantizationTier::Int4,
464 actual: query.tier(),
465 });
466 };
467 Ok(candidates
468 .iter()
469 .map(|candidate| candidate.cosine_distance(q))
470 .collect())
471}
472
473#[inline]
477pub fn approximate_int4_batch_prepared_into(
478 query: &PreparedQuery,
479 candidates: &[Int4Vector],
480 out: &mut Vec<f32>,
481) -> Result<()> {
482 out.clear();
483 let PreparedQuery::Int4(q) = query else {
484 return Err(SimdError::TierMismatch {
485 op: "approximate_int4_batch_prepared_into",
486 expected: QuantizationTier::Int4,
487 actual: query.tier(),
488 });
489 };
490 out.reserve(candidates.len());
491 out.extend(
492 candidates
493 .iter()
494 .map(|candidate| candidate.cosine_distance(q)),
495 );
496 Ok(())
497}
498
499pub fn approximate_cosine_distance(query_f32: &[f32], stored: &QuantizedData) -> f32 {
504 debug_assert_eq!(
505 query_f32.len(),
506 stored.dims(),
507 "approximate_cosine_distance: query length {} != stored dims {}",
508 query_f32.len(),
509 stored.dims(),
510 );
511 match stored {
512 QuantizedData::Full(v) => {
513 1.0 - cosine_similarity(query_f32, v)
515 }
516 QuantizedData::Int8(q) => {
517 let query_q = QuantizedVector::from_f32(query_f32);
518 1.0 - q.cosine_similarity(&query_q)
519 }
520 QuantizedData::Int4(q) => {
521 let query_q = Int4Vector::from_f32(query_f32);
522 q.cosine_distance(&query_q)
523 }
524 QuantizedData::Binary(q) => {
525 let query_q = BinaryVector::from_f32(query_f32);
526 q.cosine_distance_approx(&query_q)
527 }
528 }
529}
530
531pub fn approximate_dot_product(query_f32: &[f32], stored: &QuantizedData) -> f32 {
533 match stored {
534 QuantizedData::Full(v) => dot_product(query_f32, v),
535 QuantizedData::Int8(q) => {
536 let query_q = QuantizedVector::from_f32(query_f32);
537 q.dot_product(&query_q)
538 }
539 QuantizedData::Int4(q) => {
540 let query_q = Int4Vector::from_f32(query_f32);
541 q.dot_product(&query_q)
542 }
543 QuantizedData::Binary(_q) => {
544 let stored_f32 = _q.to_f32();
546 dot_product(query_f32, &stored_f32)
547 }
548 }
549}
550
551#[cfg(test)]
552mod tests;