Switching Embedding Providers

Relevant source files

The following files were used as context for generating this wiki page:

• cmd/app/main.go
• internal/embeddings/ollama.go
• internal/embeddings/openai.go
• internal/qdrant/client.go
• internal/search/service.go
• setup-ollama.md

The MauQNotes application is designed to convert text into vector embeddings for semantic search. The system supports multiple embedding providers, and the selection is primarily managed through environment variables. This allows flexibility in choosing different models based on performance, accuracy, or cost requirements. However, the current search service implementation is hardcoded to use the Ollama provider.

The choice of embedding model directly impacts the vector dimension size, which is a critical parameter for initializing the Qdrant vector collection. The application handles this by mapping specific model names to their corresponding dimensions.

Configuration

The embedding provider and model are configured using environment variables loaded via godotenv. The search.Init function reads these variables to determine the correct vector dimension for the Qdrant collection.

Sources: internal/search/service.go:11-15, internal/embeddings/ollama.go:20-29, internal/embeddings/openai.go:23-28

Environment Variables

Variable	Description	Default Value	Source File
EMBEDDING_MODEL	Specifies the name of the embedding model to use.	nomic-embed-text	internal/search/service.go:13
OLLAMA_URL	The base URL for the Ollama API endpoint.	http://localhost:11434	internal/embeddings/ollama.go:23
OPENAI_API_KEY	The API key for accessing the OpenAI embeddings API.	(none)	internal/embeddings/openai.go:24
QDRANT_URL	The base URL for the Qdrant vector database.	(none)	internal/qdrant/client.go:73
QDRANT_COLLECTION	The name of the collection to use in Qdrant.	(none)	internal/qdrant/client.go:75

Supported Models and Dimensions

The application determines the vector dimension based on the EMBEDDING_MODEL environment variable. This logic resides in the search.Init function.

Sources: internal/search/service.go:19-32, [setup-ollama.md:21-25]

Model Name (EMBEDDING_MODEL)	Vector Dimension	Provider
nomic-embed-text	768	Ollama
all-minilm	384	Ollama
mxbai-embed-large	512 (code) / 1024 (docs)	Ollama

Note: There is a discrepancy in the dimension for mxbai-embed-large. The code specifies 512, while the documentation suggests 1024.
Sources: internal/search/service.go:29, [setup-ollama.md:25]

The following diagram illustrates how the search.Init function determines the vector dimension.

Sources: internal/search/service.go:19-32

Architecture and Data Flow

The overall process involves the search service coordinating with an embedding provider to generate a vector, which is then used for operations (ingestion or query) with the Qdrant client.

The diagram below shows the high-level data flow for an ingestion or query operation.

Sources: cmd/app/main.go:17-31, internal/search/service.go:49-56, internal/search/service.go:70-76

While the architecture allows for multiple providers, the search service currently contains a hardcoded call to embeddings.FromOllama.

Sources: internal/search/service.go:51, internal/search/service.go:72

Embedding Provider Implementations

The codebase includes two distinct implementations for generating embeddings: Ollama and OpenAI.

Ollama Provider

This is the currently active provider used by the search service. It sends a request to a local or remote Ollama instance.

Sources: internal/embeddings/ollama.go

Key Function: FromOllama(text string) ([]float32, error)

Logic:

1. Reads OLLAMA_URL and EMBEDDING_MODEL from environment variables.
2. Constructs a JSON request body with the model and prompt text.
3. Sends a POST request to the {OLLAMA_URL}/api/embeddings endpoint.
4. Parses the JSON response.
5. Converts the resulting []float64 embedding to []float32 for use with Qdrant.

The sequence diagram below details the interaction.

Sources: internal/embeddings/ollama.go:19-63

OpenAI Provider

An implementation for the OpenAI embeddings API exists but is not currently used by the search service. To use it, internal/search/service.go would need to be modified to call embeddings.FromOpenAI.

Sources: internal/embeddings/openai.go

Key Function: FromOpenAI(text string) ([]float32, error)

Logic:

1. Reads OPENAI_API_KEY and EMBEDDING_MODEL from environment variables.
2. Constructs a JSON request body with the model and input text.
3. Sends a POST request to https://api.openai.com/v1/embeddings.
4. Sets the Authorization header with the API key.
5. Parses the JSON response.
6. Converts the []float64 embedding to []float32.

The sequence diagram for this provider is as follows.

Sources: internal/embeddings/openai.go:23-64

Summary

MauQNotes supports switching embedding providers through configuration, with implementations for both Ollama and OpenAI available. The choice of model, set via the EMBEDDING_MODEL environment variable, dictates the vector dimension used for the Qdrant collection. While the architecture is flexible, the current implementation hardcodes the use of the embeddings.FromOllama function within the search service. To enable a different provider like OpenAI, a code modification in internal/search/service.go would be necessary.