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

<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",
  "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)