Installation
Relevant source files
The following files were used as context for generating this wiki page:This document outlines the necessary steps to install, configure, and run the MauQNotes application. MauQNotes is a semantic search engine for personal notes, leveraging an external embedding model and a vector database to perform searches. The installation process primarily involves setting up these external dependencies and configuring the application to connect to them.
The core components are the Go application itself, an embedding service (like Ollama or OpenAI), and a Qdrant vector database. The application converts text notes into numerical vectors using the embedding service and stores them in Qdrant. When a query is made, it is also converted into a vector, which is then used to find the most similar notes in the database.
1. System Architecture
The application relies on two main external services: an embedding model provider and a vector database.
The following diagram illustrates the high-level architecture and interaction between components.
This diagram shows that the MauQNotes application communicates with an embedding service (either a local Ollama instance or the remote OpenAI API) to generate vectors and with a Qdrant database to store and retrieve them.
Sources: internal/search/service.go:42-45, internal/search/service.go:61-64, internal/embeddings/ollama.go, internal/embeddings/openai.go, internal/qdrant/client.go
2. Dependencies Setup
2.1. Ollama (Recommended)
Ollama is used for running embedding models locally. The recommended model is nomic-embed-text.
- Install Ollama: Download and install Ollama from the official website: https://ollama.ai/download.
- Pull Embedding Model: After installation, run the following command in your terminal to download the default model:
ollama pull nomic-embed-text - Verify Ollama: Ensure the Ollama service is running. By default, it is accessible at
http://localhost:11434. The application will connect to this URL unlessOLLAMA_URLis set in the environment.
Sources: setup-ollama.md:3-10, internal/embeddings/ollama.go:21-24
Alternative Ollama Models
You can use other models by pulling them and updating the EMBEDDING_MODEL environment variable. The application code specifies the vector dimensions for each supported model.
| Model Name | Command to Pull | Vector Dimension | Notes |
|---|---|---|---|
nomic-embed-text | ollama pull nomic-embed-text | 768 | Default, recommended |
all-minilm | ollama pull all-minilm | 384 | Smaller and faster |
mxbai-embed-large | ollama pull mxbai-embed-large | 512 | Larger and more accurate |
Sources: setup-ollama.md:13-19, internal/search/service.go:19-28
2.2. Qdrant
Qdrant is the vector database used to store and search the note embeddings. You must have a running Qdrant instance accessible to the application.
The application requires the Qdrant URL, an optional API key, and a collection name to be configured via environment variables. The application will automatically attempt to create the specified collection if it does not exist, using the correct vector dimension based on the selected embedding model.
Sources: internal/qdrant/client.go:70-76, internal/qdrant/client.go:98-114, internal/search/service.go:38-41
3. Application Configuration
The application is configured using environment variables, typically stored in a .env file in the project root. The application loads this file on startup.
Sources: internal/search/service.go:11, internal/qdrant/client.go:69, internal/embeddings/ollama.go:18, internal/embeddings/openai.go:23
Environment Variables
| Variable | Description | Default Value | Source File(s) |
|---|---|---|---|
EMBEDDING_MODEL | The name of the embedding model to use. | nomic-embed-text | internal/search/service.go:12-15 internal/embeddings/ollama.go:26-28 |
OLLAMA_URL | The URL for the Ollama API service. | http://localhost:11434 | internal/embeddings/ollama.go:21-24 |
QDRANT_URL | The base URL for the Qdrant database instance. Required. | (none) | internal/qdrant/client.go:71 |
QDRANT_API_KEY | The API key for authenticating with Qdrant. Optional. | (none) | internal/qdrant/client.go:72 |
QDRANT_COLLECTION | The name of the collection to use within Qdrant. Required. | (none) | internal/qdrant/client.go:73 |
OPENAI_API_KEY | The API key for using OpenAI's embedding service. Required for OpenAI. | (none) | internal/embeddings/openai.go:24 |
OpenAI as an Alternative
If you prefer to use OpenAI for embeddings instead of a local Ollama instance, you must provide the OPENAI_API_KEY and set EMBEDDING_MODEL to a valid OpenAI model name (e.g., text-embedding-ada-002). The application logic does not explicitly switch between FromOllama and FromOpenAI; the code in internal/search/service.go currently only calls FromOllama. To use OpenAI, the source code would need to be modified to call embeddings.FromOpenAI.
Sources: internal/embeddings/openai.go:23-28, internal/search/service.go:43, internal/search/service.go:62
4. Running the Application
Once the dependencies are running and the .env file is configured, you can run the application.
The provided documentation suggests using a Makefile command:
make run
Sources: setup-ollama.md:25-27
When executed, the main function will:
- Define a list of sample notes.
- Call
search.IngestNotesto process and store these notes in Qdrant. - Call
search.Querywith a sample query. - Print the query and the search results to the console.
Sources: cmd/app/main.go:10-31
Ingestion and Query Flow
The following sequence diagram details the process of ingesting notes when the application starts.
This diagram shows the IngestNotes function orchestrating calls to the embedding service to get vectors and to the Qdrant client to create the collection and upsert the vectorized data points.
Sources: cmd/app/main.go:16-18, internal/search/service.go:35-58, internal/embeddings/ollama.go:17-57, internal/qdrant/client.go:98-132