Prerequisites

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

To run the MauQNotes application, several external services must be configured and running. The application relies on an embedding model provider to generate vector representations of text and a vector database to store and search these embeddings. The primary components are an embedding service (like Ollama) and the Qdrant vector database.

The core functionality demonstrated in cmd/app/main.go involves two main operations: ingesting notes into the vector database and querying the database for semantically similar notes. Both processes depend on the correct setup of the prerequisites detailed below.

Sources: cmd/app/main.go:15-29

System Architecture Overview

The application connects to two main external services: an embedding model provider and a Qdrant vector database. The choice of embedding provider and its configuration directly impacts the setup of the Qdrant collection.

This diagram illustrates the high-level dependencies of the MauQNotes application.

Environment Variables

The application is configured via environment variables, typically loaded from a .env file. These variables are essential for connecting to the required external services.

Sources: internal/qdrant/client.go:67-73, internal/embeddings/ollama.go:23-32, internal/embeddings/openai.go:27-31, internal/search/service.go:12-16

Variable	Description	Default Value	Source File(s)
QDRANT_URL	The base URL for the Qdrant database instance.	(none)	internal/qdrant/client.go:69
QDRANT_API_KEY	The API key for authenticating with Qdrant. Optional.	(none)	internal/qdrant/client.go:70
QDRANT_COLLECTION	The name of the collection to use within Qdrant.	(none)	internal/qdrant/client.go:71
EMBEDDING_MODEL	The name of the embedding model to use.	nomic-embed-text	internal/search/service.go:14-16
OLLAMA_URL	The URL for the Ollama service API.	http://localhost:11434	internal/embeddings/ollama.go:25-28
OPENAI_API_KEY	The API key for the OpenAI embeddings API.	(none)	internal/embeddings/openai.go:28

External Services Setup

Vector Database: Qdrant

The application requires a running instance of the Qdrant vector database. The connection details are specified using the QDRANT_URL, QDRANT_API_KEY, and QDRANT_COLLECTION environment variables.

The qdrant.Client is responsible for all interactions with the Qdrant server. It validates that QDRANT_URL and QDRANT_COLLECTION are set before performing any operations.

Upon initialization, the application will attempt to create the specified collection if it does not already exist. The dimension of the vector space for the collection is determined dynamically based on the selected EMBEDDING_MODEL.

Sources: internal/qdrant/client.go:75-86, 94-114, internal/search/service.go:39-42

Embedding Model Provider

The application generates vector embeddings from text using an external model. While the code includes clients for both Ollama and OpenAI, the main application flow is currently hardcoded to use Ollama.

Sources: internal/search/service.go:45, internal/search/service.go:62

Ollama (Primary)

Ollama is the default service for generating embeddings.

1. Installation:
Install Ollama from the official website: https://ollama.ai/download

2. Pulling Models:
After installation, you must pull an embedding model. The recommended model is nomic-embed-text.

ollama pull nomic-embed-text

Alternative models can also be used:

# Smaller model
ollama pull all-minilm

# Larger, more accurate model
ollama pull mxbai-embed-large

3. Configuration:

• Ensure the Ollama service is running. The application will connect to it at the URL specified by OLLAMA_URL (defaults to http://localhost:11434).
• Set the EMBEDDING_MODEL environment variable to the name of the pulled model (e.g., nomic-embed-text).

Sources: setup-ollama.md, internal/embeddings/ollama.go:23-32

The following sequence diagram shows how the application generates an embedding using the Ollama service.

OpenAI (Alternative)

The codebase includes a client for generating embeddings via the OpenAI API, although it is not currently used in the main search service. To use it, the OPENAI_API_KEY and EMBEDDING_MODEL (e.g., text-embedding-ada-002) environment variables must be set.

Sources: internal/embeddings/openai.go:27-31

Model and Dimension Configuration

The dimension of the vectors stored in Qdrant is critically dependent on the embedding model chosen. The search.Init() function maps the model name from the EMBEDDING_MODEL environment variable to a specific vector dimension size.

This logic is centralized in internal/search/service.go.

This flowchart shows how the vector dimension is determined.

The supported models and their corresponding dimensions are:

Model Name	Vector Dimension	Source
nomic-embed-text	768	internal/search/service.go:22-23
all-minilm	384	internal/search/service.go:24-25
mxbai-embed-large	512	internal/search/service.go:26-27

This dimension value is then used to create the Qdrant collection with the correct vector size.

Sources: internal/search/service.go:39-42, internal/qdrant/client.go:94-98