Setting up Ollama
Relevant source files
The following files were used as context for generating this wiki page:Ollama is used within the MauQNotes project to generate text embeddings locally. These embeddings are vector representations of text that enable semantic search capabilities. By running a local Ollama instance, the application can convert notes and queries into vectors without relying on external cloud services like OpenAI. This setup is fundamental for the core Ingest and Query functionalities of the application.
The system is designed to be modular, allowing for different embedding providers. While an OpenAI client also exists, this guide focuses on the setup and integration of Ollama for generating embeddings.
Sources: setup-ollama.md, internal/embeddings/ollama.go, internal/embeddings/openai.go
Initial Setup and Installation
To use Ollama with MauQNotes, you must first install the Ollama service and download a suitable embedding model.
- 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 recommended model:
ollama pull nomic-embed-text - Verify Installation: Ensure the Ollama service is running and accessible, by default at
http://localhost:11434.
Sources: setup-ollama.md:3-10, setup-ollama.md:19-20
Configuration
The application is configured to use Ollama via environment variables, typically defined in a .env file.
| 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 match a model pulled in Ollama. | nomic-embed-text |
Sources: internal/embeddings/ollama.go:23-31
Supported Embedding Models
The choice of embedding model affects the dimension of the vectors, which is critical for setting up the Qdrant vector collection. The application automatically detects the dimension based on the model name.
| Model Name | Vector Dimension | Notes |
|---|---|---|
nomic-embed-text | 768 | Recommended default model. |
all-minilm | 384 | Smaller and faster. |
mxbai-embed-large | 1024 (in docs), 512 (in code) | Larger and potentially more accurate. Note: setup-ollama.md states 1024 dimensions, but internal/search/service.go maps it to 512. |
Sources: setup-ollama.md:23-27, internal/search/service.go:19-32
Embedding Generation Flow
The FromOllama function in the embeddings package is responsible for communicating with the Ollama API to generate embeddings for a given text.
Sources: internal/embeddings/ollama.go:20-75
API Interaction
The function constructs an HTTP POST request to the /api/embeddings endpoint of the Ollama server. The request body contains the model name and the text to be embedded. The server responds with the generated embedding vector.
The diagram below illustrates the sequence of operations when FromOllama is called.
This diagram shows the simple request-response flow between the application and the local Ollama server for generating an embedding.
Sources: internal/embeddings/ollama.go:42-55
Data Structures
The interaction with the Ollama API uses the following Go structures for serialization and deserialization of JSON data.
This diagram shows the request and response data structures for the Ollama /api/embeddings endpoint.
Sources: internal/embeddings/ollama.go:15-20
Integration with Search Service
Ollama is a core component of both the data ingestion and querying processes within the search service.
Data Ingestion
The IngestNotes function processes a list of notes, generates an embedding for each using FromOllama, and then upserts the resulting points (vector + payload) into the Qdrant database.
The following diagram shows the data flow for ingesting notes.
This flowchart illustrates the process of converting text notes into vectors via Ollama and storing them in Qdrant.
Sources: internal/search/service.go:35-58, cmd/app/main.go:15-17
Querying
The Query function takes a search query string, generates an embedding for it using FromOllama, and then uses this vector to perform a similarity search in the Qdrant database.
The following diagram shows the data flow for searching notes.
This flowchart illustrates how a text query is converted into a vector to find semantically similar notes from Qdrant.
Sources: internal/search/service.go:60-79, cmd/app/main.go:21-23, internal/qdrant/client.go:155-186
Summary
Setting up Ollama provides MauQNotes with a powerful, local, and private engine for generating the text embeddings required for its semantic search feature. The process involves installing Ollama, pulling a pre-trained model, and configuring the application via environment variables. The embeddings.FromOllama function seamlessly integrates with the Ollama API, which is then leveraged by the search service to both ingest notes into and query the Qdrant vector database. This architecture creates a self-contained and efficient semantic search system.