# Which Embedding Models Are Compatible with Semantica: A Complete Guide to Provider-Agnostic Embeddings

> Discover which embedding models are compatible with Semantica. Explore provider-agnostic embeddings from FastEmbed, Sentence-Transformers, OpenAI, and BGE with easy model switching.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: deep-dive
- Published: 2026-09-04

---

**Semantica supports four embedding provider families—FastEmbed (BGE), Sentence-Transformers, OpenAI, and standalone BGE—allowing seamless switching between models like `BAAI/bge-small-en-v1.5`, `all-mpnet-base-v2`, or `text-embedding-ada-002` via a single `set_text_model()` call without modifying downstream code.**

Semantica's embedding subsystem is deliberately architected to be provider-agnostic, enabling developers to swap between local open-source models and hosted APIs interchangeably. Whether you need lightweight on-device inference or high-performance cloud embeddings, the `semantica-agi/semantica` repository abstracts model-specific complexity behind a unified interface defined in [`semantica/embeddings/text_embedder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/embeddings/text_embedder.py) and [`semantica/embeddings/provider_stores.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/embeddings/provider_stores.py).

## Supported Embedding Providers in Semantica

The framework implements four distinct provider stores, each optimized for specific deployment scenarios and model families.

### FastEmbed and BGE Models (Local, Efficient)

The **FastEmbed** integration provides high-performance local inference for BAAI General-Purpose Embedding (BGE) models. Implemented in the `FastEmbedStore` class within [`semantica/embeddings/provider_stores.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/embeddings/provider_stores.py), this provider defaults to `BAAI/bge-small-en-v1.5` (384 dimensions) but supports larger variants like `BAAI/bge-large-en-v1.5` (1024 dimensions). FastEmbed is optimized for CPU inference with minimal latency, making it ideal for edge deployments and privacy-sensitive applications where data cannot leave the local environment.

### Sentence-Transformers (Hugging Face Ecosystem)

For access to the broader Hugging Face model hub, Semantica integrates the **Sentence-Transformers** library through the `TextEmbedder` class. When the `method` parameter is set to `"sentence_transformers"`, the system instantiates `self.model = SentenceTransformer(self.model_name)`, enabling compatibility with any sentence-transformers compatible model. Common configurations include `all-MiniLM-L6-v2` (384-dim) and `all-mpnet-base-v2` (768-dim), though thousands of community models are available.

### OpenAI Embeddings (Hosted API)

The **OpenAI** provider enables cloud-based embeddings through the `OpenAIStore` class in [`semantica/embeddings/provider_stores.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/embeddings/provider_stores.py). This implementation forwards requests to OpenAI's embedding endpoint, supporting models like `text-embedding-ada-002` (1536 dimensions). Rather than loading models locally, this provider constructs HTTP request payloads using your configured API key, shifting computational overhead to OpenAI's infrastructure.

### Standalone BGE Provider

Distinct from the FastEmbed integration, the standalone **BGE** provider offers direct access to BGE models via the `bge` method. The `BGEStore` class in [`semantica/embeddings/provider_stores.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/embeddings/provider_stores.py) wires the BGE library directly, providing an alternative interface for developers requiring specific BGE library features not exposed through FastEmbed's abstraction layer.

## How Semantica's Provider Abstraction Works

The embedding layer uses a factory pattern to decouple model selection from vector generation. The `ProviderStoreFactory` in [`semantica/embeddings/provider_stores.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/embeddings/provider_stores.py) maps string identifiers (`"fastembed"`, `"sentence_transformers"`, `"openai"`, `"bge"`) to concrete store implementations.

When you call `set_text_model(method, model_name)` on the `EmbeddingGenerator` class (defined in [`semantica/embeddings/embedding_generator.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/embeddings/embedding_generator.py)), the factory instantiates the appropriate provider:

- **FastEmbed/BGE**: Constructs `FastEmbed` or `BGE` objects with the supplied `model_name`
- **Sentence-Transformers**: Creates a `SentenceTransformer` instance via `self.model = SentenceTransformer(self.model_name)`
- **OpenAI**: Prepares HTTP request payloads with the chosen model identifier

Each provider exposes `get_embedding_dimension()`, which the vector store layer uses to validate compatibility. The system ensures that declared store dimensions match model outputs—384 for `BAAI/bge-small-en-v1.5`, 768 for `all-mpnet-base-v2`, or 1536 for OpenAI embeddings—preventing dimension mismatch errors during insertion.

## Configuring and Switching Embedding Models

You can switch between providers at runtime without changing downstream consumption code. The `set_text_model()` method accepts a `method` string and `model_name`, routing to the appropriate backend automatically.

```python

# Example 1 – Use a fast local BGE model (default)

from semantica.embeddings import EmbeddingGenerator

gen = EmbeddingGenerator()
gen.set_text_model(method="fastembed", model_name="BAAI/bge-small-en-v1.5")
embeddings = gen.generate_embeddings(["Hello world", "Semantica is awesome"])
print(embeddings.shape)   # (2, 384)

```

```python

# Example 2 – Switch to a sentence‑transformers model

gen.set_text_model(method="sentence_transformers", model_name="all-mpnet-base-v2")
emb = gen.generate_embeddings(["Another sentence"])
print(emb.shape)          # (1, 768)

```

```python

# Example 3 – Use OpenAI’s hosted embedding endpoint

gen.set_text_model(method="openai", model_name="text-embedding-ada-002")
emb = gen.generate_embeddings(["OpenAI embeddings"])
print(emb.shape)          # (1, 1536)

```

## Key Source Files and Architecture

Understanding the following files is essential for debugging or extending Semantica's embedding capabilities:

- [`semantica/embeddings/text_embedder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/embeddings/text_embedder.py) – Core class that loads the chosen model and exposes `generate_embeddings`
- [`semantica/embeddings/provider_stores.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/embeddings/provider_stores.py) – Registry of provider stores including `FastEmbedStore`, `BGEStore`, `OpenAIStore`, and `LlamaStore`
- [`semantica/embeddings/embedding_generator.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/embeddings/embedding_generator.py) – High-level façade that orchestrates model selection via `set_text_model()` and embedding generation
- [`docs/reference/vector_store.md`](https://github.com/semantica-agi/semantica/blob/main/docs/reference/vector_store.md) – Documentation on matching store dimensions to embedding models (e.g., BGE-small = 384)

## Summary

- **Semantica supports four embedding providers**: FastEmbed (BGE), Sentence-Transformers, OpenAI, and standalone BGE, each implemented in [`semantica/embeddings/provider_stores.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/embeddings/provider_stores.py)
- **Provider-agnostic switching**: Change models via `set_text_model(method, model_name)` without modifying downstream vector operations
- **Dimension validation**: The system automatically validates embedding dimensions (384, 768, 1024, 1536) match vector store configurations via `get_embedding_dimension()`
- **Local vs. hosted flexibility**: Choose between CPU-optimized local inference (FastEmbed, Sentence-Transformers) or cloud APIs (OpenAI) based on latency, privacy, and cost requirements

## Frequently Asked Questions

### How do I switch from FastEmbed to OpenAI embeddings in Semantica?

Call `gen.set_text_model(method="openai", model_name="text-embedding-ada-002")` on your `EmbeddingGenerator` instance. The `ProviderStoreFactory` automatically routes requests to the `OpenAIStore` class instead of `FastEmbedStore`, and the system validates that your vector store can accommodate the 1536-dimensional output.

### What embedding dimensions does Semantica support?

Semantica supports any dimension produced by its provider libraries, with common configurations including 384-dim (`BAAI/bge-small-en-v1.5`, `all-MiniLM-L6-v2`), 768-dim (`all-mpnet-base-v2`), 1024-dim (`BAAI/bge-large-en-v1.5`), and 1536-dim (`text-embedding-ada-002`). The `get_embedding_dimension()` method in each provider store reports the specific dimension for validation against your vector store schema.

### Can I use custom Hugging Face models with Semantica?

Yes, via the Sentence-Transformers provider. Set `method="sentence_transformers"` and specify any Hugging Face model identifier (e.g., `model_name="intfloat/multilingual-e5-large"`) in `set_text_model()`. The `TextEmbedder` class loads any compatible sentence-transformers model using `SentenceTransformer(self.model_name)`.

### Does Semantica validate embedding dimensions automatically?

Yes. Each provider store implements `get_embedding_dimension()`, and the vector store layer validates that the declared dimension matches the model's output before insertion. This prevents runtime errors from dimension mismatches between your chosen embedding model and vector database schema.