Skip to main content
Vectors should be boringly repeatable — unless you explicitly asked for chaos.
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.

​
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:
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:
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.

​
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:
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.
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.

​
3. Include Projection

Embedding responses support the same include style as chat:
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.

​
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.
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.
Use --copy / -cp to copy the emitted embedding output to the clipboard.

​
5. Local Embeddings

Use embed-local for LM Studio, Ollama, oMLX, or another OpenAI-compatible local server:
embeddinggemma is local-only in the bundled catalog and has identifiers for LM Studio, Ollama, and oMLX.

​
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 for the full response-cache model.

​
Further Exploration

Related resources:
  • LLM Overview — presets, the model catalog, and the resolution model.
  • First LLM — configure keys and run your first embed from the CLI.
  • Advanced LLM — response caching, gateways, and upstream limitations.