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

> Learn to configure embedding models like Sentence-Transformers FastEmbed BGE and Ollama in Semantica. Utilize the EmbeddingGenerator API for seamless integration.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-16

---

**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`](https://github.com/semantica-agi/semantica/blob/main/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.

```python
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`](https://github.com/semantica-agi/semantica/blob/main/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:

```python
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`](https://github.com/semantica-agi/semantica/blob/main/embedding_generator.py)) enables **hot-swapping** providers without reinitializing your pipeline. This is invaluable for A/B testing or progressive upgrades.

```python
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`](https://github.com/semantica-agi/semantica/blob/main/embedding_generator.py) or use it directly.

```python
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`](https://github.com/semantica-agi/semantica/blob/main/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:

```python

# 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`](https://github.com/semantica-agi/semantica/blob/main/semantica/embeddings/embedding_generator.py) | Façade that orchestrates provider selection and runtime switching |
| `ProviderStoreFactory` | [`provider_stores.py`](https://github.com/semantica-agi/semantica/blob/main/provider_stores.py) | Creates concrete store instances from method strings |
| `FastEmbedStore` | [`provider_stores.py`](https://github.com/semantica-agi/semantica/blob/main/provider_stores.py) | ONNX-accelerated local embeddings |
| `BGEStore` | [`provider_stores.py`](https://github.com/semantica-agi/semantica/blob/main/provider_stores.py) | Sentence-Transformers wrapper for HuggingFace models |
| `OpenAIStore` | [`provider_stores.py`](https://github.com/semantica-agi/semantica/blob/main/provider_stores.py) | HTTP client for OpenAI `/embeddings` endpoint |
| `LlamaStore` | [`provider_stores.py`](https://github.com/semantica-agi/semantica/blob/main/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

```bash

# 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`](https://github.com/semantica-agi/semantica/blob/main/pyproject.toml) or the [`docs/reference/embeddings.md`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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.