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

# Embeddings

> Text embedding generation, batching, and cache in HeavenBase.

<Note>
  *Vectors should be boringly repeatable — unless you explicitly asked for chaos.*
</Note>

The `embed` preset turns text into dense vectors for search, clustering, and routing. HeavenBase handles provider resolution, batching, deduplication, and cache the same way it handles chat — you pass strings and read vectors back.

<br />

## 1. Basic Usage

Construct an `LLM` with the `embed` preset (or pin `model=` and `provider=` explicitly). `embed` accepts one string or a list of strings:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import heavenbase as hb

llm = hb.LLM(preset="embed")

vector = llm.embed("hello")
vectors = llm.embed(["hello", "world"])
dim = llm.embed("hello", include="dim")
same_dim = llm.dim
```

The default `embed` preset uses the persistable alias `gpt-embedding-small`, which resolves to `text-embedding-3-small`. It inherits `heavenbase.llm.default_provider` unless you pin `heavenbase.llm.presets.embed.provider`.

If your chat default provider does not serve embeddings, configure the embedding preset separately:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb cfg set heavenbase.llm.presets.embed.provider openai
hb cfg set heavenbase.llm.presets.embed.model text-embedding-3-small
```

Known dimensions are stored in config: `embeddinggemma` is `768`, `text-embedding-3-small` is `1536`, `embed-v4.0` is `1536`, and `voyage-4-lite` is `1024`. `llm.dim` reads config first and falls back to one test embedding call when a custom embedding model has no configured dimension.

<br />

## 2. Dedicated Embedding Providers

Cohere and Voyage are embedding-only providers with no OpenRouter route. Pin the preset provider and use the bundled model keys:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb cfg set heavenbase.llm.presets.embed.provider cohere
hb cfg set heavenbase.llm.presets.embed.model embed-v4.0

hb cfg set heavenbase.llm.presets.embed.provider voyage
hb cfg set heavenbase.llm.presets.embed.model voyage-4-lite
```

Provider backends follow LiteLLM names (`cohere`, `voyage`). Gateway-specific `base_url` values live in `heavenbase.llm.providers`. With `gateway="portkey"` or `gateway="bifrost"`, model IDs are prefixed as `cohere/embed-v4.0` and `voyage/voyage-4-lite`.

<Warning>
  `gateway="portkey"` with `provider="openrouter"` is temporarily blocked for embeddings because Portkey Gateway does not yet support that route. Use the default OpenAI-compatible gateway or LiteLLM for OpenRouter embeddings until upstream support lands.
</Warning>

<br />

## 3. Include Projection

Embedding responses support the same `include` style as chat:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
result = llm.embed(
    ["hello", "world"],
    include=["embeddings", "dim", "usage"],
    reduce=False,
)
```

Available fields are `embeddings`, `usage`, `raw`, `elapsed`, `created_at`, and `dim`. Pass `include=None` for the default vector (or list of vectors), a string for one field, or a list for several.

<br />

## 4. CLI Output

`hb llm embed` prints the full raw embedding array by default. `--json` prints the full response object with `embeddings`, `dim`, and `usage`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb llm embed "Semantic text"
hb llm embed "Semantic text" --json
```

Use `--preview` when you only need to inspect a compact vector sample. Preview mode shows the first 4 and last 2 values rounded to 6 decimals. With `--json --preview`, the output keeps the same object keys and replaces `embeddings` with the abbreviated string.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb llm embed "Semantic text" --preview
hb llm embed "Semantic text" --json --preview
```

Use `--copy` / `-cp` to copy the emitted embedding output to the clipboard.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb llm embed "Semantic text" --json --copy
```

<br />

## 5. Local Embeddings

Use `embed-local` for LM Studio, Ollama, oMLX, or another OpenAI-compatible local server:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
local = hb.LLM(preset="embed-local", provider="lmstudio")
vector = local.embed("hello")
```

`embeddinggemma` is local-only in the bundled catalog and has identifiers for LM Studio, Ollama, and oMLX.

<br />

## 6. Batching and Cache

`embed` deduplicates repeated inputs before provider calls, splits cache misses with `embedding_batch_size`, runs split batches with bounded `embedding_max_workers`, and broadcasts cached and fresh vectors back to the original input order.

The root defaults are `embedding_batch_size=256` and `embedding_max_workers=8`; provider defaults or call kwargs can override them. These controls are excluded from provider payloads and cache keys.

Embedding cache is enabled by default under the `llm-cache` workspace. Disable it per instance with `hb.LLM(preset="embed", cache=False)` or per call with `cache=False`. See [Advanced LLM](/features/llm/advanced) for the full response-cache model.

<br />

## Further Exploration

<Tip>
  **Related resources:**

  * [LLM Overview](/features/llm/overview) — presets, the model catalog, and the resolution model.
  * [First LLM](/quickstart/first-llm) — configure keys and run your first embed from the CLI.
  * [Advanced LLM](/features/llm/advanced) — response caching, gateways, and upstream limitations.
</Tip>

<br />