FastEmbed - Cheatsheet de Embeddings Local Leve
FastEmbed (por Qdrant) é uma biblioteca rápida e leve para gerar embeddings de texto localmente. Executa modelos via ONNX Runtime (sem dependência pesada de PyTorch), o que o torna pequeno, rápido de instalar e eficiente em CPU. Além de embeddings densos, suporta esparsos (BM25, SPLADE), de interação tardia (ColBERT) e modelos de reranking — tudo que você precisa para construir busca híbrida densa+esparsa para RAG. Integra-se fortemente com o banco de dados de vetor Qdrant.
Instalação
| Método | Comando |
|---|
| pip | pip install fastembed |
| GPU (CUDA) | pip install fastembed-gpu |
| Verify | python -c "from fastembed import TextEmbedding; print('ok')" |
Embeddings Densos
from fastembed import TextEmbedding
model = TextEmbedding("BAAI/bge-small-en-v1.5") # downloads once
docs = ["FastEmbed runs on ONNX.", "It is CPU-friendly."]
vectors = list(model.embed(docs)) # generator of numpy arrays
print(len(vectors), vectors[0].shape)
| Chamada | Descrição |
|---|
TextEmbedding(model_name) | Carregar um modelo de embedding denso |
.embed(list) | Embeddings de documentos (em lote, preguiçosos) |
.query_embed(str) | Embeddings de uma consulta (alguns modelos diferem q/d) |
.passage_embed(list) | Embeddings de passagens |
TextEmbedding.list_supported_models() | Ver modelos disponíveis |
Tipos de Modelo
| Tipo | Classe | Uso |
|---|
| Dense | TextEmbedding | Similaridade semântica |
| Sparse (BM25/SPLADE) | SparseTextEmbedding | Correspondência de termos de palavra-chave/exato |
| Late interaction (ColBERT) | LateInteractionTextEmbedding | Reranking de recuperação de alta precisão |
| Reranking | TextCrossEncoder | Reordenar candidatos |
| Image | ImageEmbedding | Embeddings multimodais |
Embeddings Esparsos (para Busca Híbrida)
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: token indices + weights
Vetores esparsos capturam termos exatos (identificadores, números) que embeddings densos suavizam — a chave para busca híbrida 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."])
from fastembed import TextEmbedding, SparseTextEmbedding
# Compute both dense and sparse vectors for each chunk, upsert to Qdrant,
# then query with both and let Qdrant fuse (RRF) the results.
dense = TextEmbedding("BAAI/bge-small-en-v1.5")
sparse = SparseTextEmbedding("Qdrant/bm25")
| Passo | Ferramenta |
|---|
| Dense vectors | TextEmbedding |
| Sparse vectors | SparseTextEmbedding (BM25) |
| Store + fuse | Consulta híbrida nativa Qdrant |
| Optional rerank | TextCrossEncoder |
Por que FastEmbed (Design)
| Propriedade | Benefício |
|---|
| ONNX Runtime | Sem PyTorch; instalação pequena, rápida em CPU |
| Quantized models | Memória/latência mais baixas |
| Lazy generators | Fluxo de embeddings, memória baixa |
| Local | Sem chamadas de API; dados ficam privados |
Fluxos de Trabalho Comuns
# Batch-embed a corpus for a vector DB (CPU-friendly)
from fastembed import TextEmbedding
model = TextEmbedding("BAAI/bge-base-en-v1.5")
embeddings = list(model.embed(corpus, batch_size=64))
# Build hybrid retrieval: dense + BM25 sparse, fused in Qdrant
FastEmbed vs Alternativas
| Aspecto | FastEmbed | sentence-transformers | OpenAI embeddings API |
|---|
| Runtime | ONNX (sem torch) | PyTorch | API hospedada |
| Sparse/ColBERT | Integrado | Libs extras | Não |
| Local/private | Sim | Sim | Não |
| Melhor para | Leve local + híbrido | Ecossistema torch completo | Simplidade gerenciada |
Recursos
