Ollama Integration

Relevant source files

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

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

Ollama is integrated into MauQNotes to provide local, open-source text embedding generation. This capability is central to the application's semantic search feature, allowing it to convert text notes and search queries into numerical vectors. These vectors are then stored and queried in a Qdrant vector database, enabling searches based on semantic meaning rather than just keyword matching.

The integration is primarily handled within the internal/embeddings and internal/search packages. The embeddings package communicates directly with a running Ollama instance, while the search package orchestrates the process of generating embeddings for notes (ingestion) and queries (searching).

Sources: internal/embeddings/ollama.go, internal/search/service.go, cmd/app/main.go:18-23

Setup and Configuration

To use the Ollama integration, an Ollama instance must be running and accessible to the application. The recommended setup involves pulling a specific embedding model.

Sources: setup-ollama.md

Initial Setup Steps

1. Download and install Ollama from https://ollama.ai/download.
2. Pull the recommended embedding model via the terminal:

   ollama pull nomic-embed-text
   

3. Ensure the Ollama service is running, typically at http://localhost:11434.
4. Configure the necessary environment variables in a .env file.

Sources: setup-ollama.md:4-13, internal/embeddings/ollama.go:27-31

Environment Variables

The integration is configured through environment variables, which are loaded using godotenv.

Variable	Description	Default Value
OLLAMA_URL	The base URL for the running Ollama instance.	http://localhost:11434
EMBEDDING_MODEL	The name of the embedding model to use. Must be pulled in Ollama.	nomic-embed-text

Sources: internal/embeddings/ollama.go:25-35

Supported Embedding Models

The application is aware of several Ollama models, each with a different vector dimension size. The choice of model affects accuracy, speed, and the configuration of the Qdrant collection.

Model Name	Vector Dimension	Notes
nomic-embed-text	768	Recommended, default
all-minilm	384	Smaller and faster
mxbai-embed-large	1024 (code shows 512)	Larger and more accurate

Note: internal/search/service.go lists mxbai-embed-large with a dimension of 512, while setup-ollama.md lists it as 1024. The application logic will use 512.

Sources: setup-ollama.md:10-22, internal/search/service.go:20-29

Embedding Generation

The core logic for generating embeddings resides in the FromOllama function. This function takes a string of text and returns a vector of float32 values representing that text.

Sources: internal/embeddings/ollama.go:22-77

API Interaction

The FromOllama function constructs an HTTP POST request to the /api/embeddings endpoint of the Ollama server.

1. Request Payload: A JSON object containing the model name and the text prompt.

   // internal/embeddings/ollama.go:12-15
   type ollamaRequest struct {
       Model  string `json:"model"`
       Prompt string `json:"prompt"`
   }
   

2. HTTP Request: The function sends the request to {OLLAMA_URL}/api/embeddings.
3. Response Handling: The function decodes the JSON response. If the response contains an error message, it returns an error. Otherwise, it extracts the embedding vector.

   // internal/embeddings/ollama.go:17-20
   type ollamaResponse struct {
       Embedding []float64 `json:"embedding"`
       Error     string    `json:"error,omitempty"`
   }
   

4. Type Conversion: The returned embedding from Ollama is a []float64, which is converted to []float32 to be compatible with the Qdrant client.

Sources: internal/embeddings/ollama.go:22-77, internal/qdrant/client.go:30

Sequence Diagram: FromOllama

This diagram illustrates the sequence of operations when generating an embedding for a given text.

System Integration

Ollama embeddings are used in two primary workflows within the search service: ingesting new notes and querying existing ones.

Sources: internal/search/service.go

Note Ingestion Flow

The IngestNotes function processes a list of notes, generates an embedding for each, and upserts them into the Qdrant database.

This diagram shows the data flow for ingesting notes.

Search Query Flow

The Query function takes a text query, generates an embedding for it, and uses that vector to perform a similarity search in Qdrant.

This diagram shows the data flow for searching with a query.

Alternative Embedding Provider

The system is structured to potentially support other embedding providers. The internal/embeddings package also contains openai.go, which defines a FromOpenAI function with a similar signature to FromOllama. This suggests a modular design where the embedding source could be swapped.

Sources: internal/embeddings/openai.go