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}