Interface EmbeddingModel

All Known Implementing Classes:

AbstractInProcessEmbeddingModel, AllMiniLmL6V2EmbeddingModel, AllMiniLmL6V2QuantizedEmbeddingModel, AzureOpenAiEmbeddingModel, BedrockCohereEmbeddingModel, BedrockTitanEmbeddingModel, BgeSmallEnEmbeddingModel, BgeSmallEnQuantizedEmbeddingModel, BgeSmallEnV15EmbeddingModel, BgeSmallEnV15QuantizedEmbeddingModel, BgeSmallZhV15EmbeddingModel, BgeSmallZhV15QuantizedEmbeddingModel, CohereEmbeddingModel, DimensionAwareEmbeddingModel, DisabledEmbeddingModel, E5SmallV2EmbeddingModel, E5SmallV2QuantizedEmbeddingModel, GitHubModelsEmbeddingModel, GoogleAiEmbeddingModel, GoogleGenAiEmbeddingModel, HuggingFaceEmbeddingModel, JinaEmbeddingModel, JlamaEmbeddingModel, LocalAiEmbeddingModel, MistralAiEmbeddingModel, NomicEmbeddingModel, OllamaEmbeddingModel, OnnxEmbeddingModel, OpenAiEmbeddingModel, OpenAiOfficialEmbeddingModel, OracleEmbeddingModel, OvhAiEmbeddingModel, VertexAiEmbeddingModel, VoyageAiEmbeddingModel, WatsonxEmbeddingModel, WorkersAiEmbeddingModel

public interface EmbeddingModel

Represents a model that can convert a given text into an embedding (vector representation of the text).

Method Summary

Modifier and Type	Method	Description
default EmbeddingModel	addListener(EmbeddingModelListener listener)	Returns an EmbeddingModel that wraps this one and notifies the given listener around each embedding call.
default EmbeddingModel	addListeners(List<EmbeddingModelListener> listeners)	Returns an EmbeddingModel that wraps this one and notifies the given listeners (in iteration order) around each embedding call.
default EmbeddingRequestParameters	defaultRequestParameters()	The parameters applied to every request unless overridden by the request itself, typically derived from the model's builder-time configuration.
default int	dimension()	Returns the dimension of the Embedding produced by this embedding model.
default EmbeddingResponse	doEmbed(EmbeddingRequest request)	Performs the embedding for embed(EmbeddingRequest).
default Response<Embedding>	embed(TextSegment textSegment)	Embed the text content of a TextSegment.
default EmbeddingResponse	embed(EmbeddingRequest request)	Embeds the inputs of the given EmbeddingRequest and returns the resulting embeddings.
default Response<Embedding>	embed(String text)	Embed a text.
default Response<List<Embedding>>	embedAll(List<TextSegment> textSegments)	Embeds the text content of a list of TextSegments.
default List<EmbeddingModelListener>	listeners()	The EmbeddingModelListeners that are notified around embed(EmbeddingRequest).
default String	modelName()	Returns the name of the underlying embedding model.
default ModelProvider	provider()	The ModelProvider of this embedding model (for example ModelProvider.OPEN_AI).
default Set<ContentType>	supportedContentTypes()	The input content types this model can embed.
default Set<EmbeddingParameter<?>>	supportedParameters()	The per-call parameters this model honors.

Method Details

embed

@Experimental
default EmbeddingResponse embed(EmbeddingRequest request)

Embeds the inputs of the given EmbeddingRequest and returns the resulting embeddings.

An EmbeddingRequest carries one or more inputs to embed, together with optional per-call parameters such as dimensions or an input type. A model only honors the parameters listed in supportedParameters() and the content types listed in supportedContentTypes(); a request that uses anything else is rejected with an UnsupportedFeatureException rather than being silently ignored.

Parameters:

request - the inputs to embed and the per-call parameters.

Returns:

the embeddings and the response metadata.

Since:

1.18.0

listeners

@Experimental
default List<EmbeddingModelListener> listeners()

The EmbeddingModelListeners that are notified around embed(EmbeddingRequest). Configure them on the model's builder (via listeners(...)). Defaults to an empty list.

Since:

1.18.0

provider

@Experimental
default ModelProvider provider()

The ModelProvider of this embedding model (for example ModelProvider.OPEN_AI). It is made available to listeners through the request, response and error contexts. Defaults to ModelProvider.OTHER.

Since:

1.18.0

doEmbed

@Experimental
default EmbeddingResponse doEmbed(EmbeddingRequest request)

Performs the embedding for embed(EmbeddingRequest). This is the low-level method a provider overrides to build the actual API call; embed(EmbeddingRequest) handles per-call parameter validation and listener dispatch around it.

An implementation must override either this method (preferred) or embedAll(List) — the two have mutually-recursive defaults, so overriding neither leads to infinite recursion. The default implementation embeds the text of each input via embedAll(List), which keeps implementations that only provide embedAll(List) working.

When this method is called, the request's parameters have already been merged with defaultRequestParameters() and validated against supportedParameters() and supportedContentTypes().

Parameters:

request - the request, with parameters already merged and validated.

Returns:

the response.

Since:

1.18.0

defaultRequestParameters

@Experimental
default EmbeddingRequestParameters defaultRequestParameters()

The parameters applied to every request unless overridden by the request itself, typically derived from the model's builder-time configuration. The default is EmbeddingRequestParameters.EMPTY.

Since:

1.18.0

supportedParameters

@Experimental
default Set<EmbeddingParameter<?>> supportedParameters()

The per-call parameters this model honors. A request that populates a parameter outside this set is rejected by embed(EmbeddingRequest) with an UnsupportedFeatureException, so a parameter a model cannot apply is never silently ignored. Defaults to an empty set (the model accepts no per-call parameters).

Since:

1.18.0

supportedContentTypes

@Experimental
default Set<ContentType> supportedContentTypes()

The input content types this model can embed. A request whose inputs use a content type outside this set is rejected by embed(EmbeddingRequest) with an UnsupportedFeatureException. Defaults to {TEXT}; a multimodal model overrides this to also accept, for example, images.

Since:

1.18.0

embed

default Response<Embedding> embed(String text)

Embed a text.

Parameters:

text - the text to embed.

Returns:

the embedding.

embed

default Response<Embedding> embed(TextSegment textSegment)

Embed the text content of a TextSegment.

This is a convenience method over embed(EmbeddingRequest), so listeners are notified and the model's default per-call parameters are applied here too.

Parameters:

textSegment - the text segment to embed.

Returns:

the embedding.

embedAll

default Response<List<Embedding>> embedAll(List<TextSegment> textSegments)

Embeds the text content of a list of TextSegments.

This is a convenience method over embed(EmbeddingRequest), so listeners are notified and the model's default per-call parameters are applied here too. A provider implements its embedding logic by overriding doEmbed(EmbeddingRequest) (preferred); it may still override this method for batch-specific behavior that the request/response API does not carry (for example applying a document title from TextSegment metadata).

Parameters:

textSegments - the text segments to embed.

Returns:

the embeddings.

dimension

default int dimension()

Returns the dimension of the Embedding produced by this embedding model.

Returns:

dimension of the embedding

modelName

default String modelName()

Returns the name of the underlying embedding model.

Implementations are encouraged to override this method and provide the actual model name. The default implementation returns "unknown", which indicates that the model name is unknown.

Returns:

the model name or a fallback value if not provided

addListener

@Experimental
default EmbeddingModel addListener(EmbeddingModelListener listener)

Returns an EmbeddingModel that wraps this one and notifies the given listener around each embedding call. Listeners can also be configured directly on a model's builder via listeners(...) (see listeners()), which does not require wrapping.

Parameters:

listener - The listener to add.

Returns:

An EmbeddingModel that notifies the given listener.

Since:

1.11.0

See Also:

• listeners()

addListeners

@Experimental
default EmbeddingModel addListeners(List<EmbeddingModelListener> listeners)

Returns an EmbeddingModel that wraps this one and notifies the given listeners (in iteration order) around each embedding call. Listeners can also be configured directly on a model's builder via listeners(...) (see listeners()).

Parameters:

listeners - The listeners to add.

Returns:

An EmbeddingModel that notifies the given listeners.

Since:

1.11.0

See Also:

• listeners()