use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use std::time::SystemTime;
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ModelProvenance {
pub model: EmbeddingModel,
pub model_id: String,
pub hash: String,
pub loaded_at: SystemTime,
pub loaded_at_iso: String,
}
impl ModelProvenance {
pub fn new(model: EmbeddingModel, model_id: String) -> Self {
let loaded_at = SystemTime::now();
let loaded_at_iso = {
let dt: chrono::DateTime<chrono::Utc> = loaded_at.into();
dt.to_rfc3339()
};
let hash_input = format!("{model_id}:{loaded_at_iso}:{model:?}");
let hash = format!("{:x}", Sha256::digest(hash_input.as_bytes()));
Self {
model,
model_id,
hash,
loaded_at,
loaded_at_iso,
}
}
pub fn dimensions(&self) -> usize {
self.model.dimensions()
}
pub fn matches_model(&self, expected: EmbeddingModel) -> bool {
self.model == expected
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum EmbeddingModel {
#[default]
#[serde(alias = "BgeSmallEnV15")]
BgeSmallEnV15,
#[serde(alias = "BgeBaseEnV15")]
BgeBaseEnV15,
#[serde(alias = "BgeLargeEnV15")]
BgeLargeEnV15,
#[serde(alias = "MultilingualE5Small")]
MultilingualE5Small,
#[serde(alias = "MultilingualE5Base")]
MultilingualE5Base,
#[serde(alias = "Qwen3Embedding0_6B")]
Qwen3Embedding0_6B,
#[serde(alias = "Qwen3Embedding4B")]
Qwen3Embedding4B,
#[serde(alias = "EmbeddingGemma2")]
EmbeddingGemma2,
#[serde(alias = "AllMiniLmL6V2")]
AllMiniLmL6V2,
#[serde(alias = "ParaphraseMultilingualMiniLmL12V2")]
ParaphraseMultilingualMiniLmL12V2,
#[serde(alias = "TextEmbedding3Small")]
TextEmbedding3Small,
}
impl EmbeddingModel {
#[inline]
pub const fn native_dimensions(&self) -> usize {
match self {
EmbeddingModel::BgeSmallEnV15
| EmbeddingModel::MultilingualE5Small
| EmbeddingModel::AllMiniLmL6V2
| EmbeddingModel::ParaphraseMultilingualMiniLmL12V2 => 384,
EmbeddingModel::BgeBaseEnV15
| EmbeddingModel::MultilingualE5Base
| EmbeddingModel::EmbeddingGemma2 => 768,
EmbeddingModel::BgeLargeEnV15 | EmbeddingModel::Qwen3Embedding0_6B => 1024,
EmbeddingModel::Qwen3Embedding4B => 2560,
EmbeddingModel::TextEmbedding3Small => 1536,
}
}
#[inline]
pub const fn dimensions(&self) -> usize {
self.native_dimensions()
}
#[inline]
pub const fn is_local(&self) -> bool {
matches!(
self,
EmbeddingModel::BgeSmallEnV15
| EmbeddingModel::BgeBaseEnV15
| EmbeddingModel::BgeLargeEnV15
| EmbeddingModel::MultilingualE5Small
| EmbeddingModel::MultilingualE5Base
| EmbeddingModel::AllMiniLmL6V2
| EmbeddingModel::ParaphraseMultilingualMiniLmL12V2
| EmbeddingModel::Qwen3Embedding0_6B
| EmbeddingModel::Qwen3Embedding4B
| EmbeddingModel::EmbeddingGemma2
)
}
#[inline]
pub const fn is_remote(&self) -> bool {
matches!(self, EmbeddingModel::TextEmbedding3Small)
}
#[inline]
pub const fn max_input_tokens(&self) -> usize {
match self {
EmbeddingModel::BgeSmallEnV15 => 512,
EmbeddingModel::BgeBaseEnV15 => 512,
EmbeddingModel::BgeLargeEnV15 => 512,
EmbeddingModel::MultilingualE5Small => 512,
EmbeddingModel::MultilingualE5Base => 512,
EmbeddingModel::AllMiniLmL6V2 => 256,
EmbeddingModel::ParaphraseMultilingualMiniLmL12V2 => 128,
EmbeddingModel::Qwen3Embedding0_6B => 2048,
EmbeddingModel::Qwen3Embedding4B => 2048,
EmbeddingModel::EmbeddingGemma2 => 8192,
EmbeddingModel::TextEmbedding3Small => 8191,
}
}
#[inline]
pub const fn query_instruction(&self) -> Option<&'static str> {
match self {
EmbeddingModel::MultilingualE5Small | EmbeddingModel::MultilingualE5Base => {
Some("query: ")
}
EmbeddingModel::EmbeddingGemma2 => Some("task: search result | query: "),
EmbeddingModel::Qwen3Embedding0_6B | EmbeddingModel::Qwen3Embedding4B => Some(
"Instruct: Given a web search query, retrieve relevant passages that answer the query\nQuery: ",
),
EmbeddingModel::BgeSmallEnV15
| EmbeddingModel::BgeBaseEnV15
| EmbeddingModel::BgeLargeEnV15 => {
Some("Represent this sentence for searching relevant passages: ")
}
_ => None,
}
}
#[inline]
pub const fn document_instruction(&self) -> Option<&'static str> {
match self {
EmbeddingModel::MultilingualE5Small | EmbeddingModel::MultilingualE5Base => {
Some("passage: ")
}
EmbeddingModel::EmbeddingGemma2 => Some("title: none | text: "),
_ => None,
}
}
#[inline]
pub const fn max_instruction_bytes(&self) -> usize {
let q = match self.query_instruction() {
Some(s) => s.len(),
None => 0,
};
let d = match self.document_instruction() {
Some(s) => s.len(),
None => 0,
};
if q > d { q } else { d }
}
#[inline]
pub const fn model_id(&self) -> &'static str {
match self {
EmbeddingModel::BgeSmallEnV15 => "BAAI/bge-small-en-v1.5",
EmbeddingModel::BgeBaseEnV15 => "BAAI/bge-base-en-v1.5",
EmbeddingModel::BgeLargeEnV15 => "BAAI/bge-large-en-v1.5",
EmbeddingModel::MultilingualE5Small => "intfloat/multilingual-e5-small",
EmbeddingModel::MultilingualE5Base => "intfloat/multilingual-e5-base",
EmbeddingModel::AllMiniLmL6V2 => "sentence-transformers/all-MiniLM-L6-v2",
EmbeddingModel::ParaphraseMultilingualMiniLmL12V2 => {
"sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
}
EmbeddingModel::Qwen3Embedding0_6B => "Qwen/Qwen3-Embedding-0.6B",
EmbeddingModel::Qwen3Embedding4B => "Qwen/Qwen3-Embedding-4B",
EmbeddingModel::EmbeddingGemma2 => "google/embeddinggemma-2",
EmbeddingModel::TextEmbedding3Small => "text-embedding-3-small",
}
}
#[inline]
pub const fn supports_output_dim(&self) -> bool {
matches!(
self,
EmbeddingModel::Qwen3Embedding0_6B
| EmbeddingModel::Qwen3Embedding4B
| EmbeddingModel::EmbeddingGemma2
)
}
#[cfg(feature = "native")]
#[inline]
pub const fn bert_pooling(&self) -> Option<lattice_compute::pool::BertPooling> {
match self {
EmbeddingModel::BgeSmallEnV15
| EmbeddingModel::BgeBaseEnV15
| EmbeddingModel::BgeLargeEnV15 => Some(lattice_compute::pool::BertPooling::CLS),
EmbeddingModel::MultilingualE5Small | EmbeddingModel::MultilingualE5Base => {
Some(lattice_compute::pool::BertPooling::Mean)
}
EmbeddingModel::AllMiniLmL6V2 | EmbeddingModel::ParaphraseMultilingualMiniLmL12V2 => {
Some(lattice_compute::pool::BertPooling::Mean)
}
EmbeddingModel::Qwen3Embedding0_6B
| EmbeddingModel::Qwen3Embedding4B
| EmbeddingModel::EmbeddingGemma2
| EmbeddingModel::TextEmbedding3Small => None,
}
}
#[inline]
pub const fn key_version(&self) -> &'static str {
match self {
EmbeddingModel::TextEmbedding3Small
| EmbeddingModel::Qwen3Embedding0_6B
| EmbeddingModel::Qwen3Embedding4B => "v3",
EmbeddingModel::AllMiniLmL6V2 | EmbeddingModel::ParaphraseMultilingualMiniLmL12V2 => {
"v2"
}
EmbeddingModel::EmbeddingGemma2 => "v1",
_ => "v1.5",
}
}
}
impl std::fmt::Display for EmbeddingModel {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
EmbeddingModel::BgeSmallEnV15 => write!(f, "bge-small-en-v1.5"),
EmbeddingModel::BgeBaseEnV15 => write!(f, "bge-base-en-v1.5"),
EmbeddingModel::BgeLargeEnV15 => write!(f, "bge-large-en-v1.5"),
EmbeddingModel::MultilingualE5Small => write!(f, "multilingual-e5-small"),
EmbeddingModel::MultilingualE5Base => write!(f, "multilingual-e5-base"),
EmbeddingModel::Qwen3Embedding0_6B => write!(f, "qwen3-embedding-0.6b"),
EmbeddingModel::Qwen3Embedding4B => write!(f, "qwen3-embedding-4b"),
EmbeddingModel::EmbeddingGemma2 => write!(f, "embeddinggemma-2"),
EmbeddingModel::AllMiniLmL6V2 => write!(f, "all-minilm-l6-v2"),
EmbeddingModel::ParaphraseMultilingualMiniLmL12V2 => {
write!(f, "paraphrase-multilingual-minilm-l12-v2")
}
EmbeddingModel::TextEmbedding3Small => write!(f, "text-embedding-3-small"),
}
}
}
impl std::str::FromStr for EmbeddingModel {
type Err = String;
fn from_str(s: &str) -> Result<Self, Self::Err> {
let lower = s.to_lowercase();
let normalized = lower.trim().replace("_", "-").replace("baai/", "");
match normalized.as_str() {
"bge-small-en-v1.5" | "bge-small-en" | "bge-small" | "small" => {
Ok(EmbeddingModel::BgeSmallEnV15)
}
"bge-base-en-v1.5" | "bge-base-en" | "bge-base" | "base" => {
Ok(EmbeddingModel::BgeBaseEnV15)
}
"bge-large-en-v1.5" | "bge-large-en" | "bge-large" | "large" => {
Ok(EmbeddingModel::BgeLargeEnV15)
}
"multilingual-e5-small" | "e5-small" | "intfloat/multilingual-e5-small" => {
Ok(EmbeddingModel::MultilingualE5Small)
}
"multilingual-e5-base" | "e5-base" | "intfloat/multilingual-e5-base" => {
Ok(EmbeddingModel::MultilingualE5Base)
}
"qwen3-embedding-0.6b" | "qwen3-embedding" | "qwen3" | "qwen/qwen3-embedding-0.6b" => {
Ok(EmbeddingModel::Qwen3Embedding0_6B)
}
"qwen3-embedding-4b" | "qwen3-4b" | "qwen/qwen3-embedding-4b" => {
Ok(EmbeddingModel::Qwen3Embedding4B)
}
"embeddinggemma-2"
| "embeddinggemma2"
| "embedding-gemma2"
| "embedding-gemma-2"
| "google/embeddinggemma-2" => Ok(EmbeddingModel::EmbeddingGemma2),
"all-minilm-l6-v2"
| "minilm"
| "all-minilm"
| "sentence-transformers/all-minilm-l6-v2" => Ok(EmbeddingModel::AllMiniLmL6V2),
"paraphrase-multilingual-minilm-l12-v2"
| "paraphrase-multilingual"
| "multilingual-minilm"
| "sentence-transformers/paraphrase-multilingual-minilm-l12-v2" => {
Ok(EmbeddingModel::ParaphraseMultilingualMiniLmL12V2)
}
"text-embedding-3-small" | "openai-small" | "openai" => {
Ok(EmbeddingModel::TextEmbedding3Small)
}
_ => Err(format!(
"unknown embedding model: '{s}'. Valid: bge-small-en-v1.5, bge-base-en-v1.5, bge-large-en-v1.5, multilingual-e5-small, multilingual-e5-base, text-embedding-3-small"
)),
}
}
}
pub const MIN_MRL_OUTPUT_DIM: usize = 32;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct ModelConfig {
pub model: EmbeddingModel,
#[serde(default)]
pub output_dim: Option<usize>,
}
impl Default for ModelConfig {
fn default() -> Self {
Self::new(EmbeddingModel::default())
}
}
impl ModelConfig {
pub const fn new(model: EmbeddingModel) -> Self {
Self {
model,
output_dim: None,
}
}
pub fn try_new(
model: EmbeddingModel,
output_dim: Option<usize>,
) -> std::result::Result<Self, crate::error::EmbedError> {
let config = Self { model, output_dim };
config.validate()?;
Ok(config)
}
pub fn validate(&self) -> std::result::Result<(), crate::error::EmbedError> {
let Some(dim) = self.output_dim else {
return Ok(());
};
if !self.model.supports_output_dim() {
return Err(crate::error::EmbedError::InvalidInput(format!(
"{} does not support configurable embedding dimensions",
self.model
)));
}
if dim < MIN_MRL_OUTPUT_DIM {
return Err(crate::error::EmbedError::InvalidInput(format!(
"embedding output dimension {dim} is below minimum {MIN_MRL_OUTPUT_DIM}"
)));
}
let native = self.model.native_dimensions();
if dim > native {
return Err(crate::error::EmbedError::InvalidInput(format!(
"embedding output dimension {dim} exceeds native dimension {native} for {}",
self.model
)));
}
Ok(())
}
pub fn dimensions(&self) -> usize {
self.output_dim
.unwrap_or_else(|| self.model.native_dimensions())
}
}
#[cfg(test)]
mod tests;