> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moorcheh.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Embedding providers

> Choose Ollama, OpenAI, or Cohere for text embeddings; supported models and dimensions.

## 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

```bash theme={null}
moorcheh configure
```

Or on first run:

```bash theme={null}
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:

```bash theme={null}
moorcheh configure --force
```

See [moorcheh configure](/on-prem/cli/runtime/configure) and [moorcheh up](/on-prem/cli/runtime/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. |

<Warning>
  **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.
</Warning>

## 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:

```json theme={null}
{
  "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`):

```json theme={null}
{
  "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`.

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

## 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`.

## LLM models for `/answer` (Ollama)

Configured under the `llm` block in `config.json` (same wizard as embeddings). These IDs are for **generation**, not embeddings.

| Model ID | Parameters (approx.) | Notes |
| - | - | - |
| `qwen2.5` | \~7B | **Default** / recommended (\~4.7 GB); Ollama `latest` for this family |
| `qwen2.5:1.5b` | \~1.5B | Lighter option (\~986 MB pull) |
| `llama3.2` | varies | Alternative local chat model |
| `mistral` | varies | Alternative local chat model |

On `moorcheh up`, Moorcheh pulls the configured **embedding** model and, if different, the **LLM** model when Ollama is reachable. Changing only the LLM does not require re-uploading text data; run **`moorcheh down`** then **`moorcheh up`** to apply.

<Warning>
  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.
</Warning>

## What `moorcheh up` does by provider

```mermaid theme={null}
flowchart TD
  A[moorcheh up] --> B{Read config.json}
  B --> C{provider?}
  C -->|openai or cohere| D[Start Moorcheh server only]
  D --> E[Pass EMBEDDING_* env to container]
  C -->|ollama| F{Host Ollama on 11434?}
  F -->|Yes| G[Server only + host.docker.internal]
  F -->|No| H[Start moorcheh-ollama then server]
  H --> I[Pull embedding model if missing]
  G --> I
```

| 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](/on-prem/cli/runtime/up).

## Health check

`GET /health` and `moorcheh status` return:

```json theme={null}
{
  "status": "ok",
  "embedding_provider": "ollama",
  "model": "nomic-embed-text",
  "llm_provider": "ollama",
  "llm_model": "qwen2.5",
  "items": 0,
  "max_items": 100000,
  "remaining": 100000
}
```

## Related

* [Prerequisites](/on-prem/prerequisites) - Python, Docker; Ollama optional
* [moorcheh configure](/on-prem/cli/runtime/configure)
* [moorcheh up](/on-prem/cli/runtime/up)
* [Health](/on-prem/api-references/health)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.