705ad030fe
Vectorii corpusului k-NN persista in tabela embedding_cache (PK model+text_hash,
blob float32 LE); la warmup se vectorizeaza doar textele lipsa din cache, deci
restartul cu corpus neschimbat nu mai plateste ~1-2 min de embed (embed=0).
- app/embedding_cache.py: serializare array('f'), load/save/purge chunk 500 cu
BEGIN/COMMIT explicit (conexiuni autocommit), validare dimensiune la scriere
si citire, orchestrare sync_corpus_vectors cu embed_fn injectat
- index_corpus(vectors=): vectori precalculati cu validare aliniere; mismatch
-> fallback embed complet
- ensure_embeddings_corpus: warmup in thread la startup (block=True), calea de
request ne-blocanta (acquire non-blocking pe lock; warmup in curs -> return
imediat); purjare orfane + modele vechi doar dupa indexare reusita
- log warmup: cache=N embed=M in Xs
- 31 teste noi (cold/warm/incremental, model schimbat, concurenta, ranking
exact, echivalenta float32); suita completa 1596 passed
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
303 lines
11 KiB
Python
303 lines
11 KiB
Python
"""Modul embedding in-proces pentru sugestie cod RAR.
|
|
|
|
Design:
|
|
- Model multilingv via fastembed/ONNX (~230MB pe disc, quantizat, fara torch)
|
|
- Lazy load la prima folosire, NU la import si NU pe /healthz
|
|
- Worker NU incarca modelul (API-only)
|
|
- Degradare gratioasa: daca modelul nu se incarca -> is_available()=False,
|
|
suggest_nearest() -> [] fara exceptie, ingestia NU e blocata
|
|
- Embeddings = DOAR sugestie (nu intra in lantul de enqueue/resolve_prestatii)
|
|
- NU apelat din resolve_prestatii/load_mapping
|
|
|
|
API public (nivel modul):
|
|
index_corpus(items, signature, vectors) -> None
|
|
suggest_nearest(text, top_k) -> [{cod, is_nul, similaritate}]
|
|
is_available() -> bool
|
|
|
|
Clase (pentru teste / injectare backend):
|
|
EmbeddingEngine(backend) -- motor testabil cu backend injectabil
|
|
FastEmbedBackend() -- backend real fastembed/ONNX
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
import logging
|
|
import math
|
|
import threading
|
|
from typing import Protocol, runtime_checkable
|
|
|
|
log = logging.getLogger(__name__)
|
|
|
|
# Modelul ales: paraphrase-multilingual-MiniLM-L12-v2
|
|
# ~230MB pe disc (ONNX quantizat), 384 dim, multilingv (ro/en/etc.), suportat de
|
|
# fastembed, fara torch.
|
|
FASTEMBED_MODEL = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
|
|
|
|
|
|
# --------------------------------------------------------------------------- #
|
|
# Protocol backend (mockabil in teste) #
|
|
# --------------------------------------------------------------------------- #
|
|
|
|
@runtime_checkable
|
|
class EmbeddingBackend(Protocol):
|
|
"""Interfata minimala pentru un backend de embedding."""
|
|
|
|
def embed(self, texts: list[str]) -> list[list[float]]:
|
|
"""Intoarce o lista de vectori (cate unul per text)."""
|
|
...
|
|
|
|
|
|
# --------------------------------------------------------------------------- #
|
|
# Backend real: fastembed/ONNX #
|
|
# --------------------------------------------------------------------------- #
|
|
|
|
class FastEmbedBackend:
|
|
"""Backend fastembed/ONNX. Lazy-load la constructie.
|
|
|
|
Arunca ImportError daca fastembed nu e instalat, sau orice exceptie
|
|
de la TextEmbedding (download esuat, ONNX incompatibil etc.).
|
|
Apelantul (_load_engine) prinde aceste exceptii.
|
|
"""
|
|
|
|
def __init__(self, model_name: str = FASTEMBED_MODEL):
|
|
from fastembed import TextEmbedding # import tardiv -- nu blocheaza la import modul
|
|
self._model = TextEmbedding(model_name=model_name)
|
|
|
|
def embed(self, texts: list[str]) -> list[list[float]]:
|
|
# fastembed.embed() intoarce un generator de numpy arrays
|
|
return [vec.tolist() for vec in self._model.embed(texts)]
|
|
|
|
|
|
# --------------------------------------------------------------------------- #
|
|
# Motor de embedding (testabil, backend injectabil) #
|
|
# --------------------------------------------------------------------------- #
|
|
|
|
def _cosine_similarity(a: list[float], b: list[float]) -> float:
|
|
"""Similaritate cosine intre doi vectori. Returneaza 0.0 pe vectori nuli."""
|
|
dot = sum(x * y for x, y in zip(a, b))
|
|
na = math.sqrt(sum(x * x for x in a))
|
|
nb = math.sqrt(sum(x * x for x in b))
|
|
if na == 0.0 or nb == 0.0:
|
|
return 0.0
|
|
return dot / (na * nb)
|
|
|
|
|
|
class EmbeddingEngine:
|
|
"""Motor de embedding cu corpus indexat si cautare NN cosine.
|
|
|
|
Parametri:
|
|
backend: instanta EmbeddingBackend (real sau mock).
|
|
None => degradare gratioasa (is_available=False).
|
|
"""
|
|
|
|
def __init__(self, backend: EmbeddingBackend | None = None):
|
|
self._backend = backend
|
|
self._corpus_vecs: list[list[float]] = []
|
|
self._corpus_items: list[dict] = []
|
|
self._corpus_sig: str | None = None
|
|
|
|
def is_available(self) -> bool:
|
|
"""True daca backend-ul e disponibil si gata de folosire."""
|
|
return self._backend is not None
|
|
|
|
def has_corpus(self) -> bool:
|
|
"""True daca un corpus a fost indexat (suggest_nearest poate produce ceva)."""
|
|
return bool(self._corpus_items)
|
|
|
|
def corpus_signature(self) -> str | None:
|
|
"""Semnatura corpusului indexat (None daca gol). Apelantul re-indexeaza
|
|
doar cand semnatura nomenclatorului s-a schimbat (evita re-embed inutil)."""
|
|
return self._corpus_sig
|
|
|
|
def index_corpus(
|
|
self,
|
|
items: list[dict],
|
|
signature: str | None = None,
|
|
vectors: list | None = None,
|
|
) -> None:
|
|
"""Indexeaza corpus [{denumire, cod}] si il pastreaza in memorie.
|
|
|
|
`vectors`: vectori precalculati, aliniati POZITIONAL cu `items` (ex. din
|
|
embedding_cache). `None` (default) = comportamentul existent, embed complet
|
|
prin backend. Daca `vectors` e furnizat dar lungimea nu corespunde cu `items`
|
|
sau contine `None`, se ignora (log.warning) si se cade pe embed complet (A8) --
|
|
o dezaliniere silentioasa ar produce coduri sugerate GRESITE.
|
|
|
|
Ignora silentios daca backend-ul lipseste, corpus-ul e gol sau apare
|
|
orice exceptie la vectorizare (degradare gratioasa).
|
|
"""
|
|
self._corpus_vecs = []
|
|
self._corpus_items = []
|
|
self._corpus_sig = None
|
|
|
|
if not items or not self.is_available():
|
|
return
|
|
|
|
if vectors is not None and (len(vectors) != len(items) or any(v is None for v in vectors)):
|
|
log.warning(
|
|
"embeddings: index_corpus vectors (%d) nealiniat cu items (%d) sau contine None -- fallback embed complet",
|
|
len(vectors), len(items),
|
|
)
|
|
vectors = None
|
|
|
|
try:
|
|
if vectors is not None:
|
|
self._corpus_vecs = list(vectors)
|
|
else:
|
|
texts = [str(item["denumire"]) for item in items]
|
|
self._corpus_vecs = self._backend.embed(texts)
|
|
self._corpus_items = list(items)
|
|
self._corpus_sig = signature
|
|
except Exception as exc:
|
|
log.warning("embeddings: index_corpus esuat: %s", exc)
|
|
# corpus ramane gol -- suggest_nearest va returna []
|
|
|
|
def embed(self, texts: list[str]) -> list[list[float]]:
|
|
"""Vectorizeaza texte brute prin backend (folosit la miss-uri de cache).
|
|
|
|
Arunca daca backend-ul lipseste sau embed() esueaza -- apelantul
|
|
(sync_corpus_vectors) propaga eroarea, fara degradare gratioasa aici.
|
|
"""
|
|
if not self.is_available():
|
|
raise RuntimeError("embeddings: backend indisponibil")
|
|
return self._backend.embed(texts)
|
|
|
|
def suggest_nearest(
|
|
self,
|
|
denumire: str,
|
|
top_k: int = 3,
|
|
) -> list[dict]:
|
|
"""Returneaza top_k vecini cosine [{cod, is_nul, similaritate}].
|
|
|
|
`is_nul`: cand corpusul include exemple NUL (non-operatii),
|
|
un vecin NUL = semnal de SUPRESIE, nu cod. Default False pe corpusuri vechi
|
|
fara `is_nul` in itemi. Returneaza [] daca backend-ul lipseste, corpus-ul e gol
|
|
sau apare orice exceptie (degradare gratioasa -- nu blocheaza ingestia).
|
|
"""
|
|
if not self.is_available() or not self._corpus_items:
|
|
return []
|
|
|
|
try:
|
|
query_vecs = self._backend.embed([str(denumire)])
|
|
query_vec = query_vecs[0]
|
|
scored = [
|
|
{
|
|
"cod": item["cod"],
|
|
"is_nul": bool(item.get("is_nul", False)),
|
|
"similaritate": _cosine_similarity(query_vec, vec),
|
|
}
|
|
for item, vec in zip(self._corpus_items, self._corpus_vecs)
|
|
]
|
|
scored.sort(key=lambda r: r["similaritate"], reverse=True)
|
|
return scored[:top_k]
|
|
except Exception as exc:
|
|
log.warning("embeddings: suggest_nearest esuat: %s", exc)
|
|
return []
|
|
|
|
|
|
# --------------------------------------------------------------------------- #
|
|
# Singleton global cu lazy load (API-only, NU worker) #
|
|
# --------------------------------------------------------------------------- #
|
|
|
|
_engine: EmbeddingEngine | None = None
|
|
_engine_lock = threading.Lock()
|
|
|
|
|
|
def _load_engine() -> EmbeddingEngine:
|
|
"""Lazy load: construieste engine-ul la prima folosire.
|
|
|
|
Captureaza ORICE exceptie la incarcare (import, download, ONNX init)
|
|
si returneaza un engine degradat (backend=None) -- ingestia continua
|
|
pe exact+fuzzy, embedding = sugestie dezactivata.
|
|
"""
|
|
try:
|
|
backend = FastEmbedBackend()
|
|
log.info("embeddings: backend fastembed incarcat (%s)", FASTEMBED_MODEL)
|
|
return EmbeddingEngine(backend=backend)
|
|
except ImportError:
|
|
log.warning(
|
|
"embeddings: fastembed nu e instalat -- sugestii NN dezactivate"
|
|
)
|
|
except Exception as exc:
|
|
log.warning(
|
|
"embeddings: incarcare backend esuata (%s) -- sugestii NN dezactivate",
|
|
exc,
|
|
)
|
|
return EmbeddingEngine(backend=None)
|
|
|
|
|
|
def _get_engine() -> EmbeddingEngine:
|
|
"""Returneaza engine-ul global (lazy-init, thread-safe).
|
|
|
|
Lock-ul previne incarcarea dubla a modelului cand warmup-ul de la startup
|
|
si un request concurent ajung aici simultan.
|
|
"""
|
|
global _engine
|
|
if _engine is None:
|
|
with _engine_lock:
|
|
if _engine is None:
|
|
_engine = _load_engine()
|
|
return _engine
|
|
|
|
|
|
def is_loaded() -> bool:
|
|
"""True daca engine-ul global a fost deja construit. NU forteaza incarcarea."""
|
|
return _engine is not None
|
|
|
|
|
|
# --------------------------------------------------------------------------- #
|
|
# API public la nivel de modul (wiring L14-S6) #
|
|
# --------------------------------------------------------------------------- #
|
|
|
|
def is_available() -> bool:
|
|
"""True daca modelul e incarcat si gata de folosire."""
|
|
return _get_engine().is_available()
|
|
|
|
|
|
def has_corpus() -> bool:
|
|
"""True daca un corpus a fost indexat in motorul global.
|
|
|
|
NU forteaza incarcarea modelului: daca engine-ul nu a fost initializat inca
|
|
(`_engine is None`), corpus-ul e gol prin definitie -> False, fara cost.
|
|
Apelantii (ex. enrich_suggestions) folosesc asta ca poarta ieftina inainte de
|
|
a atinge calea scumpa (is_available/suggest_nearest, care lazy-load ~230MB).
|
|
"""
|
|
if _engine is None:
|
|
return False
|
|
return _engine.has_corpus()
|
|
|
|
|
|
def corpus_signature() -> str | None:
|
|
"""Semnatura corpusului global indexat (None daca engine ne-initializat/gol).
|
|
|
|
NU forteaza incarcarea modelului: `_engine is None` -> None fara cost.
|
|
"""
|
|
if _engine is None:
|
|
return None
|
|
return _engine.corpus_signature()
|
|
|
|
|
|
def embed_texts(texts: list[str]) -> list[list[float]]:
|
|
"""Vectorizeaza texte brute prin motorul global (folosit la miss-uri de cache).
|
|
|
|
Arunca daca engine-ul e indisponibil -- apelantul (embedding_cache.sync_corpus_vectors)
|
|
propaga eroarea catre ensure_embeddings_corpus (degradare gratioasa acolo).
|
|
"""
|
|
return _get_engine().embed(texts)
|
|
|
|
|
|
def index_corpus(items: list[dict], signature: str | None = None, vectors: list | None = None) -> None:
|
|
"""Vectorizeaza corpus [{denumire, cod}] in motorul global.
|
|
|
|
`vectors`: vezi EmbeddingEngine.index_corpus (precalculati, aliniati cu `items`).
|
|
Silentios pe eroare (degradare gratioasa).
|
|
"""
|
|
_get_engine().index_corpus(items, signature=signature, vectors=vectors)
|
|
|
|
|
|
def suggest_nearest(denumire: str, top_k: int = 3) -> list[dict]:
|
|
"""Returneaza top_k sugestii [{cod, is_nul, similaritate}] sau [] la eroare.
|
|
|
|
Sigur de apelat indiferent de starea backend-ului.
|
|
"""
|
|
return _get_engine().suggest_nearest(denumire, top_k=top_k)
|