smartdocs-api / embeddings /dense_embedder.py
Sahilalaknur's picture
Clean HF API deploy (no binary history)
fa1fead
Raw History Blame Contribute Delete
5.11 kB
# embeddings/dense_embedder.py
# WHY THIS EXISTS: Embeds text chunks using multilingual-e5-large.
# Mandatory prefixes: "passage: " at ingestion, "query: " at retrieval.
# Missing these prefixes degrades similarity scores by 0.05-0.15.
# batch_size=16 — safe for RTX 3050 6GB VRAM. LAW 4.
import torch
import numpy as np
from typing import Union
from sentence_transformers import SentenceTransformer
from config.settings import get_settings
settings = get_settings()
class DenseEmbedder:
"""
Wraps multilingual-e5-large for SmartDocs ingestion and retrieval.
Two modes:
embed_passages() — for PDF chunks at ingestion (prefix: "passage: ")
embed_query() — for user queries at retrieval (prefix: "query: ")
Never call model.encode() directly outside this class.
The prefix requirement is enforced here — not the caller's responsibility.
"""
def __init__(self):
self.model_name = settings.embedding_model
self.device = settings.embedding_device
self.batch_size = settings.embedding_batch_size # 16 for RTX 3050
self._model: SentenceTransformer | None = None
def _load_model(self) -> SentenceTransformer:
"""
Lazy loads model on first use.
Checks CUDA availability — falls back to CPU with warning if needed.
"""
if self._model is not None:
return self._model
# Verify CUDA available if cuda requested
if self.device == "cuda" and not torch.cuda.is_available():
print(
"WARNING: CUDA requested but not available. "
"Falling back to CPU. Embedding will be slower."
)
self.device = "cpu"
self._model = SentenceTransformer(
self.model_name,
device=self.device,
)
return self._model
async def warmup(self) -> None:
"""Pre-loads model so first real request is not slow."""
import asyncio
loop = asyncio.get_event_loop()
await loop.run_in_executor(None, lambda: self.embed_passages(["warmup"]))
@property
def model(self) -> SentenceTransformer:
return self._load_model()
def embed_passages(
self,
texts: list[str],
show_progress: bool = False,
) -> np.ndarray:
"""
Embeds document chunks for ingestion into pgvector.
Adds mandatory "passage: " prefix to every text.
Args:
texts: List of chunk texts (without any prefix)
show_progress: Show tqdm progress bar for large batches
Returns:
numpy array of shape (len(texts), 1024)
"""
if not texts:
return np.array([])
# MANDATORY: "passage: " prefix — this is model-specific behavior
# multilingual-e5-large was trained with these prefixes
# Wrong: model.encode(["भूमि अधिग्रहण"])
# Right: model.encode(["passage: भूमि अधिग्रहण"])
prefixed = [f"passage: {text}" for text in texts]
embeddings = self.model.encode(
prefixed,
batch_size=self.batch_size,
show_progress_bar=show_progress,
normalize_embeddings=True, # L2 normalize for cosine similarity
convert_to_numpy=True,
)
return embeddings
def embed_query(self, query_text: str) -> np.ndarray:
"""
Embeds a single user query for retrieval.
Adds mandatory "query: " prefix.
Args:
query_text: Raw user query (no prefix)
Returns:
numpy array of shape (1024,)
"""
# MANDATORY: "query: " prefix at retrieval time
prefixed = f"query: {query_text}"
embedding = self.model.encode(
[prefixed],
batch_size=1,
normalize_embeddings=True,
convert_to_numpy=True,
)
return embedding[0]
def embed_passages_batched(
self,
texts: list[str],
show_progress: bool = True,
) -> list[np.ndarray]:
"""
Embeds large lists of passages in batches.
Use this for full document ingestion (hundreds of chunks).
Returns list of individual embeddings (not stacked).
Args:
texts: List of chunk texts
show_progress: Show progress bar (recommended for large docs)
Returns:
List of numpy arrays, one per text
"""
embeddings = self.embed_passages(texts, show_progress=show_progress)
return [embeddings[i] for i in range(len(embeddings))]
# Module-level singleton — import this in ingestion_worker and retriever
_embedder_instance: DenseEmbedder | None = None
def get_embedder() -> DenseEmbedder:
"""
Returns singleton DenseEmbedder instance.
Model loads once, reused for all calls in the process lifetime.
"""
global _embedder_instance
if _embedder_instance is None:
_embedder_instance = DenseEmbedder()
return _embedder_instance