Local Deployment

Relevant source files

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

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

The local deployment of MauQNotes enables a personal semantic search engine for notes. It operates by using a locally running Ollama instance to generate text embeddings and a Qdrant vector database to store and search these embeddings. The application provides functionalities to ingest a list of notes and then query them based on semantic similarity.

The core architecture is composed of a main application that orchestrates the process, a search service that handles the business logic, an embedding service that communicates with Ollama, and a client that interacts with the Qdrant database. The entire process, from embedding generation to search, is designed to run on a local machine.

Architecture Overview

The local deployment consists of four main components that interact to provide the semantic search functionality. The main application acts as the entry point, initiating both the ingestion of notes and the search queries. It utilizes the search service to coordinate these operations. The search service, in turn, relies on the embeddings service to generate vector representations of text via a local Ollama instance and the qdrant client to manage data in the vector database.

This diagram illustrates the high-level interaction between the components.

Setup and Configuration

1. Ollama Setup

For local embedding generation, an Ollama instance must be running.

1. Install Ollama: Download and install from https://ollama.ai/download.
2. Pull an Embedding Model: The recommended model is nomic-embed-text.

   ollama pull nomic-embed-text
   

3. Verify: Ensure Ollama is running and accessible, by default at http://localhost:11434.

Alternative models can also be used, which may affect speed and accuracy.

Sources: setup-ollama.md:3-19, internal/embeddings/ollama.go:21-24

2. Environment Variables

The application is configured using a .env file. The godotenv package is used to load these variables.

Variable	Description	Default Value	Source File
QDRANT_URL	The base URL for the Qdrant instance.	(none)	internal/qdrant/client.go:70
QDRANT_API_KEY	The API key for authenticating with Qdrant.	(none)	internal/qdrant/client.go:71
QDRANT_COLLECTION	The name of the collection in Qdrant to use.	(none)	internal/qdrant/client.go:72
OLLAMA_URL	The URL of the running Ollama instance.	http://localhost:11434	internal/embeddings/ollama.go:21-24
EMBEDDING_MODEL	The name of the embedding model to use with Ollama.	nomic-embed-text	internal/search/service.go:13-16, internal/embeddings/ollama.go:26-29
OPENAI_API_KEY	The API key for OpenAI (used only if FromOpenAI is called).	(none)	internal/embeddings/openai.go:26-30

Sources: internal/qdrant/client.go:68-74, internal/embeddings/ollama.go:19-29, internal/search/service.go:12-16, internal/embeddings/openai.go:26-30

3. Embedding Models

The application supports several embedding models, each with a different vector dimension size. The model is selected via the EMBEDDING_MODEL environment variable. The search.Init() function determines the dimension size based on the chosen model, which is crucial for creating the Qdrant collection.

Model Name	Vector Dimension	Notes
nomic-embed-text	768	Recommended, default model.
all-minilm	384	Smaller and faster.
mxbai-embed-large	512	Larger and more accurate.

Note: setup-ollama.md lists the dimension for mxbai-embed-large as 1024, while search/service.go implements it as 512. The code in search/service.go will be the effective configuration.

Sources: search/service.go:18-32, setup-ollama.md:23-25

Core Processes

Data Ingestion

The ingestion process converts text notes into vector embeddings and stores them in the Qdrant database. This is initiated by the search.IngestNotes function.

The sequence of operations is as follows:

1. The main function calls search.IngestNotes with a slice of strings.
2. IngestNotes initializes a new Qdrant client.
3. It calls Init() to get the correct vector dimension for the configured model.
4. It ensures a Qdrant collection exists with the correct dimension and distance metric (Cosine) by calling client.CreateCollectionIfNotExists.
5. For each note, it calls embeddings.FromOllama to generate a vector embedding.
6. A qdrant.Point is created for each note, containing an ID, the vector, and a payload with the original text.
7. Finally, all points are sent to Qdrant in a single batch operation via client.Upsert.

This diagram shows the data ingestion flow.

Search Query

The search process takes a text query, converts it into a vector, and uses it to find the most semantically similar notes from the Qdrant database. This is handled by the search.Query function.

The sequence of operations is as follows:

1. The main function calls search.Query with a topK limit and the query string.
2. Query initializes a new Qdrant client.
3. It calls embeddings.FromOllama to convert the query string into a vector embedding.
4. It calls client.Search with the query vector and topK limit to retrieve the most similar points from Qdrant.
5. A naive re-ranking is applied to the results, slightly boosting the score of results where the payload text contains the query string.
6. The final list of results is returned to the main function for display.

This diagram shows the search query flow.

Conclusion

The local deployment of MauQNotes provides a powerful, self-contained semantic search system. By leveraging local instances of Ollama and Qdrant, it allows users to perform complex similarity searches on their personal notes without relying on external cloud services. The setup is straightforward, requiring the installation of Ollama, pulling a suitable embedding model, and configuring a few environment variables to connect the application components. The core logic, encapsulated in the search service, efficiently handles both the one-time ingestion of notes and subsequent real-time queries.