How to Configure Embedding Models in Semantica: Sentence-Transformers, FastEmbed, BGE, and Ollama Setup Guide

Configure embedding models in Semantica through the provider-agnostic EmbeddingGenerator API, which supports FastEmbed (default), Sentence-Transformers, and OpenAI out of the box, while Ollama requires LiteLLM integration.

Semantica's embedding subsystem is designed for flexibility. The semantica.embeddings module provides a unified interface that lets you switch between local models and cloud APIs without rewriting your application code. This guide walks through configuring Sentence-Transformers, FastEmbed with BGE models, and Ollama embeddings using the actual source implementation.

---

FastEmbed (Default): Zero-Configuration Local Embeddings

FastEmbed serves as Semantica's default embedding provider. It requires no GPU, no API keys, and no external dependencies beyond the base package.

How It Works

In semantica/embeddings/provider_stores.py, the FastEmbedStore class wraps fastembed.TextEmbedding and loads BAAI/bge-small-en-v1.5 by default. The store is instantiated lazily—only when generate_embeddings() is first called.

from semantica.embeddings import EmbeddingGenerator

# FastEmbed loads automatically—no config needed

gen = EmbeddingGenerator()

vec = gen.generate_embeddings("Semantica provides zero-config embeddings")
print(vec.shape)  # (384,) — BGE-small output dimension

The EmbeddingGenerator constructor accepts an optional config dict, but FastEmbed runs with sensible defaults when omitted.

---

Sentence-Transformers and BGE: Custom HuggingFace Models

For larger BGE variants or other Sentence-Transformers models, use the "sentence_transformers" method. The BGEStore class (also in provider_stores.py) handles model loading through the sentence_transformers library.

Configuration Pattern

Set method to "sentence_transformers" and specify model_name with any HuggingFace model identifier:

from semantica.embeddings import EmbeddingGenerator

gen = EmbeddingGenerator(
    config={
        "text": {
            "method": "sentence_transformers",
            "model_name": "BAAI/bge-large-en-v1.5"
        }
    }
)

vec = gen.generate_embeddings("High-quality embeddings from local BGE-large")
print(vec.shape)  # (1024,) — larger dimension for better retrieval

Available Model Options

• all-MiniLM-L6-v2 — Fast, compact (384-dim), good for prototyping
• BAAI/bge-small-en-v1.5 — Balanced speed/quality (384-dim)
• BAAI/bge-large-en-v1.5 — Best retrieval quality (1024-dim)
• BAAI/bge-m3 — Multilingual support (1024-dim)

All models download automatically on first use and cache locally.

---

Switching Embedding Models at Runtime

The EmbeddingGenerator.set_text_model() method (defined in embedding_generator.py) enables hot-swapping providers without reinitializing your pipeline. This is invaluable for A/B testing or progressive upgrades.

from semantica.embeddings import EmbeddingGenerator

gen = EmbeddingGenerator()  # Starts with FastEmbed/BGE-small

# Switch to a different Sentence-Transformers model

gen.set_text_model("sentence_transformers", "all-MiniLM-L6-v2")
vec = gen.generate_embeddings("Runtime model switching")
print(vec.shape)  # (384,)

# Switch back to default or try another BGE variant

gen.set_text_model("sentence_transformers", "BAAI/bge-large-en-v1.5")

The method signature follows: set_text_model(method: str, model_name: str, **kwargs).

---

OpenAI Embeddings: Cloud API Integration

For production workloads requiring state-of-the-art embedding quality, configure the OpenAIStore via embedding_generator.py or use it directly.

import os
from semantica.embeddings import OpenAIStore, EmbeddingGenerator

os.environ["OPENAI_API_KEY"] = "sk-..."  # Never hardcode secrets

# Direct store usage

store = OpenAIStore(model="text-embedding-3-large")
vec = store.embed("OpenAI's latest embedding model")
print(vec.shape)  # (3072,)

# Via generator facade

gen = EmbeddingGenerator(
    config={"text": {"method": "openai", "model": "text-embedding-3-small"}}
)

The OpenAIStore.embed() and embed_batch() methods return NumPy arrays identical in interface to local providers, ensuring drop-in compatibility.

---

Ollama Embeddings: LiteLLM Integration (No Native Store)

Critical distinction: Semantica does not provide a functional OllamaStore for embeddings. The placeholder LlamaStore class in provider_stores.py (lines 44-92) raises a ProcessingError if instantiated.

The Working Path: LiteLLM Wrapper

To generate embeddings from local Ollama models, route through LiteLLM using its OpenAI-compatible interface:

# Prerequisites:

# 1. pip install "semantica[llm-ollama]"

# 2. Terminal: ollama serve

# 3. Terminal: ollama pull nomic-embed-text

from litellm import LiteLLM

llm = LiteLLM(
    model="ollama/nomic-embed-text",
    api_base="http://localhost:11434"
)

response = llm.embeddings.create(input="Local embedding via Ollama")
vec = response.data[0].embedding
print(len(vec))  # 768 for nomic-embed-text

This bypasses Semantica's EmbeddingGenerator entirely. For unified management, wrap this pattern in a custom store class or precompute embeddings before ingestion.

---

Provider Architecture Deep-Dive

Understanding the internal flow helps debug configuration issues.

Component	File	Responsibility
EmbeddingGenerator	semantica/embeddings/embedding_generator.py	Façade that orchestrates provider selection and runtime switching
ProviderStoreFactory	provider_stores.py	Creates concrete store instances from method strings
FastEmbedStore	provider_stores.py	ONNX-accelerated local embeddings
BGEStore	provider_stores.py	Sentence-Transformers wrapper for HuggingFace models
OpenAIStore	provider_stores.py	HTTP client for OpenAI /embeddings endpoint
LlamaStore	provider_stores.py	Non-functional placeholder — raises ProcessingError

The factory pattern ensures embed() and embed_batch() return consistent NumPy arrays regardless of backend.

---

Installation Requirements by Provider

# Base installation (includes FastEmbed by default)

pip install semantica

# Sentence-Transformers support (usually included)

pip install "semantica[sentence-transformers]"

# OpenAI support

pip install "semantica[openai]"

# Ollama LLM support (for LiteLLM path, not native embeddings)

pip install "semantica[llm-ollama]"

Verify available extras in the package's pyproject.toml or the docs/reference/embeddings.md documentation.

---

Summary

• FastEmbed runs with zero configuration as the default provider in EmbeddingGenerator
• Sentence-Transformers and BGE models require setting "method": "sentence_transformers" with a model_name parameter
• OpenAI embeddings need an API key and use the openai method or direct OpenAIStore
• Ollama embeddings have no dedicated store—use LiteLLM with ollama/ model prefixes instead
• All providers implement identical embed()/embed_batch() interfaces for seamless swapping via set_text_model()

---

Frequently Asked Questions

Why does Ollama embedding configuration fail with a ProcessingError?

The LlamaStore class in semantica/embeddings/provider_stores.py is a non-functional placeholder that raises ProcessingError on instantiation. Semantica intentionally lacks native Ollama embedding support; use LiteLLM with an ollama/ model prefix and api_base="http://localhost:11434" as the supported alternative.

Can I use custom fine-tuned BGE models with Semantica?

Yes. Any HuggingFace-compatible Sentence-Transformers model works by passing its repository ID to model_name: gen.set_text_model("sentence_transformers", "your-org/your-finetuned-bge"). The model downloads and caches automatically via the HuggingFace Hub.

How do I verify which embedding provider is currently active?

Inspect the internal store via gen._text_embedder._store or check the generator's configuration with gen.config.get("text", {}).get("method"). For production code, track provider state externally since Semantica doesn't expose a dedicated introspection method.

What's the performance difference between FastEmbed and Sentence-Transformers?

FastEmbed uses ONNX Runtime for CPU-optimized inference and starts faster due to smaller default models. Sentence-Transformers offers broader model selection and GPU acceleration via PyTorch but has heavier dependencies. For batch processing of large corpora, FastEmbed's BAAI/bge-small-en-v1.5 often outperforms larger models on latency; for retrieval accuracy, BAAI/bge-large-en-v1.5 via Sentence-Transformers dominates.

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