How to Configure Vector Embedding Providers (Local, OpenAI, Google, MiniMax, Voyage) in code-review-graph

To configure vector embedding providers in code-review-graph, set the appropriate environment variables for your chosen backend (e.g., CRG_OPENAI_API_KEY for OpenAI, GOOGLE_API_KEY for Google Gemini) and instantiate EmbeddingStore or call get_provider() with the provider name.

The code-review-graph repository implements a pluggable embedding architecture that supports both local and cloud-based vector generation. Understanding how to configure these providers ensures you can generate code embeddings using your preferred infrastructure while maintaining data isolation between different backends.

Overview of the Embedding Provider Architecture

The core abstraction lives in code_review_graph/embeddings.py, where the base class EmbeddingProvider (lines 47-66) defines the interface for all vector generation implementations. At runtime, the helper function get_provider() (lines 672-725) inspects the provider name (local, openai, google, minimax, or voyage) and optional model argument to instantiate the correct concrete class.

Each provider implementation handles its own authentication, batching logic, and dimensionality settings. The system stores generated vectors in an EmbeddingStore (lines 560-724), which persists data to SQLite and automatically isolates embeddings by provider to prevent cross-contamination between different vector spaces.

Supported Vector Embedding Providers

Local Embeddings (sentence-transformers)

The LocalEmbeddingProvider class (lines 113-180) runs entirely on your machine using the sentence-transformers library. This provider requires no API keys and works offline.

• Environment variable: CRG_EMBEDDING_MODEL (optional, defaults to all-MiniLM-L6-v2)
• No cloud egress: Ideal for air-gapped environments or CI/CD pipelines

For optimal performance, the repository includes prewarm_local_embeddings() in code_review_graph/main.py to load the model into memory before processing large codebases.

OpenAI-Compatible Providers

The OpenAIEmbeddingProvider class (lines 558-728) supports any OpenAI-compatible endpoint, including Azure OpenAI Service, Ollama, or self-hosted inference servers.

• Required: CRG_OPENAI_API_KEY
• Base URL: CRG_OPENAI_BASE_URL (e.g., https://api.openai.com/v1 or Azure endpoints)
• Model: CRG_OPENAI_MODEL (e.g., text-embedding-3-small, text-embedding-3-large)
• Optional tuning: CRG_OPENAI_DIMENSION (vector size), CRG_OPENAI_BATCH_SIZE (request batching)

Google Gemini

The GoogleEmbeddingProvider class (lines 182-236) interfaces with Google's Gemini embedding API.

• Required: GOOGLE_API_KEY
• Default model: gemini-embedding-001 (configurable via the model parameter)
• Implementation: Uses Google's generative AI SDK with automatic retry logic

MiniMax

The MiniMaxEmbeddingProvider class (lines 274-356) connects to the MiniMax API for Chinese-optimized embeddings.

• Required: MINIMAX_API_KEY
• Fixed configuration: Model embo-01 with 1536 dimensions
• Region: Optimized for Asia-Pacific latency

Voyage AI

The VoyageEmbeddingProvider class (lines 629-724) specializes in code-aware embeddings through the Voyage AI platform.

• Required: VOYAGE_API_KEY
• Base URL: CRG_VOYAGE_BASE_URL (defaults to https://api.voyageai.com/v1)
• Default model: CRG_VOYAGE_MODEL (defaults to voyage-code-3)

Configuration via Environment Variables

Configure your chosen backend by exporting the following variables before running your application:

# Local (no API key needed)

export CRG_EMBEDDING_MODEL=all-MiniLM-L6-v2

# OpenAI-compatible (includes Azure)

export CRG_OPENAI_API_KEY=sk-...
export CRG_OPENAI_BASE_URL=https://api.openai.com/v1
export CRG_OPENAI_MODEL=text-embedding-3-small

# Google Gemini

export GOOGLE_API_KEY=AIza...

# MiniMax

export MINIMAX_API_KEY=your-minimax-key

# Voyage AI

export VOYAGE_API_KEY=your-voyage-key

The get_provider() function automatically detects which variables are present and instantiates the corresponding provider class.

Handling Cloud Egress Warnings

By default, the system emits a one-time warning to stderr before making any cloud API call unless the target URL points to localhost (lines 43-65). This safety mechanism prevents accidental data leakage to third-party services.

To suppress this warning for production deployments:

export CRG_ACCEPT_CLOUD_EMBEDDINGS=1

Setting this variable acknowledges that you intend to send code snippets to external embedding services.

Practical Implementation Examples

Example A: Explicit MiniMax Configuration

import os
from code_review_graph.embeddings import EmbeddingStore, get_provider

os.environ["MINIMAX_API_KEY"] = "MY_MINIMAX_KEY"

# Explicitly request the MiniMax provider

provider = get_provider(provider="minimax")
print(provider.name)  # Output: minimax:embo-01

store = EmbeddingStore(db_path="embeddings.db", provider="minimax")

# Embed example code snippets

vectors = provider.embed(["def foo(): pass", "class Bar: ..."])
print(vectors[:1])  # [[0.12, 0.34, ...]]

Example B: OpenAI-Compatible Provider (Azure)

import os
from code_review_graph.embeddings import EmbeddingStore

os.environ.update({
    "CRG_OPENAI_API_KEY": "AZURE_KEY",
    "CRG_OPENAI_BASE_URL": "https://my-azure.openai.azure.com/v1",
    "CRG_OPENAI_MODEL": "text-embedding-3-large",
})

# Automatically uses OpenAI provider based on env vars

store = EmbeddingStore(db_path="embeddings.db")
print(store.provider.name)  

# Output: openai:text-embedding-3-large@https://my-azure.openai.azure.com

Vector Storage and Provider Isolation

The EmbeddingStore class manages persistence in a SQLite database with an embeddings table that includes a provider column. When executing searches, the store filters results to include only vectors matching the current provider identifier (lines 552-561).

This design guarantees that:

• Vectors from different backends are never mixed in similarity searches
• You can safely switch providers without invalidating existing databases
• Each provider's specific dimensionality and normalization schemes remain isolated

Summary

• Five backends supported: Local (sentence-transformers), OpenAI-compatible, Google Gemini, MiniMax, and Voyage AI
• Environment-driven configuration: Set provider-specific API keys and endpoints via CRG_* and provider-specific variables
• Automatic provider selection: get_provider() in code_review_graph/embeddings.py instantiates the correct class based on available environment variables
• Safety warnings: Cloud providers trigger a stderr warning unless CRG_ACCEPT_CLOUD_EMBEDDINGS=1 is set or the endpoint is localhost
• Storage isolation: EmbeddingStore maintains separate vector spaces per provider in SQLite, preventing cross-provider contamination

Frequently Asked Questions

How do I switch between local and cloud providers?

Set the provider argument when calling get_provider() or creating an EmbeddingStore. For example, get_provider(provider="local") forces local embeddings regardless of API keys present in the environment. If you omit the argument, the library selects the first provider with valid credentials configured.

Can I use custom OpenAI-compatible endpoints like Azure or Ollama?

Yes. The OpenAIEmbeddingProvider class accepts any base URL via CRG_OPENAI_BASE_URL. For Azure, set this to your Azure OpenAI endpoint (e.g., https://your-resource.openai.azure.com/v1). For Ollama or other self-hosted solutions, point to your local inference server (e.g., http://localhost:11434/v1).

Why am I seeing a cloud egress warning and how do I disable it?

The warning appears when initializing a cloud provider to prevent accidental transmission of proprietary code to external APIs. To disable it, export CRG_ACCEPT_CLOUD_EMBEDDINGS=1 in your environment. This is required for all remote providers except when CRG_OPENAI_BASE_URL points to localhost.

Are embeddings from different providers stored separately?

Yes. The EmbeddingStore schema includes a provider column in the SQLite embeddings table. During similarity searches, the store automatically filters by the current provider identifier, ensuring that vectors generated by MiniMax are never compared against vectors from OpenAI or local models, as different providers use incompatible vector spaces and dimensions.

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