Skip to main content

qql_embed/
embedder.rs

1use async_trait::async_trait;
2use qql_core::error::QqlError;
3
4use crate::sparse::{Bm25Params, SparseVector};
5
6#[cfg(not(target_arch = "wasm32"))]
7/// Send/Sync bound helper for `Embedder` implementations on native targets.
8///
9/// Kept as a twin of `QdrantOpsBound` in `qql-runtime` (not shared): sharing
10/// would couple the crates backwards (`qql-embed` must stay dependency-free
11/// of the runtime) or mistype the bound (`QdrantOps: EmbedderBound` reads as
12/// an is-a relationship that does not exist). One shim per trait, each
13/// documenting its own target split.
14pub trait EmbedderBound: Send + Sync {}
15#[cfg(not(target_arch = "wasm32"))]
16impl<T: Send + Sync> EmbedderBound for T {}
17
18#[cfg(target_arch = "wasm32")]
19/// Single-threaded bound helper for `Embedder` implementations on wasm32.
20pub trait EmbedderBound {}
21#[cfg(target_arch = "wasm32")]
22impl<T> EmbedderBound for T {}
23
24/// Host-agnostic embedding backend.
25///
26/// Calls should batch when possible (`*_batch` → one HTTP request or one ONNX
27/// batch): `resolve_embeddings` batches dense, sparse-query, multi, and image
28/// jobs alike (grouped by model, one `*_batch` call per model), so remote
29/// backends must override the batch variants for real batching instead of
30/// relying on the sequential single-call defaults. Sparse is role-split:
31/// [`Self::embed_sparse_query`] (unit weights) for search text and
32/// [`Self::embed_sparse_document`] (BM25 tf saturation) for ingestion text,
33/// both defaulting to local wire-compatible BM25. Multivector (ColBERT-style)
34/// uses [`Self::embed_multi`] → `Vec<Vec<f32>>`.
35#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
36#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
37pub trait Embedder: EmbedderBound {
38    /// Embed one text into a dense vector; `model` may be empty or `"default"`.
39    async fn embed_dense(&self, text: &str, model: &str) -> Result<Vec<f32>, QqlError>;
40
41    /// Sparse embedding for **query** text: unique terms with unit weights,
42    /// matching Qdrant's `qdrant/bm25` query embedding.
43    ///
44    /// Default implementation uses the local pipeline from
45    /// [`Self::bm25_text_config`] when `model` is empty, `"default"`, or
46    /// `"qdrant/bm25"` (the local pipeline *is* that model — see
47    /// [`is_local_bm25_model`]). Non-default sparse models are rejected —
48    /// override this method to provide model-aware sparse inference.
49    async fn embed_sparse_query(&self, text: &str, model: &str) -> Result<SparseVector, QqlError> {
50        if !is_local_bm25_model(model) {
51            return Err(sparse_model_unsupported_error(model));
52        }
53        let config = self.bm25_text_config();
54        if config == crate::Bm25TextConfig::default() {
55            // Default config: reuse the process-wide pipeline instead of
56            // rebuilding the stopword set + stemmer per text.
57            return crate::bm25_text::default_pipeline().embed_query(text);
58        }
59        config.pipeline().embed_query(text)
60    }
61
62    /// Sparse embedding for **document** text at ingestion: BM25
63    /// term-frequency saturation, matching Qdrant's `qdrant/bm25` document
64    /// embedding.
65    ///
66    /// Default implementation uses the local pipeline from
67    /// [`Self::bm25_text_config`] when `model` is empty, `"default"`, or
68    /// `"qdrant/bm25"` (the local pipeline *is* that model), honoring its
69    /// [`Bm25Params`]. Non-default sparse models are rejected — override this
70    /// method to provide model-aware sparse inference.
71    async fn embed_sparse_document(
72        &self,
73        text: &str,
74        model: &str,
75    ) -> Result<SparseVector, QqlError> {
76        if !is_local_bm25_model(model) {
77            return Err(sparse_model_unsupported_error(model));
78        }
79        let config = self.bm25_text_config();
80        if config == crate::Bm25TextConfig::default() {
81            // Default config: reuse the process-wide pipeline (see the query
82            // method above).
83            return crate::bm25_text::default_pipeline().embed_document(text);
84        }
85        config.pipeline().embed_document(text)
86    }
87
88    /// Batch document-side sparse embedding. Default loops
89    /// [`Self::embed_sparse_document`]; override for real batching.
90    async fn embed_sparse_document_batch(
91        &self,
92        texts: &[String],
93        model: &str,
94    ) -> Result<Vec<SparseVector>, QqlError> {
95        let mut results = Vec::with_capacity(texts.len());
96        for text in texts {
97            results.push(self.embed_sparse_document(text, model).await?);
98        }
99        Ok(results)
100    }
101
102    /// Batch query-side sparse embedding. Default loops
103    /// [`Self::embed_sparse_query`]; override for real batching
104    /// (model-backed SPLADE / BGE-M3 sparse inference).
105    async fn embed_sparse_query_batch(
106        &self,
107        texts: &[String],
108        model: &str,
109    ) -> Result<Vec<SparseVector>, QqlError> {
110        let mut results = Vec::with_capacity(texts.len());
111        for text in texts {
112            results.push(self.embed_sparse_query(text, model).await?);
113        }
114        Ok(results)
115    }
116
117    /// Dense output dimension when it is known without running inference.
118    /// Custom and remote embedders may return `None`.
119    fn dimension(&self) -> Option<usize> {
120        None
121    }
122
123    /// Local BM25 hyperparameters used by the default
124    /// [`Self::embed_sparse_document`] / [`Self::embed_sparse_document_batch`]
125    /// implementations.
126    ///
127    /// Document-side only: it does not affect [`Self::embed_sparse_query`]
128    /// (always unit term weights) or model-backed sparse inference (SPLADE /
129    /// BGE-M3), and it is not a collection/wire setting. Defaults to
130    /// [`Bm25Params::default`], so hosts that never override it keep Qdrant's
131    /// `qdrant/bm25` defaults. Changing it affects documents embedded *after*
132    /// the change — re-ingest to apply.
133    fn bm25_params(&self) -> Bm25Params {
134        Bm25Params::default()
135    }
136
137    /// Full local BM25 text configuration (pipeline + hyperparameters) used
138    /// by the default [`Self::embed_sparse_document`] /
139    /// [`Self::embed_sparse_query`] implementations.
140    ///
141    /// Default wraps [`Self::bm25_params`] with Qdrant's text defaults (word
142    /// tokenizer, English, lowercase on, folding off, language
143    /// stopwords/stemmer), so overriding only `bm25_params` keeps working
144    /// unchanged. Override this instead to change tokenization, language,
145    /// folding, stopwords, stemming, or token length limits.
146    fn bm25_text_config(&self) -> crate::Bm25TextConfig {
147        crate::Bm25TextConfig {
148            params: self.bm25_params(),
149            ..crate::Bm25TextConfig::default()
150        }
151    }
152
153    /// Multivector (ColBERT) per-token dimension when known without inference.
154    fn multi_dimension(&self) -> Option<usize> {
155        None
156    }
157
158    /// Whether this embedder can satisfy a requested model identifier.
159    /// Dynamic providers may return `true` for every model.
160    fn accepts_model(&self, _model: &str) -> bool {
161        true
162    }
163
164    /// Embed many texts in one shot. Default loops `embed_dense`; override for
165    /// real batching (OpenAI-compatible `input: [...]`, fastembed batch, etc.).
166    async fn embed_dense_batch(
167        &self,
168        texts: &[String],
169        model: &str,
170    ) -> Result<Vec<Vec<f32>>, QqlError> {
171        let mut results = Vec::with_capacity(texts.len());
172        for text in texts {
173            results.push(self.embed_dense(text, model).await?);
174        }
175        Ok(results)
176    }
177
178    /// Multivector embedding (ColBERT-style late interaction).
179    ///
180    /// Returns one dense vector per token/segment. Default rejects so hosts
181    /// that only support single-vector dense must opt in explicitly.
182    async fn embed_multi(&self, text: &str, model: &str) -> Result<Vec<Vec<f32>>, QqlError> {
183        let _ = text;
184        Err(multi_unsupported_error(model))
185    }
186
187    /// Batch multivector embedding. Default loops [`Self::embed_multi`].
188    async fn embed_multi_batch(
189        &self,
190        texts: &[String],
191        model: &str,
192    ) -> Result<Vec<Vec<Vec<f32>>>, QqlError> {
193        let mut results = Vec::with_capacity(texts.len());
194        for text in texts {
195            results.push(self.embed_multi(text, model).await?);
196        }
197        Ok(results)
198    }
199
200    /// Image / CLIP vision embedding. `source` is a filesystem path or URL.
201    ///
202    /// Returns a single dense vector in the same space as the paired text
203    /// encoder (e.g. CLIP). Default rejects until the host opts in.
204    async fn embed_image(&self, source: &str, model: &str) -> Result<Vec<f32>, QqlError> {
205        let _ = source;
206        Err(image_unsupported_error(model))
207    }
208
209    /// Batch image embedding. Default loops [`Self::embed_image`].
210    async fn embed_image_batch(
211        &self,
212        sources: &[String],
213        model: &str,
214    ) -> Result<Vec<Vec<f32>>, QqlError> {
215        let mut results = Vec::with_capacity(sources.len());
216        for source in sources {
217            results.push(self.embed_image(source, model).await?);
218        }
219        Ok(results)
220    }
221
222    /// Cross-encoder pair scores: `(query, documents[i]) → score`.
223    ///
224    /// Returns one score per document **in the same order** as `documents`
225    /// (not sorted). Hosts that return ranked results must unpermute.
226    /// Default rejects until the host opts in (edge `TextRerank`, HTTP rerank API).
227    async fn rerank_pairs(
228        &self,
229        query: &str,
230        documents: &[String],
231        model: &str,
232    ) -> Result<Vec<f32>, QqlError> {
233        let _ = (query, documents);
234        Err(cross_rerank_unsupported_error(model))
235    }
236}
237
238/// Error when multi-vector embedding is requested but the host has no multi path.
239pub fn multi_unsupported_error(model: &str) -> QqlError {
240    let model_note = if model.is_empty() || model.eq_ignore_ascii_case("default") {
241        "no model specified".to_string()
242    } else {
243        format!("model='{model}'")
244    };
245    QqlError::execution(
246        "QQL-EMBEDDING-MULTI",
247        format!(
248            "multi-vector embedding is not available ({model_note}). \
249             Configure a multi embedder (multi_embedding_endpoint / multi_embedding_model, \
250             or edge multi_model for offline BGE-M3), pass precomputed VECTOR [[...], ...], \
251             or use UPSERT with explicit multivector bags."
252        ),
253        None,
254    )
255}
256
257/// Error when image embedding is requested but the host has no image path.
258pub fn image_unsupported_error(model: &str) -> QqlError {
259    let model_note = if model.is_empty() || model.eq_ignore_ascii_case("default") {
260        "no model specified".to_string()
261    } else {
262        format!("model='{model}'")
263    };
264    QqlError::execution(
265        "QQL-EMBEDDING-IMAGE",
266        format!(
267            "image embedding is not available ({model_note}). \
268             Configure an image/CLIP vision embedder (image_embedding_model / edge image_model, \
269             or image_embedding_endpoint), pass a precomputed VECTOR [...], \
270             or use UPSERT USING IMAGE ON FIELD <path_field>."
271        ),
272        None,
273    )
274}
275
276/// Error when cross-encoder pair rerank is requested without a scorer host.
277pub fn cross_rerank_unsupported_error(model: &str) -> QqlError {
278    let model_note = if model.is_empty() || model.eq_ignore_ascii_case("default") {
279        "no model specified".to_string()
280    } else {
281        format!("model='{model}'")
282    };
283    QqlError::execution(
284        "QQL-RERANK-CROSS",
285        format!(
286            "cross-encoder pair scoring is not available ({model_note}). \
287             Configure a rerank host (rerank_endpoint / rerank_model, or edge \
288             reranker_model for offline TextRerank / bge-reranker)."
289        ),
290        None,
291    )
292}
293
294/// Whether `model` names the local wire-compatible BM25 pipeline: empty,
295/// `"default"`, or Qdrant's `qdrant/bm25` (ASCII case-insensitive).
296///
297/// The local pipeline is byte-compatible with that model, so hosts can accept
298/// the server-side spelling instead of rejecting the name users copy from
299/// Qdrant docs.
300pub fn is_local_bm25_model(model: &str) -> bool {
301    model.is_empty()
302        || model.eq_ignore_ascii_case("default")
303        || model.eq_ignore_ascii_case("qdrant/bm25")
304}
305
306/// Error when a sparse model is requested that this embedder cannot satisfy.
307pub fn sparse_model_unsupported_error(model: &str) -> QqlError {
308    QqlError::execution(
309        "QQL-EMBEDDING-SPARSE",
310        format!(
311            "sparse model '{model}' is not available on this embedder. \
312             Omit the MODEL clause (or use MODEL 'default' / 'qdrant/bm25') \
313             for local wire-compatible BM25. To use model-aware sparse \
314             embedding (SPLADE / BGE-M3), configure a sparse embedding backend."
315        ),
316        None,
317    )
318}
319
320/// Error when a dense model is requested that this embedder cannot satisfy.
321///
322/// Mirrors [`sparse_model_unsupported_error`]: single-model hosts (WASM client
323/// embedder, fixed local models) reject non-default `MODEL` clauses instead
324/// of silently returning vectors from the wrong model.
325pub fn dense_model_unsupported_error(model: &str) -> QqlError {
326    QqlError::execution(
327        "QQL-EMBEDDING",
328        format!(
329            "dense model '{model}' is not available on this embedder. \
330             Omit the MODEL clause (or use MODEL 'default') to use the \
331             configured dense model. To serve multiple dense models, \
332             configure a model-routing dense embedding backend."
333        ),
334        None,
335    )
336}