Production Deployment
Relevant source files
The following files were used as context for generating this wiki page:
MauQNotes is a semantic search application designed to ingest and query personal notes. A successful deployment requires configuring the main Go application and setting up its two primary external dependencies: a vector database (Qdrant) and an embedding model service (Ollama or OpenAI). The application relies entirely on environment variables for configuration, making it suitable for containerized deployments.
The core functionalities are data ingestion, where notes are converted into vector embeddings and stored, and querying, where a search query is converted into a vector to find semantically similar notes from the database. The system is designed to be modular, allowing for different embedding models to be used based on configuration.
Architecture Overview
The application consists of three main components: the MauQNotes Go application, an embedding service, and the Qdrant vector database. The Go application orchestrates the process by fetching embeddings for text and then using those embeddings to interact with Qdrant for storage and retrieval.
The following diagram illustrates the high-level architecture of the system.
This diagram shows the Go application communicating with an embedding service (either Ollama or OpenAI) to generate vectors, and then using those vectors to perform operations on the Qdrant vector database.
Sources: cmd/app/main.go, internal/search/service.go, internal/qdrant/client.go, internal/embeddings/ollama.go, internal/embeddings/openai.go
Configuration
Configuration is managed exclusively through environment variables, which are loaded at runtime using the godotenv package. These variables define connection details for external services and select the embedding model.
Sources: internal/qdrant/client.go:70-76, internal/embeddings/ollama.go:26-36, internal/embeddings/openai.go:26-31, internal/search/service.go:12-15
Environment Variables
| Variable | Description | Default Value | Required | Source File |
|---|---|---|---|---|
QDRANT_URL | The base URL for the Qdrant instance. | (none) | Yes | internal/qdrant/client.go:72 |
QDRANT_API_KEY | The API key for authenticating with Qdrant. | (none) | No | internal/qdrant/client.go:73 |
QDRANT_COLLECTION | The name of the collection in Qdrant to use. | (none) | Yes | internal/qdrant/client.go:74 |
EMBEDDING_MODEL | The name of the embedding model to use. | nomic-embed-text | No | internal/search/service.go:14 |
OLLAMA_URL | The URL for the Ollama API service. | http://localhost:11434 | No | internal/embeddings/ollama.go:28 |
OPENAI_API_KEY | The API key for the OpenAI embeddings API. | (none) | If using OpenAI | internal/embeddings/openai.go:27 |
Dependency Setup
Vector Database: Qdrant
The application requires a running Qdrant instance for storing and searching vector embeddings. The connection is configured via QDRANT_URL, QDRANT_API_KEY, and QDRANT_COLLECTION.
Upon initialization, the application will attempt to create the specified collection if it does not already exist. The vector size for the collection is determined dynamically based on the selected EMBEDDING_MODEL.
Sources: internal/qdrant/client.go:101-119, internal/search/service.go:27-30
Embedding Service
The application can use one of two services to generate embeddings: Ollama (for local models) or OpenAI (as a managed service).
Ollama Setup
To use a local model with Ollama, the service must be installed and running. The application defaults to connecting to http://localhost:11434.
- Install Ollama: Download from
https://ollama.ai/download. - Pull an Embedding Model: Run
ollama pull <model_name>in the terminal.
Sources: setup-ollama.md
The application supports several models, each with a different vector dimension. This dimension is crucial for setting up the Qdrant collection correctly.
| Model Name | Vector Dimension | Notes |
|---|---|---|
nomic-embed-text | 768 | Recommended default |
all-minilm | 384 | Smaller, faster |
mxbai-embed-large | 512 | More accurate (Note: setup-ollama.md states 1024, but service.go uses 512) |
Sources: internal/search/service.go:20-25, setup-ollama.md
The Init function in the search service maps the model name to its dimension size.
// internal/search/service.go:17-26
var dim int
switch model {
case "nomic-embed-text":
dim = 768
case "all-minilm":
dim = 384
case "mxbai-embed-large":
dim = 512
default:
dim = 768 // Default
}
OpenAI Setup
As an alternative to Ollama, the application can use OpenAI's API to generate embeddings. This requires setting the OPENAI_API_KEY environment variable and ensuring the EMBEDDING_MODEL variable is set to a model compatible with OpenAI (e.g., text-embedding-ada-002). The function FromOpenAI is available but not currently called by the main search service, which defaults to FromOllama.
Sources: internal/embeddings/openai.go:26-31
Core Processes
The application's lifecycle, demonstrated in main.go, revolves around two primary processes: Ingestion and Querying.
Sources: cmd/app/main.go:16-32
Data Ingestion Flow
The ingestion process takes a list of strings (notes), generates an embedding for each, and upserts them into the Qdrant database.
The following sequence diagram shows the ingestion flow.
Query Flow
The query process takes a string query, generates an embedding for it, and uses this embedding to perform a semantic search against the Qdrant database. The service also includes a naive reranking step that slightly boosts the score of results containing the query keywords.
The following sequence diagram shows the query flow.