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

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 and 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, 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. 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 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 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), 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.

# 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)

# 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)

# 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 – Core class that loads the chosen model and exposes generate_embeddings
• semantica/embeddings/provider_stores.py – Registry of provider stores including FastEmbedStore, BGEStore, OpenAIStore, and LlamaStore
• 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 – 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
• 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}