Skip to main content
unch supports two embedding providers:
  • llama.cpp for local GGUF models
  • openrouter for remote embedding APIs
The provider and model used for index and search must match.

​
Providers

​
llama.cpp

  • default provider
  • works with built-in model ids such as embeddinggemma and qwen3
  • also accepts a direct .gguf path
  • may download a default embedding model and local yzma runtime on first run

​
openrouter

  • remote provider
  • uses an OpenRouter embedding model id such as openai/text-embedding-3-small
  • token can be stored with unch auth openrouter --token ...

​
Known model ids

​
embeddinggemma

  • default model id
  • downloaded automatically when --model is omitted
  • mean-pooling profile

​
qwen3

  • built-in known model id
  • auto-download profile
  • last-token pooling profile

​
Supported ways to select a model

unch index --model embeddinggemma
unch index --model qwen3
unch search --model qwen3 "create a new router"
unch index --model /path/to/model.gguf
unch auth openrouter --token sk-or-...
unch index --provider openrouter --model openai/text-embedding-3-small
unch search --provider openrouter --model openai/text-embedding-3-small "create a new router"

​
Provider-scoped snapshots

Each provider and model pair keeps its own active snapshot in the local index state. That means:
  • rebuilding qwen3 does not replace the active embeddinggemma snapshot
  • rebuilding openrouter/openai/text-embedding-3-small does not replace the active llama.cpp/embeddinggemma snapshot
  • switching providers or models does require a matching reindex before search

​
Default cache location

If SEMSEARCH_HOME is set, models live under: 
$SEMSEARCH_HOME/models
Otherwise unch uses the system user cache directory for the current platform.

​
Token storage for OpenRouter

unch auth openrouter writes to: 
~/.config/unch/tokens.json
At runtime, token lookup order is:
  1. OPENROUTER_API_KEY
  2. ~/.config/unch/tokens.json
  3. .semsearch/tokens.json

​
Practical rule

Always use the same provider and model family for both unch index and unch search. If they differ, ranking quality will be wrong.