Skip to content

Local‐Model‐Setup

Jump to bottom
ic005k edited this page Jul 29, 2026 · 2 revisions

Local Embedding Model Setup Guide

Overview

Knot integrates local vector search powered by llama.cpp. You can run semantic note linking and offline semantic search without online API services. Only GGUF embedding models are supported.

Model Storage Path

All local GGUF models are stored in the auto-generated hidden directory:

  • Windows: %USERPROFILE%\.Knot\model\
  • macOS / Linux: ~/.Knot/model/
  • Android: /.Knot/model/ (Root storage folder of your Android device)

Critical Note: Hidden Folder

The .Knot directory is hidden by default on every platform. You need to enable hidden file visibility to access it manually:

  • Windows: Tick "Hidden items" in File Explorer View toolbar
  • macOS: Press Shift + Command + . in Finder to toggle hidden files
  • Linux: Toggle "Show hidden files" in file manager, shortcut Ctrl + H
  • Android: Turn on "Show hidden files" in your file manager app, otherwise you cannot locate the .Knot folder.

The folder will be created automatically on first launch if missing.

Supported Format

Only embedding models with the .gguf extension are compatible. The default built-in model: multilingual-e5-small-fp32.gguf

Step-by-Step Configuration

Step 1: Open AI Preference Panel

  1. Launch Knot
  2. Open Settings → Switch to the AI tab (This guide covers local model setup only; cloud API configuration is documented separately.)

Step 2: Download or Place Your Embedding Model

Two ways to get GGUF model files:

  1. One-click download: Click the blue Download button under Local Model List to fetch the default multilingual-e5-small-fp32 model automatically.
  2. Manual installation: Download other GGUF embedding models manually, drop the .gguf file into the platform-specific /.Knot/model/ folder, then restart Knot to detect the file.

Android Manual Install Reminder: Enable hidden file visibility first in your file manager to find the .Knot directory.

Step 3: Activate the Local Model

  1. All valid GGUF files inside the model folder will appear in the Local Model List.
  2. Click the target model name (e.g. multilingual-e5-small-fp32.gguf). A blue highlighted background indicates the model is selected and active.

Step 4: Verify Model Status

Check the status text below the model list after selection:

  1. Model Status: Ok — File integrity check passed, ready for embedding inference.
  2. The string below status is the file SHA256 fingerprint for integrity validation. Corrupted files will show abnormal status.

Additional Notes

  1. Local embedding function works independently of cloud LLM APIs. You do NOT need to fill in API endpoint, API Key or cloud model ID to use local vector search.
  2. Switching models: Drop new GGUF files into the model folder, restart Knot, then click the new model in the list to switch.
  3. Troubleshooting
    • Non-Ok status: The model file is damaged. Delete the file and re-download.
    • Model not shown in list:
      1. Confirm file extension is .gguf
      2. Enable hidden file display to access the .Knot directory
      3. No special non-ASCII characters in the file path
  4. Use case: This embedding model handles semantic similarity calculation, AI cross-note linking and offline local semantic search, no online LLM required.

UI Field Reference (Matching the Preference Screenshot)

UI Section Function
Cloud AI Config (Endpoint / API Key / Model ID) Reserved for online LLM APIs like SiliconFlow. Not required for local models.
Local Model List (~/.Knot\model) Displays all detected GGUF embedding models; click to activate.
Download Button Auto-download default multilingual-e5-small-fp32.gguf embedding model.
Model Status Ok = Valid file; abnormal = corrupted / unsupported format.
Bottom Hash String SHA256 fingerprint of the currently selected model file.

Clone this wiki locally