Embedding Providers
Relevant source files
The following files were used as context for generating this wiki page:
- packages/core/src/embedding/openai-embedding.ts
- packages/core/src/embedding/gemini-embedding.ts
- packages/core/src/embedding/ollama-embedding.ts
- packages/core/src/embedding/voyageai-embedding.ts
- packages/mcp/src/embedding.ts
- packages/vscode-extension/src/config/configManager.ts
- packages/mcp/src/config.ts
Embedding Providers are a core component of the Claude Context system, responsible for transforming raw code snippets and natural language queries into high-dimensional vector representations. These vectors enable semantic search capabilities by allowing the system to calculate the mathematical similarity between a user's intent and the indexed codebase.
The architecture supports multiple external AI services and local models, including OpenAI, VoyageAI, Google Gemini, and Ollama. Each provider is implemented as a specialized class within the core package, offering unified methods for single and batch embedding generation.
Sources: packages/core/README.md, packages/mcp/README.md
Provider Architecture and Integration
The project employs a pluggable provider architecture. The Context class in the core package interacts with an Embedding interface, which is implemented by specific provider classes. This allows the system to switch between different AI backends without altering the primary indexing or search logic.
Provider Initialization Flow
The initialization of a provider typically occurs during the setup of the MCP server or the VS Code extension. A configuration object defines which provider to use and supplies the necessary API keys and model parameters.
The diagram shows how the system selects and initializes a specific embedding provider based on configuration.
Sources: packages/mcp/src/embedding.ts:5-60, packages/vscode-extension/src/config/configManager.ts:182-188
Supported Providers
OpenAI
OpenAI is the default provider, supporting high-performance models like text-embedding-3-small and text-embedding-3-large. It allows for custom base URLs, making it compatible with Azure OpenAI or proxy services.
| Feature | Description |
|---|---|
| Default Model | text-embedding-3-small |
| Required Config | apiKey |
| Optional Config | baseURL, model |
| Batch Support | Yes |
Sources: packages/mcp/src/config.ts:74-76, packages/vscode-extension/src/config/configManager.ts:47-58
VoyageAI
VoyageAI provides specialized embeddings optimized for code understanding. It is frequently used for high-accuracy semantic search in programming contexts.
| Feature | Description |
|---|---|
| Default Model | voyage-code-3 |
| Required Config | apiKey |
| Batch Support | Yes |
Sources: packages/mcp/src/config.ts:77-78, packages/vscode-extension/src/config/configManager.ts:64-73
Gemini (Google AI)
Gemini embeddings support Matryoshka representation learning, allowing for adjustable output dimensionality (e.g., 3072, 1536, 768, 256).
| Feature | Description |
|---|---|
| Default Model | gemini-embedding-001 |
| Unique Param | outputDimensionality |
| Required Config | apiKey |
Sources: packages/vscode-extension/src/config/configManager.ts:98-111, packages/mcp/README.md
Ollama (Local)
Ollama enables fully local embedding generation, ensuring that codebase data never leaves the user's machine.
| Feature | Description |
|---|---|
| Default Model | nomic-embed-text |
| Default Host | http://127.0.0.1:11434 |
| Batch Support | Handled via local API |
Sources: packages/mcp/src/embedding.ts:46-55, packages/vscode-extension/src/config/configManager.ts:81-93
Data Flow: Embedding Generation
The generation process follows a sequence where text chunks are prepared, sent to the provider's API (or local service), and returned as numerical vectors.
This sequence illustrates the batch processing flow used during codebase indexing.
Sources: packages/core/src/context.ts:512-514, packages/mcp/README.md
Batch Processing Configuration
To optimize performance, providers utilize batch processing. The default batch size is 100, but it can be adjusted via environment variables to match provider throughput limits.
// Example batch processing logic in the context engine
const EMBEDDING_BATCH_SIZE = Math.max(1, parseInt(envManager.get('EMBEDDING_BATCH_SIZE') || '100', 10));
Sources: packages/core/src/context.ts:512, packages/mcp/README.md
Configuration and Environment Variables
Providers are configured primarily through environment variables in MCP mode or via the VS Code settings UI.
| Environment Variable | Description | Provider |
|---|---|---|
EMBEDDING_PROVIDER | Selection: OpenAI, VoyageAI, Gemini, Ollama | Global |
EMBEDDING_MODEL | Specific model name | Global |
OPENAI_API_KEY | Authentication for OpenAI | OpenAI |
VOYAGEAI_API_KEY | Authentication for VoyageAI | VoyageAI |
GEMINI_API_KEY | Authentication for Google AI | Gemini |
OLLAMA_HOST | Local service address (default: localhost) | Ollama |
Sources: packages/mcp/src/config.ts:133-149, packages/vscode-extension/src/config/configManager.ts:47-111
Conclusion
Embedding Providers serve as the bridge between raw source code and the vector database. By supporting a diverse range of backends—from industry-standard cloud APIs like OpenAI and Gemini to local solutions like Ollama—Claude Context ensures flexibility in terms of cost, privacy, and performance. The unified interface across these providers allows the core search engine to maintain consistent accuracy regardless of the underlying embedding model.