# Embedding Providers and Models Used for Semantic Search in Code‑Review‑Graph

> Explore embedding providers and models for semantic search in Code-Review-Graph. Choose local, Gemini, MiniMax, or OpenAI for privacy or performance.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: how-to-guide
- Published: 2026-07-20

---

**Code‑Review‑Graph supports four distinct embedding providers—Local (sentence‑transformers), Google Gemini, MiniMax, and OpenAI‑compatible endpoints—allowing developers to choose between offline privacy and cloud‑based performance for semantic code search.**

The **Code‑Review‑Graph** (CRG) repository implements a pluggable embedding architecture in [`code_review_graph/embeddings.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/embeddings.py) that enables hybrid semantic search. This system combines traditional full‑text search with dense vector retrieval to locate relevant code patterns across your repository.

## The Four Embedding Providers

The embedding subsystem defines four concrete implementations of the abstract `EmbeddingProvider` base class. Each provider targets different operational requirements regarding latency, privacy, and model capability.

### Local Provider (Offline)

The **LocalEmbeddingProvider** uses the *sentence‑transformers* library to generate embeddings entirely offline. It defaults to the `all‑MiniLM‑L6‑v2` model, a 384‑dimensional sentence encoder optimized for speed and memory efficiency.

In [`code_review_graph/embeddings.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/embeddings.py) (lines 4‑8), the provider initializes the model with optional `trust_remote_code` protection controlled by the `CRG_ALLOW_REMOTE_CODE` environment variable. This provider requires no network connectivity and incurs zero API costs, making it ideal for private environments or CI/CD pipelines.

### Google Gemini Provider

The **GoogleEmbeddingProvider** interfaces with Google's Gemini embedding API, defaulting to the `gemini‑embedding‑001` model. This provider requires a valid `GOOGLE_API_KEY` environment variable.

As implemented in lines 81‑89 of [`code_review_graph/embeddings.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/embeddings.py), this cloud‑based option offloads computation to Google's infrastructure, trading network latency for potentially higher‑quality multilingual embeddings.

### MiniMax Provider

The **MiniMaxEmbeddingProvider** connects to the MiniMax cloud API to generate 1536‑dimensional vectors using the `embo‑01` model. Configuration requires a `MINIMAX_API_KEY` environment variable.

The implementation (lines 70‑78) handles MiniMax‑specific authentication and batching constraints, providing a middle ground between local inference and large‑provider redundancy.

### OpenAI‑Compatible Provider

The **OpenAIEmbeddingProvider** supports any `/v1/embeddings`‑compatible endpoint, including OpenAI, Azure OpenAI, Ollama, LiteLLM, and vLLM. The model selection is controlled via the `CRG_OPENAI_MODEL` environment variable.

Found in lines 84‑93 of [`code_review_graph/embeddings.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/embeddings.py), this provider offers maximum flexibility for organizations running self‑hosted embedding gateways or requiring specific model versions like `text‑embedding‑3‑small`.

## The EmbeddingProvider Interface

All providers implement the abstract base class `EmbeddingProvider` defined in lines 46‑58 of [`code_review_graph/embeddings.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/embeddings.py). This contract ensures interchangeable behavior across the search pipeline:

```python
class EmbeddingProvider(ABC):
    def embed(self, texts: list[str]) -> list[list[float]]: ...
    def embed_query(self, text: str) -> list[float]: ...
    @property
    def dimension(self) -> int: ...
    @property
    def name(self) -> str: ...

```

- **`embed()`**: Batch encodes multiple documents for indexing.
- **`embed_query()`**: Encodes a single search query, potentially using task‑specific optimizations.
- **`dimension`**: Returns the vector size (384 for MiniLM, 1536 for MiniMax, etc.).

## Hybrid Search Architecture

The semantic search implementation lives in [`code_review_graph/search.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/search.py) and operates as a dual‑pipeline system that merges lexical and semantic relevance signals.

### FTS5 BM25 vs Vector Similarity

When `hybrid_search()` is invoked, CRG executes two parallel retrieval strategies:

1. **FTS5 BM25**: A SQLite full‑text index rebuilt via `rebuild_fts_index()` (lines 25‑68) that performs keyword‑based matching on code tokens.
2. **Embedding Search**: Vector similarity lookup against the `embeddings` table populated by the active provider, implemented in `_embedding_search`.

### Reciprocal Rank Fusion

Results from both pipelines are merged using **Reciprocal Rank Fusion** (`rrf_merge`, lines 50‑74). This algorithm combines rankings from disparate sources without requiring score normalization, producing a unified relevance score that balances exact keyword matches with semantic similarity.

```python
from code_review_graph.search import hybrid_search
from code_review_graph.graph import GraphStore

store = GraphStore("/tmp/crg.db")
results = hybrid_search(
    store,
    query="extract all public API endpoints from a SpringBoot project",
    limit=20,
)

```

## Configuration and Environment Variables

Provider selection and behavior are controlled through environment variables read at initialization:

- **`CRG_EMBEDDING_MODEL`**: Overrides the default model for the Local provider (e.g., `all-mpnet-base-v2`).
- **`CRG_OPENAI_MODEL`**: Selects the specific OpenAI model (e.g., `text-embedding-3-small`).
- **`CRG_ALLOW_REMOTE_CODE`**: Enables `trust_remote_code` for sentence‑transformers loading (security‑sensitive).

These variables are parsed in [`embeddings.py`](https://github.com/tirth8205/code-review-graph/blob/main/embeddings.py) during provider instantiation (lines 97‑104).

## Implementation Examples

### Initializing Specific Providers

```python
from code_review_graph.embeddings import (
    LocalEmbeddingProvider,
    OpenAIEmbeddingProvider,
)

# Offline local inference

local = LocalEmbeddingProvider()
vectors = local.embed(["def foo(): pass", "class Bar: ..."])

# OpenAI-compatible endpoint

openai = OpenAIEmbeddingProvider(
    api_key="sk-...",
    model="text-embedding-3-small",
    base_url="https://api.openai.com/v1"
)
query_vec = openai.embed_query("How to iterate over a Python list?")

```

### Pre‑warming Local Models

On Windows and certain environments, sentence‑transformers must be loaded in the main thread before forking:

```python
from code_review_graph.embeddings import prewarm_local_embeddings

prewarm_local_embeddings()  # Loads model once to prevent thread-safety issues

```

## Summary

- **Four provider options** cover offline (sentence‑transformers), Google Gemini, MiniMax, and any OpenAI‑compatible endpoint.
- **Abstract interface** (`EmbeddingProvider`) standardizes `embed()`, `embed_query()`, and `dimension` across all implementations.
- **Hybrid retrieval** combines SQLite FTS5 BM25 with vector similarity using Reciprocal Rank Fusion in [`code_review_graph/search.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/search.py).
- **Environment variables** `CRG_EMBEDDING_MODEL`, `CRG_OPENAI_MODEL`, and `CRG_ALLOW_REMOTE_CODE` control runtime configuration without code changes.
- **Local provider** defaults to `all‑MiniLM‑L6‑v2` (384‑dim) and supports `trust_remote_code` security controls.

## Frequently Asked Questions

### What is the default embedding model for offline usage?

The **LocalEmbeddingProvider** defaults to `all‑MiniLM‑L6‑v2`, a lightweight 384‑dimensional model from the sentence‑transformers library. You can override this via the `CRG_EMBEDDING_MODEL` environment variable, for example to use `all-mpnet-base-v2` for potentially higher accuracy at the cost of inference speed.

### How does Code‑Review‑Graph combine keyword and semantic search?

CRG implements **Reciprocal Rank Fusion** (`rrf_merge` in [`code_review_graph/search.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/search.py) lines 50‑74) to merge results from SQLite FTS5 BM25 (lexical search) and cosine similarity on vector embeddings (semantic search). This hybrid approach ensures exact keyword matches remain highly ranked while semantically related but syntactically different code is also surfaced.

### Can I use a self‑hosted embedding model with Code‑Review‑Graph?

Yes. The **OpenAIEmbeddingProvider** accepts any `/v1/embeddings`‑compatible endpoint via the `base_url` parameter. This supports self‑hosted solutions like Ollama, vLLM, or LiteLLM gateways, allowing you to run `text‑embedding‑3‑small` or custom models entirely within your infrastructure without external API calls.