Embeddings

The embedding service converts text into vectors for semantic search, clustering, and memory retrieval. It is available as ctx.embeddings when an embedding provider is selected.

Use the service

import type {Context} from '@deepseek-ai/cordis'
import type {} from '@dsh-ai-providers/core'

export const inject = ['embeddings']

export async function index(ctx: Context, texts: string[]) {
  const result = await ctx.embeddings.embed(texts, {
    inputType: 'document',
    priority: 'background',
  })
  return result.vectors
}

embed() returns vectors in input order, the responding model, vector dimensions, and token usage when reported. The project-maintained OpenAI-compatible services reject empty strings. embedOne() is a convenience for one string.

Use inputType: 'query' for search queries and inputType: 'document' for indexed content when the provider distinguishes them. The OpenAI-compatible transport does not send this field because the OpenAI embeddings API has no equivalent; the Jina and Cohere providers send it as the model's own task (retrieval.query or search_query, and the document equivalents), Ollama has no equivalent and ignores it, and a provider for an instruction-based model can map it to the prefixes or fields that model expects. Never compare vectors from different models or dimensions. cosineSimilarity() from @dsh-ai-providers/core validates dimensions before comparing two vectors.

Prefetch and batching

prefetch(texts, options) starts background preparation without returning a promise. The selected service can deduplicate it with a later equivalent embed() call and retain the result for the configured hold period.

The OpenAI-compatible provider splits large input arrays according to its configured batch size. This is transport batching; the returned vectors remain in the original order.

OpenAI-compatible options

Option	Meaning
dimensions	Requested vector length for models that support shortening
user	Optional end-user identifier sent to the API

The provider calls POST /embeddings.

Index consistency

Store the returned model and dimensions with an index or collection. If either changes, rebuild the affected vectors before searching them. A connection can change its selected model without changing the consumer API, but that does not make vectors from the old and new models compatible.

Batch related documents where practical. The service preserves ordering, so callers can associate vectors[n] with texts[n]; do not infer identity from vector contents. For interactive search, embed the query at foreground priority and keep bulk indexing in the background so the concurrency gate can preserve responsive capacity.

Failure and cancellation

An empty input array returns an empty vector list without contacting the provider. An empty string inside a non-empty request is invalid-input. A requested dimension the provider cannot produce is unsupported; authentication, quota, and unknown-model responses are rejected. Pass an AbortSignal from indexing jobs and user searches so queued work and active HTTP requests can stop when their owner disappears.

prefetch() is deliberately fire-and-forget: it never reports a result and never throws to its caller. Use embed() whenever completion or failure matters to application state.