Embedding providers - Moorcheh Documentation

Overview

Text namespaces need an embedding provider to turn documents and search queries into vectors. Moorcheh On-Prem supports three providers, configured once and stored in ~/.moorcheh/config.json.

Provider	API key	Ollama / Docker	Best for
Ollama	Not required	Optional host install or bundled `moorcheh-ollama`	Fully local, no cloud
OpenAI	Required	Server container only	Hosted embeddings, familiar models
Cohere	Required	Server container only	Multilingual and v4 models

Vector namespaces (you upload precomputed vectors) do not use these providers for ingest or vector search. You only need a provider if you use text upload or text search.

Configure once

moorcheh configure

Or on first run:

moorcheh up

If no config exists, moorcheh up runs the same interactive wizard before starting Docker. Saved settings:

File	Contents
`~/.moorcheh/config.json`	`provider`, `model`, `api_key` (cloud only), `base_url`
`~/.moorcheh/data/`	Namespaces and items (unchanged)

Re-run setup:

moorcheh configure --force

See moorcheh configure and moorcheh up.

After you change settings

Action	When
`moorcheh down` then `moorcheh up`	Whenever you change embedding or LLM in `config.json` (including after `moorcheh configure --force`) while the stack was already running. Configure alone does not restart Docker.
Re-upload text documents	When you change embedding provider or model and you already have text namespaces under `~/.moorcheh/data`. Old vectors no longer match the new model.

Existing data: If ~/.moorcheh/data already contains namespaces or uploaded items, switching embedding provider or model can make text search and RAG answers unreliable for those namespaces until you re-upload with the new embeddings. moorcheh configure warns and asks for confirmation when it detects stored data. Vector namespaces (you supplied vectors) are unaffected by embedding config, but dimension must still match what you uploaded.

Configuration file

Path (all platforms):

~/.moorcheh/config.json

On Windows this resolves to C:\Users\<you>\.moorcheh\config.json. moorcheh configure and moorcheh up write this file. Every moorcheh up reads it to set EMBEDDING_* and LLM_* environment variables on the server container. Your namespaces and items stay in ~/.moorcheh/data/ — that folder is separate from config. Changing config does not migrate or re-embed existing text data automatically.

Schema

Settings live under the embedding object:

{
  "embedding": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "api_key": "sk-...",
    "base_url": "https://api.openai.com/v1"
  }
}

Field	Required	Description
`provider`	Yes	`ollama`, `openai`, or `cohere`
`model`	Yes	Model id from the tables below
`api_key`	For `openai` / `cohere`	Omitted for `ollama`
`base_url`	No (defaults applied)	Override API endpoint (proxy, custom host)

Ollama example (no api_key):

{
  "embedding": {
    "provider": "ollama",
    "model": "nomic-embed-text",
    "base_url": "http://host.docker.internal:11434"
  }
}

base_url in the file is a template default; moorcheh up still passes the runtime URL (host.docker.internal vs http://ollama:11434) into the container based on host vs bundled Ollama.

Editing and security

Prefer moorcheh configure --force to change provider or model safely (with a warning if data already exists).
You may edit config.json by hand to tweak base_url or rotate an API key, then run moorcheh down and moorcheh up so the running container picks up changes.
On Linux and macOS, the file is created with mode 600 (owner read/write only).
Do not commit config.json to git or share it in tickets — it can contain provider API keys.
Back up ~/.moorcheh/data for your indexes; treat config.json as secrets if it includes api_key.

If provider is empty or invalid, moorcheh up fails. Run moorcheh configure --force to fix a broken file.

Supported models and dimensions

Use the same model for all text namespaces on one server. When creating a vector namespace, set vector_dimension to match your embedding model output (text namespaces infer dimension from the first embed).

Ollama (local)

Model ID	Dimensions	Notes
`nomic-embed-text`	768	Smaller, faster
`mxbai-embed-large`	1024	Recommended default
`all-minilm`	384	Smallest footprint

Moorcheh pulls the selected model automatically on moorcheh up when Ollama is reachable (host or bundled). You do not need a separate ollama pull unless you skipped pull with --skip-ollama-model-pull.

OpenAI

Model ID	Dimensions	Notes
`text-embedding-3-small`	1536 (default)	Recommended
`text-embedding-3-large`	3072 (default)	Higher quality
`text-embedding-ada-002`	1536	Legacy

API key is stored in config.json (file mode 600 on Unix). The server calls OpenAI from inside the container; outbound HTTPS is required.

Cohere

Model ID	Dimensions	Notes
`embed-v4.0`	1536 (fixed in Moorcheh)	Recommended; multimodal-capable API
`embed-english-v3.0`	1024	English-optimized
`embed-multilingual-v3.0`	1024	100+ languages

API key required. Base URL default: https://api.cohere.com/v2.

Do not mix embedding models across text namespaces on the same instance. Existing namespaces were built with one vector size; changing the model without re-uploading will break search quality and dimension checks.

What `moorcheh up` does by provider

Provider	Containers started	Embedding model pull
openai / cohere	`moorcheh-onprem-server`	N/A (cloud)
ollama (host running)	Server only	Auto-pull if missing
ollama (host down)	Server + `moorcheh-ollama`	Auto-pull after Ollama is ready

Override flags: --embedding-provider, --embedding-model, --embedding-api-key, --bundled-ollama, --use-host-ollama. See moorcheh up.

Health check

GET /health and moorcheh status return:

{
  "status": "ok",
  "embedding_provider": "ollama",
  "model": "nomic-embed-text",
  "items": 0,
  "max_items": 100000,
  "remaining": 100000
}

Prerequisites — Python, Docker; Ollama optional
moorcheh configure
moorcheh up
Health

​Overview

​Configure once

​After you change settings

​Configuration file

​Schema

​Editing and security

​Supported models and dimensions

​Ollama (local)

​OpenAI

​Cohere

​What moorcheh up does by provider

​Health check

​Related

Overview

Configure once

After you change settings

Configuration file

Schema

Editing and security

Supported models and dimensions

Ollama (local)

OpenAI

Cohere

What `moorcheh up` does by provider

Health check

Related