FastEmbed - Cheatsheet Embedding Leggeri Locali
FastEmbed (di Qdrant) è una libreria veloce e leggera per generare embedding di testo localmente. Esegue i modelli tramite ONNX Runtime (nessuna pesante dipendenza PyTorch), che la rende piccola, veloce da installare ed efficiente sulla CPU. Oltre agli embedding densi supporta sparse (BM25, SPLADE), late-interaction (ColBERT) e modelli di reranking — tutto ciò che serve per costruire una ricerca ibrida densa+sparse per RAG. Si integra strettamente con il database vettoriale Qdrant.
Installazione
| Metodo | Comando |
|---|
| pip | pip install fastembed |
| GPU (CUDA) | pip install fastembed-gpu |
| Verifica | python -c "from fastembed import TextEmbedding; print('ok')" |
Embedding Densi
from fastembed import TextEmbedding
model = TextEmbedding("BAAI/bge-small-en-v1.5") # scarica una volta
docs = ["FastEmbed runs on ONNX.", "It is CPU-friendly."]
vectors = list(model.embed(docs)) # generatore di array numpy
print(len(vectors), vectors[0].shape)
| Chiamata | Descrizione |
|---|
TextEmbedding(model_name) | Carica un modello di embedding denso |
.embed(list) | Embedding di documenti (batch, lazy) |
.query_embed(str) | Embedding di una query (alcuni modelli differenziano q/d) |
.passage_embed(list) | Embedding di passaggi |
TextEmbedding.list_supported_models() | Vedi i modelli disponibili |
Tipi di Modello
| Tipo | Classe | Usa |
|---|
| Denso | TextEmbedding | Somiglianza semantica |
| Sparse (BM25/SPLADE) | SparseTextEmbedding | Corrispondenza di termini/esatti |
| Late interaction (ColBERT) | LateInteractionTextEmbedding | Recupero reranking ad alta precisione |
| Reranking | TextCrossEncoder | Riordina i candidati |
| Immagine | ImageEmbedding | Embedding multimodali |
Embedding Sparse (per Ricerca Ibrida)
from fastembed import SparseTextEmbedding
sparse = SparseTextEmbedding("Qdrant/bm25")
sv = list(sparse.embed(["exact term ABC-123 matters"]))
print(sv[0].indices, sv[0].values) # sparse: indici token + pesi
Gli embedding sparse catturano i termini esatti (identificatori, numeri) che gli embedding densi liscia — la chiave per una ricerca ibrida forte.
Reranking
from fastembed.rerank.cross_encoder import TextCrossEncoder
reranker = TextCrossEncoder("Xenova/ms-marco-MiniLM-L-6-v2")
scores = reranker.rerank("what is fastembed?",
["FastEmbed is an embedding lib.", "Unrelated text."])
Ricerca Ibrida con Qdrant
from fastembed import TextEmbedding, SparseTextEmbedding
# Calcola vettori densi e sparse per ogni chunk, eseguire l''upsert su Qdrant,
# quindi interroga con entrambi e lascia che Qdrant fonda (RRF) i risultati.
dense = TextEmbedding("BAAI/bge-small-en-v1.5")
sparse = SparseTextEmbedding("Qdrant/bm25")
| Passaggio | Strumento |
|---|
| Vettori densi | TextEmbedding |
| Vettori sparse | SparseTextEmbedding (BM25) |
| Memorizza + fondi | Query ibrida nativa di Qdrant |
| Reranking opzionale | TextCrossEncoder |
Perché FastEmbed (Progettazione)
| Proprietà | Beneficio |
|---|
| ONNX Runtime | Nessun PyTorch; installazione piccola, veloce sulla CPU |
| Modelli quantizzati | Memoria/latenza inferiore |
| Generatori lazy | Stream embedding, bassa memoria |
| Locale | Nessuna chiamata API; i dati rimangono privati |
Flussi di Lavoro Comuni
# Batch-embed un corpus per un DB vettoriale (consapevole della CPU)
from fastembed import TextEmbedding
model = TextEmbedding("BAAI/bge-base-en-v1.5")
embeddings = list(model.embed(corpus, batch_size=64))
# Costruisci recupero ibrido: denso + BM25 sparse, fuso in Qdrant
FastEmbed vs Alternative
| Aspetto | FastEmbed | sentence-transformers | OpenAI embeddings API |
|---|
| Runtime | ONNX (nessun torch) | PyTorch | Hosted API |
| Sparse/ColBERT | Built-in | Librerie extra | No |
| Locale/privato | Sì | Sì | No |
| Migliore per | Locale leggero + ibrido | Ecosistema torch completo | Semplicità gestita |
Risorse
