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