use super::binary::BinaryVector;
use super::int4::Int4Vector;
use super::quantized::{QuantizedVector, cosine_similarity_i8_trusted, dot_product_i8_trusted};
use super::{cosine_similarity, dot_product};
use crate::error::{EmbedError, Result};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum NormalizationHint {
Unknown,
Unit,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[non_exhaustive]
pub enum QuantizationTier {
Full,
Int8,
Int4,
Binary,
}
impl QuantizationTier {
pub fn bytes_per_dim(&self) -> f32 {
match self {
Self::Full => 4.0,
Self::Int8 => 1.0,
Self::Int4 => 0.5,
Self::Binary => 0.125,
}
}
pub fn compression_ratio(&self) -> f32 {
4.0 / self.bytes_per_dim()
}
pub fn storage_bytes(&self, dims: usize) -> usize {
match self {
Self::Full => dims * 4,
Self::Int8 => dims,
Self::Int4 => dims.div_ceil(2),
Self::Binary => dims.div_ceil(8),
}
}
pub fn from_age_seconds(age_secs: u64) -> Self {
const HOUR: u64 = 3600;
const DAY: u64 = 86400;
const WEEK: u64 = 604800;
if age_secs < HOUR {
Self::Full
} else if age_secs < DAY {
Self::Int8
} else if age_secs < WEEK {
Self::Int4
} else {
Self::Binary
}
}
}
#[derive(Debug, Clone)]
#[non_exhaustive]
pub enum QuantizedData {
Full(Vec<f32>),
Int8(QuantizedVector),
Int4(Int4Vector),
Binary(BinaryVector),
}
impl QuantizedData {
pub fn tier(&self) -> QuantizationTier {
match self {
Self::Full(_) => QuantizationTier::Full,
Self::Int8(_) => QuantizationTier::Int8,
Self::Int4(_) => QuantizationTier::Int4,
Self::Binary(_) => QuantizationTier::Binary,
}
}
pub fn dims(&self) -> usize {
match self {
Self::Full(v) => v.len(),
Self::Int8(q) => q.len(),
Self::Int4(q) => q.dims,
Self::Binary(q) => q.dims,
}
}
pub fn storage_bytes(&self) -> usize {
match self {
Self::Full(v) => v.len() * 4,
Self::Int8(q) => q.len(),
Self::Int4(q) => q.data.len(),
Self::Binary(q) => q.data.len(),
}
}
pub fn from_f32(vector: &[f32], tier: QuantizationTier) -> Self {
match tier {
QuantizationTier::Full => Self::Full(vector.to_vec()),
QuantizationTier::Int8 => Self::Int8(QuantizedVector::from_f32(vector)),
QuantizationTier::Int4 => Self::Int4(Int4Vector::from_f32(vector)),
QuantizationTier::Binary => Self::Binary(BinaryVector::from_f32(vector)),
}
}
pub fn to_f32(&self) -> Vec<f32> {
match self {
Self::Full(v) => v.clone(),
Self::Int8(q) => q.to_f32(),
Self::Int4(q) => q.to_f32(),
Self::Binary(q) => q.to_f32(),
}
}
pub fn promote(&self, target: QuantizationTier) -> Self {
let f32_data = self.to_f32();
Self::from_f32(&f32_data, target)
}
pub fn demote(&self, target: QuantizationTier) -> Self {
self.promote(target) }
}
#[derive(Debug, Clone)]
#[non_exhaustive]
pub enum PreparedQuery {
Full(Vec<f32>),
Int8(QuantizedVector),
Int4(Int4Vector),
Binary(BinaryVector),
}
impl PreparedQuery {
#[inline]
pub fn from_f32(query_f32: &[f32], tier: QuantizationTier) -> Self {
match tier {
QuantizationTier::Full => Self::Full(query_f32.to_vec()),
QuantizationTier::Int8 => Self::Int8(QuantizedVector::from_f32(query_f32)),
QuantizationTier::Int4 => Self::Int4(Int4Vector::from_f32(query_f32)),
QuantizationTier::Binary => Self::Binary(BinaryVector::from_f32(query_f32)),
}
}
#[inline]
pub fn tier(&self) -> QuantizationTier {
match self {
Self::Full(_) => QuantizationTier::Full,
Self::Int8(_) => QuantizationTier::Int8,
Self::Int4(_) => QuantizationTier::Int4,
Self::Binary(_) => QuantizationTier::Binary,
}
}
#[inline]
pub fn dims(&self) -> usize {
match self {
Self::Full(v) => v.len(),
Self::Int8(q) => q.len(),
Self::Int4(q) => q.dims,
Self::Binary(q) => q.dims,
}
}
}
#[inline]
pub fn prepare_query(query_f32: &[f32], tier: QuantizationTier) -> PreparedQuery {
PreparedQuery::from_f32(query_f32, tier)
}
#[derive(Debug, Clone)]
pub struct PreparedQueryWithMeta {
pub query: PreparedQuery,
pub norm: NormalizationHint,
}
impl PreparedQueryWithMeta {
#[inline]
pub fn from_f32(query_f32: &[f32], tier: QuantizationTier, norm: NormalizationHint) -> Self {
Self {
query: PreparedQuery::from_f32(query_f32, tier),
norm,
}
}
#[inline]
pub fn tier(&self) -> QuantizationTier {
self.query.tier()
}
#[inline]
pub fn dims(&self) -> usize {
self.query.dims()
}
}
#[inline]
pub fn is_unit_norm(v: &[f32]) -> bool {
let sq = dot_product(v, v);
(sq - 1.0).abs() < 1e-4
}
#[inline]
pub fn prepare_query_with_norm(
query_f32: &[f32],
tier: QuantizationTier,
norm: NormalizationHint,
) -> PreparedQueryWithMeta {
PreparedQueryWithMeta::from_f32(query_f32, tier, norm)
}
#[inline]
pub fn approximate_cosine_distance_prepared(
query: &PreparedQuery,
stored: &QuantizedData,
) -> Result<f32> {
match (query, stored) {
(PreparedQuery::Full(q), QuantizedData::Full(s)) => Ok(1.0 - cosine_similarity(q, s)),
(PreparedQuery::Int8(q), QuantizedData::Int8(s)) => {
Ok(1.0 - cosine_similarity_i8_trusted(s, q))
}
(PreparedQuery::Int4(q), QuantizedData::Int4(s)) => Ok(s.cosine_distance(q)),
(PreparedQuery::Binary(q), QuantizedData::Binary(s)) => Ok(s.cosine_distance_approx(q)),
_ => Err(EmbedError::TierMismatch {
op: "approximate_cosine_distance_prepared",
expected: stored.tier(),
actual: query.tier(),
}),
}
}
#[inline]
pub fn try_approximate_cosine_distance_prepared(
query: &PreparedQuery,
stored: &QuantizedData,
) -> Result<f32> {
approximate_cosine_distance_prepared(query, stored)
}
#[inline]
pub fn try_approximate_dot_product_prepared(
query: &PreparedQuery,
stored: &QuantizedData,
) -> Result<f32> {
approximate_dot_product_prepared(query, stored)
}
#[inline]
pub fn approximate_cosine_distance_prepared_with_meta(
meta: &PreparedQueryWithMeta,
stored: &QuantizedData,
_stored_norm: NormalizationHint,
) -> Result<f32> {
approximate_cosine_distance_prepared(&meta.query, stored)
}
#[inline]
pub fn approximate_dot_product_prepared(
query: &PreparedQuery,
stored: &QuantizedData,
) -> Result<f32> {
match (query, stored) {
(PreparedQuery::Full(q), QuantizedData::Full(s)) => Ok(dot_product(q, s)),
(PreparedQuery::Int8(q), QuantizedData::Int8(s)) => Ok(dot_product_i8_trusted(q, s)),
(PreparedQuery::Int4(q), QuantizedData::Int4(s)) => Ok(s.dot_product(q)),
(PreparedQuery::Binary(_), QuantizedData::Binary(_)) => Err(EmbedError::Internal(
"Binary has no prepared dot product; use approximate_cosine_distance_prepared".into(),
)),
_ => Err(EmbedError::TierMismatch {
op: "approximate_dot_product_prepared",
expected: stored.tier(),
actual: query.tier(),
}),
}
}
#[inline]
pub fn batch_approximate_cosine_distance_prepared(
query: &PreparedQuery,
stored: &[QuantizedData],
) -> Result<Vec<f32>> {
stored
.iter()
.map(|item| approximate_cosine_distance_prepared(query, item))
.collect()
}
#[inline]
pub fn batch_approximate_cosine_distance_prepared_into(
query: &PreparedQuery,
stored: &[QuantizedData],
out: &mut Vec<f32>,
) -> Result<()> {
out.clear();
out.reserve(stored.len());
for item in stored {
match approximate_cosine_distance_prepared(query, item) {
Ok(distance) => out.push(distance),
Err(e) => {
out.clear();
return Err(e);
}
}
}
Ok(())
}
#[inline]
pub fn approximate_int8_batch_prepared(
query: &PreparedQuery,
candidates: &[QuantizedVector],
) -> Result<Vec<f32>> {
let PreparedQuery::Int8(q) = query else {
return Err(EmbedError::TierMismatch {
op: "approximate_int8_batch_prepared",
expected: QuantizationTier::Int8,
actual: query.tier(),
});
};
Ok(candidates
.iter()
.map(|candidate| 1.0 - cosine_similarity_i8_trusted(candidate, q))
.collect())
}
#[inline]
pub fn approximate_int8_batch_prepared_into(
query: &PreparedQuery,
candidates: &[QuantizedVector],
out: &mut Vec<f32>,
) -> Result<()> {
out.clear();
let PreparedQuery::Int8(q) = query else {
return Err(EmbedError::TierMismatch {
op: "approximate_int8_batch_prepared_into",
expected: QuantizationTier::Int8,
actual: query.tier(),
});
};
out.reserve(candidates.len());
out.extend(
candidates
.iter()
.map(|candidate| 1.0 - cosine_similarity_i8_trusted(candidate, q)),
);
Ok(())
}
#[inline]
pub fn approximate_int4_batch_prepared(
query: &PreparedQuery,
candidates: &[Int4Vector],
) -> Result<Vec<f32>> {
let PreparedQuery::Int4(q) = query else {
return Err(EmbedError::TierMismatch {
op: "approximate_int4_batch_prepared",
expected: QuantizationTier::Int4,
actual: query.tier(),
});
};
Ok(candidates
.iter()
.map(|candidate| candidate.cosine_distance(q))
.collect())
}
#[inline]
pub fn approximate_int4_batch_prepared_into(
query: &PreparedQuery,
candidates: &[Int4Vector],
out: &mut Vec<f32>,
) -> Result<()> {
out.clear();
let PreparedQuery::Int4(q) = query else {
return Err(EmbedError::TierMismatch {
op: "approximate_int4_batch_prepared_into",
expected: QuantizationTier::Int4,
actual: query.tier(),
});
};
out.reserve(candidates.len());
out.extend(
candidates
.iter()
.map(|candidate| candidate.cosine_distance(q)),
);
Ok(())
}
pub fn approximate_cosine_distance(query_f32: &[f32], stored: &QuantizedData) -> f32 {
debug_assert_eq!(
query_f32.len(),
stored.dims(),
"approximate_cosine_distance: query length {} != stored dims {}",
query_f32.len(),
stored.dims(),
);
match stored {
QuantizedData::Full(v) => {
1.0 - cosine_similarity(query_f32, v)
}
QuantizedData::Int8(q) => {
let query_q = QuantizedVector::from_f32(query_f32);
1.0 - q.cosine_similarity(&query_q)
}
QuantizedData::Int4(q) => {
let query_q = Int4Vector::from_f32(query_f32);
q.cosine_distance(&query_q)
}
QuantizedData::Binary(q) => {
let query_q = BinaryVector::from_f32(query_f32);
q.cosine_distance_approx(&query_q)
}
}
}
pub fn approximate_dot_product(query_f32: &[f32], stored: &QuantizedData) -> f32 {
match stored {
QuantizedData::Full(v) => dot_product(query_f32, v),
QuantizedData::Int8(q) => {
let query_q = QuantizedVector::from_f32(query_f32);
q.dot_product(&query_q)
}
QuantizedData::Int4(q) => {
let query_q = Int4Vector::from_f32(query_f32);
q.dot_product(&query_q)
}
QuantizedData::Binary(_q) => {
let stored_f32 = _q.to_f32();
dot_product(query_f32, &stored_f32)
}
}
}
#[cfg(test)]
mod tests;