IEmbeddingClient

Interfaces · AiDotNet.Interfaces

Turns text into embedding vectors, reporting transport failure as a value rather than an exception.

Known implementations: CachingEmbeddingClient, DeterministicEmbeddingClient, OpenAICompatibleEmbeddingClient

For Beginners

An embedding model reads a piece of text and returns a list of numbers that captures what the text is about; two texts about the same thing get similar lists. This interface is how the library asks for those numbers without caring which provider answers. If you have no provider, use the deterministic client and everything still runs, just without real semantic meaning.

How It Works

This is the seam every embedding-backed feature talks to, so the core library gains no provider dependency: the shipped implementations are an OpenAI-compatible HTTP client, a caching decorator, and a deterministic in-memory client that contacts nothing at all. A batch call is the primitive rather than a single-text call because every provider charges and rate-limits per request, and a novelty decision usually needs a candidate plus several neighbours at once.

Implementations must be safe for concurrent use, must preserve input order in Vectors, and must return Failure for a transport or provider error instead of throwing, so a caller can decide whether an unavailable provider means “accept” or “reject”. Argument mistakes — a null list, a null entry, an empty batch — remain exceptions, because those are programming errors rather than run-time conditions. An implementation must never write an API key to disk, a log, or a returned failure reason.

Properties

Property Summary
string ModelId { get; } Gets the identifier of the embedding model this client requests.

Methods

Method Summary
ValueTask<EmbeddingBatch> EmbedAsync(IReadOnlyList<string> texts, CancellationToken cancellationToken) Embeds one batch of texts, preserving input order.