OpenAICompatibleEmbeddingClient

Models & Types · AiDotNet.Agentic.Embeddings

An IEmbeddingClient for any provider that speaks the OpenAI /v1/embeddings wire format.

Implements: IEmbeddingClient

For Beginners

This is the adapter that asks a real provider to turn text into vectors. You give it your API key and, if you are not using OpenAI itself, the URL of a compatible service. It handles the network details — timeouts, retrying a request that failed for a temporary reason, and reporting a permanent failure in a way that cannot be mistaken for a real answer.

How It Works

The transport mirrors ChatClientBase exactly: a caller-owned HttpClient is never mutated, an owned one gets the configured timeout, a non-success response becomes an HttpResponseException so the status survives on .NET Framework, and retries use the same doubling backoff over 429, 408, 5xx and transport errors — with the same NET5_0_OR_GREATER split, because HttpRequestException.StatusCode does not exist on net471 and the inner WebException has to be inspected instead.

Three things differ from the reference implementation deliberately. Upstream accepts only a hard-coded list of model names and picks a provider from that name, so an OpenAI-compatible gateway, a local server, or any new model is a ValueError; here the endpoint is a parameter and any model name is legal. Upstream has no retry and no timeout at all. And upstream returns an empty vector on failure, which its caller then stores as that program’s embedding forever; here a failure is an explicit Failure carrying only a status code or exception type — never the response body, which can echo request content.

Each input is truncated to MaxInputCharacters before it is sent, because the text being embedded is usually a model-authored program and an unbounded candidate must not become an unbounded request body. The API key is held in memory for the lifetime of the client and is never logged, serialized, or persisted.

Constructors

Constructor Summary
OpenAICompatibleEmbeddingClient(string apiKey, string modelId, string endpoint, HttpClient httpClient, int maxInputCharacters, int maxRetries, int initialRetryDelayMilliseconds, int timeoutMilliseconds) Initializes an embeddings client.

Properties

Property Summary
int MaxInputCharacters { get; } Gets the per-input character bound applied before a request is sent.
string Endpoint { get; } Gets the endpoint requests are posted to.
string ModelId { get; }

Methods

Method Summary
ValueTask<EmbeddingBatch> EmbedAsync(IReadOnlyList<string> texts, CancellationToken cancellationToken)

Fields

Field Summary
int DefaultMaxInputCharacters The default per-input character bound.
string DefaultEndpoint The public OpenAI embeddings endpoint used when none is supplied.
string DefaultModelId The model requested when none is supplied.