---
title: "Embeddings Module"
description: "Text and graph embedding generation — Sentence-Transformers, FastEmbed, OpenAI, BGE, LlamaStore, with pooling strategies and graph embedding managers."
icon: "vector-square"
---
> Unified interface for generating vector representations of text, nodes, and graphs.
---
## Overview
The **Embeddings Module** converts text and graph structures into dense vectors for semantic search, entity resolution, and GraphRAG retrieval. It abstracts multiple providers behind a single API and supports five pooling strategies.
Main entry point — provider-agnostic text embedding generation.
Text-specific embedding with batching and caching.
Node and subgraph embedding for structural similarity.
Embedding lifecycle for vector store integration.
Pluggable backends: OpenAI, BGE, FastEmbed, LlamaStore.
Mean, Max, CLS, Attention, Hierarchical pooling.
---
## EmbeddingGenerator
Main entry point — handles provider selection and batching:
```python
from semantica.embeddings import EmbeddingGenerator
# Sentence-Transformers (default, free, local)
generator = EmbeddingGenerator(model="sentence-transformers")
embeddings = generator.generate(["Text 1", "Text 2"])
# Specific model
generator = EmbeddingGenerator(model="BAAI/bge-large-en-v1.5")
embeddings = generator.generate(texts)
# OpenAI
import os
generator = EmbeddingGenerator(
model="openai",
model_name="text-embedding-3-small",
api_key=os.getenv("OPENAI_API_KEY")
)
# FastEmbed (fast CPU-optimized)
generator = EmbeddingGenerator(model="fastembed")
```
---
## Supported Models
| Provider | Model | Dimension | Notes |
|----------|-------|-----------|-------|
| `sentence-transformers` | `all-MiniLM-L6-v2` | 384 | Default, fast, free |
| `sentence-transformers` | `all-mpnet-base-v2` | 768 | Higher quality |
| `bge` | `BAAI/bge-large-en-v1.5` | 1024 | State-of-the-art retrieval |
| `fastembed` | `BAAI/bge-small-en-v1.5` | 384 | Fast, CPU-optimized |
| `openai` | `text-embedding-3-small` | 1536 | OpenAI API |
| `openai` | `text-embedding-3-large` | 3072 | OpenAI API, highest quality |
| `llama` | any Ollama model | varies | Local inference |
---
## TextEmbedder
Specialized for text with automatic batching:
```python
from semantica.embeddings import TextEmbedder
embedder = TextEmbedder(model="sentence-transformers", cache_dir=".emb_cache")
# Single text
embedding = embedder.embed("Hello world")
# Batch
embeddings = embedder.embed_batch(
["Text 1", "Text 2", ..., "Text 10000"],
batch_size=128,
show_progress=True
)
```
---
## Provider Stores
Each provider implements the `ProviderStore` interface and can be used independently:
```python
from semantica.embeddings import (
OpenAIStore, BGEStore, FastEmbedStore, LlamaStore,
ProviderStoreFactory
)
# OpenAI
store = OpenAIStore(api_key=os.getenv("OPENAI_API_KEY"), model="text-embedding-3-small")
embedding = store.embed("Hello world")
# BGE (Sentence-Transformers wrapper)
store = BGEStore(model="BAAI/bge-large-en-v1.5")
embedding = store.embed("Hello world")
# FastEmbed
store = FastEmbedStore(model="BAAI/bge-small-en-v1.5")
embedding = store.embed("Hello world")
# LlamaStore (Ollama local)
store = LlamaStore(model="llama3.2", base_url="http://localhost:11434")
embedding = store.embed("Hello world")
# Auto-select from config
store = ProviderStoreFactory.create(provider="openai", model="text-embedding-3-small")
```
---
## Pooling Strategies
Control how token-level embeddings are aggregated into a single vector:
```python
from semantica.embeddings import (
MeanPooling, MaxPooling, CLSPooling,
AttentionPooling, HierarchicalPooling, PoolingStrategyFactory
)
# Mean pooling (default — best for most tasks)
pooler = MeanPooling()
pooled = pooler.pool(token_embeddings)
# Max pooling (captures strongest features)
pooler = MaxPooling()
# CLS token pooling (first token — good for classification)
pooler = CLSPooling()
# Attention-weighted pooling
pooler = AttentionPooling()
# Hierarchical: chunk-level → global mean (best for long documents)
pooler = HierarchicalPooling(chunk_size=512)
# Create from config
pooler = PoolingStrategyFactory.create(strategy="mean")
```
---
## GraphEmbeddingManager
Embed graph nodes and subgraphs for structural similarity and GraphRAG:
```python
from semantica.embeddings import GraphEmbeddingManager
manager = GraphEmbeddingManager(
text_embedder=TextEmbedder(model="sentence-transformers"),
graph_store=graph_store
)
# Embed all nodes
node_embeddings = manager.embed_nodes(kg)
# Embed a specific subgraph (for GraphRAG context)
subgraph_embedding = manager.embed_subgraph(
kg, center_node="Apple Inc.", hops=2
)
# Find similar nodes
similar = manager.find_similar_nodes("apple_inc", top_k=5)
```
---
## VectorEmbeddingManager
Manages the full embedding lifecycle for vector store integration:
```python
from semantica.embeddings import VectorEmbeddingManager
from semantica.vector_store import VectorStore
vector_store = VectorStore(backend="faiss", dimension=768)
manager = VectorEmbeddingManager(
embedder=TextEmbedder(model="sentence-transformers"),
vector_store=vector_store
)
# Embed and store documents
ids = manager.embed_and_store(documents, metadata=metadata_list)
# Search
results = manager.search("machine learning algorithms", top_k=10)
```
---
## Similarity Computation
```python
from semantica.embeddings import calculate_similarity
score = calculate_similarity(embedding_a, embedding_b, method="cosine")
# → 0.0 to 1.0
# Euclidean distance converted to similarity
score = calculate_similarity(embedding_a, embedding_b, method="euclidean")
```
---
## Convenience Functions
```python
from semantica.embeddings import (
embed_text, generate_embeddings, calculate_similarity,
pool_embeddings, check_available_providers
)
# Single text
emb = embed_text("Hello world", method="sentence_transformers")
# Batch
embs = generate_embeddings(texts, method="openai")
# Check what's installed
providers = check_available_providers()
# → {"sentence_transformers": True, "fastembed": True, "openai": False}
```
---
## GPU Acceleration
```python
generator = EmbeddingGenerator(model="sentence-transformers", device="cuda")
# device: "cpu" | "cuda" | "mps"
```
---
## Caching
Embedding cache reuse is used by Distance Intelligence (v0.5.0) to avoid recomputing embeddings for large distance matrix calculations:
```python
embedder = TextEmbedder(
model="sentence-transformers",
cache_dir=".embeddings_cache",
cache_ttl=3600 # TTL in seconds
)
```
---
## See Also
Store and search the generated embeddings.
Chunk text before embedding.
Distance Intelligence uses graph embeddings.
Semantic deduplication uses embeddings for entity resolution.